完善桌面端发布稳定化门禁

2026-07-02 09:41:55 +08:00
parent f33cc0948e
commit 965c38d3b2
11 changed files with 554 additions and 9 deletions
@@ -28,10 +28,12 @@ npm run desktop:build:app

 - [ ] `frontend/package.json`、`package-lock.json`、Tauri 配置、Cargo manifest/lock 版本一致。
 - [ ] `VITE_BUILD_CHANNEL=release` 和 `VITE_BUILD_COMMIT=<release tag commit>` 由 CI 注入，且 `npm run release:env:check` 通过。
+- [ ] 在正式 release tag 和签名环境中执行 `npm run desktop:release-readiness:check`，确认 tag、构建元数据、签名/公证变量、updater 私钥和生产 artifact HTTPS 基址齐备。
 - [ ] macOS app 已签名和公证。
 - [ ] updater `.sig` 使用组织 CI secret 或密钥库中的私钥生成，私钥未进入仓库。
- [ ] 设置 `TAURI_SIGNING_PRIVATE_KEY`、`TAURI_SIGNING_PRIVATE_KEY_PASSWORD` 和 Apple 签名/公证变量后，以 `REQUIRE_DESKTOP_SIGNING=true` 再次执行 `npm run release:env:check`，随后执行 `npm run desktop:build -- --bundles app`。
- [ ] 正式 updater feed 执行 `npm run desktop:update-feed:check -- --feed <latest.json> --artifacts-dir <artifact-dir>`。
+- [ ] 设置 `TAURI_SIGNING_PRIVATE_KEY`、`TAURI_SIGNING_PRIVATE_KEY_PASSWORD` 和 Apple 签名/公证变量后，以 `REQUIRE_DESKTOP_SIGNING=true` 再次执行 `npm run release:env:check`，随后执行 `npm run desktop:build:macos-release -- --ci`。
+- [ ] 正式 updater feed 先执行 `npm run desktop:update-feed:create -- --artifact <CTMS.app.tar.gz> --base-url <versioned-https-artifact-prefix> --output-dir <release-dir>` 生成 `latest.json` 与 `SHA256SUMS.txt`。
+- [ ] 正式 updater feed 执行 `npm run desktop:update-feed:check -- --feed <release-dir>/latest.json --artifacts-dir <release-dir>`，并确认 checksum manifest、updater artifact、`.sig` 和 `latest.json` 均通过校验。
 - [ ] 不可变制品先上传，`latest.json` 最后原子替换；若 feed 校验未通过，不替换线上 `latest.json`。
 - [ ] Web 与 Desktop 制品记录同一产品版本、Git 标签和完整提交 SHA。

@@ -50,6 +52,7 @@ npm run desktop:build:app
 - [ ] `ctms_token` 只允许由 `secureSessionStorage` 处理。
 - [ ] 系统通知只能通过 `frontend/src/runtime/notifications.ts` 发送，标题和正文保持通用。
 - [ ] CI release 候选 workflow 包含 version/runtime/desktop/ui/type/unit/build/desktop app smoke 门禁。
+- [ ] signed macOS release candidate workflow 只允许从 `vX.Y.Z` tag 运行，并包含签名环境检查、Universal macOS 构建、update feed 生成、checksum 校验和 verified release directory 上传。

 人工复审还必须确认：

@@ -127,3 +130,20 @@ npm run desktop:build:app
 - 签名后的 updater artifacts、`.sig`、checksum manifest 和 `latest.json` 在真实发布目录内通过 `npm run desktop:update-feed:check`。
 - 不可变制品上传完成后，再原子替换线上 `latest.json`。
 - Desktop 端到端人工回归矩阵、最小窗口体验验收和系统通知/自动更新真实环境验证。
+
+## 7. 2026-07-02 发布稳定化推进记录
+
+本次推进补齐了发布链路自动化，不改变桌面端产品边界：
+
+- 新增 `npm run desktop:build:macos-release`，封装 Universal macOS `app`/`dmg` release candidate 构建命令。
+- 新增 `npm run desktop:update-feed:create`，从签名 updater artifact 和 `.sig` 生成 `latest.json`、复制发布目录文件并生成 `SHA256SUMS.txt`。
+- `npm run desktop:update-feed:check` 在传入 `--artifacts-dir` 时要求并校验 `SHA256SUMS.txt`。
+- 新增 `npm run desktop:release-readiness:check`，在正式签名候选构建前检查 release tag、构建元数据、签名/公证变量、updater 私钥和生产 artifact HTTPS 基址。
+- 新增 `.github/workflows/desktop-release-candidate.yml`，在 release tag 上执行签名候选构建、feed 生成、feed 校验并上传 verified release directory。
+- `npm run desktop:release:check` 已检查上述脚本和 workflow，避免发布链路回退。
+
+仍未自动完成、正式发布前必须人工确认：
+
+- Apple Developer 凭据、证书、签名身份、公证结果和组织 updater 私钥。
+- 生产下载源的不可变制品上传和线上 `latest.json` 原子替换。
+- 真实环境下的自动更新安装、系统通知、单实例和完整人工回归。
@@ -110,6 +110,28 @@
 5. CI 与发布流程：Web 与 Desktop 必须从同一提交、同一语义化版本号和同一正式标签构建；发布候选应执行本文档列出的相关质量门禁。
 6. Windows 兼容验证：仅作为第二阶段兼容性目标，验证 Credential Manager、路径处理、通知/updater 编译、WebView2 和安装器假设；未获明确批准前不发布正式 Windows 安装包。

