高风险发布的灰度发布与回滚设计

一个团队的工程成熟度，最能看出来的时刻不是 code review，而是他们怎么描述凌晨三点出事之后的应对流程。大多数上线计划死在"我们会密切监控"这句话上——这话从来没救过谁。下面是我用来编写上线与回滚计划的思路，目标是在你人累得不行、pager 还在响的时候，这份计划依然能用。

发布于 2026-03-01 · ✓ 已更新 2026-05-11 · 阅读约 6 分钟 · 作者：Spec Coding 编辑团队 · 审校：编辑政策

什么才算真正的"高风险"

一次发布只要碰到四件事之一，就属于高风险：钱、身份、落盘数据、用户触达。任何代码路径只要动账、做身份验证、写不可逆状态，或者发邮件/通知，就需要一份上线计划。其他的东西通常挂在 feature flag 后面加点轻量监控就够了。

原因是爆炸半径。一个坏掉的 UI 组件影响的是一个按钮。一个坏掉的账单迁移影响的是接下来两周的收入确认。计划的重量必须匹配爆炸半径。

我实际在用的上线计划

我的 spec 里每一次高风险发布都有同样的四个部分。任何一个缺了，你就是在事故现场临时发明安全模型。

Pre-flight checks

这些是在部署之前做的，不是部署过程中做的。任何一项失败，发布就不走。

• 集成测试在接近生产规模的数据量下通过（至少 10% 的生产行数，而不是 100 行的 fixture）。
• Dry-run 迁移在生产快照上执行，耗时在维护窗口的预算之内。
• 回滚流程至少有一次被非作者的人在 staging 端到端跑完。
• On-call 已经知道发布窗口，runbook 已经打开放在手边。

分阶段上线，每一步都有明确的 gate

不是"逐步上线"。是带数字的 gate：

Stage 1: 仅内部用户（≤50 个账号）               — soak 24h
Stage 2: 1% 客户流量                              — soak 6h，检查 SLO
Stage 3: 10% 客户流量                             — soak 12h，检查 SLO
Stage 4: 50% 客户流量                             — soak 2h
Stage 5: 100%                                     — 监控 72h 后再宣布稳定

每一个 gate 都是一个决策点。要有一个——真名实姓的那种人，不是"团队"——来决定是继续推进、按住不动，还是回滚。spec 里要写清楚每一阶段的那个人是谁。

Stop-loss 阈值

这些是触发自动或人工回滚的数字。模糊的 stop-loss（"感觉不太对就回滚"）在凌晨三点会被任何想回去睡觉的人推翻。

• 错误率：相关端点的 5xx 率超过基线 3× 并持续 10 分钟，回滚。
• 延迟：p95 延迟超过基线 2× 并持续 15 分钟，回滚。
• 业务指标：受影响漏斗的转化率相对"上周同一天"基线下降超过 15%，回滚。
• 数据一致性：invariant checker 一旦检测到不一致（例如订单总额 ≠ 明细金额之和），立即回滚。

回滚机制——按类型逐一命名

上线计划里最重要的一件事：回滚在物理层面到底意味着什么。不同类型的响应时间相差一个数量级：

• Feature flag flip——秒级。翻开关，60 秒内用户回到旧行为。
• 代码 revert + 重新部署——5 到 20 分钟，取决于 CI。需要新一次部署；旧代码必须仍然兼容当前数据。
• 配置变更——1 到 5 分钟。只有在配置可热加载、不需要部署的前提下才算数。
• 任务暂停——不固定。能停掉新任务，但在途任务可能还需要善后。
• 数据库回滚或修复——小时级到天级。真正危险的那一档。很多时候只能选择 forward-fix。

如果你的回滚落在最后两档，你其实没有回滚——你有的是一个 forward-fix。请在 spec 里明明白白地这么写。把一次 DB 迁移假装成"可以回滚"，是事故雪崩的标准开头。

向前兼容原则

