什么是runbook

什么是runbook

 

Runbook（直译为“运行手册”）是一套标准化的操作流程文档，用于指导工程师或系统在遇到特定事件（如系统故障、日常维护、紧急发布）时，按预定步骤快速、正确地完成任务。

你可以把它想象成飞机的紧急检查清单或消防员的灭火预案——在压力大、时间紧的情况下，无需思考“下一步做什么”，只需照着步骤执行。

Runbook 的核心内容

一份典型的 Runbook 包含：

• 触发条件：什么时候使用这份手册（例如“CPU 持续 5 分钟超过 90%”）

• 角色与权限：谁负责执行、需要哪些系统权限

• 详细步骤：命令行、API 调用、界面操作等，甚至包括截图

• 验证方法：如何确认每一步已成功

• 回滚方案：如果失败，如何撤销操作

• 联系人：升级路径（遇到问题找谁）

举例场景

问题：订单支付服务响应变慢。

Runbook 可能写：

1. 登录跳板机 ssh jump@prod

2. 运行 kubectl get pods -n payment 查看异常 Pod

3. 重启问题 Pod：kubectl delete pod <pod名>

4. 验证：运行 curl localhost:8080/health，预期返回 200

5. 若未恢复，按联系人列表通知 SRE 组长

为什么重要

• 降低人为错误：高压下不会漏步骤

• 加速恢复：无需现场查资料或调试

• 知识传承：老员工的经验被固化下来

• 合规：满足审计对操作可追溯的要求

与相关概念的区别

 

概念	侧重点	形式
Runbook	具体操作步骤	脚本、文档、流程图
Playbook（如 Ansible）	自动化配置管理	可执行的代码
SOP（标准作业程序）	通用业务/质量流程	通常为文档

在现代 DevOps 中，Runbook 正逐渐从纯文档演变为半自动化或全自动化（例如使用 Rundeck、StackStorm 等工具），称为 “Automated Runbook”。不过，即使全自动，背后依然遵循同一套逻辑：输入条件 → 执行步骤 → 验证输出。

如果你需要，我可以给出一份简单的 Runbook 模板，或说明如何编写第一个 Runbook。

 

Runbook 模板

 

下面是一份通用 Runbook 模板，你可以直接复制到文档（如 Confluence、Markdown 文件）中，根据实际场景填写。模板已按“故障排查”场景设计，稍加修改也适用于部署、回滚、备份等任务。

---

[Runbook 名称]

例如： 订单服务 CPU 飙升处理 Runbook

1. 基本信息

 

项目	内容
Runbook ID	RB-2025-001
适用系统/服务	订单服务 (order-api)
触发条件	CPU > 85% 持续 5 分钟 / 接口 P99 延迟 > 2s
预期效果	CPU 降至 50% 以下，恢复正常响应
风险等级	中（可能短暂影响部分请求）
维护人	张伟（SRE）
最后更新	2026-06-01

2. 前置准备

• 已登录跳板机 / Kubernetes 控制节点

• 拥有 kubectl、curl 权限，或已切换至 prod 命名空间

• 已知服务所在集群：k8s-prod-cluster

• 备好监控面板链接（如 Grafana 看板）

3. 诊断步骤（快速判断）

1. 查看 Pod 资源使用

   bash

   kubectl top pods -n order-ns --sort-by=cpu

2. 检查最近事件

   bash

   kubectl get events -n order-ns --sort-by='.lastTimestamp'

3. 查看日志错误高峰

   bash

   kubectl logs -l app=order-api -n order-ns --tail=100 | grep ERROR

4. 修复步骤

方案A（首选）：水平扩容

bash

kubectl scale deployment order-api -n order-ns --replicas=4

• 验证：kubectl get pods -n order-ns | grep order-api（状态全为 Running）

方案B（备选）：重启异常 Pod

bash

kubectl delete pod -l app=order-api -n order-ns

• 注意：会短暂中断请求（约10-30s），确保有重试机制。

方案C（最后手段）：限流降级

修改配置中心（如 Apollo）开启限流：

bash

curl -X POST config-service/update -d '{"order.rate.limit":100}'

5. 验证恢复

• CPU 使用率 < 50%

  bash

  kubectl top pods -n order-ns | grep order-api

• 接口测试正常

  bash

  curl -w "%{http_code}" https://order.example.com/health

• 查看告警是否消除（监控面板不再触发）

6. 回滚步骤（如果修复导致问题）

• 扩容回滚：kubectl scale deployment order-api -n order-ns --replicas=2

• 限流回滚：curl -X POST config-service/update -d '{"order.rate.limit":0}'（0 表示不限流）

7. 升级路径

 

情况	联系人	联系方式
无权限执行	SRE on-call	@sre-team（企业微信）
扩容后仍 CPU 高	架构组-李工	li@company.com
业务影响扩大	值班经理	123-4567（内部热线）

8. 事后记录（执行后填写）

• 执行时间：____

• 执行人：____

• 实际效果：☐ 成功 ☐ 失败 ☐ 部分成功

• 根本原因（如有）：____

• 改进建议：____

---

使用建议

• 首次使用前：把所有 order-api、order-ns 等示例占位符替换为真实资源名

• 定期演练：每季度模拟一次，验证步骤是否依然有效

• 自动化：将第4步的脚本放入 Rundeck/Ansible 中，变成“一键执行”

