oncall-runbook

On-Call 值班手册技能

为一项服务编写完整的值班手册，让值班工程师在凌晨 3 点收到告警时，无需向任何人求助就能自信地响应。

优秀的值班手册能消除“我该先做什么？”这一难题，从而缩短平均解决时间（MTTR）。手册面向刚收到呼叫、需要立即采取行动的值班工程师，而不是悠闲阅读文档的人。

必要输入

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

• 服务名称及其功能
• 团队和技术负责人姓名
• 告警列表——当前会呼叫值班人员的告警名称
• 监控配置——Datadog / Grafana / CloudWatch / PagerDuty / 等
• 常见故障模式——最常出现的问题及其解决方法
• 升级联系人——值班人员无法解决问题时应联系谁
• 部署配置——值班人员能否回滚？如何操作？
• 服务依赖项——此服务依赖什么？又有哪些服务依赖它？

输出格式

---

值班手册：[Service Name]

团队：[Team name] | 技术负责人：[Name] PagerDuty 服务：[Link] | 升级策略：[Policy name] 上次更新：[Date] | 下次审查：[Date + 90 days]

**第一次为此服务值班？**请先阅读[开发者入职文档]，了解架构和系统的工作方式。本手册假设你已了解此服务。

---

快速参考

仪表板：[链接——收到呼叫后首先打开] 日志：[链接——查看日志的位置] **手册索引：**跳转到触发呼叫的告警 → [下方的告警列表] **30 分钟内无法解决？**请通过 [Slack / PagerDuty] 联系：[Name]

回滚命令（请记住）：

[rollback command — e.g. kubectl rollout undo deployment/[service-name]]

---

升级矩阵

情况	升级给	方式	多久后
无法诊断告警	[Tech lead name]	Slack 私信 / 电话	30 分钟
告警需要更改基础设施	[Platform team]	#platform Slack	立即
影响客户	[CSM / Support lead]	#incidents Slack	立即（P1）
数据库问题	[DBA or data team]	Slack / PagerDuty	立即
[Specific dependency] 宕机	[[Dependency] on-call]	PagerDuty / Slack	立即
长时间中断（>1 小时）	[Engineering manager]	电话	1 小时

联系人：

姓名	职务	Slack	电话
[Name]	技术负责人	@[handle]	[Number]
[Name]	工程经理	@[handle]	[Number]
[Name]	平台 / 基础设施	@[handle]	[Number]
[Platform team]	基础设施值班人员	#platform	PagerDuty

---

服务架构（概览）

[Upstream callers]
        │
        ▼
[This Service]
        │
        ├──→ [Primary Database]
        ├──→ [Cache — e.g. Redis]
        └──→ [Downstream Service / Queue]

如果此服务宕机，以下服务会受到影响：[下游使用方列表] 如果以下服务宕机，此服务会受到影响：[上游依赖项列表]

---

告警处理手册

告警：[Alert Name 1 — e.g. HighErrorRate]

含义：[通俗说明——例如：“最近 5 分钟内，超过 5% 的 API 请求返回了 5xx 错误”] **严重级别：**P1 / P2 / P3 **是否影响 SLO：**是 / 否 — [如果是：此告警表示错误预算正以 [X]× 的速率消耗]

步骤 1 — 确认并评估

# Check current error rate
[query or dashboard link]

# Check which endpoints are erroring
[query or command]

步骤 2 — 检查近期变更

# Any deploys in the last hour?
[command or link to deployment log]

# Recent config changes?
[where to check]

步骤 3 — 检查依赖项

# Is the database healthy?
[health check command or link]

# Is [downstream service] healthy?
[health check command or link]

步骤 4 — 诊断

如果看到	表示	操作
[Error pattern 1]	[Cause]	[Action]
[Error pattern 2]	[Cause]	[Action]
[Error pattern 3]	[Cause]	[Action]
没有明显规律	原因未知	联系 [name] 升级处理

步骤 5 — 修复或缓解

# If caused by bad deploy — roll back:
[rollback command]

# If caused by [specific issue]:
[fix command]

# If caused by upstream dependency:
[mitigation — e.g. enable circuit breaker, reduce traffic, etc.]

解决后：

• 确认错误率已恢复至基线
• 检查下游服务是否受到影响
• 如果是 P1：启动事件后审查——参阅 [incident-postmortem skill]
• 在 #incidents 中更新解决情况摘要

---

告警：[告警名称 2 — 例如 HighLatency]

含义：[例如“P99 响应时间连续超过 1 秒，且持续时间超过 3 分钟”] **严重级别：**P1 / P2 / P3 **SLO 影响：**是 — 延迟 SLO 违约

步骤 1 — 评估影响范围

# Check which endpoints are slow
[query or dashboard — broken down by endpoint]

# Check if latency is across all regions or localised
[query or command]

步骤 2 — 常见原因及解决方法

原因	信号	解决方法
数据库查询缓慢	仪表盘上显示 DB 延迟飙升	[检查慢查询日志：command]
缓存未命中风暴	仪表盘上显示缓存命中率下降	[命令或操作]
内存压力 / GC	服务仪表盘上显示内存占用高	[命令或操作 — 例如重启、扩容]
上游服务缓慢	跟踪记录显示耗时集中在外部调用	联系 [service] 值班人员升级处理
流量激增	仪表盘上显示请求速率飙升	[扩容：command]

