Codex App Manager macOS 增量更新引擎详解:Sparkle delta + EdDSA 验签 + 原子回滚原理全解
Codex App Manager macOS 增量更新引擎详解:Sparkle delta + EdDSA 验签 + 原子回滚原理全解
📦 Codex App Manager(CAM) 是一款面向官方 Codex 桌面应用的跨平台安装、更新与卸载管理器。它的 macOS 增量更新引擎基于 Sparkle delta 补丁,配合 EdDSA(Ed25519)签名验证与同卷原子回滚机制,能把约 406 MB 的全量更新压缩到 18–40 MB 的小包,且任何一步失败都会安全回退,保证"更新永不弄坏你的应用"。🚀
上图:更新主界面会直接显示"Update size ~19.6 MB",这正是 Sparkle delta 增量补丁带来的体积优势。
一、先看效果:406 MB 变 19.6 MB 是怎么回事
普通的全量更新相当于把整个 Codex.app(约 406 MB)重新下载一遍;而增量更新只下载"新旧版本之间的差异"。CAM 的引擎在真实数据上验证过:一个 18 MB 的 Codex3575-3511-arm64.delta 补丁,加在 3511 版基础上,能重建出与官方 404 MB 完整包逐字节一致的新版本(详见 apply.rs 文件头注释)。
对国内用户来说,收益不仅是流量:镜像站 codex-app-mirror 会原样转发 OpenAI 的 delta 附件,签名与官方完全一致,下载更快更稳。⬇️
二、解析 Sparkle appcast:增量更新的"目录"
整个流程的第一步是解析 Sparkle 的 appcast(RSS 格式的更新源),实现在 appcast.rs。它的结构很直观:
- 每个
<item>代表一个版本,sparkle:version是单调递增的构建号(如3575) <enclosure>是全量包(.zip)<sparkle:deltas>里是一组增量补丁,每个补丁带sparkle:deltaFrom("从哪个构建号升上来")和sparkle:edSignature(EdDSA 签名)
仓库里的测试夹具 appcast.xml 就是一个完整示例。解析时按元素本地名匹配、忽略 XML 命名空间前缀,所以对上游格式的小改动非常健壮。
三、选择最优策略:delta 还是 full?
拿到 appcast 后,plan.rs 会生成一份"更新计划"(UpdatePlan):
| 情况 | 策略 | 下载量 |
|---|---|---|
| 已装构建号 ≥ 最新版本 | 无需更新 | 0 |
| 已装版本恰好是某个 delta 的起点 | ✅ 用 delta | 约 18–40 MB |
| 没有覆盖当前版本的 delta | 回退全量包 | 约 406 MB |
计划里还会算出 savings_pct(节省百分比),直接展示给 UI。下载由 download.rs 完成,支持断点续传、暂停/取消,并设置了 512 MB(delta)/ 2 GB(全量包)的大小上限保护(limits.rs)。
深色模式下同样清晰展示增量更新体积与当前版本,方便用户一键 Update now。
四、EdDSA 验签:更新安全的第一道锁 🛡️
增量包只有几十 MB,一旦被人篡改,后果比全量包更隐蔽。CAM 在 verify.rs 中内置了 OpenAI 的 Sparkle Ed25519 公钥(从官方 Codex.app 的 SUPublicEDKey 中提取并硬编码固定),用 ed25519_dalek 执行严格验签(verify_strict)。
原理一句话:签名是 base64 编码的 64 字节 EdDSA 签名,公钥固定在客户端,镜像/CDN 就算被攻破,也造不出能通过验签的更新包。 这就是"国内镜像"与"官方签名"能共存的关键——镜像只改 URL,不改字节、不重签名(见 docs/macos-delta-updates.md)。
五、BinaryDelta 工具:把补丁"长"成新应用
验签通过后,进入重建环节。CAM 内置了 Sparkle 官方开源的 BinaryDelta 工具(版本锁定 2.9.1,与 Codex.app 内置的 Sparkle 完全对齐,可读取 Patch format 4.2/LZMA 补丁):
- 构建时运行 scripts/vendor-binary-delta.sh,按固定 SHA-256 校验后装入
src-tauri/resources/ - 更新时调用
BinaryDelta apply 旧版本 输出目录 补丁文件,在同卷暂存目录重建全新 bundle - 这一步完全不碰安装目录,属于"非破坏性"操作 🧪
注意 apply.rs 的契约:调用方必须在 apply 之前完成 EdDSA 验签、apply 之后完成代码签名门禁——两道关卡夹着唯一的重建步骤。
六、codesign + Gatekeeper:重建后的双重安检
delta 重建出来的 bundle 不是"信它",而是"审它"。codesign.rs 里的 gate_reconstructed 依次执行四道检查:
| 门禁 | 命令/手段 | 作用 |
|---|---|---|
| ① 签名完整性 | codesign --verify --deep --strict |
任何一个字节被改过都会失败 |
| ② 产品身份 | 读取 CFBundleIdentifier |
防止 ChatGPT Classic 混入 |
| ③ 团队 ID | TeamIdentifier == 2DC432GLL2 |
必须是 OpenAI 官方签名 |
| ④ Gatekeeper | spctl --assess --type execute |
确认已公证(notarized) |
这是"最强信任锚点":即使镜像整体失守,攻击者也无法伪造 OpenAI 的 Apple Developer ID 签名。🔐
七、原子交换与一键回滚:更新失败也能秒退 🔁
最后一步(swap.rs)是整个引擎里唯一"破坏性"的环节,设计得非常保守:
- 优雅退出 Codex:通过 AppleScript 请求 quit 并轮询等待,绝不强杀——正在运行的 agent 任务要允许完成;
- 同卷校验:暂存目录必须与安装目录同一磁盘卷(跨卷
rename不是原子的),预检不通过直接拒绝; - 两步 rename 交换:旧 bundle →
backup-Codex.app,新 bundle → 安装路径。每一步边界都会写入事务日志(SwapObserver),即使中途断电也有恢复路径; - 重启并健康检查:新版本的备份一直保留,直到确认新版本启动正常;若健康检查失败,
rollback()一条命令把旧版本"放回去",用户几乎无感。💪
就像云海之上平稳的航线:delta 验签、签名门禁、原子交换层层兜底,更新过程始终可控。
八、兜底哲学:delta 失败,更新永不失败 ✅
整套设计有一条铁律:delta 失败绝不阻塞更新。在 mac_update.rs 中,以下任何一种情况都会自动回退到同一个 appcast item 里的全量包:
- 本地
BinaryDelta工具缺失 - 已装 bundle 被用户改过(basis 不匹配)
- 补丁版本与工具不兼容(version skew)
- apply 过程任何报错
UI 上会如实标注"full (delta 应用失败回退)"。对新手用户而言,这意味着你只需要点"Update now",剩下的交给引擎。🌊
更新体验应当如湖面般平静:无需关心 delta、签名与回滚细节,一切自动完成。
九、相关源码与文档导航 📚
| 模块 | 路径 |
|---|---|
| appcast 解析 | crates/codex-mac-engine/src/appcast.rs |
| 更新策略规划 | crates/codex-mac-engine/src/plan.rs |
| EdDSA 验签 | crates/codex-mac-engine/src/verify.rs |
| delta 重建 | crates/codex-mac-engine/src/apply.rs |
| 签名门禁 | crates/codex-mac-engine/src/codesign.rs |
| 原子交换/回滚 | crates/codex-mac-engine/src/swap.rs |
| macOS 增量更新总览 | docs/macos-delta-updates.md |
| Tauri 侧更新编排 | src-tauri/src/app/mac_update.rs |
| 引擎集成测试 | crates/codex-mac-engine/tests/ |
总结:Sparkle delta 解决"快",EdDSA 验签 + codesign 门禁解决"真",同卷原子交换 + 备份回滚解决"稳"。三者叠加,构成了 Codex App Manager macOS 增量更新引擎的完整闭环。🎯



