# 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/<rid>/`).
- **검증(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-<arch>.dmg` (+ `.app` in DMG) | GitHub Releases | Developer ID + 공증 필수 |
| **Mobile (MAUI)** | Android | `VideoDownloader-<ver>-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/<owner>/<repo>/releases/latest/download/<asset>` + 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)