需要我帮你针对某个特定场景（如数据库备份、新版本回滚）定制一份模板吗？

本回答由 AI 生成，内容仅供参考，请仔细甄别。

 

新版本回滚

 

下面是一份专门针对新版本回滚场景的 Runbook 模板。适用于应用发布后出现严重 Bug、性能下降或数据异常时，快速恢复到上一个稳定版本。

---

[Runbook 名称]

例如： 订单服务 v2.3.0 回滚 Runbook

1. 基本信息

 

项目	内容
Runbook ID	RB-ROLLBACK-001
适用服务	订单服务 (order-api)
触发条件	新版本（v2.3.0）上线后出现： • 错误率 > 5% • P99 延迟 > 3s • 关键接口 500 错误 • 数据一致性告警
回滚目标	恢复至上一个稳定版本 v2.2.1
预期影响	服务中断约 30-60 秒，期间部分请求失败（需客户端重试）
风险等级	高（涉及数据兼容性）
维护人	李丽（发布负责人）
最后更新	2026-06-10

2. 前置准备

• 确认当前故障确实由新版本引起（对比旧版本监控基线）

• 确认上一个稳定版本的镜像/包仍然可用

  bash

  # 示例：检查镜像仓库
  docker pull registry.company.com/order-api:v2.2.1

• 通知相关方（产品、客服、运营）即将回滚

• 备份当前版本的配置与日志（用于事后分析）

• 打开数据库备份（如需回滚 schema）

3. 回滚步骤（按顺序执行）

3.1 流量切换（首选方案：K8s 镜像回滚）

bash

# 1. 修改 deployment 镜像版本
kubectl set image deployment/order-api order-api=registry.company.com/order-api:v2.2.1 -n prod

# 2. 等待滚动更新完成
kubectl rollout status deployment/order-api -n prod --timeout=2m

3.2 验证回滚状态

bash

# 查看 Pod 是否全部 Running
kubectl get pods -n prod -l app=order-api

# 查看镜像版本是否已回滚
kubectl describe deployment order-api -n prod | grep Image

3.3 数据库回滚（如新版本改了 schema）

⚠️ 谨慎操作：此步不可逆，需确认兼容性

sql

-- 示例：删除新版本新增的字段
ALTER TABLE orders DROP COLUMN new_discount_type;

-- 或恢复旧触发器/存储过程
SOURCE /backup/schema_v2.2.1.sql;

3.4 配置回滚（如使用配置中心）

bash

# 回滚到上一个配置版本（以 Apollo 为例）
curl -X POST http://apollo-service/rollback \
  -d 'appId=order-api&version=20260610_old'

4. 验证恢复

• 接口返回正常

  bash

  curl -w "%{http_code}" https://order.example.com/api/v1/health
  # 预期：200

• 错误率降至正常水平（< 0.1%）

• 核心业务场景测试通过

  bash

  # 示例：创建订单
  curl -X POST https://order.example.com/api/v1/order \
    -d '{"userId":123,"productId":456}' -H "Content-Type: application/json"

• 监控告警消除（观察 5 分钟）

5. 回滚失败应对（如果回滚后问题依旧）

 

问题	应对措施
Pod 启动失败（CrashLoopBackOff）	检查镜像是否存在、环境变量是否正确 → 执行第 6 节“强制回滚”
数据库不兼容	恢复全量数据库备份（需提前准备）
配置中心不可用	手动修改环境变量并重启 Pod
回滚后仍然高错误率	考虑保留现场，立即升级至 v2.2.2 修复版本（如有）

6. 强制回滚（如果普通回滚失效）

bash

# 直接替换 deployment 的 YAML
kubectl edit deployment order-api -n prod
# 手动将 image 改为 v2.2.1 并保存

# 或删除所有 Pod 强制重建
kubectl delete pods -l app=order-api -n prod

7. 升级路径（无法自行解决时）

 

情况	联系人	联系方式
K8s 操作受阻	平台组 on-call	@k8s-team
数据库回滚失败	DBA 老周	zhou@company.com
回滚后仍有业务影响	值班经理	400-xxx-xxx
需要紧急修复补丁	开发负责人 王工	wang@company.com

8. 事后记录（回滚完成后填写）

• 回滚执行时间：____

• 执行人：____

• 回滚是否成功：☐ 是 ☐ 否

• 根本原因（新版本问题）：____

• 影响时长：从故障发生到回滚完成共 ____ 分钟

• 改进措施：

  • 增加金丝雀发布阶段

  • 完善自动化测试覆盖

  • 本次回滚流程优化点：____

---

针对不同部署方式的补充说明

 

部署方式	回滚命令示例
Kubernetes	kubectl rollout undo deployment/order-api
Docker Compose	docker-compose down && docker-compose up -d（配合镜像版本标签）
Ansible	ansible-playbook rollback.yml -e version=v2.2.1
Terraform	terraform apply -var 'app_version=v2.2.1'
传统虚拟机	重启服务 + 替换二进制文件 + 重启 supervisor

最佳实践提醒

1. 提前演练：每季度在生产预发环境真实回滚一次

2. 保留历史版本：至少保留最近 5 个稳定镜像/包

3. 回滚窗口：尽量在低峰期（如凌晨）执行，但故障时优先恢复

4. 全自动回滚：结合监控系统（Prometheus + 告警）自动触发回滚

需要我针对你的具体部署环境（比如 ECS、K8s、Serverless）进一步调整模板吗？