全栈灰度发布：让上线从赌博变成可回退流程

灰度不是“只给 5% 用户看新页面”。它是一段有时间边界的生产评估：挑选代表性人群，将新版本与控制组对照，观测预先约定的用户和系统指标，达到继续条件才扩量，达到停止条件立刻暂停。

灰度前先做可逆设计

明确版本标识、适用用户、流量分组、开关 owner、最小观察窗口和回滚按钮。分组应稳定，避免同一用户刷新时反复切版本；敏感权限不能通过可被客户端篡改的实验参数决定。开关服务故障时指定安全默认值，不能把未知状态解释为放行。

把代码、功能开关、实验配置、数据库结构和用户配置视作不同变化面。功能开关可以先随代码上线、再单独开启；危险开关要有审计和权限。每个开关都写负责人、创建日期、目标、移除版本和过期时间，定期删除完成实验的开关。

指标要能比较、能归因

除整体错误率外，按 canary/control、版本、用户路径拆分 HTTP 错误、P95/P99、崩溃、队列积压、数据库负载、业务转化和人工投诉。只看总体平均会稀释小流量中的严重故障。指标窗口要匹配功能行为：低频任务可能需要等待一个完整周期，不能拿 5 分钟数据断言长期成功。

在发布前为每项定义基线、允许差值、最小样本和失效保护。如果实验样本不足、指标延迟或归因不清，决策应是暂停/延长观察，而不是自动继续。避免一次叠加多个灰度，导致无法定位差异来源。

数据库变更通常不是一键回滚

采用 expand-migrate-contract：先新增兼容字段或表；部署同时能读旧/新形态的代码；回填并核对；切换读写；观察旧路径停止后再单独清理旧字段。DDL、回填和代码版本要可独立控制。数据删除、不可逆转换和外部副作用不能靠切回旧二进制恢复。

区分三类应急动作：关功能旗标止损，回滚代码恢复旧行为，修复/恢复数据处理已写入的错误状态。任何一种都要写触发条件、执行人、命令入口、验证指标和失效时升级路径。回滚前确认旧代码仍兼容已迁移的数据。

放量阶段

内部账号与自动化烟测，确认路由、权限、日志和关键事务。
小比例真实流量，观察对照指标和实际核心路径。
按小步逐级扩量，每一步留出足以覆盖主要行为的观察窗口。
错误、延迟、业务指标或投诉触发阈值时暂停，不在排障期间继续放量。
全量后继续保留回滚窗口，并记录最终版本、配置和指标快照。

观察窗口与停止信号

阈值需在发布前结合基线、业务影响和样本量定好：关键路径成功率下降、授权拒绝异常、P95 超预算、队列积压持续增长或投诉集中出现，都可以成为暂停条件。高严重度安全/数据完整性信号不应等待统计显著性，立即关闭功能或停止流量。普通波动则结合对照组、流量结构、部署事件和依赖指标判断，避免因单个噪点频繁回滚。

每一步记录开始时间、目标比例、版本与配置、观察指标、决策人和下一检查点。暂停后先冻结配置与发布动作，保留可关联的日志和 trace，再决定恢复、修复或回退。只有原因已定位、修复已验证、受影响数据已核对且继续观察窗口明确时，才重新开始放量；不能把回滚当作故障分析的替代品。

复盘与治理

记录灰度人群、开始/结束时间、指标、决定和回滚演练结果。若出现故障，写清影响人群、发现延迟、止损时间、数据修复和后续责任项。定期统计开关数量、未清理开关、失败发布率和回滚耗时，避免“有回滚按钮”却没人验证。

流量分组需覆盖新旧客户端、核心用户路径、地区/设备差异和关键依赖，不要只从最活跃用户中抽样。涉及外部服务的功能应定义超时、熔断、降级结果和重试上限；重复重试可能放大故障。出现样本量不足、指标延迟、依赖异常或无法归因时，应暂停扩量并延长观察，不能将“还没看到问题”当成通过。

每个发布候选都生成短 runbook：稳定版本、候选版本、配置差异、备份点、健康探针、阈值、暂停入口、回滚入口和回滚后验证。预发布演练要验证命令退出码、实际流量、数据库兼容和告警；手动参数必须标清占位符与目标服务。邮件、通知、结算和授权下载等不可逆副作用要有补偿或人工处置方式，不能只切回旧页面就宣布恢复。

参考：Google SRE Workbook：Canarying Releases。