# 灰度发布与回滚 Runbook

> 版本：v1.0 | 状态：初稿（待 TechLead 补充部署部分）
> 关联：PRODUCTION_EXECUTION_PLAN.md、PRODUCTION_PHASE1_STATUS.md

---

## 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、渠道、地区等维度灰度
- 支持热开关，无需重启

---

## 2. 灰度发布检查单

### 2.1 发布前检查

- [ ] 所有 P0/P1 缺陷已关闭
- [ ] 上一节 8 个 PM 文档已全部建立
- [ ] 审计日志可查询、可追溯
- [ ] PostgreSQL migration 已执行，数据完整
- [ ] 运营后台可看到工单列表/统计
- [ ] health/readiness 检查通过

### 2.2 发布后检查（每阶段完成后）

- [ ] Webhook 可用率 ≥ 99.5%（当前无 metrics，**需补齐 P1**）
- [ ] 错误率 < 0.5%（同上）
- [ ] 转人工率 ≤ 15%
- [ ] 工单创建/分配/解决链路可正常工作
- [ ] 审计日志正常写入
- [ ] 无新增 P0/P1 问题

---

## 3. 回滚触发条件

### 3.1 必须立即回滚的条件

满足以下任意条件，立即启动回滚，无需审批：

| 条件 | 说明 |
|------|------|
| Webhook 可用率 < 95% | 大量请求失败 |
| P0 安全漏洞被触发 | 如签名校验被绕过 |
| PostgreSQL 数据损坏 | 审计/工单写入失败 |
| 100% 请求返回 5xx | 服务完全不可用 |
| 错误率 > 5% | 持续 5min 以上 |

### 3.2 建议回滚的条件

满足以下条件时，技术负责人评估是否回滚：

| 条件 | 说明 |
|------|------|
| 错误率 > 2% 持续 10min | 异常但未达必须回滚阈值 |
| 特定渠道全部失败 | 如 Telegram webhook 全部报错 |
| SLA 指标连续劣化 | 响应时间 P95 > 10s |

### 3.3 不需要回滚的条件

- 边缘渠道偶发超时（< 0.5%）
- 非核心功能（如 knowledge base 搜索偶发无结果）
- 新版本 warning 日志增加（不影响功能）

---

## 4. 回滚操作流程

### 4.1 当前状态

生产一期**自动回滚机制未落地**，依赖人工执行。

### 4.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 正常工作

---

## 5. 故障恢复后的重新发布

当回滚后问题修复，需重新走灰度流程：

1. 问题根因分析完成
2. 修复方案经过代码 review
3. 在 staging/预发布环境验证
4. 从灰度 5% 重新开始，不允许跳阶段

---

## 6. 灰度期间监控（待实现）

| 指标 | 当前状态 | 目标 |
|------|----------|------|
| Webhook 成功率 | 未监控 | P1 缺口 |
| API 错误率 | 未监控 | P1 缺口 |
| PostgreSQL 查询延迟 | 未监控 | P1 缺口 |
| 工单未关闭积压 | 未监控 | P1 缺口 |
| 签名校验失败率 | 未监控 | P1 缺口 |

> **说明**：metrics/tracing/SLO 属于 P1 缺口，灰度前必须补齐，否则无法客观评估灰度质量。

---

## 7. 当前版本状态

- **本文档版本**：v1.0
- **生效日期**：2026-04-30
- **下次审查**：灰度/回滚机制正式落地后
