Runbook + 知识库

Runbook 是什么

"凌晨 3 点被叫醒的那个人，第一眼能看懂、能动手做的步骤指南。"

它不是项目文档，不是架构图。它是面对一个具体告警 / 故障时，那一个人需要的：

这个告警是什么意思
第一步先看哪个仪表板
常见原因 1 / 2 / 3 + 各自怎么处理
怎么联系到上下游负责人
升级路径：自己搞不定找谁

一份 Runbook 的标准骨架

# Runbook: 付款 API 错误率告警

## 告警含义
付款 API HTTP 5xx 比例 > 1%（5 分钟窗口）

## 影响评估
快速看：
- Grafana 大盘 [链接]
- 当前请求量 + 错误率分布
- 影响地区 / 渠道

## 常见原因 + 处理

### 1. 数据库连接池耗尽（最常见）
症状：app 日志一片 connection refused
处理：
  - 临时：`kubectl scale deployment/payment --replicas=8`
  - 检查 RDS 监控，确认 master 没挂
  - 长期：增大 pool 配置（PR #xxx 模板）

### 2. 上游支付通道故障
症状：与某家通道相关的 trace 全部 timeout
处理：
  - 立即切到备用通道：`kubectl ... patch ...`
  - 通知商务联系对方
  - 客户公告（按预设模板）

### 3. 部署引入 bug
症状：错误率从某个时间点突然上升
处理：
  - kubectl rollout undo deployment/payment
  - 通知发版人
  - 进入 SEV-2 复盘

## 联系人
- 服务 Owner: @alice (SRE 群 / 飞书 #payment-sre)
- DBA on-call: @bob
- 上游通道商务: @carol

## 升级路径
30 分钟未恢复 → 升级到 Lead
1 小时未恢复 → 拉客服 + CTO

关键原则

1. 告警 → Runbook 链接是底线

每个告警必须带 Runbook URL：

# Prometheus 告警规则
- alert: HighErrorRate
  annotations:
    runbook_url: https://wiki/runbook/high-error-rate
    summary: "Error rate > 1% on {{ $labels.service }}"

凌晨被叫醒的人不该现想"该看哪里"——所有东西从告警一键跳过去。

2. 写得像 step-by-step 不是说明文

❌ "需要分析当前的连接池使用情况和上游服务健康度" ✓ "1. 打开 [Grafana 链接]；2. 看 'pool_active' 是否到上限；3. 如果到了，跑..."

3. 命令尽量可复制可粘贴

kubectl -n prod logs -l app=payment --tail=100 | grep ERROR

不是 "kubectl logs the payment pod and check errors"。

4. 每次事故后修一次 Runbook

postmortem 行动项里通常有"完善 Runbook"——真的去改。Runbook 是活文档，不是一次写完不动的。

自动化优先

"能自动化的就别让 on-call 手做。"

Runbook 步骤里"先扩容"——能不能自动 HPA？
"重启某 Pod"——能不能 livenessProbe 自动来？
"切到备用通道"——能不能 Circuit Breaker 自动切？

Runbook 只承载真的需要人判断的步骤。SRE Book 把这种"自动化能消灭的人工劳作"叫 Toil——值得专门花时间消灭。

Knowledge Base 整体架构

Runbook 只是知识库的一部分。完整架构：

公司 Wiki / Backstage / Notion
├── Runbooks（怎么处理告警 X）
├── ADR（Architecture Decision Records，重要决策为什么这么做）
├── Onboarding（新人怎么本地起服务）
├── Service Catalog（每个服务的 owner / SLO / 依赖）
├── Architecture Diagrams（系统总图）
├── Postmortems（历史事故）
└── How-to / FAQ（常见操作）

ADR：架构决策记录

# ADR-2026-001: 选用 Loki 而不是 ELK

**状态**：已采纳
**日期**：2026-04-12
**决策者**：@xxx, @xxx

## 背景
日志量增长，原 ELK 集群成本和运维负担都重。

## 选项
1. 升级 ELK 集群
2. 改用 Loki + Grafana
3. 用云商托管日志

## 决策
选 Loki：与已有 Grafana 集成自然，存储成本预期更低。

## 后果
- 全文搜索能力下降，已确认现有查询模式以标签过滤为主
- 团队需要学 LogQL（培训计划 ...）

ADR 让 6 个月后的人知道为什么决策成这样——不写就只能猜。

工具

Confluence / Notion：传统文档型，富文本
Backstage（Spotify 开源 → CNCF Incubating）：开发者门户 + TechDocs（git-based 文档）
MkDocs / Docusaurus / VitePress：静态生成器，docs-as-code
Git 仓库 + Markdown：最简最强，适合 SRE / 工程团队

选项越简单，越容易被维护。Notion 写 Runbook 比 Confluence 流畅——这种小事影响 Runbook 是否真的被更新。

反模式

"找老员工问"是公司主要知识源：bus factor 危险
Runbook 全在某个人脑子里：写下来或在重要事故里被坑
Wiki 上 1000 篇文档，最后修改时间 2 年前：定期审；老的归档或删
告警没 Runbook 链接 / 链接是 404：告警 review 时检查
不允许 Runbook 修错的人改：必须低门槛，任何人都能 PR