cicd-playbook

CI/CD Playbook 技能

为服务或团队编写一份完整、可执行的 CI/CD 操作手册，涵盖新工程师理解、参与并安全运维流水线所需的一切内容。

好的操作手册不是一张图，而是一份能回答以下问题的文档：运行什么、何时运行、为何运行、由谁负责，以及出故障时该怎么做。

所需输入

如果尚未提供，请询问以下信息：

• 服务名称和简要描述
• 技术栈——语言、框架、容器化方式（Docker 等）
• 源代码管理——GitHub / GitLab / Bitbucket、分支策略
• CI 平台——GitHub Actions / CircleCI / Jenkins / BuildKite / 其他
• CD 平台 / 部署目标——Kubernetes、ECS、Lambda、Heroku、VM 等
• 环境——例如 dev、staging、production（以及任何 canary / feature 环境）
• 部署频率——团队多久发布一次？
• 现有门禁——人工审批、冒烟测试、功能标志
• 值班安排——部署期间由谁负责？

输出格式

---

CI/CD 操作手册：[服务名称]

服务：[名称] | 团队：[团队名称] 最后更新：[日期] | 负责人：[姓名 / 角色] 流水线平台：[CI 工具] → [CD 工具 / 平台]

---

概述

[用 2–3 句话描述此服务的功能，以及 CI/CD 流水线采用当前结构的原因。包括部署目标和团队的发布频率。]

部署频率：[每天多次 / 每日 / 每周 / 按需] 流水线平均耗时：[X 分钟] 回滚时间（p95）：[X 分钟]

---

流水线阶段

[Branch push]
    │
    ▼
[1. Build & Lint] ──fail──▶ ❌ Block PR
    │
    ▼
[2. Unit Tests] ──fail──▶ ❌ Block PR
    │
    ▼
[3. Integration Tests] ──fail──▶ ❌ Block PR
    │
    ▼
[4. Security Scan] ──fail──▶ ⚠️ [Block / Warn — specify]
    │
    ▼
[5. Build Artefact / Container Image]
    │
    ▼
[6. Deploy to Staging] ──fail──▶ ❌ Block promotion
    │
    ▼
[7. Smoke Tests (Staging)]
    │
    ▼
[8. Manual Approval Gate] ──(if required)
    │
    ▼
[9. Deploy to Production] ──fail──▶ 🔁 Auto-rollback (if configured)
    │
    ▼
[10. Post-deploy checks]

---

阶段定义

阶段 1 — 构建与代码检查

运行内容：[构建命令] + [代码检查工具——例如 ESLint、golangci-lint、flake8] **触发条件：**任何分支上的每次提交 **是否阻断：**是 — 此阶段失败时，PR 无法合并 典型耗时：[X 分钟] **失败时的负责人：**PR 作者

常见失败原因：

• [例如：缺少依赖——推送前在本地运行 npm install]
• [例如：违反代码检查规则——运行 npm run lint --fix 自动修复大多数问题]

---

阶段 2 — 单元测试

运行内容：[测试命令——例如 npm test、go test ./...、pytest] **覆盖率门槛：**至少 [X]%——低于此阈值时流水线失败 **触发条件：**每次提交 **是否阻断：**是 典型耗时：[X 分钟]

覆盖率报告：[查看位置——例如上传至 Codecov，可在 CI 构件中查看]

---

阶段 3 — 集成测试

运行内容：[测试套件说明——例如“使用 Docker Compose，通过测试数据库运行 API 集成测试”] 环境：[临时测试环境 / 共享测试数据库 / 等] **触发条件：**向 main 提交，以及针对 main 的功能分支上的每次提交 **是否阻断：**是 典型耗时：[X 分钟]

运行缓慢时：[例如：“可在本地使用 SKIP_INTEGRATION=true 跳过集成测试——在 CI 中绝不能跳过”]

---

阶段 4 — 安全扫描

工具：[例如 Snyk、Trivy、OWASP Dependency Check、Semgrep] 检查内容：[依赖漏洞 / SAST / 密钥检测——列出适用项] **阻断条件：**发现严重和高危问题 **不阻断条件：**发现中危和低危问题（会标记，但不阻断） **触发条件：**向 main 提交的每次提交

处理标记出的漏洞：

1. 检查是否有可用修复——升级依赖
2. 如果没有可用修复，则创建安全工单，并添加带有理由的抑制规则
3. 没有工单和负责人时，绝不能抑制问题

---

阶段 5 — 构建构件

生成内容：[Docker 镜像 / 二进制文件 / zip 文件——请具体说明] 镜像仓库：[ECR / GCR / Docker Hub / Artifactory — URL] 标签约定：[service-name]:[git-sha]（在 main 上也标记为 :latest） **触发条件：**仅在向 main 提交时触发（不适用于功能分支）

---

阶段 6 — 部署到预发布环境

部署方式： [例如 Helm upgrade / kubectl apply / ecs deploy / Terraform apply] 预发布环境 URL： [URL] 触发条件： 从 main 成功构建制品后自动触发 谁可以部署到预发布环境： 任何工程师（自动）

环境变量： 在 [Vault / AWS SSM / GitHub Secrets / 等] 中管理 预发布环境不等于生产环境： [在此说明配置、规模或数据上的任何差异]

---

阶段 7 — 烟雾测试（预发布环境）

运行内容： [说明 — 例如“10 个关键路径测试，涵盖登录、核心 API 端点和支付流程”] 工具： [例如 Playwright / Postman / 自定义脚本] 通过标准： 所有烟雾测试均在 [X 秒] 超时限制内通过 是否阻止发布： 是 — 如果烟雾测试失败，则不会继续部署到生产环境

