部署流程指南（Deployment Guide）
文档编号：DOC-OPS-AM-02
版本：V1.0
创建日期：2026-08-11
维护人：听云（WCL） / TL
保密级别：🟢 可公开发布
关联文档：管理员操作手册 README、日常运维 SOP、备份恢复、监控告警、凭据管理、DIP1-EXT 外部服务集成指南
一、文档定位
本文件定义听云（WCL）执行的部署流程 SOP，覆盖首次部署、迭代部署、回滚三大场景。所有部署操作须经 TL 授权，听云执行，听码（WDE）不参与生产部署。
1.1 部署类型
| 类型 |
触发条件 |
频率 |
决策人 |
| 首次部署 |
子项目首次上线 |
1 次/子项目 |
TL + SPO |
| 迭代部署 |
版本发布 / Bug 修复 / 功能更新 |
按需 |
TL |
| 紧急部署 |
P0/P1 故障修复 |
按需 |
TL |
| 回滚部署 |
部署失败 / 严重 Bug |
按需 |
TL |
| 扩容部署 |
容量不足 / 性能优化 |
按需 |
TL |
1.2 部署原则
- TL 授权：所有生产部署须经 TL 明确授权（口头/OWLG/Issue）
- 备份先行：部署前必须备份（数据库 + 配置 + 镜像）
- 健康验证：部署后必须验证健康检查 + 业务流程
- 回滚预案：每次部署必须准备回滚方案
- OWLG 留痕：每次部署全流程记录到 OWLG
- 零中断：迭代部署优先蓝绿/滚动，避免服务中断
二、首次部署 SOP
2.1 部署前置条件
| # |
检查项 |
责任人 |
状态 |
| 1 |
听码（WDE）交付物完整（代码/迁移脚本/Dockerfile/docker-compose） |
WDE → WCL |
⬜ |
| 2 |
凭据清单已注册（credential-inventory.md 状态为 ACTIVE） |
TL + WCL |
⬜ |
| 3 |
.env.prod.local 已配置全部环境变量 |
TL |
⬜ |
| 4 |
外部服务已就绪（Cloudflare R2 / WhatsApp / Expo / Sentry） |
TL + WCL |
⬜ |
| 5 |
域名 / DNS / SSL 证书已配置 |
TL |
⬜ |
| 6 |
数据库实例已就绪 + 迁移脚本已审查 |
WDE → WCL |
⬜ |
| 7 |
监控告警已配置（指标 / 告警规则 / 通知渠道） |
WCL |
⬜ |
| 8 |
备份策略已落地（数据库 / 配置 / 镜像） |
WCL |
⬜ |
| 9 |
TL 部署授权（OWLG 编号） |
TL |
⬜ |
| 10 |
回滚预案已准备 |
WCL |
⬜ |
2.2 首次部署流程
T-1 日：完成全部前置条件检查
↓
T-1 日：TL 生成全部凭据 → 配置到 .env.prod.local / Secret
↓
T 日 09:00：听云启动部署
├─ 拉取代码（指定 commit）
├─ 构建镜像（docker build）
├─ 推送镜像（如使用镜像仓库）
├─ 执行 docker compose up -d
├─ 执行数据库迁移（alembic upgrade head）
├─ 执行种子数据脚本（如需要）
└─ 启动全部服务
↓
T 日 10:00：健康检查
├─ GET /health 返回 200
├─ 全部容器 Up
├─ 数据库连接正常
└─ 外部服务连通性正常
↓
T 日 10:30：业务流程验证
├─ 用户登录（JWT 验证）
├─ 文件上传（R2 验证）
├─ 推送发送（WhatsApp / Expo 验证）
├─ 错误监控（Sentry 验证）
└─ 关键业务路径走通
↓
T 日 12:00：部署完成报告
├─ 听云编写 ops/private/dip1/DIP1-生产环境部署完成报告.md
├─ 记录 OWLG-YYYYMMDD-NN
└─ 通知 TL
↓
T+1 日 09:00：24h 观察期结束
├─ 监控指标正常
├─ 无 P1+ 故障
└─ TL 同步至主仓 WLG（DLG-xx）
2.3 首次部署验证清单
三、迭代部署 SOP
3.1 迭代部署前置条件
| # |
检查项 |
责任人 |
| 1 |
听码（WDE）交付新版本（代码 + 迁移脚本 + 变更说明） |
WDE |
| 2 |
TL 审核代码 + 授权部署 |
TL |
| 3 |
变更影响评估（数据库 / 配置 / 接口） |
WCL |
| 4 |
备份当前生产环境（数据库 + 镜像） |
WCL |
| 5 |
回滚预案准备 |
WCL |
| 6 |
部署窗口确认（避开业务高峰） |
WCL + TL |
3.2 迭代部署流程（蓝绿部署）
T-1 日：完成前置条件 + 备份
↓
T 日部署窗口：
├─ 拉取新版本代码（指定 commit）
├─ 构建新镜像（tag: <version>-new）
├─ 启动新版本容器（green 环境，不接入流量）
├─ 健康检查 green 环境
├─ 执行数据库迁移（如需要，向前兼容）
├─ 切换流量到 green 环境
├─ 观察 15 分钟（监控 + 错误率）
└─ 停止 old 容器（保留 24h 用于回滚）
↓
T+1 日：观察期结束，清理 old 容器 + 镜像
3.3 迭代部署验证清单
四、回滚 SOP
4.1 回滚触发条件
| 触发条件 |
决策人 |
回滚类型 |
| 部署后健康检查失败 |
WCL |
立即回滚 |
| 部署后 30 分钟内 5xx 错误率 > 5% |
WCL |
立即回滚 |
| 部署后关键业务流程不可用 |
WCL + TL |
立即回滚 |
| 部署后 24h 内发现严重 Bug |
TL |
评估后回滚 |
| 数据库迁移导致数据问题 |
TL |
数据恢复 + 代码回滚 |
4.2 回滚流程
触发回滚条件
↓
听云立即记录 OWLG（标记为 P1）
↓
通知 TL（如未响应，听云可自主执行回滚）
↓
代码回滚：
├─ 停止新版本容器
├─ 启动旧版本容器（保留的 24h 内）
├─ 切换流量回旧版本
└─ 健康检查
↓
数据库回滚（如需要）：
├─ 评估迁移是否可向后回滚
├─ 如可回滚：alembic downgrade -1
└─ 如不可回滚：恢复备份（数据丢失风险）
↓
验证回滚成功
↓
24h 观察期
↓
编写回滚报告 + 复盘
4.3 回滚验证清单
五、扩容部署 SOP
5.1 扩容触发条件
| 触发条件 |
阈值 |
持续时间 |
| CPU 使用率 |
> 70% |
30 分钟 |
| 内存使用率 |
> 80% |
30 分钟 |
| 响应时间 |
> P99 2 秒 |
15 分钟 |
| 数据库连接数 |
> max × 70% |
15 分钟 |
| 磁盘使用率 |
> 75% |
立即 |
5.2 扩容流程
| 步骤 |
操作 |
责任人 |
| 1 |
听云发起扩容申请（OWLG） |
WCL |
| 2 |
TL 审批 + 资源确认 |
TL |
| 3 |
资源申请（云厂商控制台） |
TL |
| 4 |
配置更新（docker-compose 副本数） |
WCL |
| 5 |
滚动重启服务 |
WCL |
| 6 |
验证扩容效果 |
WCL |
| 7 |
监控 24h |
WCL |
六、部署记录要求
6.1 OWLG 记录要素
每次部署须在 OWLG 中记录：
| 要素 |
说明 |
| 部署类型 |
首次 / 迭代 / 紧急 / 回滚 / 扩容 |
| 部署版本 |
Git commit hash + 版本号 |
| 部署时间 |
开始时间 + 结束时间 |
| 变更内容 |
代码变更 + 数据库迁移 + 配置变更 |
| 验证结果 |
健康检查 + 业务流程验证 |
| 回滚情况 |
是否回滚 + 原因 |
| 观察期 |
24h 观察结果 |
6.2 部署报告（首次部署）
首次部署完成后，听云编写部署报告至 ops/private/<子项目>/ 目录：
- 文件名：
<子项目>-生产环境部署完成报告.md
- 内容：部署过程 + 配置变更 + 验证结果 + 容器状态
- 保密级别：🔴 私有（含部署细节）
- 同步规则：❌ 不同步公开仓
七、修订记录
| 版本 |
日期 |
修订人 |
修订内容 |
| V1.0 |
2026-08-11 |
DT |
初始化部署流程指南；定义首次/迭代/回滚/扩容四类部署 SOP；明确部署前置条件、流程、验证清单；定义回滚触发条件与流程 |
本文件为听云（WCL）执行部署操作的标准流程。所有部署须 TL 授权 + 备份先行 + 健康验证 + 回滚预案。