自动更新工程：electron-updater、差分更新、灰度发布与失败回滚

自动更新工程：electron-updater、差分更新、灰度发布与失败回滚

桌面应用的更新机制是安全级别最高的基础设施：它是唯一会向全部用户分发可执行代码的通道。一次签名错误的发布可以让几十万安装实例崩溃，一次被劫持的更新等于全网 RCE。本文拆解自动更新的完整工程：更新源与元数据、代码签名与校验、差分包、灰度与强制更新策略、Windows/macOS 平台差异、以及更新失败的回滚协议。

一、更新模型：全量包 vs 应用内热更新

Electron 应用有两种更新粒度：

• 安装包级更新（Squirrel/electron-updater）：下载新版安装包/增量包，安装后重启应用。Electron 主进程二进制、原生模块变更只能走这条。
• 资源内热更新：渲染层 JS/CSS、模型文件、模板、预设资源（音色表、转场包）放在可独立下载的资源目录，不重启即可生效。

成熟产品两者并用：代码走安装包（慢、严、少发），资源走热更新通道（快、灵活、可灰度）。端侧模型文件尤其适合热更新------模型版本与应用版本解耦后，修一个检测模型不用发整个安装版（见端侧推理篇）。本文主要讲前者，后者的元数据/灰度/回滚机制是其子集。

二、更新清单（manifest）：更新决策的唯一依据

客户端不直接猜文件名，而是拉取一份带版本与校验信息的清单：

{
  "version": "4.3.0",
  "releaseDate": "2026-09-18T10:00:00Z",
  "minimumVersion": "4.0.0",
  "forceUpdate": false,
  "notes": "修复 H.265 代理生成在部分 AMD 机型上失败的问题",
  "platforms": {
    "win32-x64": {
      "full": { "url": "https://cdn.example.com/app/4.3.0/Setup-4.3.0.exe",
                "size": 118_400_000, "sha512": "......" },
      "delta": { "url": ".../4.2.1-to-4.3.0.delta", "from": "4.2.1",
                 "size": 24_100_000, "sha512": "......" }
    },
    "darwin-arm64": { "full": { "url": ".../App-4.3.0-arm64.dmg", "size": 142_000_000, "sha512": "......" } }
  },
  "rollout": { "channel": "stable", "percentage": 100, "minOsVersion": "10.0.19045" }
}

关键字段的工程语义：

• sha512：下载完成后必须先校验哈希再执行------CDN 缓存污染、代理篡改、半截下载都靠它拦截。electron-updater 默认对 latest.yml 内的哈希做这件事，自研通道必须自己实现，不能省。
• minimumVersion：低于此版本的客户端必须更新（旧版存在严重 bug 或后端协议不兼容时），客户端据此决定"静默稍后提示"还是"阻断使用"。
• minOsVersion：系统不满足时整个版本对该客户端不可见，避免装完才发现起不来。
• delta + from：差分更新的起点版本；没有匹配的差分包就回退全量包（见第四节）。

清单本身必须通过 HTTPS 获取，且客户端可对清单做签名校验（公钥内置在应用内）。HTTPS 防传输篡改，签名防源站/CDN 账号被盗------只信 HTTPS 在供应链攻击面前不够。

三、签名与平台机制

Windows

electron-updater（NSIS 安装包）流程：下载 → 校验哈希 → 运行安装包（安装包本身有 Authenticode 签名）→ 安装到用户目录 → 重启。要点：

1. 安装包必须用 EV 或 OV 代码签名证书签名，否则 SmartScreen 拦截率极高，更新体验变成"红色警告弹窗"。
2. 证书要提前买好并走时间戳服务（RFC 3161 timestamp）------证书过期后旧签名仍然有效，否则老版本无法续签。
3. 差分包（.delta）同样要签名/校验。

macOS

公证（notarization）是强制环节：构建后把包提交 Apple 公证服务， stapler 把公证票据钉进包内。未公证的应用在用户机器上被 Gatekeeper 直接拒绝，自动更新后第一次启动就报"已损坏/无法验证开发者"。更新流程中 dmg/zip 下载校验后，安装到 /Applications，同样需要签名链完整 + 公证票据，不能因为"是应用自己装的"而跳过。

Linux

AppImage 方案与 Windows 类似（下载替换 + 哈希）；deb/rpm 走系统包管理器更合用户习惯，但自动更新体验割裂，桌面产品多数选 AppImage 自持。

四、差分更新：省的是用户的带宽和等待

从 4.2.1（118MB）到 4.3.0，实际只改了几个 asar 内文件。差分方案：

打包时：对每个历史版本 N 与新版本生成差分包（bsdiff 或 blockmap 级块差分）
更新时：
  1. 客户端读本地版本 → 查清单有无对应 from 字段的 delta
  2. 有：下载 delta（典型 10~30% 全量大小），本地合并出完整新包
  3. 合并产物重新算 sha512，必须等于全量包的声明哈希 ← 关键校验点
  4. 无 delta（跨版本太多/差分无收益）：直接全量

electron-updater 的 blockmap 机制更细：它按内容块（block）做差分，本地文件未改的块直接复用，只下载变化块------即使从 4.2.1 升级，也只取真实变更块。工程取舍：