任何不能干净回滚的数据库变更，旧代码必须在新代码上线之前就能与新 schema 一起工作。这就是 expand-contract：先把新列加成 nullable，回填数据，再改读写路径，最后把旧列作为单独一次发布删掉。每一阶段都可独立回滚。

如果你没法把这次发布描述成一串向前兼容的阶段，那这次发布就不是"高风险安全"的，应该安排维护窗口。

写在 spec 里的 runbook

把 runbook 直接放在 spec 里，或者贴一个链接过去。它要能不需要解读就回答：

• 我现在怎么判断这次发布有没有在正常工作？（具体的 dashboard 地址，具体的指标）
• 这个 dashboard 上"健康"长什么样？（具体的数值区间）
• 如果不健康，第一步干什么？（具体的命令，具体的 UI 按钮）
• 不确定时我 page 谁？（具体的人或值班组，带 SLA）

判断一份 runbook 好不好用的测试：一个新来的 on-call 工程师能不能在凌晨三点自己执行完，不用 page 别人？如果不能，spec 就还没写完。

通常会出问题的地方

• 回滚计划写过，但没演练过。第一次执行就在事故现场。总有东西会坏。
• 阈值的基线取的是"上周"而不是"上周同一天"，于是日内正常波动不是触发假回滚，就是掩盖了真问题。
• feature flag 给代码路径加了，但没给数据迁移加，于是没法做局部回滚。
• stop-loss 是研发写的，但产品没看过。"可接受"的错误率要么太保守，要么太宽松。

这四种在事故复盘里会反反复复出现。上线计划存在的意义，恰恰是在发布前把这些问题逼出来，而不是发布后。

精简版

写发布计划时，假设执行的人很累、现在是凌晨三点，而唯一真正懂这次变更的人刚好去休假了。任何一步需要判断的，就加一句话。任何一个阈值是文字不是数字的，就补上数字。任何一步写着"联系团队"的，就换成具体的人和电话号码。

写这份东西花的时间，比你事后从一次无法干净止损的发布里恢复出来的时间，少一个数量级。

评审时看什么

这篇文章适合用在高风险发布评审时。别从“原则”聊起，直接拿一条真实改动来对照，看看规格里还缺什么。

• 写停止发布的指标，不要只写“观察”。
• 区分配置回滚、代码回滚、迁移回滚和人工修复。
• 标明扩量窗口和负责人。
• 给值班同事一条可以照做的回退路径。

上线计划不是附录。出问题时，大家最先找的就是它。

例子：10% 灰度不能只写“观察稳定后扩大”。规格里要写清人群、观察窗口、监控面板、暂停负责人，以及错误率、延迟或收入指标达到什么阈值时必须回滚。

落地例子

新计价引擎上线时，不要只写“分阶段灰度”。先用内部账号，再放 1% 低风险客户，再选择一组需要人工复核发票的客户。每一步都要有观察时间、停止阈值和负责人。回滚也不只是撤代码，已经生成的发票可能需要红冲、审计记录和客户沟通口径。

这些内容上线前写清楚，事故时才不用在压力下补会计政策和客服话术。

还要把“谁可以按下暂停键”写清楚。很多高风险发布出问题，不是因为没有监控，而是监控已经报警却没人确定自己有没有权限停。规格里应写明暂停人、通知渠道、恢复条件，以及恢复后是否继续原来的灰度节奏。

发布结束后也要补一行结果：是否触发暂停、哪些阈值最敏感、下次灰度是否需要改顺序。

可复制产物：规格写作片段

当工单看似清楚但还缺验收语言时使用。它要求作者写出角色、触发、结果和证据。

规格写作评审片段：高风险发布的灰度发布与回滚设计

本次要做的决策：
- 把模糊需求改写成可以由工程和 QA 共同判断的验收条款。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

写作边界：避免模糊动词，每条验收标准都要有可见的通过或失败信号。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。