灰度发布的具体做法，是把一次发布拆成可独立验证的小批次，为每批设定放量对象、观测指标和通过阈值，按“小流量验证—扩大范围—全量”推进；每批都预设回滚触发条件和回滚动作，指标越界时停止放量并回退，确认稳定后再进入下一批。整个过程围绕四份产物展开：发布批次表、观测指标清单、回滚预案和每批放行记录。
要点总览（TL;DR）
- 灰度发布按“设计批次—准备输入—放量观测—判定放行或回滚—记录结论”推进，每批都要有范围、指标、阈值和判定人。
- 首批可从内部账号、白名单用户、小比例流量或单组节点切入，放量梯度逐档放大，观测窗口至少覆盖一个完整业务周期，并尽量让某一批跨越业务高峰。
- 观测指标分技术与业务两层，阈值以发布前基线为依据；回滚触发条件写成“指标+持续时间+判定人”的可判定形式，并提前准备流量切回、版本回退和数据处置动作。
- 发布负责人对放行与回滚拍板，研发、测试、运维值班和业务方各负其责，每批交接写入放行记录。
- 全量后核对指标是否回归基线、回滚预案是否仍可用、遗留问题是否登记，记录归档供下次同类发布复用。
灰度发布的操作主线：从批次设计到全量放行
一次灰度发布可以按“设计批次—准备每批输入—执行放量观测—判定放行或回滚—记录结论”五个动作推进。每个动作都有明确的输入和输出，避免发布过程变成临时商量。
第一步是设计批次。把本次变更拆成若干批次，确定首批覆盖范围、后续每档放量比例，以及进入全量的条件。批次数量取决于变更影响面和系统承载能力，通常三到五档即可覆盖从极小流量到全量的过渡。
第二步是准备每批输入。每批开始前，需要明确四项内容：本批包含的变更内容、影响的功能与用户范围、本批重点观测的指标、指标通过与否的阈值。这四项写清楚，放量时才有判定依据。
第三步是执行。按计划放量，在观测窗口内持续查看指标，对照阈值做出判定。判定结果只有两种：放行进入下一批，或触发回滚。
第四步是记录。每批结束后登记放行记录，写明批次范围、观测结果、判定结论和判定人。这份记录既是后续批次的依据，也是发布结束后复盘的材料。
把上述内容固化成一张批次推进表，发布过程中直接按表执行：
| 批次 | 放量范围 | 观测指标 | 通过阈值 | 观测窗口 | 判定结论 | 判定人/时间 |
|---|---|---|---|---|---|---|
| 第1批 | 内部账号或指定用户 | 错误率、核心接口耗时、关键业务转化 | 错误率不高于基线+0.5个百分点 | 2小时 | 放行/回滚 | 填写 |
| 第2批 | 5%流量 | 同上，增加业务侧反馈 | 同上 | 4小时 | 放行/回滚 | 填写 |
| 第3批 | 30%流量 | 同上，增加资源水位 | 同上 | 覆盖一个业务高峰 | 放行/回滚 | 填写 |
| 第4批 | 100% | 全量指标复核 | 回归基线 | 24小时 | 完成/回滚 | 填写 |
表格中的档位和时长是示意，实际取值要结合系统流量规模和业务周期调整。表格的价值在于把“放多少、看什么、谁来判”提前写死，减少发布当天的临场决策。
批次怎么切：放量对象、梯度与观测窗口的设定方法
首批范围的选择直接影响风险暴露面。常见切分方式有四种：按内部账号切分，先让研发、测试、业务方自己使用；按用户维度切分，选择可识别的白名单用户或特定区域用户；按流量比例切分，通过路由规则把一定比例请求导向新版本；按机器节点切分，先在一台或一组节点上部署新版本。内部账号和单节点适合验证功能正确性，流量比例适合验证容量和稳定性。
放量梯度通常从小比例起步，逐档放大。常见档位是1%、5%、10%、30%、50%、100%，具体档位不必照搬，关键是每档之间留出足够的观测时间，并且后一档的放量规模不超过前一档验证过的承载能力。每档停留时长由两个因素决定：观测窗口长度和业务周期。观测窗口要覆盖至少一个完整的业务请求周期，涉及交易、支付等场景时，应覆盖一个业务高峰或一个对账周期。
观测窗口与流量波峰的关系需要提前确认。如果首批放量安排在低峰期，指标平稳只能说明低负载下可用，不能代表高峰表现。稳妥的做法是让至少一个批次跨越业务高峰，或在高峰前完成小比例验证、高峰时保持当前比例观察。
部分变更不适合按小比例灰度。数据结构变更、消息格式变更、涉及上下游协议不兼容的改动，新旧版本可能无法同时读写同一份数据。这类变更的替代做法是：先做兼容性设计，让新旧版本能并行处理；无法兼容时，采用停机窗口或双写迁移方案，把验证重点放在迁移脚本的演练和数据一致性核对上，而不是流量比例。
观测指标与回滚触发条件怎么写
观测指标分两层。技术指标反映系统是否正常，包括接口错误率、请求耗时、超时率、CPU与内存水位、数据库连接数、消息积压量。业务指标反映用户是否受到影响，包括下单成功率、支付成功率、登录成功率、核心页面转化率、客诉量。两层指标要同时看，技术指标正常但业务指标下滑，同样说明发布有问题。
阈值设定以基线为依据。取发布前一段时间的指标均值作为基线，结合日常波动范围确定容忍区间。例如错误率基线为0.1%，日常波动在0.1%到0.3%之间，阈值可以设为0.5%；超过即视为异常。阈值要与告警联动，指标越界时自动通知值班人员，避免依赖人工盯屏。
回滚触发条件要写成可判定的形式，包含三个要素：指标、持续时间、判定人。例如“核心接口错误率连续5分钟超过1%，由发布负责人判定回滚”。只写“指标异常时回滚”无法执行，因为异常的程度和持续时间没有界定。
回滚动作清单在发布前准备好，至少包含：把流量切回旧版本、回退部署版本、处置新版本产生的数据（如新写入的字段、新产生的消息）、通知相关方。数据处置尤其需要提前设计，避免回滚后新旧数据混用导致二次故障。
| 触发条件 | 判定标准 | 判定人 | 回滚动作 |
|---|---|---|---|
| 接口错误率越界 | 连续5分钟高于阈值 | 发布负责人 | 流量切回旧版本，保留现场日志 |
| 核心业务成功率下降 | 低于基线超过约定幅度且持续10分钟 | 发布负责人与业务方确认 | 切回旧版本，核对业务数据 |
| 资源水位异常 | CPU或内存持续高于警戒线 | 运维值班 | 停止放量，评估是否回退 |
| 严重客诉或功能不可用 | 出现明确的功能阻断 | 发布负责人直接判定 | 立即回滚，通报相关方 |
角色分工与各环节交付物
灰度发布需要明确谁放量、谁观测、谁拍板。角色不清时，最常见的问题是指标异常后没人决定是否回滚，放量停在半途。
发布负责人对整次发布负责，决定每批是否放行、是否回滚，是放行与回滚的最终决策人。研发负责变更内容的技术正确性，处理发布中出现的代码与配置问题，提供回滚所需的技术动作。测试负责验证新版本功能是否符合预期，在首批放量后给出功能验证结论。运维或值班人员负责执行放量与流量切换操作，持续监控技术指标，发现越界及时上报。业务方从业务指标和用户反馈角度提供判断，参与涉及业务影响的回滚决策。
| 角色 | 主要职责 | 交付物 |
|---|---|---|
| 发布负责人 | 组织批次设计，判定放行与回滚 | 批次推进表、放行记录、回滚决定 |
| 研发 | 保证变更正确，准备回滚动作 | 变更说明、回滚操作步骤 |
| 测试 | 验证功能，反馈验证结论 | 首批功能验证记录 |
| 运维/值班 | 执行放量，监控技术指标 | 放量操作记录、指标观测记录 |
| 业务方 | 关注业务指标与用户反馈 | 业务侧观察结论 |
每批交接时，上一环节要把本批范围、观测结果和遗留问题写进放行记录，下一环节据此决定是否继续。异常发生时的通报路径也要提前约定：值班人员发现指标越界，第一时间通知发布负责人；涉及业务影响时同步业务方；需要回滚时由发布负责人下达指令并通报所有相关角色。
这些记录如果散落在聊天工具和临时文档里，事后很难还原每批的判定依据。把批次任务、放行记录和回滚预案放进统一的工作项与文档中管理，可以让每批的状态、负责人和结论都有据可查。ONES 支持在工作项中记录发布批次与状态流转，并通过文档沉淀回滚预案和放行记录，适合把上述表格和清单落到可追踪的载体上；具体字段和流程配置可按团队实际发布流程设置。
一次完整示例：从首批放量到回滚处置
以下为演示情景，用于说明批次推进和回滚处置的连贯过程，不代表真实系统数据。
某系统计划上线订单查询接口的性能优化版本，变更涉及查询逻辑调整，影响订单列表页。发布负责人设计四个批次：内部账号、5%流量、30%流量、全量。观测指标为接口错误率、查询平均耗时、订单列表页打开成功率，阈值分别为错误率不高于0.5%、平均耗时不超过优化前的80%、打开成功率不低于基线。
首批放给内部账号，观测2小时，三项指标均在阈值内，测试确认功能正常，发布负责人记录放行。第二批放量5%，观测4小时，指标平稳，放行。第三批放量30%，放量后20分钟，值班人员发现查询平均耗时上升到优化前的95%，接近阈值但未越界，同时订单列表页打开成功率下降1个百分点。发布负责人判断该批未达到预期收益且存在劣化趋势，决定停止放量，暂不回滚，延长观测30分钟。延长观测期内平均耗时继续上升并越过阈值，发布负责人下达回滚指令。
运维将流量切回旧版本，研发确认旧版本运行正常，测试抽查订单列表页功能，业务方核对订单数据无异常。回滚完成后，研发定位到新查询逻辑在特定数据量下未命中索引，修复后重新提交验证。再次发布时从内部账号批次重新开始，前两批通过后，第三批改为10%流量并延长观测窗口，确认稳定后再放大到30%和全量。
完成检查：灰度发布收尾要核对什么
全量放行后，发布并未真正结束，需要逐项核对以下内容，确认闭环：
- 全量放行条件是否满足：最后一批观测窗口内指标是否全部在阈值内，放行记录是否有判定人签字或确认。
- 回滚预案是否仍可用：全量后旧版本是否仍可切回，回滚所需的数据处置方案是否还有效；确认后归档，供后续发布参考。
- 观测指标是否回归基线：全量运行一段时间后，技术指标和业务指标是否回到发布前水平，有无持续性偏差。
- 遗留问题是否登记：发布过程中出现的未解决问题、临时绕行方案、待优化项，是否已登记并指定跟进人。
- 发布记录是否完整：批次推进表、放行记录、回滚记录（如有）是否齐全，能否支撑事后复盘。
收尾核对完成后，本次灰度发布才算结束。记录归档的价值在于，下一次同类变更可以直接复用批次设计和阈值设定，减少重复设计成本。
常见问题
灰度发布的第一批一定要从内部账号开始吗？
内部账号是常见起点，适合先验证功能正确性和基本可用性，但并非唯一选择。如果变更只影响特定区域用户，或系统已有成熟的白名单机制，也可以直接从可识别的白名单用户开始。选择首批范围的核心判断是：这批用户能否覆盖主要使用路径，出问题时影响面是否可控，以及能否快速获得有效反馈。内部账号的优势是反馈渠道直接、问题定位快；白名单用户或小比例流量的优势是更接近真实使用场景。
观测窗口内指标一直平稳，是否可以提前进入下一批？
不建议仅凭“看起来平稳”提前放量。观测窗口的长度是按业务周期设定的，短时间平稳可能只是尚未覆盖到高峰流量或特定请求组合。如果确实需要缩短窗口，应由发布负责人确认两点：本批已覆盖至少一个完整请求周期，且关键业务指标与技术指标均无劣化趋势。涉及交易、支付等场景时，提前放量的风险更高，稳妥做法是保持原定窗口，等覆盖高峰后再判定。
指标越界但未达到回滚条件，应该怎么处理？
这种情况属于观察区，处理方式是停止放量、延长观测，同时由发布负责人组织研发和运维排查原因。可以设定一个明确的观察时限，例如延长30分钟，并约定观察期内指标继续劣化到什么程度就转为回滚。观察期间要保留现场日志和指标快照，便于事后定位。如果劣化趋势明确、影响面在扩大，即使尚未触及原定阈值，发布负责人也可以直接判定回滚，阈值是判定依据，不是回滚的唯一前提。
数据结构或消息格式变更怎么做灰度？
这类变更不适合简单按流量比例灰度，因为新旧版本可能无法同时读写同一份数据。可行路径是先做兼容性设计，让新旧版本能并行处理同一份数据，再按正常批次推进；无法做到兼容时，采用停机窗口或双写迁移方案，把验证重点放在迁移脚本演练、数据一致性核对和回滚后的数据处置上。无论哪种方式，回滚预案都要写清楚新版本写入的数据如何识别和处理，避免回滚后新旧数据混用。
发布记录应该记到什么颗粒度，才够事后复盘？
至少覆盖每批的范围、观测指标实际值、判定结论、判定人和时间，以及异常时的处置动作。如果某批延长了观测或调整了放量比例，也要记录调整原因。记录的目的不是留痕本身，而是让没参与发布的人能还原“当时看到了什么、依据什么做的决定”。这些内容放进统一的工作项和文档中管理，比散落在聊天记录里更容易检索和复用；ONES 支持在工作项中记录发布批次与状态流转，并通过文档沉淀回滚预案和放行记录，具体字段和流程可按团队实际发布流程配置。
