⚡

运行手册设计与编写Skill runbooks-structure

这个技能专注于创建和维护结构化操作运行手册，用于指导工程师进行系统故障排除、维护、事件响应和值班操作。关键词：运行手册、DevOps、操作手册、文档最佳实践、故障排除指南、事件响应流程、Kubernetes、云原生、自动化运维。

DevOps 0 次安装 0 次浏览 更新于 3/25/2026

name: 运行手册-结构 user-invocable: false description: 用于创建结构化操作运行手册供人类操作员使用。涵盖运行手册组织、文档模式和清晰操作程序的最佳实践。 allowed-tools:

  • Read
  • Write
  • Edit
  • Bash
  • Grep
  • Glob

运行手册 - 结构

创建清晰、可操作的运行手册，用于操作任务、维护和故障排除。

什么是运行手册？

运行手册是操作任务的逐步文档：

  • 故障排除 - 诊断和修复问题
  • 事件响应 - 处理生产事件
  • 维护 - 常规操作任务
  • 值班 - 值班工程师的参考

基本运行手册结构

最小可行运行手册

# 服务名称：任务/问题

## 概述
简要描述本运行手册涵盖的内容。

## 前提条件
- 所需访问/权限
- 需要的工具
- 所需知识

## 步骤

### 1. 第一步
第一行动的详细说明。

### 2. 第二步
第二行动的详细说明。

## 验证
如何验证任务是否成功完成。

## 回滚（如果适用）
如果需要，如何撤销更改。

全面运行手册模板

# [服务]：[任务/问题标题]

**最后更新：** 2025-01-15
**所有者：** 平台团队
**严重程度：** 高/中/低
**预计时间：** 15 分钟

## 概述

简要描述本运行手册解决的问题或任务。

## 何时使用此运行手册

- 警报触发：`high_cpu_usage`
- 客户报告：响应时间慢
- 计划维护窗口

## 前提条件

- [ ] VPN 访问生产网络
- [ ] AWS 控制台访问（读/写）
- [ ] kubectl 配置为生产集群
- [ ] Slack 访问 #incidents 频道

## 上下文

### 架构概述
简要说明相关系统架构。

### 常见原因
- 数据库连接池耗尽
- 工作进程内存泄漏
- 第三方 API 速率限制

## 诊断步骤

### 1. 检查系统健康

