Mac 渠道接入更新包签名、OSS 上传与渠道清单

问题：mac 侧此前只有 archive-only 构建，dev-mac 渠道不产出更新包、不上传、无渠道清单，客户端拿不到 macOS 更新（里程碑曾因签名/公证凭据未就绪而暂缓）。改动： - build-macos-ci.mjs 改为 dev-mac 发布入口：开启 createUpdaterArtifacts 产出 .app.tar.gz + .sig，生成 universal DMG 与渠道清单 latest.json，构建后用产物内烘焙的公钥复核签名，再按 AGC_RELEASE_DRY_RUN 决定是否上传 OSS - 新增 verify-updater-signature.mjs（minisign ED 预哈希校验）+ 单测：验签失败或 keyId 不一致立即失败关闭，绝不写 OSS - Jenkinsfile：新增 AGC_RELEASE_VERSION / AGC_RELEASE_DRY_RUN（默认开启）/ AGC_UPDATE_RELEASE_NOTES / OSSUTIL_BIN 参数；withCredentials 注入 AgcUpdaterSigningKey(+密码) 与 AliyunAccessKeyId/Secret；归档补 latest.json、 .sig 与更新摘要 - 既有单测口径更新：archive-only → 发布型，并新增「必须先验签再上传」守卫 - 文档：技术方案、里程碑、运维文档同步；Apple 签发与公证暂缺显式记录为未验证项（--no-sign、appleSigned=false、notarized=false）验证：单测 11/11 + 42/42；Jenkinsfile 四个 sh 块语法通过；伪造 bundle 端到端验证清单（两平台同 URL/同签名、universal 首装包被正确选中）、真实 Tauri 签名验签通过、错钥匙报 keyId 不一致、篡改报校验失败、dry-run 上传计划顺序正确。
2026-09-19 17:49:25 +08:00
parent 261228ed3f
commit b1cadd0cc8
8 changed files with 589 additions and 58 deletions
@@ -3,7 +3,7 @@
 | 字段        | 值                                                                 |
 | ----------- | ------------------------------------------------------------------ |
 | Version     | 1.0                                                                |
-| Status      | deferred                                                           |
+| Status      | in-progress                                                           |
 | Date        | 2026-09-17                                                         |
 | Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |

@@ -30,7 +30,9 @@
 - macOS 签名证书与公证凭据可用；若不满足，本里程碑只能交付构建与清单能力，并明确标注未验证项。
 - macOS 通用包所需的双架构工具链（两个 darwin 目标）在构建机上可用。

-本里程碑暂缓执行：macOS 构建机与签名 / 公证凭据尚未就绪，改由后续独立变更承接；暂缓期间 dev-mac 渠道不发布。
+构建与发布能力已落地：专用 macOS Jenkins 节点（label `genarrative-agc-macos`）+ `Jenkinsfile.ai-game-creator-shell-macos-build` + `scripts/build-macos-ci.mjs` 负责 universal 构建、双架构隔离 smoke、universal DMG、渠道清单 `latest.json`、更新包验签门禁与 OSS 上传（`AGC_RELEASE_DRY_RUN` 默认开启）。
+
+仍未就绪：Apple 代码签名与公证凭据（产物保持未签名 + 未公证，构建清单显式记录 `appleSigned=false` / `notarized=false`，首装需手动放行 Gatekeeper）；「安装 → 重启接管新版本」的实机更新闭环、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）尚未验收。

 ## 验收标准

@@ -161,8 +161,11 @@
 - macOS 采用 universal 包，两个平台键对应同一更新产物；主程序用 lipo 检查两种架构，Codex 资源分别做原生身份/摘要与启动验证。Rosetta 结果不代替 Intel 真机验收。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
- macOS 发布方式：`dev-mac` 产物在本机 mac 上执行发布入口上传，Jenkins 暂不新增 macOS 节点；macOS 代码签名与公证凭据未确认前，相关闭环记为未验证项，不静默通过。
+- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、渠道清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为开，只有显式关闭才会写入 OSS。
+- macOS 代码签名与公证暂缺：产物为未签名 + 未公证，`--no-sign` 保留，构建清单与 `latest.json` 显式记录 `appleSigned=false` / `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
+- 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。

 待办：

- macOS `dev-mac` 渠道落地（macOS 构建机、签名与公证、安装后重启验证、是否接入 Jenkins macOS 节点）暂缓，由后续独立变更单独完成；在此之前 `dev-mac` 渠道只有构建与清单能力，不发布。
+- macOS `dev-mac` 渠道已落地构建与发布能力：Mac Jenkins 节点、release 入口（更新包 + 签名 + 首装包 + 渠道清单）、验签门禁与 dry-run 默认开启均已就绪。
+- 剩余待办：Apple 代码签名与公证凭据（未就绪期间以未验证项记录）、macOS 安装后重启接管新版本的实机验证、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）。
@@ -724,7 +724,11 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.

 Mac universal 构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发且不设置 trigger；不接入现有每小时版本调度，不改 Windows 发布职责。它使用独立 Jenkins workspace，禁止指向开发 checkout 或共享其可写 target/node_modules。

-该 Job 的目标仅为构建并归档：保留源码版本、不读取远端版本、不注入发布私钥/OSS 凭据、不运行 release upload。执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 universal app 与 DMG、分别运行 arm64/x86_64 隔离 smoke。归档限 `artifacts/` 下的 DMG、SHA-256、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+该 Job 的职责是构建并发布 `dev-mac` 渠道更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 universal app、arm64/x86_64 隔离 smoke、universal DMG 与渠道清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+
+发布凭据全部走 Jenkins 全局凭据，并在 `withCredentials` 内注入当前进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；私钥与凭据不写入 workspace、日志或归档产物。上传顺序为更新包、签名、首装包，三者全部成功后才覆盖 `agc/dev-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 默认开启，dry-run 只打印将上传的对象、不写任何 OSS 对象。Mac 节点需要 `ossutil`（实测 1.7.19 原生 arm64 可用，装在 `~/.local/bin`，已在 Job 的 PATH 内），可用 `OSSUTIL_BIN` 指定命令名或绝对路径。首次发布建议显式指定 `AGC_RELEASE_VERSION`，避免按渠道高水位递增时出现版本链回退。
+
+产物边界：macOS 代码签名与公证暂缺，构建保持 `--no-sign`，构建清单显式记录 `appleSigned=false` / `notarized=false`。用户首次安装需要在 Gatekeeper 中手动放行；更新包校验本身只依赖 minisign 签名，因此未签名不阻断自动更新的校验环节，但「安装 → 重启接管新版本」的实机闭环仍未验证，不得以构建成功替代。

 该 Job 的 Rust 编译走 sccache 对象缓存，与 `Genarrative-Api-Build`、`Genarrative-Stdb-Module-Build` 一致：`RUSTC_WRAPPER=sccache`、`CARGO_INCREMENTAL=0`、`SCCACHE_CACHE_SIZE=20G`。`SCCACHE_DIR` 默认落在稳定缓存根 `~/caches/genarrative-jenkins/agc-macos/sccache`，可用 `GENARRATIVE_AGC_MACOS_CACHE_ROOT` 覆盖；缓存根固定在 HOME 下而不是 `WORKSPACE` 内，避免 workspace 重建后无改动也触发近似冷构建。节点未安装 sccache 时管线打印提示并回退到真实 `rustc`，不阻断构建。universal 双架构各自独立编译，依赖 crate 的复用收益约为单架构的两倍；命中情况由构建末尾的 `sccache --show-stats` 输出，供判断是否需要预热或调整缓存上限。