烟雾测试套件位置： [测试文件或文件夹链接]

---

阶段 8 — 人工审批关卡

适用范围： [生产环境部署 / 影响超过 X% 流量的部署 / 部署到特定区域] 谁可以审批： [例如团队中的任何工程师 / 首席工程师 / 值班工程师] 审批超时： [例如 24 小时 — 如果未获审批则自动取消] 如何审批： [GitHub Actions 审批步骤 / Slack 命令 / 其他方式 — 附链接]

以下情况请暂缓审批：

• 生产环境中存在正在处理的事故
• 部署不在部署时段内（见下文）
• 尚未通知值班工程师

---

阶段 9 — 部署到生产环境

部署方式： [与预发布环境相同或不同 — 请注明] 部署时段： [例如 UTC 时间周一至周四 09:00–16:00 — 周五或银行假日前不部署] 金丝雀 / 渐进式发布： [是 — 初始流量占比 X%，Y 分钟后全面发布 / 否 — 全量部署] 部署通知： [Slack 频道 — #deployments]

部署期间的值班人员： 在部署后的检查通过之前，由负责部署的工程师承担责任。

---

阶段 10 — 部署后检查

自动检查（部署后运行 [X 分钟]）：

• 错误率：<[X]%（基线：[Y]%）
• P99 延迟：<[X]ms（基线：[Y]ms）
• [关键业务指标]：与基线相比在 [X]% 范围内

监控位置： [Datadog / Grafana / CloudWatch 仪表板 — 链接]

如果检查失败： 请参阅下文的回滚流程。

---

环境

环境	用途	部署触发条件	URL	数据
开发环境	本地开发	手动	localhost	已填充的测试数据
预发布环境	生产前验证	自动（main）	[URL]	匿名化的生产环境副本
生产环境	线上流量	人工审批	[URL]	线上数据

---

分支策略

模式： [主干开发 / GitFlow / GitHub Flow — 简要说明]

分支	用途	谁合并	部署目标
main	可用于生产环境的代码	PR + 审查	预发布环境 → 生产环境
feature/*	功能开发	作者	无（仅运行 CI）
hotfix/*	生产环境关键修复	首席工程师	经审批后可跳过预发布关卡

紧急修复流程： [说明何时以及如何使用紧急修复分支 — 哪种级别的事故足以跳过标准流程]

---

回滚流程

自动回滚： [是 — 部署后错误率超过 [X]% 时触发 / 否 — 仅手动回滚]

手动回滚步骤：

# 1. Identify the last known good image tag
[command to list recent deployments]

# 2. Deploy the previous version
[deployment command with previous tag]

# 3. Confirm rollback is live
[smoke test command or health check URL]

# 4. Notify the team
[Slack command or template]

回滚决策权限： 任何值班工程师都可以发起回滚，无需等待审批。

回滚后：

1. 创建部署后事故报告（参见 [incident-postmortem skill]）
2. 未修复根本原因前，不要重新部署相同的提交
3. 通知 [相关方 / 支持团队] 已回滚及预计修复时间

---

密钥和配置管理

密钥存储： [Vault / AWS SSM / GitHub Secrets / Doppler — 请注明] 如何添加新密钥：

1. [步骤 1]
2. [步骤 2] 谁有访问权限： [角色或团队] 轮换策略： [密钥轮换频率及负责人]

切勿： 将密钥提交到源代码管理中，即使是 .env 文件也不行。流水线包含密钥扫描（第 4 阶段），会标记此类问题。

---

常见故障及修复方法

故障	可能原因	修复方法
构建失败，提示 "module not found"	未安装依赖项	运行 [install command] 并提交 lock file
集成测试超时	测试数据库未填充数据／外部服务不可用	检查 [service] 状态；重新运行流水线
暂存环境部署后冒烟测试失败	缺少环境变量	检查 [config location]；比较暂存环境和生产环境的环境变量
生产环境部署卡在审批环节	未通知审批人	在 #deployments 中标记 @[on-call handle]
部署后错误率飙升	部署不良／上游依赖项异常	检查 [dashboard]；若持续超过 5 分钟，则启动回滚

---

部署期间的值班职责

• 负责部署的工程师须在生产环境部署后 [X 分钟] 内监控部署后检查
• 如果你无法在部署后进行监控，请在 #deployments 中明确交接给另一位工程师
• 工作时间以外的部署：仅限热修复 — 部署前务必通知值班工程师

---

反模式

• 不要描述从未测试过的回滚流程 — 理论上的回滚不算回滚计划；应在生产环境部署前先在暂存环境中测试
• 不要在周五或节假日前部署，除非有明确负责整个周末监控的值班工程师
• 不要将密钥提交到源代码管理中，即使是在非生产分支中也不行 — 流水线中的密钥扫描会发现此问题，但预防才是标准做法
• 生产环境部署后不要跳过监控 — 负责部署的工程师必须在指定的观察时段内监控错误率和延迟
• 不要在没有关联工单和明确负责人时忽略安全扫描发现的问题 — 缺乏问责的忽略处理会不断累积，形成无人管理的风险

质量检查

• 每个阶段在失败时都有明确的负责人
• 回滚流程已经过测试 — 不是纸上谈兵
• 密钥管理部分注明了实际使用的工具（而非“使用密钥管理”）
• 部署时段明确具体 — 不能写“工作时间内”
• 部署后检查阈值已根据实际基线指标进行校准

示例触发短语

• “记录 CI/CD 流水线。”
• “编写部署流程。”
• “定义发布门禁。”
• “记录构建和测试阶段。”
• “创建部署指南。”