```bash
# 检查 pod 状态
kubectl get pods -n production

# 预期输出：所有 pod 处于 Running 状态

决策点： 如果 pod 处于 CrashLooping 状态，继续步骤 2。否则，跳过到步骤 3。

2. 检查应用程序日志

# 查看最近日志
kubectl logs -n production deployment/api-server --tail=100

寻找：

  • 包含“connection refused”的错误消息
  • 堆栈跟踪
  • 重复警告

3. 检查数据库性能

# 连接到 RDS 指标
aws cloudwatch get-metric-statistics \
  --namespace AWS/RDS \
  --metric-name DatabaseConnections \
  --dimensions Name=DBInstanceIdentifier,Value=prod-db

解决步骤

选项 A：重启服务（快速修复）

  1. 优雅地排空 pod：

    kubectl drain pod/api-server-abc123 --ignore-daemonsets

  2. 验证新 pod 是否健康：

    kubectl get pods -n production | grep api-server

  3. 监控 5 分钟： 在 Datadog 仪表板中检查错误率。

选项 B：扩展资源（长期修复）

  1. 增加数据库连接池：

    # 编辑 configmap
kubectl edit configmap app-config -n production

# 更改：DB_POOL_SIZE: "10"
# 改为：DB_POOL_SIZE: "20"

  2. 重启部署：

    kubectl rollout restart deployment/api-server -n production

  3. 监控滚动更新：

    kubectl rollout status deployment/api-server -n production

验证

  • [ ] 所有 pod 处于 Running 状态：kubectl get pods -n production
  • [ ] 错误率 < 1%：检查 Datadog 仪表板
  • [ ] 响应时间 < 200ms p95：检查 Datadog 仪表板
  • [ ] 无警报触发：检查 PagerDuty

回滚

如果修复导致问题：

# 回滚到上一个版本
kubectl rollout undo deployment/api-server -n production

# 验证回滚
kubectl rollout status deployment/api-server -n production

后续行动

  • [ ] 创建事后分析工单：JIRA-1234
  • [ ] 如果需要，更新监控警报
  • [ ] 安排事件后回顾
  • [ ] 将学到的内容记录在团队维基中

相关运行手册

示例格式：

- [数据库连接故障排除](./database-connections.md)
- [Pod 重启程序](./pod-restart.md)
- [事件响应指南](./incident-response.md)

联系信息

  • 主要值班： 检查 PagerDuty 时间表
  • 升级： 平台团队负责人
  • Slack 频道： #platform-incidents

修订历史

日期 作者 更改
2025-01-15 Alice 添加验证步骤
2025-01-10 Bob 初始版本 

## 运行手册组织

### 目录结构

runbooks/ ├── README.md # 所有运行手册的索引 ├── templates/ │ ├── troubleshooting.md # 故障排除模板 │ ├── maintenance.md # 维护任务模板 │ └── incident-response.md # 事件响应模板 ├── services/ │ ├── api-gateway/ │ │ ├── high-latency.md │ │ ├── connection-errors.md │ │ └── scaling.md │ └── database/ │ ├── slow-queries.md │ └── replication-lag.md ├── infrastructure/ │ ├── kubernetes/ │ │ ├── pod-restart.md │ │ └── node-drain.md │ └── networking/ │ └── firewall-rules.md └── on-call/ ├── first-responder.md ├── escalation-guide.md └── common-alerts.md


## 最佳实践

### 为清晰而写

```markdown
# 好：清晰、具体的步骤
## 重启 API 服务器

1. 检查当前 pod 状态：
   ```bash
   kubectl get pods -n production -l app=api-server

  1. 删除 pod（它将自动重启）：

    kubectl delete pod <pod-name> -n production

  2. 验证新 pod 是否运行：

    kubectl get pods -n production -l app=api-server

    预期：STATUS = Running


```markdown
# 差：模糊、假设知识
## 修复 API 问题

1. 重启那个东西
2. 检查是否工作
3. 如果不工作，试试别的

包括决策树

## 诊断

1. 检查服务是否响应：
   ```bash
   curl -f https://api.example.com/health

如果成功： 服务正常。检查应用程序日志（步骤 3）。 如果失败： 服务中断。检查 pod 状态（步骤 2）。

  1. 检查 pod 状态：

    kubectl get pods -n production

    如果 CrashLooping： 检查日志中的错误（步骤 4）。 如果 Pending： 检查节点资源（步骤 5）。 如果 Running： 服务应该正常。检查 DNS（步骤 6）。


### 提供预期输出

```markdown
## 检查数据库连接

```bash
psql -h prod-db.example.com -U app -c "SELECT 1"

预期输出：

 ?column?
----------
        1
(1 row)

如果看到“connection refused”：

  • 检查安全组是否允许流量
  • 验证数据库是否运行
  • 检查凭据在秘密管理器中

### 使用检查清单

```markdown
## 部署前检查清单

- [ ] 代码已审查和批准
- [ ] CI 中的测试通过
- [ ] 数据库迁移已测试
- [ ] 回滚计划已记录
- [ ] 监控警报已配置
- [ ] 值班工程师已通知
- [ ] 部署窗口已安排

常见模式

紧急响应

# 紧急：数据库中断

**时间敏感：** 在 5 分钟内完成

## 立即行动（首先执行）

1. **寻呼数据库团队：**
   使用 PagerDuty 事件：“数据库中断”

2. **通知利益相关者：**
   在 #incidents 中发布：“数据库中断。正在调查。”

3. **启用维护模式：**
   ```bash
   kubectl set env deployment/api-server MAINTENANCE_MODE=true

调查（等待时）

  1. 在 RDS 控制台检查实例状态
  2. 查看 CloudWatch 日志中的错误
  3. 检查部署历史中的近期更改

沟通模板

每 10 分钟在 #incidents 中更新：

[HH:MM] 数据库仍中断。数据库团队正在调查。 影响：所有 API 请求失败。 预计恢复时间：未知。


### 常规维护

```markdown
# 月度数据库维护

