Codex App Manager macOS 增量更新引擎详解:Sparkle delta + EdDSA 验签 + 原子回滚原理全解

原创2026-11-05 03:29:431,918 阅读

Codex App Manager macOS 增量更新引擎详解:Sparkle delta + EdDSA 验签 + 原子回滚原理全解

📦 Codex App Manager(CAM) 是一款面向官方 Codex 桌面应用的跨平台安装、更新与卸载管理器。它的 macOS 增量更新引擎基于 Sparkle delta 补丁,配合 EdDSA(Ed25519)签名验证与同卷原子回滚机制,能把约 406 MB 的全量更新压缩到 18–40 MB 的小包,且任何一步失败都会安全回退,保证"更新永不弄坏你的应用"。🚀

Codex App Manager macOS 增量更新界面

上图:更新主界面会直接显示"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)。

Codex App Manager macOS 增量更新深色模式

深色模式下同样清晰展示增量更新体积与当前版本,方便用户一键 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 补丁):

  1. 构建时运行 scripts/vendor-binary-delta.sh,按固定 SHA-256 校验后装入 src-tauri/resources/
  2. 更新时调用 BinaryDelta apply 旧版本 输出目录 补丁文件,在同卷暂存目录重建全新 bundle
  3. 这一步完全不碰安装目录,属于"非破坏性"操作 🧪

注意 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)是整个引擎里唯一"破坏性"的环节,设计得非常保守:

  1. 优雅退出 Codex:通过 AppleScript 请求 quit 并轮询等待,绝不强杀——正在运行的 agent 任务要允许完成;
  2. 同卷校验:暂存目录必须与安装目录同一磁盘卷(跨卷 rename 不是原子的),预检不通过直接拒绝;
  3. 两步 rename 交换:旧 bundle → backup-Codex.app,新 bundle → 安装路径。每一步边界都会写入事务日志(SwapObserver),即使中途断电也有恢复路径;
  4. 重启并健康检查:新版本的备份一直保留,直到确认新版本启动正常;若健康检查失败,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 增量更新引擎的完整闭环。🎯

登录后查看全文
Codex-App-Manager