+## 2026-07-02 发布稳定化推进记录
+
+本次推进仍保持第一、二阶段边界，不引入离线、本地业务存储、内嵌后端或独立桌面业务 UI。
+
+已补齐的发布稳定化自动化：
+
+- 新增 `npm run desktop:build:macos-release`，用于 macOS Universal `app`/`dmg` 正式候选构建。
+- 新增 `npm run desktop:update-feed:create`，从签名 updater artifact 和 `.sig` 生成 `latest.json` 与 `SHA256SUMS.txt`，并要求 artifact URL 使用包含当前版本号的 HTTPS 不可变路径。
+- `npm run desktop:update-feed:check` 在传入 `--artifacts-dir` 时同步校验 `SHA256SUMS.txt`、updater artifact、`.sig` 和 `latest.json`。
+- 新增 `npm run desktop:release-readiness:check`，用于在进入正式签名候选构建前确认当前提交精确匹配 `vX.Y.Z` tag、构建元数据、签名/公证变量、updater 私钥和生产 artifact HTTPS 基址已经齐备。
+- 新增 `.github/workflows/desktop-release-candidate.yml`，在 release tag 上执行签名 macOS 候选构建、feed 生成、feed 校验和 GitHub artifact 上传；它不替代人工发布审批和生产下载源原子替换。
+- `npm run desktop:release:check` 已纳入上述发布候选工作流和脚本存在性检查，防止发布链路门禁被误删。
+
+仍需正式发布负责人在真实发布环境完成：
+
+- Apple Developer 签名、公证凭据和组织 updater 私钥配置。
+- 从正式 `vX.Y.Z` tag 运行 signed macOS release candidate workflow。
+- 将已校验的不可变制品上传到生产下载源，最后原子替换线上 `latest.json`。
+- 执行桌面端人工端到端回归、最小窗口体验验收和真实系统通知/自动更新验证。
+
+进入端到端人工回归前，应先确认 `npm run desktop:release-readiness:check` 在正式 release tag 和签名环境中通过；否则只能进行普通 smoke 验证，不能判定 macOS 发布稳定化已经完成。
+
 如果后续任务试图新增离线登录、本地业务数据存储、内嵌后端、本地业务队列、离线同步或绕过后端权限审计，应先修改并评审本计划书，不能直接实现。

 ## 当前质量门禁
@@ -106,8 +106,8 @@ npm run desktop:build:app
 npm run desktop:build:app
 ```

-正式桌面发布构建仍必须设置 updater 签名私钥后执行
-`npm run desktop:build -- --bundles app`。
+正式桌面发布构建仍必须设置 updater 签名私钥和 Apple 签名/公证变量后，先执行
+`npm run desktop:release-readiness:check`，再执行 `npm run desktop:build:macos-release -- --ci`。

 后端改动应补充执行受影响模块的后端测试、迁移检查和接口回归。

@@ -122,8 +122,8 @@ The release pipeline must:
 2. build macOS Universal desktop artifacts;
 3. sign and notarize the macOS app;
 4. produce updater artifacts and `.sig` files with the updater private key;
-5. generate `latest.json` and a checksum manifest;
-6. verify the feed with `npm run desktop:update-feed:check -- --feed <latest.json> --artifacts-dir <artifact-dir>`;
+5. generate `latest.json` and a checksum manifest with `npm run desktop:update-feed:create`;
+6. verify the feed with `npm run desktop:update-feed:check -- --feed <release-dir>/latest.json --artifacts-dir <release-dir>`;
 7. upload immutable artifacts first;
 8. atomically replace `latest.json` last.

@@ -131,6 +131,13 @@ For Universal macOS artifacts, `latest.json` must provide both
 `darwin-aarch64` and `darwin-x86_64` entries pointing at the same Universal
 update package.

+The signed release candidate workflow lives at
+`.github/workflows/desktop-release-candidate.yml`. It must be run from a
+matching `vX.Y.Z` tag and produces a verified release directory as a GitHub
+artifact. That artifact is still only a release candidate; the release owner
+must upload immutable files to the production download origin and replace
+`latest.json` atomically after validation.
+
 ## Windows Build Readiness

 Second-phase Windows work is limited to CI compatibility validation. A
@@ -167,8 +174,10 @@ export TAURI_SIGNING_PRIVATE_KEY="$UPDATER_PRIVATE_KEY"
 export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="$UPDATER_PRIVATE_KEY_PASSWORD"
 export REQUIRE_DESKTOP_SIGNING=true
 npm run release:env:check
-npm run desktop:build -- --bundles app
-npm run desktop:update-feed:check -- --feed src-tauri/target/release/bundle/latest.json --artifacts-dir src-tauri/target/release/bundle
+npm run desktop:release-readiness:check
+npm run desktop:build:macos-release -- --ci
+npm run desktop:update-feed:create -- --artifact <CTMS.app.tar.gz> --base-url <versioned-https-artifact-prefix> --output-dir <release-dir>
+npm run desktop:update-feed:check -- --feed <release-dir>/latest.json --artifacts-dir <release-dir>
 ```

 The Desktop build must run on macOS for the current first-phase target. A signed