**时间表：** 每月第一个星期日，UTC 时间 2 AM
**持续时间：** 约 2 小时
**停机时间：** 无（滚动维护）

## 维护前

**1 周前：**
- [ ] 在 #engineering 中宣布维护窗口
- [ ] 创建日历事件
- [ ] 准备回滚计划

**1 天前：**
- [ ] 验证备份是否近期（< 24 小时）
- [ ] 测试备份恢复（暂存环境）
- [ ] 确认值班覆盖

## 维护步骤

1. **创建快照：**
   ```bash
   aws rds create-db-snapshot \
     --db-instance-identifier prod-db \
     --db-snapshot-identifier maintenance-$(date +%Y%m%d)

  1. 应用更新： 遵循 RDS 控制台更新向导

  2. 监控重启： 监控 CloudWatch 指标 15 分钟

维护后

  • [ ] 验证所有服务健康
  • [ ] 在 #engineering 中发布完成
  • [ ] 更新维护日志

### 知识转移

```markdown
# 新工程师入职：部署流程

## 学习目标

完成此运行手册后，您将：
- 了解我们的部署管道
- 知道如何部署到暂存环境
- 知道如何回滚不良部署

## 步骤 1：理解管道

我们的部署流程：

GitHub → CI（GitHub Actions）→ ArgoCD → Kubernetes


**练习：** 在 ArgoCD 中查看最近的部署

## 步骤 2：部署到暂存环境

**跟学：** 先观察资深工程师部署。

1. 创建功能分支
2. 打开拉取请求
3. 等待 CI 通过
4. 合并到主分支
5. 观察 ArgoCD 同步

**实践：** 将自己的更改部署到暂存环境。

## 步骤 3：部署到生产环境

**生产部署前要求：**
- [ ] 完成 3+ 次暂存部署
- [ ] 与团队负责人审查
- [ ] 阅读事件响应运行手册

**实操：** 与团队负责人配对进行第一次生产部署。

## 认证

- [ ] 完成 5 次暂存部署
- [ ] 完成 1 次生产部署（有监督）
- [ ] 能解释回滚程序

**认证人：** _________________ 日期：_______

反模式

不要遗漏上下文

## 差：无上下文

### 修复 API

运行此命令：
```bash
kubectl delete pod api-server-abc

好：解释原因

重启 API 服务器

何时使用： API 返回 500 错误，日志显示内存泄漏。

为什么有效： 删除 pod，Kubernetes 创建新 pod 以清除状态。

kubectl delete pod api-server-abc

预期： 新 pod 启动时约 30 秒停机时间。


### 不要跳过验证步骤

```markdown
# 差：无验证
## 部署新版本

1. 更新镜像标签
2. 应用更改
3. 完成！

# 好：包括验证
## 部署新版本

1. 更新 deployment.yaml 中的镜像标签
2. 应用更改：
   ```bash
   kubectl apply -f deployment.yaml

  1. 验证滚动更新：

    kubectl rollout status deployment/api-server

    等待“成功滚动更新”

  2. 检查 pod 健康：

    kubectl get pods -l app=api-server

    所有 pod 应显示 STATUS: Running

  3. 验证端点：

    curl https://api.example.com/health

    应返回 200 OK


### 不要假设知识

```markdown
# 差：使用未解释的行话
## 修复 Pod

检查 ingress 并确保服务网格正常工作。

# 好：解释术语
## 修复 Pod 连接性

1. **检查 ingress**（将流量路由到 pod 的负载均衡器）：
   ```bash
   kubectl get ingress -n production

  1. 验证服务网格（Istio，管理 pod 到 pod 通信）：

    kubectl get pods -n istio-system

    所有 Istio 控制平面 pod 应处于 Running 状态。


## 相关技能

- **故障排除指南**：创建诊断程序
- **事件响应**：处理生产事件