灰度发布按流量比例还是按用户标识：染色规则和回滚边界怎么设计

放了 10% 流量，客服先炸了：问题不在版本，在分流方式

某次上线，团队按惯例切了 10% 的流量到新版本。上线两小时后客服开始收到一类很怪的反馈：有用户说页面"一会儿能用一会儿报错"，刷新几次又好了，再刷新又不行。研发拿着账号去查，日志里这个用户的请求被分散在了两个版本上——前一次打到 1.2.0，后一次打到 1.1.9，报错的那几次恰好全都落在 1.2.0。可问题是，用测试账号怎么复现都复现不出来，因为测试账号被固定在单一版本上，永远只会走出一种路径。

最后定位到的原因不算复杂：新版在会话里多写了一个字段，旧的会话解析器遇到这个字段直接抛异常，导致登录态被判定失效。真正让这件事变成事故的，不是那个字段，而是同一个用户在两个版本之间来回横跳——他每次刷新的体验都不同，服务端复现不了，用户也说不清，工单里只能写"页面有问题"。

这类事故的根因几乎从来不是代码写错了，而是灰度分流的粒度选错了。按流量比例随机的做法，在请求维度上是"10%"，落到用户维度上却可能是"几乎所有人都会碰到新版至少一次"，而且是随机的、不可控的碰。要理解这件事，得先把灰度的真实目的说清楚。

灰度的真实目的：不是"慢慢放"，是"把爆炸半径圈住"

很多人把灰度理解成"降低上线压力"，其实这个理解太软了。灰度真正的价值是三件事，缺一件都不算灰度：第一，能明确知道谁在灰度里；第二，能把这批人随时调出去；第三，出问题时能快速圈定受影响的范围。这三件事的共同前提，是"灰度人群"必须是一个稳定的集合。

按比例随机放行，恰好在这三件事上全都打折扣。你不知道谁在灰度里（只知道大概有百分之多少的流量），你不能把某个具体的人调出去（只能整体降低比例，降低的同时还会把另一些人换进来），出了问题你也很难回答"影响了哪些用户"——因为答案取决于请求，而不是取决于人。

灰度要能兜住风险，前提就是回答"这个用户的这次操作走的是哪一版"这个问题时，答案在时间上是稳定的。今天走新版的人，明天还得走新版，直到你主动改变规则。这就是按用户标识染色要解决的问题。

按比例随机：10% 的流量，落到用户身上可能是 90% 的覆盖率

按比例分流的实现通常很朴素：在网关或负载均衡上对每个请求独立做一次随机数判断，命中就走新版。注意"每个请求独立"这几个字——一个请求一次判定，请求之间没有任何关联。

这就带来一个常被忽略的数学事实。设单次请求进新版概率为 p，一个用户完成一次业务操作会发出 n 个请求（打开页面、拉列表、提交表单、轮询状态，一次下单流程发出几十个请求很正常），那么这个用户至少有一次碰到新版的概率是 1-(1-p)^n。p=0.1、n=50 时，这个概率是 99.5%。

也就是说，"10% 流量灰度"在用户感知层面，约等于"99% 的用户都会在新旧版本间跳来跳去"。你以为只放开了十分之一的口子，实际上几乎所有人都被溅到了。更麻烦的是，这种溅到是无规律的：同一个人先走旧版再走新版，或者先走新版再走旧版，顺序完全随机。

所以按比例灰度最大的问题从来不是"比例不好调"，而是同一个用户的连续请求会随机落在新旧两个版本上。这个结论要记住，后面所有的设计都是围绕它展开的。

同一个人跨版本，具体会坏在哪几处

跨版本本身不必然出错，只有当新旧两版在"状态"上不兼容时才会出问题。真实的坏法大概有下面几种，每一种都有共同特征：偶发、看不出规律、在测试环境百分百复现不了。

会话与登录态。新版往 session 或 token 里加了字段，旧版的解析逻辑遇到未知字段直接失败，或者反过来新版要求的字段旧版没写。结果就是用户隔几分钟掉一次线，而且掉线时机跟任何操作都没有相关性。这类问题在按流量比例灰度下会表现得极其诡异，因为用户的登录请求可能走旧版、后续业务请求走新版，两边对 session 的理解不一致。

