summary
2023-04-08 15:23，腾讯云收到云 API 服务异常告警，随后工单、售后群与微博大量反馈控制台登录不上。根因是云 API 服务新版本向前兼容性考虑不够、配置数据灰度机制不足：本次 API 升级中接口协议变化，后台发布新版本后对旧版本前端传来的数据处理逻辑异常，生成了一条错误配置数据，因灰度机制不足迅速扩散到全网地域，造成整体 API 使用异常，依赖云 API 的云函数、文字识别、微服务平台、音频内容安全、验证码等也不可用。故障持续近 87 分钟，1957 个客户报障。
timeline
15:23 告警，立即恢复并尝试排查。15:47 发现回滚版本未能完全恢复，进一步定位。15:57 定位根因为配置数据错误，设计修复方案。16:02 全地域数据修复，API 逐地域恢复。16:05 观测到除上海外地域已恢复，定位上海技术组件存在 API 循环依赖。16:25 上海经流量调度至其他地域恢复。16:45 上海恢复，API 与依赖 API 的 PaaS 彻底恢复；控制台流量剧增，按 9 倍容量扩容。16:50 请求量恢复常态。17:45 持续观察一小时无问题，按预案结束。
root_cause
云 API 升级后新版本接口协议变化，对旧版本前端传入的数据处理逻辑异常，生成一条错误配置数据；灰度机制不足使该错误数据快速扩散到全网地域，控制面（控制台与云 API）整体异常。回滚时又因承载 API 的容器平台自身依赖 API 调度（循环依赖），无法自动拉起，需人工启动。
amplifiers
① 兼容性缺口：新版本未充分处理旧前端数据，产生错误配置。② 灰度缺失：错误数据无灰度即全量扩散。③ 循环依赖：API 容器平台依赖 API 自身调度，回滚后无法自动拉起，需人工。④ 恢复洪峰：控制台恢复后流量 9 倍激增，需紧急扩容。
mitigation
标准回滚将后台与配置数据同时回滚旧版本并重启 API；因循环依赖改人工启动；全地域数据修复+上海流量调度；控制台按 9 倍扩容。后续提升系统韧性、强化变更管理与保护、增强故障响应与沟通。
lessons
API 升级必须保持向前兼容并充分沙箱验证；配置变更须灰度发布；控制面组件不得循环依赖自身；回滚预案须覆盖依赖闭环。
checklist
① API 版本变更强制向前兼容+沙箱演练。② 配置数据灰度发布与回滚。③ 消除控制面循环依赖（或使用带外调度）。④ 回滚预案演练覆盖依赖闭环场景。