步骤 3 — 20 分钟内未解决则升级处理 通过 PagerDuty / Slack 通知 [技术负责人]。

---

告警：[告警名称 3 — 例如 DatabaseConnectionPoolExhausted]

含义：[例如“服务已用尽所有可用的数据库连接 — 新请求将会失败”] **严重级别：**P1 **SLO 影响：**是 — 将立即导致错误

立即缓解：

# Restart the service to flush stale connections
[restart command]

# Check current connection count
[DB connection query]

稳定后诊断根本原因：

# Check for long-running queries holding connections
[query]

# Check if a recent deploy changed connection pool config
[where to check]

解决方法：[例如“在配置中增大连接池 / 终止长时间运行的查询 / 扩容服务”]

---

告警：[告警名称 4 — 例如 QueueBacklogHigh / ConsumerLag]

含义：[例如“消息队列积压超过 10,000 条 — 消费者处理速度跟不上”] **严重级别：**P2 **SLO 影响：**视情况而定 — 如果队列积压，下游系统将收到延迟的数据

步骤 1 — 检查消费者健康状况

# Are consumers running?
[command]

# Consumer error rate?
[dashboard or query]

步骤 2 — 检查消息内容

# Are there poison messages causing retries?
[command to inspect dead-letter queue or failed messages]

步骤 3 — 可选处理方式

如果	则
消费者已停止运行	重启消费者：[command]
队列中有毒消息	移至 DLQ：[command]
消费者运行正常但速度缓慢	扩容消费者：[command]
上游生产消息过快	联系 [上游服务] 负责人升级处理

---

告警：[按相同模式添加其他告警]

---

诊断速查表

用于快速诊断的常用命令。可直接粘贴并运行，无需修改。

# Service health
[health check command]

# Recent logs (last 100 lines)
[log command]

# Error logs only
[error log filter command]

# Current pod / instance status
[kubectl get pods / aws ecs describe-tasks / etc.]

# Restart the service
[restart command]

# Roll back to previous version
[rollback command]

# Database connection count
[DB query]

# Cache hit rate
[cache stats command]

# Current request rate
[metrics query]

---

实用仪表盘链接

仪表盘	URL	用途
服务概览	[Link]	首选入口 — 错误率、延迟、请求速率
数据库	[Link]	连接数、慢查询、复制延迟
基础设施	[Link]	CPU、内存、磁盘
队列 / 消费者	[Link]	积压深度、消费者吞吐量
上游依赖项	[Link]	一目了然地查看依赖项健康状况

---

事件沟通

宣布发生事件时：

立即在 #incidents 中发布：

🔴 INCIDENT — [Service Name]
Status: Investigating
Impact: [Who is affected and how]
Paged: [Your name]
Next update: [Time — max 30 min from now]

事件期间每 30 分钟更新一次：

🔴 UPDATE — [Service Name] — [Time]
Status: [Investigating / Identified / Mitigating / Resolved]
Latest: [One sentence on what you found or did]
Next update: [Time]

解决后：

✅ RESOLVED — [Service Name] — [Time]
Duration: [X minutes]
Impact: [Summary of who was affected]
Cause: [One sentence]
Follow-up: [PIR required? Yes/No — link when created]

---

值班交接

每次值班结束时使用此模板：

--- ON-CALL HANDOFF: [Service Name] ---
Date: [Date]
Outgoing: [Your name]
Incoming: [Next on-call name]

INCIDENTS THIS SHIFT:
- [Incident summary — date, duration, cause, resolution, follow-up required]

OPEN ISSUES TO WATCH:
- [Anything not fully resolved / trending in the wrong direction]

CHANGES SINCE LAST HANDOFF:
- [Deploys, config changes, infra changes that affect on-call awareness]

RUNBOOK GAPS FOUND:
- [Anything you had to figure out that isn't documented — please add it]

ANYTHING ELSE:
- [Notes for incoming on-call]

---

质量检查

• 每个会通知值班人员的告警都有对应的运行手册条目 — 不得遗漏任何告警
• 回滚命令准确无误，且近期已测试
• 升级联系人留有最新的电话号码和 Slack 用户名
• 诊断命令可正常运行 — 近期至少有一人执行过这些命令
• 每次换班时都使用交接模板 — 不仅限于发生事件时
• 每次事件结束后，都将“我不得不自行摸索但文档中未记录的事项”补充到此运行手册中

反模式

• 不要编写包含模糊诊断步骤（如“查看日志”）的告警操作手册——每个步骤都必须指定要运行的确切命令、仪表板链接或查询
• 不要在操作手册中加入没有具体值班操作的告警——没有明确响应路径却通知人员的告警，只会引发恐慌，而无法解决问题
• 不要让回滚命令没有文档记录或未经测试——从未执行过的回滚流程，会在最需要时失效
• 不要只列出升级联系人，却不提供电话号码和 Slack 用户名——在凌晨 3 点发生事故时，仅靠电子邮件的升级途径毫无用处
• 不要只编写一次操作手册，就把它当成永久文档——事故发生后，操作手册会逐渐过时；每次事故都必须触发对相关操作手册条目的审查