本地缓存与静态资源。新版前端打包出的 chunk 文件名变了，旧版 HTML 引用的还是老 chunk；用户的浏览器里同时缓存着两版资源，加载时互相打架，表现是白屏或者某个模块报 "Loading chunk failed"。如果静态资源走 CDN 并且发布时做了覆盖式更新，这个问题会更严重——旧版 HTML 请求的资源已经被新版覆盖了。

数据结构与写入。这是最危险的一类。新版往订单表里写了一个新字段，旧版不写；同一张表里出现两种形态的数据，新版读旧数据时对 null 的处理没写全就崩，旧版读新数据时直接忽略这个字段但业务逻辑已经不对了。更糟的是下游的报表、对账、数据仓库，它们拿到的是混合数据，而且没有任何标记能区分这行数据是哪一版写的。

幂等与重复提交。新旧两版生成的幂等键规则不一致，同一个业务操作在两版上生成了两个不同的幂等键，防重失效，直接后果可能是重复下单或者重复扣款。这种问题一旦发生就不是"体验不好"，是要赔钱的。

排查成本。顺带说一个容易被低估的损失：跨版本让归因变得几乎不可能。日志格式两版不同，链路追踪里一个 traceId 横跨两个版本的服务实例，报警聚合出来的错误曲线是锯齿状的。团队要花的时间不是修 bug，而是先搞清楚"这个 bug 在哪个版本上"。

按用户标识染色：让哈希结果对同一个人永远不变

染色（traffic coloring / tagging）的做法说白了就一句话：别对请求做随机，对标识做哈希。流量进入系统后，网关从请求里取出一个稳定的标识——用户 ID、租户 ID、设备 ID——算一个哈希值，取模后落在阈值区间内的进新版。因为标识是稳定的，同一个人所有请求的哈希结果恒定，他要么全程在旧版，要么全程在新版，不会再横跳。

实现上只有两个硬性要求，但这两个要求经常被做错。

第一，哈希函数必须长期稳定。不要用带随机盐的哈希，也不要在每次发布时更换算法。如果一次发布导致哈希重新洗牌，那么原来在灰度里的人可能被洗出去、原来在灰度外的人被洗进来——对有状态的变更来说，这等于制造了一次全量跨版本迁移，比不染色还糟。取模的分母也要固定，比如固定 hash(id) % 100 得到 0-99 的分桶值，然后判断"是否小于 10"；把 10 调到 20 时，分桶值 0-9 的人不受影响，只有 10-19 的人新进来。这个单调性非常重要：放量只增不减，不会有人被换出去。

第二，必须有白名单旁路。内部测试账号、种子用户要能强制进灰度，绕过哈希。做法是在染色逻辑之前先查一遍白名单。反过来说，也要有能力把某个具体的人强制踢出灰度——这是出事后最快的止血手段，比整体调比例精准得多。

标识从哪来，怎么一路透传到异步链路

染色成不成立，九成取决于透传做没做全。在 HTTP 层给请求打个 header 是最容易的一步，真正难的是这个标签能不能跟着请求走到系统的每一个角落。

标识的来源按优先级排：登录态里的用户 ID 最优先，它最稳定、跨设备一致、语义清晰；其次是租户或企业 ID，做 B 端系统时按租户染色往往是更好的选择，因为一个企业的人应该看到同一套行为，否则同一家公司里 A 同事能用的功能 B 同事用不了，工单能把你淹死；再次是设备 ID 或匿名 Cookie，用于未登录场景；最末才是匿名会话 ID，它的有效期最短，只适合做非常短期的验证。

透传的路径大致是这样：客户端请求进来，统一网关解析身份后计算染色标签，写入一个标准化 header（比如 X-Gray-Tag），然后把标签放进 RPC 调用的上下文里随链路传递；服务之间调用时不允许丢弃这个上下文；发往消息队列的消息，要把标签写进消息头或消息体；消费端取出标签后再按标签路由到对应版本的消费者，或者由消费端自己按标签决定走新逻辑还是旧逻辑；定时任务和批处理脚本启动时也要带上标签——很多团队就是在这里漏掉的，凌晨的批处理任务没有标签，跑出了全量的新逻辑。

