从 0 到 1 搭建灰度发布体系:我们跳过的坑

第一次做灰度,我们的方案是”把 Nginx 权重调成 1%“。上线十分钟后出了事故,回滚花了二十分钟——因为没人知道那 1% 到底是谁。

一、灰度的三个真问题

分给谁。 随机 1% 流量意味着每次请求都可能落到新版本,同一个用户刷新页面看到不同结果。对于有状态的业务,这本身就是 bug。

看什么。 只看错误率会漏掉”没报错但结果错了”的问题;只看业务指标,又在流量太小的时候没有统计意义。

怎么退。 回滚速度决定事故影响面。我们的目标是 60 秒内完成流量切换。

二、流量染色:从随机到定向

最终采用的分流维度:

维度 用途 示例
用户 ID 哈希 保证同一用户始终命中同一版本 hash(uid) % 100 < 5
白名单 内部员工、测试账号 指定 uid 列表
地域 按机房/城市灰度 先切一个边缘机房
请求头 供测试手动指定版本 x-release-tag: v2

实现上,在网关做一次决策,把结果写入请求头,下游所有服务读同一个头,不再各自判断。这避免了”上游走新版本、下游走老版本”的错配。

// 网关:一次决策,全链路透传
const bucket = hash(uid) % 100;
const tag = whitelist.has(uid) ? 'v2' : bucket < ratio ? 'v2' : 'v1';
proxy.headers['x-release-tag'] = tag;

三、指标对齐:新旧版本必须可比

灰度期间最容易被忽略的是数据污染。新版本写入的数据、产生的行为,会混进整体指标里,导致判断失真。

我们的做法是给每条业务数据打上 release_tag,所有对比看板都按 tag 拆分:

SELECT
  release_tag,
  count(*) AS pv,
  sum(if(status = 'success', 1, 0)) / count(*) AS success_rate,
  approx_quantile(latency_ms, 0.95) AS p95
FROM request_log
WHERE dt = '2025-11-20'
GROUP BY release_tag;

然后看三个层次:

  1. 技术指标:错误率、P95 延迟、超时率;
  2. 业务指标:下单转化、搜索点击、接口成功率;
  3. 异常信号:日志里新出现的 error 类型、慢查询数量、GC 次数。

第三条最容易被忽略,却最常发现真问题。我们有一次灰度,所有指标都正常,但新版本的 Full GC 次数是老版本的 4 倍——只是还没到影响延迟的程度。

四、自动回滚:把决策交给规则

人工判断太慢。我们定义了明确的回滚条件:

rollback_rules:
  - metric: error_rate
    condition: new > baseline * 1.5 && new > 0.01
    window: 5m
  - metric: p95_latency
    condition: new > baseline * 1.3
    window: 5m
  - metric: business_conversion
    condition: new < baseline * 0.9
    window: 15m

触发后自动执行:网关权重归零 → 新旧版本都保留 → 发通知 → 归档现场(保留日志与 profile 快照)。

规则要满足两个条件才有用:窗口足够长以避开抖动,动作足够快以限制影响。我们的窗口是 5 分钟,切换动作 15 秒内完成。

五、分阶段放量

我们固定用四个阶段,每个阶段有明确的观察期:

阶段 流量 观察期 通过标准
内部 白名单 1 天 无阻断性 bug
小流量 5% 2 小时 三类指标全部正常
中流量 30% 6 小时 含一次完整业务高峰
全量 100% — 保留 24 小时可回滚

“含一次完整业务高峰”是硬性要求。我们曾有版本在低峰期表现完美,到了午高峰因为连接池不够直接雪崩。

六、踩过的坑

  • 只灰度应用,不灰度配置。 一次事故源于配置中心的新配置对所有实例生效,灰度完全失效。配置也要有版本和灰度能力。
  • 数据库变更不可灰度。 加字段可以,改字段类型不行。所有 schema 变更必须向前兼容,分两次发布。
  • 回滚不等于恢复。 新版本已经写入的数据不会自动消失。回滚方案必须包含数据侧的处置说明。
  • 缓存是灰度的盲区。 新版本写入的缓存格式可能老版本读不了。我们后来给 key 加了版本前缀。

七、效果

上线半年,共执行 187 次灰度发布,其中 9 次触发自动回滚,没有一次演变成线上事故。发布频率从每周 1 次提升到每周 4 次,工程师对发布的心理负担显著下降。

灰度体系的价值不在于”降低风险”这个抽象说法,而在于它让团队敢频繁发布。而频繁发布,本身就是最好的质量保障。