部署步骤和发布 Runbook
目的
定义部署前、部署中、部署后的固定步骤，避免发布依赖个人记忆。
发布前检查
发布前检查要记录“验证了什么”，不要只记录命令名。
| 检查 | 目的 | JS/TS 示例 | 其他栈示例 |
|---|---|---|---|
| 合并前门禁 | 确认 format/lint/typecheck/test/build 通过 | pnpm check |
go test ./...、pytest && ruff check .、cargo test && cargo clippy |
| Migration 验证 | 确认 schema 变化能在目标版本执行 | pnpm db:migrate |
Alembic/Django/Flyway/SQLx/Diesel migration |
| 发布前 smoke | 验证关键业务闭环仍可用 | pnpm smoke:m1 |
项目定义的 smoke 脚本或 E2E smoke |
如果涉及 runtime daemon：
| 检查 | 目的 | JS/TS wrapper 示例 | 原生命令示例 |
|---|---|---|---|
| Runtime test | 验证 claim、heartbeat、状态转换、错误回传 | pnpm runtime:test |
go test ./...、cargo test、daemon package tests |
| Runtime build | 确认 worker/daemon 可发布 | pnpm runtime:build |
go build ./cmd/daemon、Docker image build |
如果涉及 provider 集成：
| 检查 | 目的 | 示例 |
|---|---|---|
| Witness test | 用 fixture 验证 webhook、签名、payload normalization、权限映射 | pnpm witness:test |
| Provider smoke | 调真实 provider 跑一次低风险闭环，验证凭证、网络、adapter、事件回传 | pnpm smoke:codex |
三角色发布职责
| 角色 | 发布前确认 | 发布后确认 |
|---|---|---|
| 产品负责人 | 用户影响、发布范围、沟通对象、Business Approver | 用户反馈、产品指标、是否需要后续 action |
| 技术负责人 | 技术风险、migration、回滚方式、是否允许上线 | 错误率、核心路径、是否需要技术债 |
| 平台 / 资深工程师 | CI、部署入口、dashboard、alert、smoke 命令 | 监控稳定、日志可查、发布记录完整 |
标准部署流程
确认 release scope
-> CI required checks 通过
-> migration plan 确认
-> feature flag / rollback plan 准备
-> 部署 API
-> 部署 Web
-> 部署 runtime daemon 或 worker
-> 执行 post-release smoke
-> 观察 dashboard 和 error rate
-> 发布通知到 Lark/Slack
部署证据
每次部署至少记录：
| 字段 | 说明 |
|---|---|
| Release id | version、commit 或 image digest |
| Owner | 发布负责人 |
| PRs | 包含哪些 PR |
| CI | required checks 链接 |
| Migration | 是否包含 schema 变化 |
| Flags | 开启/关闭哪些 feature flag |
| Smoke | 发布后验证结果 |
| Rollback | 回滚路径 |
| Dashboard | 监控链接 |
这些入口必须能从当前项目的 docs/PROJECT.md 找到。发布负责人不应该靠收藏夹、群聊历史或个人记忆找到发布系统和 dashboard。
数据库 Migration 策略
| 类型 | 要求 |
|---|---|
| Additive migration | 优先使用，先加字段/表，再逐步切流 |
| Destructive migration | 必须有备份、回滚计划、人工 approval |
| Backfill | 必须限速、可恢复、可观测 |
| Index migration | 大表必须评估锁和耗时 |
回滚流程
判断影响范围
-> 关闭 feature flag
-> 回滚 Web/API/image
-> 如需要，暂停 runtime daemon claim
-> 验证错误率和关键路径
-> 更新事故/发布记录
数据库回滚不能默认假设可逆。涉及数据删除或结构破坏时，应先做 forward fix 或恢复备份评估。
Lark/Slack 发布卡片
发布完成后发送：
版本：
Owner：
Commit：
PRs：
Migration：
Smoke：
Dashboard：
Rollback：
后续 Agent 就绪要求
这一节在人类发布流程稳定后再看。
Agent 可以参与发布前检查，但不应直接执行生产部署。允许的 Agent 动作：
- 汇总 release scope。
- 检查 checklist。
- 收集 CI/smoke 证据。
- 起草 release note。
- 标记风险项。
生产部署、回滚和 migration approval 由人类负责。
下一步阅读
读完或填完这份文档后，通常继续看：
- 53-可观测性SRE-observability-sre.md：发布和回滚明确后，继续看上线后如何观察和排障。