最容易漏的三处是：消息队列、定时任务、第三方回调。消息消费没有标签，等于灰度之外还有一条并行链路在全量跑新代码；定时任务同理；而支付回调、短信回调这类第三方发起的请求根本没有内部身份，需要单独设计兜底规则（通常是按回调对应的业务单据反查该单据的染色归属，查不到就一律走旧版）。

有一个很实用的自检办法：在新版服务里把每个请求携带的标签打进日志，跑一段时间后统计"落到新版的请求里标签缺失的比例"。这个数字只要大于零，就说明透传有洞，而且洞的位置能从缺失请求的接口分布里直接看出来。不要凭感觉判断透传做完了，要看这个缺失率。

染色维度怎么选：一张对照表说清楚

选染色维度本质上是在选"一致性的边界"——你希望哪些请求必须落在同一版本上，就按那个维度染。下面是几种常见维度的对照。

这张表里最该记住的判断标准是这一句：无状态只读的服务可以按比例，任何涉及会话、写入、数据结构的变更必须按标识。不存在中间地带。如果你的改动同时包含这两种，那就按有状态的标准来——从严不会错，从宽一定会出事。

未登录、多端、CDN：三个会把染色悄悄破坏掉的地方

未登录用户。拿不到账号 ID 时，通常退到设备 ID 或服务端下发的匿名 Cookie。这里有个坑：匿名 Cookie 有效期短，用户清一次缓存就换了一个身份，也就换了一次版本。所以对未登录路径，最稳的做法不是"找一个更好的标识"，而是确保未登录路径本身是无状态的——浏览、搜索、展示这些接口本来就不该有跨请求的状态依赖，做到这一点，即使用户换了版本也不会出问题。

多端同账号。一个人同时在手机和 PC 上操作，如果按设备 ID 染色，他会在两个终端上看到两个版本。如果是纯 UI 改动问题不大，但只要涉及数据结构——比如新版在草稿里多存了一个字段，用户在 PC 上存的草稿手机端读不了——就是实打实的故障。有状态变更一律按账号 ID 染，不要用设备 ID 顶替。

CDN 与静态资源。HTML 可以按标签分流，但 JS、CSS 这类静态资源是 CDN 缓存的，标签往往传不到资源请求上。做法只有两种：一是两版静态资源使用不同的文件名（内容哈希），发布时共存而不是覆盖，旧版 HTML 请求老资源、新版 HTML 请求新资源；二是如果必须覆盖发布，就接受"灰度期间资源版本与 HTML 版本可能错配"这个事实，并且确保新版代码对老资源、老代码对新资源都能容错。前者才是正解，后者只是妥协。

回滚边界划在哪：先问一句"旧版能不能读新版写的数据"

回滚不是"把流量切回去"这么一个动作，它有两个层次，分不清这两个层次是灰度事故扩大的主要原因。

切流回滚指的是把灰度比例调回 0，或者清空染色名单、摘掉白名单。它的特点是快，秒级生效，而且对没有产生新数据的变更完全够用——纯粹的逻辑改动、UI 改动、只读接口优化，切流就是全部。

数据回滚指的是处理新版已经写入生产的数据。这一层往往被忘掉。只要新版写过数据，切流回滚之后旧版仍然要读这些数据，如果旧版读不懂，回滚就是假的——流量切回去了，故障照样在。

划分边界的判据其实就一句话：如果现在把流量全部切回旧版，旧版能不能正常读取新版已经写入的数据？能，那切流回滚就够了；不能，那这次变更在设计阶段就必须带上数据兼容方案，否则它根本不具备灰度的资格。

按这个判据，回滚的准备可以分成三档，每档要做的功课差别很大：

第一档，无状态改动。切流即可，最干净，不需要额外的回滚预案，只需要确认流量链路是真的切干净了（包括 MQ 消费者和定时任务）。

第二档，有状态但数据结构兼容。切流之外，还要观察旧版读新数据有没有异常。典型情况是新版多写了一个字段，旧版忽略它——看起来没问题，但如果存在"旧版读出来再写回"的路径，那个字段会被抹掉，造成静默的数据丢失。要专门检查所有读改写回的接口。

