feat(ai-customer-service): add gate readiness verification and handoff docs
This commit is contained in:
Your Name
@@ -1,152 +1,144 @@
|
||||
# 灰度发布与回滚 Runbook
|
||||
|
||||
> 版本：v1.0 | 状态：初稿（待 TechLead 补充部署部分）
|
||||
> 关联：PRODUCTION_EXECUTION_PLAN.md、PRODUCTION_PHASE1_STATUS.md
|
||||
> 版本：v1.1
|
||||
> 状态：灰度门禁已定义，本地/容器化回滚演练已通过，待真实共享预生产/灰度环境演练
|
||||
> 关联：`docs/MONITORING_ALERTING.md`、`docs/GRAY_DASHBOARD_MINIMUM.md`、`docs/PREPROD_VERIFICATION_RECORD.md`、`docs/ROLLBACK_DRILL_RECORD.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 灰度发布策略
|
||||
## 1. 前提
|
||||
|
||||
### 1.1 灰度阶段定义
|
||||
开始任何灰度放量前，必须满足：
|
||||
|
||||
| 阶段 | 流量比例 | 持续时间 | 通过条件 |
|
||||
|------|----------|----------|----------|
|
||||
| 灰度 5% | 5% 新版本 / 95% 老版本 | 1-2 天 | 错误率 < 1%，无 P0/P1 问题 |
|
||||
| 灰度 20% | 20% 新版本 / 80% 老版本 | 2-3 天 | 错误率 < 0.5%，SLA 指标达标 |
|
||||
| 灰度 100% | 100% 新版本 | - | 灰度 20% 稳定 48h 后全量 |
|
||||
|
||||
### 1.2 灰度切换方式
|
||||
|
||||
**当前实现状态**：生产一期**灰度发布能力未落地**，尚无配置化灰度开关。
|
||||
|
||||
**临时方案**：通过 Kubernetes `Deployment` 副本数控制：
|
||||
- 灰度 5%：新版本 1 副本，老版本 19 副本
|
||||
- 灰度 20%：新版本 4 副本，老版本 16 副本
|
||||
- 全量：新版本 20 副本，老版本 0 副本
|
||||
|
||||
**正式方案（待实现）**：
|
||||
- 引入 feature flag 服务（LD / Apollo）
|
||||
- 按用户 ID、渠道、地区等维度灰度
|
||||
- 支持热开关，无需重启
|
||||
1. Gate B 已通过
|
||||
当前状态：**本地/容器化预演已通过，真实共享预生产环境待复跑**
|
||||
2. 最小鉴权已落地
|
||||
3. 工单闭环语义已收口
|
||||
4. 最小监控指标和阈值已定义
|
||||
|
||||
---
|
||||
|
||||
## 2. 灰度发布检查单
|
||||
## 2. 灰度放量节奏
|
||||
|
||||
### 2.1 发布前检查
|
||||
默认节奏如下：
|
||||
|
||||
- [ ] 所有 P0/P1 缺陷已关闭
|
||||
- [ ] 上一节 8 个 PM 文档已全部建立
|
||||
- [ ] 审计日志可查询、可追溯
|
||||
- [ ] PostgreSQL migration 已执行，数据完整
|
||||
- [ ] 运营后台可看到工单列表/统计
|
||||
- [ ] health/readiness 检查通过
|
||||
| 档位 | 流量占比 | 最短观察时间 | 进入条件 | 回退条件 |
|
||||
|------|----------|--------------|----------|----------|
|
||||
| Stage 1 | 5% | 30 分钟 | Gate B 通过，部署稳定，核心指标全绿 | 任一 P0/P1 指标触发 |
|
||||
| Stage 2 | 20% | 2 小时 | Stage 1 稳定，`5xx <= 0.5%`，`audit fail = 0` | 5xx > 1%、audit fail > 0、DB 异常 |
|
||||
| Stage 3 | 50% | 半天 | Stage 2 稳定，handoff 比率无异常升高 | 指标明显劣化或人工链路承压 |
|
||||
| Stage 4 | 100% | 次日 | Stage 3 稳定跨工作日，无新增 P0/P1 | 任一核心门禁不满足 |
|
||||
|
||||
### 2.2 发布后检查（每阶段完成后）
|
||||
说明：
|
||||
|
||||
- [ ] Webhook 可用率 ≥ 99.5%（当前无 metrics，**需补齐 P1**）
|
||||
- [ ] 错误率 < 0.5%（同上）
|
||||
- [ ] 转人工率 ≤ 15%
|
||||
- [ ] 工单创建/分配/解决链路可正常工作
|
||||
- [ ] 审计日志正常写入
|
||||
- [ ] 无新增 P0/P1 问题
|
||||
- **最短观察时间不是建议，是门禁**
|
||||
- 任意阶段都不允许跳级放量
|
||||
- 任意阶段出现 P0/P1 指标时，不继续放量
|
||||
|
||||
---
|
||||
|
||||
## 3. 回滚触发条件
|
||||
## 3. 放量前检查单
|
||||
|
||||
### 3.1 必须立即回滚的条件
|
||||
- [ ] 共享预生产环境已复跑 Gate B 脚本
|
||||
- [ ] 最近一次部署产物与验证记录关联清晰
|
||||
- [ ] `live` / `ready` 探针正常
|
||||
- [ ] PostgreSQL migration 版本与目标一致
|
||||
- [ ] webhook signed request 联调已通过
|
||||
- [ ] ticket / audit / dedup 验证通过
|
||||
- [ ] 灰度 dashboard 可查看 8 个最小指标
|
||||
|
||||
满足以下任意条件，立即启动回滚，无需审批：
|
||||
---
|
||||
|
||||
| 条件 | 说明 |
|
||||
## 4. 继续放量的判定条件
|
||||
|
||||
每个档位进入下一档前，必须满足：
|
||||
|
||||
1. `webhook 5xx <= 0.5%`
|
||||
2. `webhook reject` 没有异常升高
|
||||
3. `audit 写入失败数 = 0`
|
||||
4. `postgres 连接异常 = 0`
|
||||
5. `readiness down 次数 = 0` 或未影响流量池
|
||||
6. `单实例重启次数 <= 2 / 10 分钟`
|
||||
7. `handoff 比率 <= 25%` 或未高于基线 `2x`
|
||||
8. ticket 创建量与人工处理能力匹配，没有积压失控
|
||||
|
||||
---
|
||||
|
||||
## 5. 立即回滚条件
|
||||
|
||||
满足以下任意条件，立即回滚当前灰度版本：
|
||||
|
||||
| 条件 | 原因 |
|
||||
|------|------|
|
||||
| Webhook 可用率 < 95% | 大量请求失败 |
|
||||
| P0 安全漏洞被触发 | 如签名校验被绕过 |
|
||||
| PostgreSQL 数据损坏 | 审计/工单写入失败 |
|
||||
| 100% 请求返回 5xx | 服务完全不可用 |
|
||||
| 错误率 > 5% | 持续 5min 以上 |
|
||||
| Webhook 5xx `> 5%` 持续 5 分钟 | 服务主链不可接受 |
|
||||
| PostgreSQL 异常导致 `ready` 持续失败 | 核心依赖异常 |
|
||||
| Audit 写入失败数 `> 0` 且持续 5 分钟 | 合规/追溯链路断裂 |
|
||||
| Ticket 创建链路断裂 | 人工服务主链损坏 |
|
||||
| 全量 readiness down 或实例反复重启 | 当前版本不稳定 |
|
||||
|
||||
### 3.2 建议回滚的条件
|
||||
---
|
||||
|
||||
满足以下条件时，技术负责人评估是否回滚：
|
||||
## 6. 建议回滚条件
|
||||
|
||||
| 条件 | 说明 |
|
||||
出现以下情况时，停止继续放量并由 TechLead 决策是否回滚：
|
||||
|
||||
| 条件 | 处理 |
|
||||
|------|------|
|
||||
| 错误率 > 2% 持续 10min | 异常但未达必须回滚阈值 |
|
||||
| 特定渠道全部失败 | 如 Telegram webhook 全部报错 |
|
||||
| SLA 指标连续劣化 | 响应时间 P95 > 10s |
|
||||
|
||||
### 3.3 不需要回滚的条件
|
||||
|
||||
- 边缘渠道偶发超时（< 0.5%）
|
||||
- 非核心功能（如 knowledge base 搜索偶发无结果）
|
||||
- 新版本 warning 日志增加（不影响功能）
|
||||
| Webhook 5xx `> 1%` 持续 5 分钟 | 冻结当前档位，评估回滚 |
|
||||
| Handoff 比率高于基线 `2x` | 判断意图识别/降级是否异常 |
|
||||
| Reject 数持续高于 20% | 检查上游签名或渠道配置 |
|
||||
| 单实例重启次数过高 | 排查资源、崩溃或配置问题 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 回滚操作流程
|
||||
## 7. 回滚动作
|
||||
|
||||
### 4.1 当前状态
|
||||
### 7.1 立即动作
|
||||
|
||||
生产一期**自动回滚机制未落地**，依赖人工执行。
|
||||
1. 停止继续放量
|
||||
2. 将灰度比例回退到上一个稳定档位
|
||||
3. 若当前档位无稳定状态，直接回退到旧版本
|
||||
|
||||
### 4.2 手动回滚步骤（当前临时方案）
|
||||
### 7.2 回滚后必须检查
|
||||
|
||||
```bash
|
||||
# 1. 确认当前版本和历史版本
|
||||
kubectl rollout history deployment/ai-customer-service
|
||||
|
||||
# 2. 查看当前版本状态
|
||||
kubectl get pods -l app=customer-service
|
||||
|
||||
# 3. 回滚到上一版本
|
||||
kubectl rollout undo deployment/ai-customer-service
|
||||
|
||||
# 4. 确认回滚成功
|
||||
kubectl rollout status deployment/ai-customer-service
|
||||
|
||||
# 5. 确认旧版本 pod 运行正常
|
||||
kubectl get pods -l app=customer-service
|
||||
```
|
||||
|
||||
### 4.3 回滚后检查
|
||||
|
||||
- [ ] `/actuator/health` 返回 `{"status":"up"}`
|
||||
- [ ] `/actuator/ready` 返回 `{"status":"up"}`
|
||||
- [ ] 手动测试 webhook 消息接收
|
||||
- [ ] 确认审计日志正常写入
|
||||
- [ ] 确认工单 API 正常工作
|
||||
- [ ] `live` 正常
|
||||
- [ ] `ready` 正常
|
||||
- [ ] signed webhook 再次联调通过
|
||||
- [ ] ticket 创建恢复
|
||||
- [ ] audit 写入恢复
|
||||
- [ ] PostgreSQL 无新错误
|
||||
|
||||
---
|
||||
|
||||
## 5. 故障恢复后的重新发布
|
||||
## 8. 演练要求
|
||||
|
||||
当回滚后问题修复，需重新走灰度流程：
|
||||
Gate C 前至少完成一次回滚演练，且留下证据：
|
||||
|
||||
1. 问题根因分析完成
|
||||
2. 修复方案经过代码 review
|
||||
3. 在 staging/预发布环境验证
|
||||
4. 从灰度 5% 重新开始，不允许跳阶段
|
||||
1. 演练时间
|
||||
2. 演练版本
|
||||
3. 触发条件
|
||||
4. 回滚动作
|
||||
5. 回滚后验证结果
|
||||
|
||||
没有演练记录，不得宣称“可安全灰度放量”。
|
||||
|
||||
推荐入口：
|
||||
|
||||
- [scripts/verify_gate_c_rollback.sh](/home/long/project/立交桥/projects/ai-customer-service/scripts/verify_gate_c_rollback.sh)
|
||||
- 最近一次本地/容器化记录：[ROLLBACK_DRILL_RECORD.md](/home/long/project/立交桥/projects/ai-customer-service/docs/ROLLBACK_DRILL_RECORD.md)
|
||||
|
||||
---
|
||||
|
||||
## 6. 灰度期间监控（待实现）
|
||||
## 9. 当前状态结论
|
||||
|
||||
| 指标 | 当前状态 | 目标 |
|
||||
|------|----------|------|
|
||||
| Webhook 成功率 | 未监控 | P1 缺口 |
|
||||
| API 错误率 | 未监控 | P1 缺口 |
|
||||
| PostgreSQL 查询延迟 | 未监控 | P1 缺口 |
|
||||
| 工单未关闭积压 | 未监控 | P1 缺口 |
|
||||
| 签名校验失败率 | 未监控 | P1 缺口 |
|
||||
当前正确口径：
|
||||
|
||||
> **说明**：metrics/tracing/SLO 属于 P1 缺口，灰度前必须补齐，否则无法客观评估灰度质量。
|
||||
- **灰度门禁：已定义**
|
||||
- **本地/容器化 Gate B：已通过**
|
||||
- **本地/容器化 Gate C 回滚演练：已通过**
|
||||
- **真实共享预生产环境 Gate B：待复跑**
|
||||
- **Gate C 灰度监控与回滚演练：待完成**
|
||||
|
||||
---
|
||||
因此：
|
||||
|
||||
## 7. 当前版本状态
|
||||
|
||||
- **本文档版本**：v1.0
|
||||
- **生效日期**：2026-04-30
|
||||
- **下次审查**：灰度/回滚机制正式落地后
|
||||
> **现在可以说“灰度门禁框架已补齐”，但还不能说“灰度已经可执行上线”。**
|
||||
|
||||
Reference in New Issue
Block a user