企业官网建设流程全解析

FyAgent 是一款 AI 时代的个人随身数字人格工具，能把你的模型、AI 账号、技能与提示词带到每一个 AI 客户端里。这篇文章将完整拆解它的发布流水线：一次vX.Y.Z标签推送如何经过 macOS Developer ID 签名与公证、Windows 代码签名、构建证明（Attestation），最终变成一条不可篡改的正式 Release。

一、为什么桌面应用的发布流水线必须"多此一举"

浏览器里的一次部署失败可以回滚，但桌面应用不同：

• 用户直接执行你签发的二进制——安装程序被篡改的后果由用户承担；
• macOS 会主动拦截：没有 Developer ID 签名和 Apple 公证（Notarization）的应用，Gatekeeper 直接拒绝打开；
• Windows 用户依赖数字签名判断安装程序是否可信。

因此 FyAgent 的 Release 工作流设计目标只有八个字：来源可证明、资产不可抵赖。

整条流水线由 .github/workflows/release.yml 定义，官方流程文档见 docs/fyagent/development/ci-release/release.md。它在标签触发时启动，共 8 个 Job，全部通过严格的needs依赖串联，任何一环失败即整体失败（fail closed）。

二、第一步：冻结源码与发布资格校验（Eligibility）

流水线从eligibilityJob 开始，它做的是发布前的身份核验：

1. 校验请求信封：在 checkout 之前，先验证事件来源是否为官方仓库、工作流 SHA 是否合法，防止伪造的 dispatch 请求；
2. 绑定标签与提交：vX.Y.Z标签指向的 SHA 就是"冻结源码"，运行期间main分支如何移动都不影响本次构建；
3. 版本一致性：标签号必须与 Cargo 工作区版本号完全一致，漂移即失败；
4. 双模式设计：formal（正式，持有签名/公证密钥）与preflight（诊断，拿不到任何签名密钥，发布条件恒为假）。

这一步的输出——app_version、source_sha、workflow_sha——会像"血统证明"一样传递到后面所有 Job。

三、第二步：Windows 构建与四段式签名验证

Windows 侧覆盖x64 与 ARM64 两种架构，且强制要求同架构原生 Runner（windows-2025与 ARM 原生 Runner），并逐一核对 Node、pnpm、Rust 工具链版本，任何一个版本漂移都会直接中止。

签名链路拆成四个独立 Job，形成"构建者不能自证清白"的分离设计：

关键细节：

• 签名模式由 scripts/release/windows-signing.mjs 统一管理，signed/unsigned二选一；unsigned 模式下签名密钥配置必须完全不存在，防止半配置状态；
• 生成的 signing-status.json 使用固定 schema（fyagent-windows-signing-status/v1），发布说明中的 Windows 签名表格完全由它生成，凭证永远不进入文档；
• NSIS 安装脚本契约由 scripts/release/verify-windows-nsis-contract.mjs 在构建前后各验证一次，安装脚本模板位于 src-tauri/nsis/installer.nsi。

四、第三步：macOS Developer ID 签名与 Apple 公证

macOS 侧在macos-15上构建Universal（arm64 + x86_64）应用，流程由 scripts/release/macos-developer-id.sh 驱动：

1. 导入证书：Apple Root CA 与 Developer ID G2 CA 导入临时钥匙串（脚本内置 apple-root-ca.cer 与 apple-developer-id-g2-ca.cer）；
2. 签名 .app：codesign深度签名后，用 verify-macos-signed-app.sh 独立复核签名；
3. 公证应用：notarytool submit提交后轮询notarytool info直至 Apple 返回终态——而不是把notarytool wait的超时当作拒绝（最长可等待 9000 秒）；
4. Staple 票据：把公证票据钉在 app 和 DMG 上，离线环境也能通过校验；
5. 样式化 DMG：create-macos-dmg.sh 打包带背景图、Applications软链接和.DS_Store布局的安装镜像，用户打开即可"拖拽安装"：

6. 挂载复核：DMG 会被只读挂载，逐项验证版本号、Applications软链接目标、背景文件、主可执行文件 SHA-256 与签名前完全一致，最后由 verify-macos-signed-dmg.sh 做终极校验。

五、第四步：构建证明（Attestation）与一次性发布

签名只是"谁签的"，构建证明回答的是"在哪个环境、用哪份代码签的"：

• pin-release-build-inputs把所有签名前的构建输入打包成不可变 bundle；
• verify-assets下载最终安装程序与证据，生成 3 个安装程序 + 3 个机器可读证据文件共 6 个证明主体；
• attest调用 GitHub 官方actions/attest生成Sigstore 构建证明 bundle，与 3 个安装程序、3 个证据文件组装成恰好 7 个 Release 附件——多一个少一个都算失败；
• publishJob 最后做一次性发布事务：重新核验标签与 SHA、全量枚举已有 Release 防止重复、创建草稿 → 上传 →重新下载验证→ 才允许转正式发布。一旦发布，版本即不可变；若草稿残留，还会通过 verify-release-draft-ownership.mjs 证明"草稿归属"后才能恢复，杜绝误覆盖。

对下载用户来说，每个 Release 都附带 download-manifest.json（由 scripts/generate-download-manifest.mjs 生成），包含各平台资产的哈希与来源提交，可独立核验。

六、这套 CI/CD 实践的核心设计要点

1. 单一事实来源：标签目标 SHA = 冻结源码，所有 Job 只认这个 SHA；
2. 职责分离：构建、签名、验证各在不同 Job（甚至不同 Runner）完成，签名者无法自证；
3. 原生构建：三种架构全部在本机原生 Runner 上构建，杜绝交叉编译的架构漂移；
4. Fail Closed：任何"不确定"的状态（草稿归属不明、发布结果未知）都拒绝继续；
5. 契约测试护航：流水线本身也有测试，如 tests/releaseWorkflow.test.ts、tests/windowsNsisContract.test.ts、tests/releaseAssets.test.ts，脚本改了但契约没跟上会被 CI 直接拦下。

七、延伸阅读

• 发布流程官方说明：docs/fyagent/development/ci-release/release.md
• CI 持续集成流程说明：docs/fyagent/development/ci-release/ci.md
• 全部发布脚本目录：scripts/release/
• 版本与发布说明模板：docs/release-notes/README.md

这套"冻结源码 → 原生构建 → 分离签名 → 公证 → 构建证明 → 一次性发布"的流水线，为任何发布桌面端的开源项目提供了一个可直接借鉴的 CI/CD 完整实践范本。