第三档，数据结构不兼容。必须同时准备三样东西：双写或影子字段、可执行的回滚脚本、以及数据修复方案。切流只是这套流程的第一步，后面还有数据要处理。这一档的变更，说实在的，应该先想办法拆成兼容的形式再上——能拆就别硬上。

还有一类东西是切流撤不回来的：已经发出去的外部副作用。短信、推送、邮件、扣款、发货、第三方接口调用，这些动作一旦发生就无法撤销。新版里如果有这类动作，要么在灰度期用开关关掉、等全量后再打开，要么把它们延迟到灰度结束后的批处理里统一执行。别让灰度用户成为不可逆动作的第一批实验对象。

数据结构变更：把"替换"拆成"扩展"，每一步都能单独回滚

数据结构变更是最需要克制的一类。原则很简单：扩展式迁移优于替换式迁移。不要在一个版本里既改写入格式又改读取逻辑，把它拆成三步。

第一步，只加不改。新增字段，新旧版本都写这个字段（或者新版写、旧版在写回时保留），旧版的读取逻辑完全不动。这一步的回滚是最干净的，因为没有任何已有逻辑依赖新字段。

第二步，切换读取。新版开始读新字段，同时保留对旧字段的兼容读取——读到空就回退到旧字段。这一步出问题可以退回第一步，因为数据还在两个字段里都有。

第三步，清理。等全量稳定运行一段时间、确认没有旧版本实例在跑之后，再下线旧字段和兼容代码。这一步不急着做，很多团队把兼容代码留半年也无所谓，留着比删了出事强。

配合这个流程，几个具体动作要注意。双写在灰度期是必要的：新旧字段同时写，保证任何一版读都不会缺数据，灰度结束后再用脚本回填历史数据。绝对不要在灰度期间做不可逆的数据变换——把某个字段加密后覆盖原值、删除列、修改字段类型，这些操作一旦执行就无法随切流回滚。

消息格式同理。先让所有消费者能同时消费新旧两种格式，再让生产者切换到新格式。顺序反了就会出现"新版发的消息旧版消费不了"，而且消息已经进了队列，切流也救不回来。

缓存也别忘了。灰度期新旧两版共用同一个缓存 key 命名空间会互相污染——新版写的序列化格式旧版反序列化失败，或者反过来。做法是在 key 里带版本前缀，或者灰度期干脆用独立的缓存实例。后者更干净，成本也就是多一组实例。

放量的节奏：按样本量推进，不要按时间推进

常见的放量阶梯是 1% → 5% → 20% → 50% → 100%，这个序列本身没问题，问题在于很多人按"每个档位停留 N 小时"来推进。时间不是有效的判据，样本量才是。1% 的流量如果一天只有几百个请求，统计上什么结论都得不出来；而 1% 的流量如果对应几万个真实用户，两小时就够了。

比较稳的做法是给每一档设一个"最小样本量"门槛：比如灰度用户数达到某个量级、或者关键接口的调用次数达到某个量级，并且包含了至少一个完整的业务高峰和一个低谷，才允许升档。日终批处理、对账、结算这类低频但关键的任务，必须至少跑过一轮才能继续。

观察指标要分三层看，而且每一层都必须按版本分组——只看大盘等于没做灰度。大盘错误率 0.1% 看起来很健康，可能这 0.1% 全部来自只占 5% 流量的新版，换算成新版自身的错误率是 2%，早该回滚了。

技术指标：错误率、P99/P95 延迟、超时率、熔断与重试次数、内存与 GC 表现、下游依赖的错误率变化。重点看"新版有没有出现旧版根本没有的错误类型"，新错误类型比错误率上升更值得警惕，它通常意味着有路径没被覆盖到。

业务指标：转化率、下单成功率、支付成功率、页面停留时长、客服工单量，以及工单文本里异常关键词的出现频率。这一层往往是最后一道防线——技术指标全绿但转化率掉了两个点，说明新版在功能上没问题，在体验上出了问题。

数据指标：新结构字段的写入量、脏数据比例、双写一致性比对的结果差异数、下游报表是否出现口径异常。数据类问题通常不会立刻报警，而是在几小时后的对账里才浮现，所以这一层必须有主动的比对任务，不能等下游来问。

