incident-runbook-templates

事故 Runbook 模板

生产就绪的事故响应 Runbook 模板，涵盖检测、分诊、缓解、解决和沟通。

何时使用本技能

• 创建事故响应流程
• 构建针对具体服务的 Runbook
• 建立升级路径
• 记录恢复流程
• 响应正在发生的事故
• 培训 on-call 工程师

核心概念

1. 事故严重级别

严重级别	影响	响应时间	示例
SEV1	完全中断、数据丢失	15 分钟	生产环境宕机
SEV2	严重降级	30 分钟	关键功能损坏
SEV3	轻微影响	2 小时	非关键缺陷
SEV4	极小影响	下一个工作日	外观问题

2. Runbook 结构

1. Overview & Impact
2. Detection & Alerts
3. Initial Triage
4. Mitigation Steps
5. Root Cause Investigation
6. Resolution Procedures
7. Verification & Rollback
8. Communication Templates
9. Escalation Matrix

详细模式与实战示例

详细的模式文档位于 references/details.md。当上述导航层级不够用时，请阅读该文件。

最佳实践

应该做的

• 保持 Runbook 更新 - 每次事故后都进行复盘
• 定期测试 Runbook - 游戏日、混沌工程
• 包含回滚步骤 - 始终留有退路
• 记录前提假设 - 步骤生效必须满足哪些条件
• 链接到仪表盘 - 在高压下快速访问

不应该做的

• 不要假设对方有背景知识 - 为凌晨 3 点的大脑写作
• 不要跳过验证 - 确认每一步都生效
• 不要忘记沟通 - 让利益相关者知情
• 不要独自处理 - 尽早升级
• 不要跳过事后复盘 - 从每次事故中学习

故障排查

Runbook 步骤在预发布环境有效，但在真实事故中失败

步骤往往假设了一些在健康环境中成立、但在故障期间不成立的前提条件。对于 Runbook 中的每条命令，都添加一个前置条件检查，以及一条“如果此命令失败该怎么办”的说明：

# Step: Check pod status
kubectl get pods -n payments

# Prerequisites: kubectl configured, kubeconfig points to correct cluster
# If this fails: run `aws eks update-kubeconfig --name prod-cluster --region us-east-1`
# Expected output: pods in Running state

On-call 工程师惊慌失措，不按顺序跳过步骤

在 Runbook 顶部添加一个与各章节编号对应的带编号检查清单，这样响应者在高压下无需阅读整份文档就能跟踪进度：

## Quick Checklist
- [ ] 1. Declare incident severity and open war room
- [ ] 2. Check service health (Section 4.1)
- [ ] 3. Check recent deployments (Section 4.1)
- [ ] 4. Roll back if deploy is suspect (Section 4.1)
- [ ] 5. Post initial notification to #payments-incidents
- [ ] 6. Escalate if > 15 min unresolved

Runbook 已过时——命令引用了旧的集群名称或端点

Runbook 会腐化，因为它们是手动更新的。在顶部加入“最后验证”日期和负责人，并添加一个 CI 检查，验证所有 curl 端点和 kubectl 上下文名称仍然有效：

## Runbook Metadata
| Field | Value |
|---|---|
| Last verified | 2024-11-15 |
| Owner | @platform-team |
| Review cadence | After every SEV1/SEV2 |

工程师埋头处理时，利益相关者的沟通被延误

指定一个专门的事故沟通者角色（与事故指挥官分开），其唯一职责就是发布状态更新。在沟通模板中添加一个固定的议程：

Update every 15 minutes (even if no new information):
- Current status (Investigating / Mitigating / Monitoring)
- Impact (what is broken, who is affected, % of traffic)
- What we are doing right now
- Next update in: 15 minutes

数据库 Runbook 命令在错误执行时导致额外停机

在破坏性 SQL 命令前添加明确的警告，并要求在执行前进行 dry-run 输出检查：

-- WARNING: This terminates active connections. Verify count first.
-- DRY RUN (check count before terminating):
SELECT count(*) FROM pg_stat_activity WHERE state = 'idle' AND query_start < now() - interval '10 minutes';

-- EXECUTE only after verifying count is reasonable (< 50):
SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE state = 'idle' AND query_start < now() - interval '10 minutes';

相关技能

• postmortem-writing - 解决事故后，使用事后复盘模板记录根因和预防措施
• on-call-handoff-patterns - 规范轮班交接，使接班的响应者能全面了解正在发生的事故