From be01a116ca88b10068a6cdc4a79107009e8ac658 Mon Sep 17 00:00:00 2001 From: Yun Chan Date: Sat, 15 Aug 2026 13:46:05 +0900 Subject: [PATCH] deploy: self-hosted build machines operational (vd-linux/vd-mac) - 4 artifacts built & native-exec E2E passed (HLS download EXIT=0 on both) --- DEPLOYMENT_PLAN.md | 193 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 DEPLOYMENT_PLAN.md diff --git a/DEPLOYMENT_PLAN.md b/DEPLOYMENT_PLAN.md new file mode 100644 index 0000000..57773e9 --- /dev/null +++ b/DEPLOYMENT_PLAN.md @@ -0,0 +1,193 @@ +# Video Downloader — 멀티플랫폼 배포 체계 계획서 (v1) + +> **범위**: Windows · macOS · Linux 데스크톱 + Android · iOS 모바일의 **빌드→서명→패키징→배포→업데이트** 전 체계. +> GitHub Releases 를 단일 배포 소스로, GitHub Actions 로 전 아티팩트 자동 빌드. +> +> **작성일**: 2026-08-15 · **관련 문서**: `BROWSER_FEATURES_PLAN.md`(v2) · `MOBILE_PLAN.md`(v1) +> **조사 근거**: 전문 조사팀 20회 검색 + GitHub Releases API 로 툴체인 바이너리 실물 검증 (2026-08 기준) + +--- + +## 0. 핵심 결론 + +1. **배포 소스는 GitHub Releases 단일 채널** — 계정/서버 인프라 없음(제품 철학과 일치). 태그(`v*`) 푸시 → CI 매트릭스 빌드 → Draft Release → QA → Publish. +2. **⚠️ 중대 발견: CefGlue.Avalonia 는 Linux 미지원** (공식 문서 명시, 이슈 #189). MOBILE_PLAN/BACKLOG 의 "크로스플랫폼 브라우저 = CEF" 가정 수정 필요 → **플랫폼별 네이티브 WebView 계층**(Windows=WebView2, macOS=WKWebView, Linux=WebKitGTK)을 기본으로 하고 CEF는 Windows/macOS 보조 후보로 강등. 단, 네이티브 WebView 는 응답 가로채기(미디어 스니핑)가 CEF 보다 약함 → **크로스플랫폼 감지 품질 게이트를 별도로 통과해야 이관** (기존 Gate #1 정신 유지). +3. **macOS 는 Apple Developer Program($99/년) 없이는 실효 배포 불가** (공증 필수). 첫 macOS 릴리스 전 가입 예산 수립. +4. **데스크톱 자동 업데이트**: v1 = GitHub latest 태그 폴링 + 설치 열기(무의존·전 OS 공통), v2 = Velopack(델타 업데이트, Windows 우선 도입). +5. **툴체인(yt-dlp/ffmpeg/deno)은 전 플랫폼 자동 다운로드 가능** — 단 ffmpeg macOS arm64 는 BtbN 빌드가 없어 **ffmpeg-static 릴리스** 사용 (§4 검증표). + +--- + +## 0.5 자체 빌드머신 (운영 중 — 2026-08-15 구축 완료) + +GitHub Actions 대신(또는 보완으로) **사용자 소유 빌드머신 2대**로 리눅스/macOS 산출물을 생산한다: + +| 별칭 | 머신 | 사양 | SDK | 역할 | +|---|---|---|---|---| +| `vd-linux` | ChanpacaLaptop (Linux Mint 22.3) — Tailscale `100.65.55.115` | x86_64 · 32C · 62GB | 8.0.424 + 10.0.400 | `linux-x64` 빌드 | +| `vd-mac` | Mac mini M2 (macOS 26.5.2) — LAN `192.168.0.127` / Tailscale `100.88.141.44` | arm64 | 8.0.424 + 10.0.400 | `osx-arm64` 빌드 (+iOS 임시) | + +- **접속**: SSH 키 인증(`~/.ssh/id_ed25519_vd`, `~/.ssh/config` 별칭). 엔드포인트·자격증명은 `.env`(git 무시). +- **빌드 명령**: `bash build/remote/build-remote.sh [linux|mac|all]` — git HEAD 소스를 머신에 전송 → Cli+Avalonia RID별 self-contained publish → 산출물 tar.gz 수집(`out/remote//`). +- **검증(2026-08-15)**: linux-x64·osx-arm64 양쪽 4산출물 생성(ELF/Mach-O arm64 매직 확인), **양 머신에서 네이티브 실행 E2E 통과** — HLS 테스트 스트림 64세그먼트 다운로드+병합 EXIT=0. +- **운영 지식**: Avalonia 12.1 게터는 .NET 10 SDK 필요(8만 있으면 CS0103). 빌드머신 절전 시 SSH 끊김 → 재연결 감지 폴러 패턴으로 자동 재개 검증됨. Mac 무헤드 운용 시 "네트워크 접근 시 깨우기" 활성화 권장. +- GitHub Actions(§5)는 리포지토리 공개 시 **자동 백업 채널**로 병행. + +## 1. 제품 × 아티팩트 매트릭스 + + +| 제품 | 플랫폼 | 아티팩트 | 채널 | 서명 | +|---|---|---|---|---| +| **App (WPF+WebView2)** — 주력 | Windows x64 | `VideoDownloader-Setup-x64.exe` (Inno, 기존) | GitHub Releases | Authenticode (선택, 후순위) | +| | Windows arm64 | `VideoDownloader-Setup-arm64.exe` (기존) | 〃 | 〃 | +| **App (Avalonia 셸)** — 크로스플랫폼 이관 | Linux x64/arm64 | `videodownloader-linux-x64.tar.gz` (기본) + `.AppImage` + `.deb` | GitHub Releases | (GPG 서명 선택) | +| | macOS x64/arm64 | `VideoDownloader-.dmg` (+ `.app` in DMG) | GitHub Releases | Developer ID + 공증 필수 | +| **Mobile (MAUI)** | Android | `VideoDownloader--arm64.apk` | GitHub Releases + Obtainium | Keystore (CI 시크릿) | +| | Android (Play, 선택) | `.aab` | Google Play (추출코드 없는 빌드) | Play App Signing | +| | iOS | `.ipa` | TestFlight → App Store | Apple 배포 인증서 | +| **Server / 웹 컴패니언** | 데스크톱 앱에 내장 | 별도 배포 없음 (앱이 Kestrel 서빙) | — | 앱 서명에 포함 | + +**버저닝**: `Major.Minor.Patch` 세마버 + 태그 `v*`. 모든 프로젝트 공통 버전(csproj `Version` 일괄 주입 `-p:Version=`). + +--- + +## 2. 데스크톱 상세 + +### 2.1 Windows (현재 자산 유지) +- 기존 체계 그대로: `dotnet publish -c Release -r win-x64/arm64 --self-contained`(폴더 배포) → ISCC 2회 → `out/Setup-*.exe`. `build/publish.ps1` 스크립트를 CI 잡으로 감싸기만 하면 됨. +- Windows arm64 는 x64 러너에서 교차 publish 가능(현재 방식 그대로 CI 호환). + +### 2.2 macOS (Avalonia 셸) +1. `dotnet publish -c Release -r osx-arm64/-x64 --self-contained` (폴더; **CEF/단일파일 불가 원칙** — 네이티브 WebView 라면 폴더 배포로 충분) +2. `.app` 래핑: `Contents/MacOS/`(호스트) · `Contents/Resources/` · `Info.plist` (Avalonia 공식 가이드) +3. **universal 보다 아키텍처별 DMG 2개가 저렴** (lipo 병합은 호스트만 가능, CEF 프레임워크는 별도) +4. 서명/공증 파이프라인: + ``` + codesign --force --options runtime --timestamp --sign "Developer ID Application: ..." App.app + xcrun notarytool store-credentials NOTARY --apple-id ... --team-id ... --password ... + xcrun notarytool submit App.dmg --keychain-profile NOTARY --wait + xcrun stapler staple App.app + ``` + - DMG 생성: `create-dmg`/`dmgbuild` (macOS 러너에서만) + - LAN 페어링(모바일 연동) 시 macOS 로컬 네트워크 프라이버시 프롬프트 대응 안내 UI 필요 +5. **툴체인 Gatekeeper 주의**: 앱이 HttpClient 로 내려받는 yt-dlp/deno/ffmpeg 는 quarantine xattr 이 안 붙음 → 런타임 자동다운로드 설계가 Gatekeeper 이슈를 자동 회피 (현재 설계 유지가 정답) + +### 2.3 Linux (Avalonia 셸) +- **기본 = tar.gz self-contained** (모든 배포판 보장), **편의 = AppImage** (linuxdeploy/appimagetool), **선택 = .deb** (dpkg-deb, `Depends:` 는 네이티브만). +- AppImage 함정: Ubuntu 24.04 는 libfuse2 부재 → tar.gz 병행 의무화. +- Avalonia(X11) 의존: `libx11-6 libice6 libsm6 libfontconfig1` (+브라우저 엔진이 WebKitGTK면 `libwebkit2gtk-4.1`, CEF면 Chrome 셋: `libnss3 libgbm1 libasound2 libatk1.0 libcups2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libdbus-1-3 libdrm2` + mesa). +- 네이티브 데스크톱 항목(파일 다이얼로그 등)에 `libgtk-3` 선택 의존 가능. + +### 2.4 크로스플랫폼 브라우저 엔진 전략 (수정) +| OS | 1순위 | 대안 | 감지(스니핑) 전망 | +|---|---|---|---| +| Windows | **WebView2** (현행) | CefGlue | 최상 (WebResourceResponseReceived) | +| macOS | **WKWebView** (WebView.Avalonia) | CefGlue(동작 보고됨) | WKURLSchemeHandler/프록시 조합 필요 — 품질 게이트 필수 | +| Linux | **WebKitGTK** (WebView.Avalonia) | CEF(**미지원 이슈 #189**) | WebKit의 리소스 인터셉트로 제한적 — 품질 게이트 필수 | + +→ **Gate #1'**: 3OS 각각 "HLS/DASH/MP4 직링크 감지 + 쿠키 전달" E2E 통과 시에만 해당 OS 베타 출시. 통과 못하면 해당 OS 는 "링크 붙여넣기 다운로더"(브라우저 없음, 현재 Avalonia 앱 형태)로 출시. + +--- + +## 3. 모바일 상세 + +### 3.1 Android +```bash +dotnet publish src/Mobile -f net10.0-android -c Release \ + -p:AndroidPackageFormat=apk -p:RuntimeIdentifiers=android-arm64 \ + -p:AndroidKeyStore=true -p:AndroidSigningKeyStore=$KS \ + -p:AndroidSigningKeyAlias=vd -p:AndroidSigningKeyPass=... -p:AndroidSigningStorePass=... +``` +- 배포: GitHub Releases APK + **Obtainium 지원** (README에 `app.json` 원탭 설정 배포 → GitHub Release 만으로 자동 업데이트 채널 확보) +- Play (선택, 후순위): `AndroidPackageFormat=aab` + 사이트 특화 추출 코드 제거 빌드 변형 + +### 3.2 iOS +- TestFlight 외부 10,000명 (베타 리뷰 24-48h). 내부 100명 무리뷰. +- **필수**: `PrivacyInfo.xcprivacy` (2024-05부터 누락 시 ITMS-91053 리젝 — MAUI 바인딩 항목 포함 점검) +- **심사 프레이밍 (가이드라인 2.5.13 부합)**: "사용자 소유 PC 원격 제어 + 자기 라이브러리 시청" — 심사 메모에 자기 PC 연결 데모 영상 첨부. 5.2.3 회피: 기기 내 추출 코드 없음(전부 PC 실행) 명시. +- CI: macOS 러너에서 빌드+서명 (인증서/프로비저닝 시크릿), 업로드는 App Store Connect API. + +--- + +## 4. 툴체인 바이너리 매핑 (GitHub Releases 검증 완료, 2026-08) + +| 툴 | Windows x64/arm64 | macOS (universal/x64/arm64) | Linux x64/arm64 | +|---|---|---|---| +| yt-dlp | `yt-dlp.exe` / `yt-dlp_arm64.exe` | `yt-dlp_macos` (universal2) ✅ | `yt-dlp_linux` / `yt-dlp_linux_aarch64` ✅ | +| ffmpeg | BtbN `win64-gpl` / `winarm64-gpl` | ⚠️ BtbN 없음 → **ffmpeg-static releases** (x64+arm64 darwin) | BtbN `linux64-gpl` / `linuxarm64-gpl` ✅ | +| deno | `deno-x86_64-pc-windows-msvc.zip` | `deno-aarch64/x86_64-apple-darwin.zip` ✅ | `deno-x86_64/aarch64-unknown-linux-gnu.zip` ✅ | + +- 공통 패턴: `https://github.com///releases/latest/download/` + SHA256 검증파시(.sha256sum/SUMS) — 기존 `YtDlpRunner`/`DenoRunner` 자동설치 메커니즘을 `Core/Platform/IToolLocator` 추상화 아래 **OS/아키텍처 매니페스트 테이블**로 일반화 (재구성 계획 ②와 동일 작업). +- ffmpeg macOS 공급처 이원화(BtbN/ffmpeg-static)는 `IToolLocator` 구현체의 플랫폼별 다운로드 소스 매핑으로 흡수. + +--- + +## 5. CI/CD (GitHub Actions) + +```yaml +# .github/workflows/release.yml (개요) +on: { push: { tags: ['v*'] } } +jobs: + test: # dotnet test (단위+E2E) — 전 플랫폼 빌드의 관문 + desktop: + strategy: + matrix: + include: + - { os: windows-latest, rid: win-x64 } + - { os: windows-latest, rid: win-arm64 } # 교차 publish + - { os: ubuntu-latest, rid: linux-x64 } + - { os: ubuntu-24.04-arm, rid: linux-arm64 } + - { os: macos-latest, rid: osx-arm64 } # 무료 M1 러너(공개 저장소) + - { os: macos-13, rid: osx-x64 } + steps: [checkout, setup-dotnet(8/10), publish(폴더/Inno/AppImage/deb/DMG), 서명·공증(macOS만), upload-artifact] + android: [ubuntu-latest, JDK21+MAUI 워크로드, dotnet publish apk, 서명, upload] + ios: [macos-latest, 워크로드, 서명(ipa), TestFlight 업로드] + release: + needs: [test, desktop, android] + steps: [download-artifact, softprops/action-gh-release@v2 (draft: true)] +``` + +- **시크릿**: `MACOS_P12`(base64)/`KEYCHAIN_PASS`/`NOTARY_PROFILE`(Apple ID·팀·앱비밀번호) · `ANDROID_KEYSTORE/ALIAS/PASS` · (iOS) `ASC_KEY`. +- macOS 서명 함정: 키체인 자동 잠금 방지 타임아웃 설정. +- 공개 저장소 기준 러너 무료(macOS 포함). 비공개 전환 시 macOS 10× 과금 유의. +- QA 통과 후 Draft → Publish 수동 승격. + +## 6. 업데이트 체계 + +| 대상 | 방식 | +|---|---| +| Windows/Linux/macOS v1 | `GET /repos/:owner/:repo/releases/latest` 태그 비교 → "다운로드·설치" 버튼(설치 파일 열기) | +| Windows v2 | **Velopack** (델타+자동적용; Inno → Velopack 설치기 일회 마이그레이션 릴리스) | +| Android | Obtainium (GitHub Releases 연동) / Play (후순위) | +| iOS | TestFlight·App Store 표준 흐름 | +| 툴체인 | 기존 yt-dlp 자동갱신 + `IToolLocator` 버전 체크 확장 | + +--- + +## 7. 로드맵 (배포 관점) + +| 단계 | 내용 | 전제 | +|---|---|---| +| D1 | 리포지토리 GitHub 공개 + `release.yml`(test→win x64/arm64→draft) — **현재 Windows 체계를 CI 로 이식** | 없음 (즉시) | +| D2 | Android APK 잡 추가 (M1 완료 시점) | M1 | +| D3 | Linux tar.gz/AppImage/deb 잡 (Avalonia 셸 Gate #1' 통과 후) | 크로스플랫폼 셸 | +| D4 | macOS DMG + 서명·공증 잡 (Developer Program 가입 후) | $99/년 + Gate #1' | +| D5 | iOS TestFlight 잡 | M3 | +| D6 | 자동 업데이트 v1(태그 폴링) → v2(Velopack) | D1 이후 언제든 | + +## 8. 리스크 요약 + +1. **CEF Linux 미지원** — 네이티브 WebView 폴백 확정, 감지 품질 게이트로 방어 (§2.4) +2. macOS 공증 = Apple Developer Program 필수 (미가입 시 macOS 배포 중단) +3. AppImage/libfuse2, ffmpeg macOS 공급처 부재(BtbN) → ffmpeg-static 대체 (§4) +4. iOS 프라이버시 매니페스트 누락 리젝 (ITMS-91053) +5. 비공개 리포지토리 전환 시 macOS 러너 비용 10× + +## 출처 (핵심) +- CefGlue Linux 미지원: [OutSystems/CefGlue #189](https://github.com/OutSystems/CefGlue/issues/189) · [CefGlue.Avalonia NuGet](https://www.nuget.org/packages/CefGlue.Avalonia) +- macOS 배포: [Avalonia macOS 가이드](https://avaloniaui.net/blog/the-definitive-guide-to-building-and-deploying-avalonia-applications-for-macos) · [.NET macOS publish](https://learn.microsoft.com/en-us/dotnet/core/deploying/macos) · [notarytool 워크플로](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow) +- Linux: [Avalonia Linux 의존성](https://docs.avaloniaui.net/docs/deployment/linux) · [deb-control](https://man7.org/linux/man-pages/man5/deb-control.5.html) +- CI: [GitHub M1 러너](https://github.blog/changelog/2024-01-30-github-actions-introducing-the-new-m1-macos-runner-available-to-open-source/) · [애플 인증서 설치](https://docs.github.com/actions/use-cases-and-examples/deploying/installing-an-apple-certificate-on-macos-runners-for-xcode-development) · [action-gh-release](https://github.com/softprops/action-gh-release) +- 툴체인: [yt-dlp releases](https://github.com/yt-dlp/yt-dlp/releases) · [BtbN ffmpeg](https://github.com/btbn/ffmpeg-builds/releases) · [ffmpeg-static](https://github.com/eugeneware/ffmpeg-static) · [deno releases](https://github.com/denoland/deno/releases) +- 모바일: [MAUI publish-cli](https://learn.microsoft.com/en-us/dotnet/maui/android/deployment/publish-cli?view=net-maui-10.0) · [TestFlight 한도](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers/) · [가이드라인 2.5.13](https://developer.apple.com/app-store/review/guidelines/) · [Obtainium](https://github.com/ImranR98/Obtainium) +- 업데이트: [Velopack](https://github.com/velopack/velopack) · [cross-compile](https://docs.velopack.io/packaging/cross-compiling)