别再吹“全自动”：一份 AI‑Coding 上线前的灰度与回滚手册（简单版）

0、先破后立：别再只看"能跑/跑分/演示很顺"，上线考验的不是聪明，是可控与可撤回。

AI‑Coding 最容易把团队带沟里的一点是：Demo 很像成功，合进主干也没报错，于是就以为稳了。可线上从不按脚本走：流量分布不一样、数据更脏、依赖更慢、权限更复杂。你要的不是"它写得快"，而是"它改了也不怕"。这份手册只做一件事：把 AI 生成的改动，放进一条能灰度、能观测、能回滚的发布链路里。

1、交付：上线前最重要的交付物不是代码，而是"变更包"，让别人一眼看懂你动了什么、怎么验、怎么退。

灰度上线不是点按钮，是交付一套可执行材料。合格的 AI‑Coding 变更包，最少包含这些内容：

变更摘要（3 行以内） ：改了哪个能力、影响哪些用户、是否改协议/数据。
影响面清单：改动文件/模块、依赖服务、触发链路、可能受影响的页面或接口。
验收步骤：用例列表 + 操作路径 + 预期结果；别写"自行验证"。
回滚策略：回滚入口在哪里（开关/回滚包/版本回退）、回滚会丢什么数据、回滚后怎么确认恢复。
风险点声明：哪几条是"可能翻车的"，提前说透，别等报警再解释。

一句话：交付要像 PR 说明书，不要像聊天记录。

2、可控：灰度的本质是"把变化关进笼子"，笼子叫开关、限流、权限、范围。

很多 AI 生成的改动之所以危险，是因为它默认"全量生效"。上线前要把可控点做出来，至少三层：

功能开关（Feature Flag）
- 默认关闭，灰度期间只对指定人群打开。
- 开关要能线上实时切换，不要发版才能关。
- 开关要分层：全局开关 + 用户/租户开关 + 请求级开关（必要时）。
范围限制（Scope Lock）
- 只在某些路由/模块/实验组生效。
- 对数据写入更保守：先读路径灰度，再写路径灰度；能影子写就先影子写。
安全闸门（Safety Gate）
- 关键操作加二次确认或权限校验，不因灰度而放松。
- 失败时降级：走旧逻辑、返回兼容响应、或者直接 fail‑closed（按业务选）。

一句话：上线前先问"怎么关"，再谈"怎么开"。

3、复现：灰度不是"试试"，灰度是"按脚本演练"；能复现的事故才可控。

发布前要做两类复现：功能复现与故障复现。

功能复现：把最关键的 10 条链路写成可重复执行的脚本或清单。
- 同一条链路至少覆盖：正常、边界、异常（超时/缺字段/重复请求）。
- 如果是 UI 改动：必须覆盖状态（loading/empty/error/disabled）。
故障复现（演练） ：提前演练 3 种最常见坏事：
1. 依赖慢/超时：你是重试、降级还是熔断？
2. 数据不符合预期：你是容错还是直接拒绝？
3. 回滚执行：关开关或回版本后，验证点是什么，多久能确认恢复？

一句话：把"我觉得没问题"换成"我能重复证明没问题"。

4、成本：灰度做得好，是把事故成本压到最小；做得差，是把排查成本放大到不可收拾。

很多团队舍不得花半天做灰度，最后花三天救火。成本主要烧在三处：

排查时间：没有对比组、没有埋点、没有版本标识，线上异常像无头苍蝇。
沟通轮次：没有变更包，大家只能翻聊天、翻 commit、翻猜测。
回滚代价：一旦写入不可逆数据，回滚不再是"撤回"，而是"修复工程"。

省成本的简单做法也三条：

保留对照组：灰度必须有"旧逻辑仍在跑"的人群或路径。
把验证自动化：能用脚本跑就别靠手点；能用监控断言就别靠肉眼看图。
写入路径更慢放量：读路径 10% 先走，写路径 1% 后走，别反过来。

一句话：省下的灰度工时，往往会变成更贵的救火工时。

5、安全：灰度期间最危险的错觉是"只放小流量，所以安全风险也小"，其实小流量照样能泄露、照样能越权。

安全不因灰度而降级，反而要更严，因为你在引入新路径。上线前把这几件事当成底线：

权限一致：新逻辑必须复用旧的鉴权链路，别在新代码里另写一套"简化版"。
输入校验一致：AI 生成的接口改动最爱漏校验，灰度前把参数校验、长度限制、枚举范围补齐。
日志不泄露：灰度为排查会加日志，但别把 token、手机号、身份证、密钥写进去；脱敏规则要统一。
回滚权限：谁能关开关、谁能回版本要写清，避免紧急时"没人敢动/谁都能动"。

一句话：灰度不是试验场，安全线一毫米都别退。

6、观测与回滚：灰度要有"仪表盘"和"刹车"，没有这两样就等于蒙眼开车。

很多事故不是因为 bug 很大，而是因为"没有及时发现"或"发现了关不掉"。上线前把观测和刹车做扎实：

观测指标（至少四类）

正确性：错误率、异常码比例、关键断言失败次数。
性能：P95/P99 延迟、超时率、依赖耗时。
业务：转化、下单、提交成功率等关键漏斗指标。
资源：CPU、内存、队列积压、连接池耗尽等。

版本与链路标识

灰度请求必须能在日志/链路追踪里区分：新旧逻辑、实验组、版本号。
发生问题时，你要能回答："哪些请求走了新逻辑？"

回滚分级

一级刹车：关开关（秒级）
二级刹车：降级到旧服务/旧路径（分钟级）
三级刹车：回版本 （看流水线，尽量做到可预测）
并写清：触发条件是什么、谁执行、执行后验证点是什么。

一句话：灰度不是"慢慢放量"，灰度是"放量同时随时能停"。

快速测评清单（上线前跑一遍，过了再谈"全自动"）

变更包是否齐：摘要、影响面、验收步骤、回滚方式、风险点是否一页讲清。
开关是否真能关：线上能否实时关闭，关闭后是否立刻回到旧逻辑。
范围是否可锁：能否只对指定租户/用户/路由生效，并保留对照组。
回滚是否演练过：至少演练一次"关开关"和一次"回版本"，并记录耗时与验证点。
写入路径是否谨慎：新逻辑涉及写库/发消息时，是否晚放量、是否可逆、是否有补偿方案。
监控是否能定位到组：错误率上升时，能否一眼看出是新逻辑还是旧逻辑、是哪一组。
安全线是否一致：鉴权、校验、脱敏、审计是否与旧链路一致或更严。
门禁是否跑完：lint、单测、关键集成测试、静态扫描是否通过，失败项是否有记录与处理。
告警阈值是否可执行：告警触发后谁看、怎么判断、多久必须刹车，有没有写死。
人能接得住：紧急时刻，值班同学是否知道开关在哪、仪表盘在哪、回滚怎么做。