216 lines
13 KiB
Markdown
216 lines
13 KiB
Markdown
# D3RO Voice 업데이트 시스템 평가와 2026 방법론
|
|
|
|
기준일: 2026-09-13. 이 문서는 현재 자동 업데이트·릴리스 체계를 평가하고, 2026년
|
|
9월 기준 업계 방법론에 맞춘 목표 아키텍처와 결정 사항을 기록한다. 운영 절차는
|
|
[`release-guide.md`](./release-guide.md), 정책 정본은
|
|
[`release/update-policy.json`](../../release/update-policy.json)이다.
|
|
|
|
---
|
|
|
|
## 1. 결론
|
|
|
|
**기반은 좋다. 그러나 "업데이트 시스템"이라 부르기엔 미완성이다.**
|
|
|
|
현재 데스크톱은 `electron-updater` + GitLab Generic Package Registry feed로
|
|
동작하며, 버전 SSOT·CHANGELOG gate·메타데이터 자가검증·서명 fail-closed까지
|
|
갖춘 릴리스 파이프라인을 이미 보유한다. 이 부분은 업계 표준보다 앞서 있다.
|
|
|
|
반면 다음은 없다.
|
|
|
|
- **업데이트 채널**: stable/beta/alpha 구분이 없고 `latest.yml` 하나만 존재한다.
|
|
- **메이저/증분 정책**: major 승격, 최소 지원 버전, 강제 업데이트, 버전 갭에 따른
|
|
full 재설치 판단이 전혀 없다. 모든 업데이트가 동일하게 취급된다.
|
|
- **단계적 롤아웃(staged rollout)과 킬 스위치**: 없다.
|
|
- **배포 호스트 일관성**: 제품의 공개 배포 허브(admin·site 다운로드)는 Forgejo
|
|
`git.chanpaca.net/yunchan/d3ro-voice`인데, 정작 updater feed는 GitLab
|
|
(project 1172)을 가리킨다. 게다가 `verify-release-metadata.mjs`는 Forgejo
|
|
릴리스 배포를 **금지**하고 있어 Forgejo로 릴리스할 수 없다.
|
|
- **업데이트 서명**: `latest.yml` 메타데이터 서명(Ed25519)이 "future work"로만
|
|
남아 있다. 코드 서명은 요구하지만 feed 자체 무결성은 TLS + SHA-512에만 의존한다.
|
|
|
|
**판정: `[~]` (부분).** 데스크톱 단일 채널·단일 호스트 업데이터로는 동작하지만,
|
|
다중 채널·강제 업데이트·Forgejo 배포·릴리스 관리 방법론을 갖춘 "업그레이드 체계"는
|
|
아직 아니다. 이 문서와 함께 추가된 코드가 그 격차를 메운다.
|
|
|
|
---
|
|
|
|
## 2. 현재 구현 인벤토리
|
|
|
|
| 구성 | 위치 | 상태 |
|
|
|---|---|---|
|
|
| 업데이터 서비스 | `apps/desktop/src/main/services/UpdateService.ts` | 단일 feed, 4h 주기, 동의 다이얼로그, skip version |
|
|
| feed SSOT | `apps/desktop/src/main/update-feed.ts` | canonical Forgejo registry `latest` (버전 비고정) + legacy GitLab mirror 상수 |
|
|
| 빌더 publish | `apps/desktop/electron-builder.yml` | `provider: generic`, `detectUpdateChannel: false` |
|
|
| 버전 SSOT | `release/product-version.json` | `1.2.0` / `1020001` |
|
|
| 버전 동기화 | `scripts/ci/sync-version.mjs` | 태그·패키지·lockfile·Android/iOS/.NET 일치 fail-closed |
|
|
| 메타데이터 검증 | `scripts/ci/verify-release-metadata.mjs` | feed·publisher·workflow 계약 self-test |
|
|
| GitLab publisher | `scripts/ci/publish-gitlab-release.mjs` | 버전별 + `latest`, 설치자산 우선, public 재검증 (legacy mirror) |
|
|
| Forgejo publisher | `scripts/ci/publish-forgejo-release.mjs` | canonical feed·Release·policy 게시, 동일 버전 재게시 fail-closed |
|
|
| Windows 산출물 gate | `scripts/ci/verify-windows-release-artifact.ps1` | Authenticode·PE version·SHA-512 |
|
|
| CI | `.gitlab-ci.yml` `package-*` → `publish-release` | 태그 전용 |
|
|
| Forgejo | `.forgejo/workflows/release.yml` | tag 전용 release·feed 게시 (동일 publisher 수렴) |
|
|
| 릴리스 노트 | `CHANGELOG.md` (Keep a Changelog) | publisher가 섹션 누락 시 실패 |
|
|
|
|
---
|
|
|
|
## 3. 갭 상세
|
|
|
|
### 3.1 채널 부재
|
|
`detectUpdateChannel: false`이고 `updater.channel` 설정이 없어 항상 `latest.yml`을
|
|
읽는다. 베타/알파 사용자를 분리할 수 없고, prerelease를 안정 채널에 노출하지 않으려면
|
|
매번 수동으로 feed를 조작해야 한다.
|
|
|
|
### 3.2 메이저/증분 판단 부재
|
|
`_promptUserConsent`는 버전과 무관하게 동일한 3버튼 다이얼로그를 띄운다.
|
|
`update-available` 이벤트에 `isMandatory` 필드가 선언돼 있지만 실제로 계산하지 않는다.
|
|
major 승격(예: 1.x → 2.x)에서 사용자가 "나중에"를 눌러 구버전에 남을 수 있고,
|
|
버전 갭이 큰 클라이언트가 differential patch를 시도하다 실패할 수 있다.
|
|
|
|
### 3.3 Forgejo 배포 금지
|
|
`verify-release-metadata.mjs:147-148`은 Forgejo workflow에
|
|
`sync-and-publish-forgejo-release`가 포함되면 실패시킨다. 이 스크립트가 버전을
|
|
`1.0.0`으로 하드코딩한 legacy이기 때문이다. 결과적으로 Forgejo에는 릴리스가
|
|
존재하지만(v1.0.0, 2026-08-20) 최신 체계에서는 갱신되지 않는다. 제품의 공개
|
|
다운로드 페이지(`site/`, `apps/web/download`, `apps/admin/releases`)는 모두
|
|
Forgejo를 정본으로 본다.
|
|
|
|
### 3.4 staged rollout / 킬 스위치 부재
|
|
`stagingPercentage`를 쓰지 않아 새 버전이 전 사용자에게 즉시 노출된다. 잘못된
|
|
릴리스 회수는 "더 높은 버전으로 forward-fix"만 가능하다.
|
|
|
|
### 3.5 메타데이터 서명 부재
|
|
SHA-512는 TLS 종단 간 무결성만 보장한다. Feed 호스트가 침해되면 악성 설치자를
|
|
서명 검증 이전에 내려줄 수 있다. 2026년 표준(Doyensec SafeUpdater, Sparkle 2.9
|
|
signed feed, Tauri ed25519 강제)은 **매니페스트 서명**을 요구한다.
|
|
|
|
### 3.6 릴리스 gate 신뢰성 저하 (발견)
|
|
`apps/desktop/package.json`의 `typecheck`는 `tsc --noEmit`인데 `tsconfig.json`이
|
|
`files: []` + `references` 구조라 **아무 파일도 검사하지 않는다**. 실제로
|
|
`tsc -p tsconfig.node.json --noEmit`을 돌리면 다수의 기존 오류가 나온다
|
|
(`bootstrap.ts`, `support-handlers.ts` 등). 즉 "typecheck GREEN"은 데스크톱
|
|
main/preload에 대해 아무 의미가 없고, 릴리스 게이트가 이 착시에 의존한다.
|
|
(`npm run lint`와 vitest는 정상 동작.)
|
|
|
|
### 3.7 버전 번호 이력 불일치
|
|
git 태그는 `v1.0.0`에서 멈춰 있고, live `latest.yml`은 `0.2.1-alpha`다. 제품 버전
|
|
정본은 `1.1.0`이다. 태그→릴리스 파이프라인은 "같은 커밋에서 검증"을 요구하므로
|
|
`1.1.0` 릴리스가 아직 시작되지 않았음을 보여준다.
|
|
|
|
---
|
|
|
|
## 4. 2026 방법론 (조사 요약)
|
|
|
|
### 4.1 프레임워크 선택
|
|
|
|
| 옵션 | 특징 | 판단 |
|
|
|---|---|---|
|
|
| **electron-updater + electron-builder v26/27+** | blockmap 차분, 채널, `stagingPercentage`, Windows 서명 검증, generic provider | **유지**. 이미 통합돼 있고 가장 성숙 |
|
|
| Velopack | Squirrel 대체, JS/Electron 지원, delta | 빌드 프레임워크 교체 비용 큼 |
|
|
| Tauri updater | ed25519 서명 강제, `latest.json` | Tauri 전용 |
|
|
| Sparkle | macOS 전용, 서명 feed, critical update | 교차 플랫폼 아님 |
|
|
| update-electron-app | 공식 Squirrel 경로 | 채널·staged rollout 없음 |
|
|
|
|
결론: **electron-updater를 유지하고 v27+ 보안 기본값(파일 단위 `files[]` 메타데이터,
|
|
fail-closed 서명 검증, 명시적 publish) 방향으로 설정을 정렬**한다.
|
|
|
|
### 4.2 차분(delta) vs 전체(full)
|
|
|
|
- electron-updater는 캐시된 이전 설치자를 기준으로 `.blockmap`의 변경 블록만
|
|
HTTP Range로 내려받는다. 첫 업데이트는 항상 full이다.
|
|
- **full로 강제해야 하는 경우**: (a) 현재 버전을 신뢰할 수 없음/손상, (b) major
|
|
승격(스키마·ABI 변경), (c) minor 갭이 임계 이상, (d) 서버가 Range 미지원.
|
|
- 구현: `autoUpdater.disableDifferentialDownload`를 위 조건에서 켠다.
|
|
- **2026-11-20 현재 Windows 적용:** Electron 43 설치본이 Cloudflare의 100 MiB 업로드 한도를 넘어 `nsis.differentialPackage: false`와 최대 solid 압축을 사용한다. Windows는 `.blockmap` 차분 없이 항상 전체 설치본을 받도록 `fullInstallVersionGap: 0`을 게시하며, macOS 패키징은 유지한다. 상세한 게시 중단·복구 증거는 `docs/evidence/2026-11-17-backlog-operations.md`에 있다.
|
|
|
|
### 4.3 채널과 staged rollout
|
|
|
|
- 채널: `latest`(stable) / `beta` / `alpha`. 클라이언트 `updater.channel` +
|
|
`allowPrerelease`로 선택. 빌드 측은 `generateUpdatesFilesForAllChannels`로
|
|
채널별 메타데이터를 생성할 수 있다.
|
|
- staged rollout: `latest.yml`의 `stagingPercentage` + 클라이언트의 영구 사용자
|
|
해시. 회수는 **더 높은 버전**으로만 가능(같은 버전 재배포 불가).
|
|
|
|
### 4.4 릴리스 관리 방법론
|
|
|
|
- **SemVer**: breaking=MAJOR, 하위호환 기능=MINOR, 버그픽스=PATCH. 릴리스된 버전은
|
|
불변(immutable). 잘못된 릴리스는 새 PATCH로 forward-fix.
|
|
- **Conventional Commits** → `feat`=MINOR, `fix`=PATCH, `BREAKING CHANGE`/`!`=MAJOR.
|
|
자동화 도구는 release-please(릴리스 PR 게이트) / semantic-release(완전 자동) /
|
|
changesets(모노레포). 이 저장소는 SSOT+수동 승인 게이트를 이미 쓰므로
|
|
**release-please식 게이트를 유지**하고 커밋 컨벤션만 도입한다.
|
|
- **Trunk-based development**가 2026 기본. 릴리스 브랜치는 필요 시 JIT로 자르고
|
|
태그 후 제거. 이 저장소는 `main` + 태그 릴리스로 이미 TBD에 가깝다.
|
|
- **Git 태그**: annotated + 서명(`git tag -s`) + `v` 접두 semver. 보호 태그 규칙으로
|
|
삭제·강제 이동을 막는다. 릴리스 태그는 절대 이동하지 않는다.
|
|
- **CHANGELOG**: Keep a Changelog. `[Unreleased]`를 PR에서 유지하고 릴리스 시
|
|
날짜 섹션으로 이동. YANKED 표기.
|
|
|
|
### 4.5 CI/CD
|
|
|
|
- 코드 품질 CI는 모든 push에서, 릴리스/배포 CI는 **태그에서만**.
|
|
- 태그가 버전 SSOT·CHANGELOG·테스트·서명을 모두 통과해야 publish.
|
|
- 자산을 먼저 업로드하고 **메타데이터(latest.yml)를 마지막에** 게시해 배포 중
|
|
404를 막는다(현 publisher가 이미 구현).
|
|
- 공개 URL에서 재검증(fail-closed).
|
|
|
|
출처: semver.org, conventionalcommits.org, keepachangelog.com,
|
|
electron.build auto-update/code-signing/publish, forgejo.org packages/actions,
|
|
trunkbaseddevelopment.com, sre.google release-engineering, Doyensec SafeUpdater.
|
|
|
|
---
|
|
|
|
## 5. 목표 아키텍처
|
|
|
|
```text
|
|
┌───────────────────────────── release/update-policy.json (SSOT)
|
|
│
|
|
author commit → version:check → test → build (signed)
|
|
│
|
|
└→ tag vX.Y.Z (annotated, protected)
|
|
│
|
|
┌───────────────┼───────────────────────────┐
|
|
│ │ │
|
|
GitLab CI GitHub Actions Forgejo Actions
|
|
(primary) (mirror) (release hub + feed)
|
|
│ │ │
|
|
└───────────────┴──────────────┬────────────┘
|
|
▼
|
|
publish-forgejo-release.mjs (canonical)
|
|
publish-gitlab-release.mjs (legacy mirror)
|
|
│
|
|
┌────────────────────────┴────────────────────────┐
|
|
▼ ▼
|
|
Forgejo Generic Registry (canonical feed) GitLab Generic Registry (legacy)
|
|
.../generic/d3ro-voice/<version|latest>/ .../generic/d3ro-voice/<version|latest>/
|
|
│
|
|
▼
|
|
electron-updater → 채널(latest/beta/alpha) → 정책(mandatory/full-vs-delta)
|
|
```
|
|
|
|
- **Canonical runtime feed**: Forgejo
|
|
`https://git.chanpaca.net/api/packages/yunchan/generic/d3ro-voice/latest`.
|
|
- **Legacy mirror**: GitLab project 1172 `latest`. 기존 `0.2.1-alpha` 설치본이
|
|
GitLab을 계속 폴링하므로, 새 설치자가 Forgejo feed를 갖는 버전을 받을 때까지
|
|
유지한다. 마이그레이션 완료 후 제거 가능.
|
|
- **정책 SSOT**: `release/update-policy.json`. 빌드에 번들되는 기본값 + feed에서
|
|
원격 오버라이드(선택). 서버에서 정책을 내려 강제 업데이트·킬 스위치를 즉시
|
|
적용할 수 있다.
|
|
|
|
---
|
|
|
|
## 6. 결정 기록 (ADR 요약)
|
|
|
|
1. **ADR-UPD-01**: electron-updater를 유지한다. 빌드 프레임워크 교체는 비용 대비
|
|
이득이 없다.
|
|
2. **ADR-UPD-02**: Forgejo를 canonical 배포·feed 호스트로 한다. GitLab은 legacy
|
|
mirror로 남긴다.
|
|
3. **ADR-UPD-03**: 채널(latest/beta/alpha)과 최소 지원 버전·강제 업데이트·full
|
|
재설치를 `release/update-policy.json`으로 정본화한다.
|
|
4. **ADR-UPD-04**: 태그는 annotated `vX.Y.Z`이며 이동하지 않는다. 릴리스는
|
|
forward-fix만 허용한다.
|
|
5. **ADR-UPD-05**: Forgejo 배포 금지 조항을 제거하고, 버전 하드코딩 없는
|
|
`publish-forgejo-release.mjs`로 대체한다.
|
|
6. **ADR-UPD-06** (권고): 데스크톱 `typecheck`가 실제로 검사하도록
|
|
`tsc -b` 또는 `tsc -p tsconfig.node.json`로 교체하고 기존 오류를 별도
|
|
워크스트림에서 정리한다. 이 문서 범위에서는 릴리스 게이트가 착시에 의존하지
|
|
않도록 `verify-release-metadata.mjs`에 최소한의 경고를 남긴다.
|