• 只保留最近 2~3 个版本的差分包：再老的版本直接全量（差分包本身要占 CDN 存储，且跨多版本差分的收益被稀释）。
• 合并后哈希等于全量包是差分正确性的唯一证明，不等则丢弃合并结果走全量------永远不安装"不知道是什么"的合并产物。
• 合并需要磁盘上同时有旧包与足够临时空间；空间不足（< 全量包 1.5 倍）直接全量下载，别做一半失败。

五、发布节奏：通道与灰度

一套通道模型把"内部测试→小流量→全量"工程化：

internal（内部 dogfood，100 人）
  → beta（公开测试通道，1~5% 用户，手动加入）
    → stable-canary（灰度 5% → 20% → 50%）
      → stable（100%）

客户端根据用户设置（beta 开关）+ 稳定的用户分桶（如 hash(userId) % 100 < percentage，同一用户在同一版本的灰度过程中不反复横跳）决定能看到哪个版本。灰度的核心价值是崩溃率信号：

发布后监控：
  - 启动崩溃率（更新后第一次启动即崩 = 阻断性事故）
  - 关键操作错误率（导出失败率、打开工程失败率）
  指标超阈值（如崩溃率 > 0.5%）→ 暂停灰度（percentage 冻结/回 0）

清单是静态 JSON，暂停灰度 = 改服务端清单，客户端无需任何动作。这就是为什么更新决策必须服务端驱动而不是把"最新版本"写死在客户端。

回滚的关键细节：应用内不支持自动降级（数据库/工程文件可能已被新版迁移，见工程迁移篇------v3 的文件 v2 读不了）。线上回滚的正确动作是：

1. 立即下线新版清单（未更新的用户停在旧版）。
2. 灰度中已更新的用户：发布一个版本号更高的修复版（4.3.1），而不是把清单指回 4.2.1。
3. 数据迁移不可逆是常态，"前进式修复"永远比"降级"安全。

六、更新时机：别打断正在剪片子的人

更新交互是产品体验的一部分，协议再正确也不能在错误的时刻弹：

1. 后台静默下载：启动后、空闲时下载，绝不在导出/录制/AI 任务进行中触发。
2. 安装时机：下载完成只提示"已准备好，重启生效"，由用户选"立即重启/下次启动时安装"；有未保存变更时禁用立即重启，先走保存/草稿恢复流程。
3. 强制更新例外 ：minimumVersion 类阻断性更新也要先让用户完成当前工作（给宽限倒计时 + 自动保存），而不是强杀进程。
4. 更新中防重启：安装阶段对用户可见进度（24MB / 118MB），防止用户以为卡死强退导致安装中断。
5. 企业/离线环境：提供"检查更新"手动入口与离线包导入路径，部分用户在内网无法访问 CDN。

七、更新器自身的健壮性

更新器是"修 bug 的代码"，但它自己也会有 bug，且它的 bug 让后续所有修复无法送达------它必须是整个代码库里防御最厚的模块：

风险	防御
下载中断	断点续传（HTTP Range）/ 临时文件 + 完成后 rename
磁盘满	下载前检查空间（全量包 ×2 预留）；失败保留旧版不动
哈希不符	拒绝安装，删除损坏包，下次重试
JSON 清单异常	旧清单兜底（TTL 内）；解析失败当作"无更新"，不报错轰炸
更新器版本太老	清单格式保留版本字段，旧客户端读不懂的新字段忽略（前向兼容设计）
时间/系统代理	不依赖系统时间做强制更新裁决（服务端时间为准）
安装失败	Windows 安装器失败自动回滚到旧目录；macOS 保留旧 .app 副本直到首次成功启动

首次启动确认是最后一道保险：新版安装后第一次成功启动并完成健康检查（窗口正常创建、工程可加载）才清除"待确认"标记；连续 N 次启动失败，安装器/启动器回退到旧版并上报。没有这个机制，一个"装完即崩"的版本会让用户永久打不开应用。

八、热更新资源的轻量协议

模型/模板/预设等资源走简化版同一套机制：

{ "resources": [
  { "id": "face-detector", "version": 3, "url": "...", "sha256": "...",
    "minAppVersion": "4.1.0", "size": 4_200_000, "rollout": 100 }
] }

客户端比对本地 resourceVersion 清单 → 后台下载到缓存目录 → 校验 sha256 → 原子 rename → 切换激活版本（保留上一版，异常即回退）。资源回退比代码回退安全得多（无数据迁移问题），这也是把模型独立出包的另一个红利：模型可以自由回滚。

九、小结

环节	要点
清单	版本/哈希/最低版本/灰度比例，服务端驱动；清单签名
签名	Windows Authenticode + 时间戳；macOS 签名 + 公证
差分	blockmap 最近 2~3 版；合并产物哈希必须等于全量包
灰度	internal→beta→canary→stable；分桶稳定；崩溃率熔断
回滚	只前进式修复，不自动降级（数据单向迁移）
时机	空闲下载、用户决定安装、强制更新也先保工作
自健壮	续传、空间检查、旧清单兜底、首次启动确认
热更新	模型资源独立版本，校验后原子切换，可自由回退

自动更新的设计哲学是把"发布"从一个动作变成一个带观测与熔断的过程：每一次发布都可以被 5% 的流量验证、被崩溃率叫停、被下一个版本修复。更新通道握着通往全部用户的钥匙，因此它的每一个环节------清单、签名、差分、灰度、回滚------都按"最坏情况一定发生"来设计，是工程严谨度的试金石。