报警阈值要提前定死并且写成规则，不要留给人判断。新版错误率超过旧版基线的 2 到 3 倍，或者出现旧版没有的新错误类型，或者核心业务指标跌幅超过预设值——立即回滚，先回滚再查原因。灰度期最大的诱惑是"再观察五分钟看看"，而这五分钟往往就是事故从"影响 1% 用户"变成"影响 5% 用户"的时间。

灰度环境的服务器资源：独立部署这件事不能省

方法论讲完了，落到资源上还有一件容易被砍掉的事：灰度必须有自己独立的实例资源，不能跟旧版混部在同一批机器上。理由是灰度的意义就在于隔离爆炸半径——新版把 CPU 打满、把内存吃光、把连接池耗尽，如果它和旧版共享机器，那这个爆炸半径就直接覆盖了生产全量。

资源量上，一般按生产峰值的 10% 到 30% 预留灰度实例就够了，具体看灰度比例和单实例承载能力。大促、活动这类场景需要额外扩容，因为灰度期的总容量是"旧版全量 + 灰度增量"，不是互相替换。数据侧的隔离更关键：灰度库要么用独立库（干净但数据不真实），要么在生产库里用影子表（真实但风险高）。涉及写入的变更，优先选独立库加生产只读副本的组合，宁可数据不够真实，也不要让灰度写坏生产数据。

这种"临时、弹性、验证完就还回去"的资源形态，其实很适合走短周期租用的物理机或裸金属，而不是一上来就按年付锁死。像一万网络这样深耕 IDC 19 年（成立于 2007 年）的服务商，提供的多形态算力与裸金属资源，匹配的就是这类按项目周期弹性伸缩的验证环境需求——灰度跑完就释放，不需要为一次发布长期持有机器。

如果灰度方案里包含地域维度的验证，还需要在不同地域各起一组灰度实例做对照，这时候多节点能力就很重要。华南、华东、华北多节点加 BGP 多线的组合，能让你在同一个染色规则下对比不同地域用户的真实链路表现，而不是只在一个机房里自测。像一万网络这类具备多节点布局的服务商，在这种跨地域对照验证的场景里能省掉不少协调成本。

关于灰度与回滚的几个高频疑问

Q1：灰度比例从多少开始合适？

A1：没有万能数字，但有一个实用的起点逻辑：先看你一天的真实用户量。日活十万以上的业务，1% 起步完全够用，一小时内就能拿到几千个样本；日活只有几千的话，1% 可能一天才几十个人，统计上毫无意义，起步就要放到 5% 甚至 10%。真正要守的底线不是比例大小，而是这一档的样本量能不能支撑你得出结论。样本不够就别升档，也别因为"看起来没问题"就提前放量。另外内部员工和种子用户应该在第一档之前就先跑一遍，这一步不算灰度，算冒烟。

Q2：染色标识用账号 ID 还是设备 ID？

A2：只要改动涉及会话、写入或数据结构，一律用账号 ID。设备 ID 的问题在于同一个人换设备、清缓存、用无痕模式就会换身份，也就换了一次版本，恰恰是你要避免的横跳。设备 ID 只在两种情况下可用：一是改动纯粹是只读展示，没有任何跨请求状态；二是用户根本没登录，且你已经确认这条路径无状态。B 端系统优先考虑租户 ID，它比账号 ID 更能保证"同一家公司的人看到同一套行为"，避免同事之间功能不一致带来的工单。

Q3：没登录的用户怎么染色？

A3：两条路，选哪条取决于这条路径有没有状态。第一条是退到设备 ID 或服务端下发的匿名 Cookie，能做，但要接受它会漂移——用户清一次缓存就换版本。第二条，也是更推荐的，是把未登录路径设计成无状态的：浏览、搜索、商品展示这类接口本来就不该有跨请求的状态依赖，做到这一点，即使用户被分到不同版本也不会出问题，染色粒度粗一点无所谓。如果未登录路径确实有状态（比如未登录购物车），那就别在未登录场景下灰度这个改动，等用户登录后再走新版逻辑。

Q4：数据库字段变了，还能灰度吗？

