📚 课程目录第3章灰度发布基础操作流程

3. 灰度发布基础操作流程：环境搭建、流量切分策略、逐步放量比例设定、回滚机制

适用场景

新功能、新算法或模型上线前，需要在小范围真实用户中验证稳定性与效果。
存在多个并行版本（如A/B实验），需按用户、地域或设备渠道逐步扩大曝光。
对系统变更（配置、UI、API）的变更范围和影响需精确控制，降低全量发布风险。
已建立灰度基础设施（如网关、配置中心、Feature Flag平台）的团队可快速复用。

前置条件

已完成灰度发布平台的搭建或已接入第三方Feature Flag系统（如LaunchDarkly、Unleash）。
待发布的版本/配置已部署到生产环境的少数金丝雀节点或独立环境。
灰度策略定义清晰：按哪些维度切分（用户ID哈希、地域、设备类型、操作系统版本等）。
监控体系就绪：至少包括版本错误率、延迟P99、CPU/内存使用率、核心业务指标（转化率、下单量等）。
回滚预案已编写并经过预演：手动/自动回滚的命令、依赖同步、数据补偿方案。

操作步骤

环境搭建：在灰度发布平台创建发布任务，关联目标集群/命名空间。配置灰度分流规则（路由层或应用层）。
流量切分策略配置：依据业务需求选择一种或组合策略，定义分流规则。常用策略对比见下表。
逐步放量比例设定：初始放量1%～5%，观察15～30分钟；通过审核后提升至10%、25%、50%、75%、100%。每个台阶完成后需人工或自动审批。
灰度监控与决策：实时观察错误率、性能、业务指标。若指标超阈值则触发回滚或暂停。
全量发布或回滚：灰度验证通过后执行全量发布；异常时立即执行回滚机制。

流量切分策略对比

策略	实现方式	适用场景	注意事项
按用户ID（哈希取模）	对用户ID取模，将部分哈希值映射到灰度版本	需用户级细粒度控制，保证同一用户始终访问同一版本	用户ID需稳定；若用户量小，随机性不足
按地域	通过IP解析或用户属性中的地理位置	功能受法规限制或需本地化验证时	需维护地域白名单；IP库更新需同步
按设备（OS/机型/版本）	从UA或客户端上报中提取设备特征	兼容性测试或针对特定硬件做优化	设备标识可能变化；部分设备组合样本少

逐步放量比例设定示例

推荐台阶：1% → 5% → 10% → 25% → 50% → 75% → 100%。

每个台阶停留时间至少等同于一个业务观察周期（如15分钟或一个请求高峰时段）。

关键指标阈值：错误率上升超过0.5%或延迟P99增加20%即触发暂停。

# 示例：基于Nginx的流量切分配置（按用户ID取模）
upstream backend-v1 {
    server 10.0.1.10:8080;
}
upstream backend-v2 {
    server 10.0.2.10:8080;
}
split_clients "${http_x_user_id}" $version {
    5%     "v2";
    *      "v1";
}
location /api/ {
    proxy_pass http://backend-${version};
}

回滚机制

手动回滚：在灰度平台点击“回滚”按钮，自动将流量切回旧版本，并删除灰度配置。
自动回滚：配置监控告警规则，当错误率或性能指标超过阈值时，平台自动执行回滚并通知负责人。
数据库回滚：若灰度版本涉及数据迁移，需准备回退脚本或快照。
缓存清理：回滚后可能产生新旧版本缓存不一致，需主动清理CDN或本地缓存。

输入输出物

类型	输入物	输出物
环境	目标集群IP/域名、准入凭证	灰度分流规则配置文件（如YAML）、路由表
策略	用户ID白名单、地域白名单、设备特征库	灰度规则JSON（Feature Flag配置）
放量	初始比例、增长步长、审批人列表	灰度发布任务状态（待审批/进行中/已完成）
回滚	回滚脚本、数据回退SQL、缓存清除命令	回滚执行报告、新旧版本对比拉取结果

责任边界

开发/测试：提供灰度版本并验证基本功能；编写回滚脚本；确认灰度策略的准确性。
运维/SRE：负责环境搭建、监控配置、灰度发布平台操作；执行放量审批；监控指标报警。
产品/业务方：定义灰度维度（地域、用户群）；参与各台阶的验收；决策是否全量或回滚。
QA：在灰度环境中进行冒烟测试；验证灰度流量是否按预期切分；检查新旧版本数据一致性。

记录材料

灰度发布任务编号、发布时间、操作人、修改的配置项。
每个放量台阶的观察日志（指标截图或自动化检查结果）。
回滚操作的触发原因、执行时间、恢复到哪个版本。
灰度发布后复盘记录（问题、改进点）。

异常处理

常见异常及对策：

灰度流量切分不生效：检查路由规则缓存是否刷新；确认Feature Flag SDK版本是否匹配；通过CURL模拟请求测试。
监控指标突然飙升：立即暂停放量（手动关闭灰度开关）；查看灰度版本日志是否存在大量异常；执行回滚。
回滚后仍有部分用户访问旧版本：可能是本地浏览器缓存或CDN缓存未清除；强制走新域名或添加版本参数。
数据库表结构变更导致回滚失败：回滚前确认数据迁移脚本有回退能力；前期做好Schema版本管理。

验收标准

灰度配置正确：请求按预期比例/维度路由到新版本，日志中可验证。
各放量台阶均经过人工审批或自动化检查通过。
监控指标（错误率≤0.1%基线，P99延迟≤基线×1.2，业务指标无显著下降）全部合格。
回滚机制验证：从任意放量比例执行回滚后，所有流量在1分钟内切回旧版本，指标恢复至基线水平。
完整记录归档，包含所有操作步骤、截图、审批截图及复盘结论。