A4：能，但必须把"替换"拆成"扩展"，一步到位地上就等于放弃灰度。顺序是：先加字段且新旧版本都写，读取逻辑完全不动；跑稳之后新版切换到读新字段，同时保留读旧字段的兼容回退；全量稳定一段时间后再下线旧字段。每一步都能单独回滚，而且每一步的回滚都很干净。要绝对避免的是在灰度期间做不可逆变换——删除列、改字段类型、把原字段加密后覆盖，这些操作执行了就撤不回来，流量切回去也没用。

Q5：灰度期间要不要双写？

A5：只要数据结构不兼容，就必须双写。双写的意义是保证任何一版读数据都不会缺字段，这样切流回滚之后旧版还能正常工作，回滚才是真的回滚。双写的代价是写入逻辑变复杂、两份数据要保持一致，所以灰度期一定要配一个一致性比对任务，定期比对新旧字段的差异数量，差异数不为零就说明有路径漏了。要提醒的是，双写不等于可以长期双写——它是灰度期的临时状态，全量稳定后要收敛到单写并回填历史数据，否则这套双份逻辑会变成长期的技术债。

Q6：回滚是切流量还是重新发一版旧代码？

A6：优先切流量，不要重新发版。重新发旧版意味着要走一次完整的构建、发布、实例启动流程，几分钟到几十分钟不等，而这期间故障一直在发生。切流量是改一个配置或者调一个阈值，秒级生效。前提是切流量的开关要提前部署好并且验证过——很多团队的惨痛教训是开关本身没测过，出事时发现开关失效，只能被迫走发版回滚。正确的做法是：每次灰度前先演练一次切流，确认它是真的能把流量切干净，包括消息队列消费者和定时任务这两条旁路。

Q7：灰度要观察哪些指标才算够？

A7：三层都要看，而且每一层都必须按版本分组统计，只看大盘是灰度的头号误区。技术层看错误率、P99 延迟、超时率、下游依赖错误率；业务层看转化率、下单与支付成功率、客服工单量；数据层看新字段写入量、脏数据比例、双写一致性比对差异。其中最有信号价值的两个是"新版是否出现旧版没有的新错误类型"和"核心业务指标是否下跌"——前者说明有路径没覆盖，后者说明功能没问题但体验坏了。技术指标全绿但转化率掉了，这种案例太常见了。

Q8：观察多久可以算安全？

A8：至少覆盖一个完整的业务高峰加一个完整的低谷，外加一轮日终批处理或对账。只盯白天是抓不到夜间问题的：批处理任务、结算、报表、第三方对账文件这些链路往往在凌晨跑，而且它们通常不经过染色透传，是灰度最容易漏的地方。如果业务有明显的周期性（比如每周一高峰、每月初结算），还要覆盖对应的周期。我的建议是把升档条件写成"样本量门槛加必过的关键任务轮次"，而不是"观察 N 小时"，后者太容易被主观判断带偏。

结论：判断标准只有一条，其余都是执行细节

回到最初那个"页面一会儿正常一会儿报错"的问题。它不是运气不好，是按流量比例灰度在有状态变更上的必然结果——随机判定让同一个人在两个版本间反复横跳，而会话、缓存、数据结构一旦跨版本不一致，用户看到的就是时好时坏的诡异现象，服务端还复现不了。

所以判断标准就一条：无状态只读的服务可以按比例，任何涉及会话、写入、数据结构的变更必须按用户标识染色。按比例灰度的成本几乎是零，但它的适用面也窄得可怜；按标识染色的代价是需要提前打通标识透传，包括消息队列、定时任务、第三方回调这些最容易漏的旁路，还要保证哈希函数长期稳定、放量单调不回撤。

至于回滚边界，判断的方法也只有一句话：如果现在把流量全切回旧版，旧版能不能正常读新版写的数据。能，切流就够了；不能，说明这次变更的数据兼容方案没做，它根本还不具备上灰度的资格。把数据结构变更拆成"加字段—切读取—清理"三步，每一步都能单独回滚，比追求一次性改完要稳得多。

最后再强调一遍那个最容易被忽略的数字：所有观察指标必须按版本分组看。大盘错误率 0.1% 在新版只占 5% 流量的情况下，换算过来是新版的 2%，这已经是必须回滚的水平了。灰度做了一半的团队，基本上都是栽在这件事上。

本文为发布方法论层面的经验整理，涉及的行业口径均为市场参考，具体以签约时最新报价与合同为准。