runbook-generator

name	runbook-generator
description	运维手册生成器

运维手册生成器 (Runbook Generator)

等级： 强大 (POWERFUL)
类别： 工程
领域： DevOps / 站点可靠性工程 (SRE)

---

概述

分析代码库并生成生产级的运维手册 (Runbooks)。自动检测你的技术栈（CI/CD、数据库、托管、容器），然后生成包含复制粘贴命令、验证检查、回滚流程、升级路径和时间预估的分步手册。通过与配置文件修改日期关联的过期检测，保持手册内容的时效性。

---

核心能力

• 技术栈检测 — 从代码库文件中自动识别 CI/CD、数据库、托管和编排方式。
• 手册类型 — 部署、事故响应、数据库维护、扩容、监控设置。
• 格式规范 — 编号步骤、可复制粘贴的命令、✅ 验证检查、时间预估。
• 升级路径 — 包含联系信息和决策标准的 L1 → L2 → L3 路径。
• 回滚流程 — 每个部署步骤都有对应的撤销操作。
• 过期检测 — 手册章节引用配置文件；当源文件更改时标记提醒。
• 测试方法论 — 用于分段环境 (Staging) 验证的演练框架，每季度审阅机制。

---

使用场景

适用于：

• 代码库没有运维手册，需要快速初始化。
• 现有手册已过时或不完整（指向仓库，重新生成）。
• 新工程师入职，需要清晰的运维流程。
• 准备事故响应演习或审计。
• 从零开始设置监控和值班轮换。

跳过场景：

• 系统处于早期阶段，尚未形成稳定的运维模式。
• 手册已存在且只需微调（直接编辑）。

---

技术栈检测

给定仓库后，在编写任何手册内容前先扫描以下信号：

# CI/CD
ls .github/workflows/     → GitHub Actions
ls .gitlab-ci.yml         → GitLab CI
ls Jenkinsfile            → Jenkins
ls .circleci/             → CircleCI
ls bitbucket-pipelines.yml → Bitbucket Pipelines

# 数据库
grep -r "postgresql\|postgres\|pg" package.json pyproject.toml → PostgreSQL
grep -r "mysql\|mariadb"           package.json               → MySQL
grep -r "mongodb\|mongoose"        package.json               → MongoDB
grep -r "redis"                    package.json               → Redis
ls prisma/schema.prisma            → Prisma ORM (检查 provider 字段)
ls drizzle.config.*                → Drizzle ORM

# 托管
ls vercel.json                     → Vercel
ls railway.toml                    → Railway
ls fly.toml                        → Fly.io
ls .ebextensions/                  → AWS Elastic Beanstalk
ls terraform/  ls *.tf             → 自建 AWS/GCP/Azure (检查 provider)
ls kubernetes/ ls k8s/             → Kubernetes
ls docker-compose.yml              → Docker Compose

# 框架
ls next.config.*                   → Next.js
ls nuxt.config.*                   → Nuxt
ls svelte.config.*                 → SvelteKit
cat package.json | jq '.scripts'   → 检查 build/start 命令

将检测到的技术栈映射到手册模板。一个 Next.js + PostgreSQL + Vercel + GitHub Actions 的仓库需要：

• 部署手册 (Vercel + GitHub Actions)
• 数据库手册 (PostgreSQL 备份、迁移、vacuum)
• 事故响应 (包含 Vercel 日志 + pg 查询调试)
• 监控设置 (Vercel Analytics, pg_stat, 告警)

---

手册类型

1. 部署手册 (Deployment Runbook)

# 部署手册 — [应用名称]
**技术栈：** Next.js 14 + PostgreSQL 15 + Vercel  
**最后验证日期：** 2025-03-01  
**源配置：** vercel.json (修改时间: git log -1 --format=%ci -- vercel.json)  
**负责人：** 平台团队  
**预计总耗时：** 15–25 分钟  

---

## 部署前检查清单
- [ ] 所有 PR 已合并到 main
- [ ] main 分支 CI 通过 (GitHub Actions 绿色)
- [ ] 数据库迁移已在分段环境测试
- [ ] 回滚计划已确认

## 步骤

### 步骤 1 — 在本地运行 CI 检查 (3 分钟)
```bash
pnpm test
pnpm lint
pnpm build

✅ 预期：全部通过，0 错误。.next/ 目录下有构建产物。

步骤 2 — 执行数据库迁移 (5 分钟)

# 先在分段环境执行
DATABASE_URL=$STAGING_DATABASE_URL npx prisma migrate deploy

✅ 预期：All migrations have been successfully applied.

# 验证迁移已应用
psql $STAGING_DATABASE_URL -c "\d" | grep -i migration

✅ 预期：迁移表显示今天日期的条目。

步骤 3 — 部署到生产环境 (5 分钟)

git push origin main
# 或者手动触发：
vercel --prod

✅ 预期：Vercel 控制台显示部署中。URL 格式为： https://app-name-<hash>-team.vercel.app

步骤 4 — 生产环境冒烟测试 (5 分钟)

# 健康检查
curl -sf https://your-app.vercel.app/api/health | jq .

# 核心路径
curl -sf https://your-app.vercel.app/api/users/me \
  -H "Authorization: Bearer $TEST_TOKEN" | jq '.id'

✅ 预期：health 返回 {"status":"ok","db":"connected"}。Users API 返回有效的 ID。

步骤 5 — 监控 10 分钟

• 检查 Vercel Functions 日志是否有错：vercel logs --since=10m
• 检查 Vercel Analytics 中的错误率：< 1% 5xx
• 检查数据库连接池：SELECT count(*) FROM pg_stat_activity; (< 80% of max_connections)

---

回滚

如果冒烟测试失败或错误率激增：

# 通过 Vercel 即时回滚（首选 — < 30 秒）
vercel rollback [previous-deployment-url]

# 数据库回滚（仅当迁移已应用时）
DATABASE_URL=$PROD_DATABASE_URL npx prisma migrate reset --skip-seed
# 警告：这会重置到上一次迁移。请先确认对数据的影响。

✅ 回滚后预期：上一个部署 URL 变为活跃状态。通过冒烟测试验证。

---

升级

• L1 (值班工程师)： 检查 Vercel 日志，运行冒烟测试，尝试回滚
• L2 (平台负责人)： 数据库问题、数据丢失风险、回滚失败 — Slack: @platform-lead
• L3 (CTO)： 生产环境宕机 > 30 分钟、数据泄露 — PagerDuty: #critical-incidents

---

### 2. 事故响应手册 (Incident Response Runbook)

```markdown
# 事故响应手册
**严重程度：** P1 (宕机), P2 (性能下降), P3 (轻微问题)  
**预计总耗时：** P1: 30–60 分钟, P2: 1–4 小时  

## 第一阶段 — 分诊/分类 (5 分钟)

### 确认事故
```bash
# 应用有响应吗？
curl -sw "%{http_code}" https://your-app.vercel.app/api/health -o /dev/null

# 检查 Vercel 函数错误（过去 15 分钟）
vercel logs --since=15m | grep -i "error\|exception\|5[0-9][0-9]"

✅ 200 = 应用正常。5xx 或超时 = 事故确认。

宣布严重程度：

• 网站完全宕机 → P1 — 立即呼叫 L2/L3
• 部分性能下降 / 响应慢 → P2 — 通知团队频道
• 单个功能损坏 → P3 — 创建工单，在工作时间内修复

---

第二阶段 — 诊断 (10–15 分钟)

# 最近的部署 — 刚刚发布了什么吗？
vercel ls --limit=5

# 数据库健康状况
psql $DATABASE_URL -c "SELECT pid, state, wait_event, query FROM pg_stat_activity WHERE state != 'idle' LIMIT 20;"

# 慢查询 (> 30 秒)
psql $DATABASE_URL -c "SELECT pid, now() - pg_stat_activity.query_start AS duration, query FROM pg_stat_activity WHERE state = 'active' AND now() - pg_stat_activity.query_start > interval '30 seconds';"

# 连接池饱和度
psql $DATABASE_URL -c "SELECT count(*), max_conn FROM pg_stat_activity, (SELECT setting::int AS max_conn FROM pg_settings WHERE name='max_connections') t GROUP BY max_conn;"

诊断决策树：

• 最近部署 + 新错误 → 回滚（见部署手册）
• 数据库查询超时 / 连接池饱和 → 杀掉慢查询，扩容连接数
• 外部依赖失败 → 检查状态页，添加熔断器
• 内存/CPU 激增 → 检查 Vercel 函数日志是否有死循环

---

第三阶段 — 缓解 (耗时视情况而定)

# 杀掉失控的数据库查询
psql $DATABASE_URL -c "SELECT pg_terminate_backend(<pid>);"

# 扩容数据库连接 (Supabase/Neon — 调整连接池大小)
# Vercel → Settings → Environment Variables → 更新 DATABASE_POOL_MAX

# 启用维护模式（如果你有功能开关/Feature Flag）
vercel env add MAINTENANCE_MODE true production
vercel --prod  # 带着开关重新部署

---

第四阶段 — 解决与事后分析 (Postmortem)

事故解决后，在 24 小时内：

1. 编写事故时间线（发生了什么，何时，谁发现的，如何修复的）
2. 识别根本原因 (5-Whys)
3. 定义包含责任人和截止日期的行动项
4. 如果有步骤缺失或错误，更新此手册
5. 添加本来可以更早发现此问题的监控/告警

事后分析模板： docs/postmortems/YYYY-MM-DD-incident-title.md

---

升级路径

级别	人员	何时	联系方式
L1	值班工程师	永远是第一位	PagerDuty 轮换
L2	平台负责人	数据库问题、需要回滚	Slack @platform-lead
L3	CTO/工程副总裁	P1 > 30 分钟, 数据丢失	电话 + PagerDuty

---

### 3. 数据库维护手册 (Database Maintenance Runbook)

```markdown
# 数据库维护手册 — PostgreSQL
**周期：** 每周清理/Vacuum (自动)，每月人工审阅  

## 备份

```bash
# 全量备份
pg_dump $DATABASE_URL \
  --format=custom \
  --compress=9 \
  --file="backup-$(date +%Y%m%d-%H%M%S).dump"

✅ 预期：文件已创建，大小 > 0。pg_restore --list backup.dump | head -20 显示表信息。

验证备份可还原（每月测试）：

pg_restore --dbname=$STAGING_DATABASE_URL backup.dump
psql $STAGING_DATABASE_URL -c "SELECT count(*) FROM users;"

✅ 预期：行数与生产环境匹配。

迁移

# 务必先在分段环境测试
DATABASE_URL=$STAGING_DATABASE_URL npx prisma migrate deploy
# 验证无误后：
DATABASE_URL=$PROD_DATABASE_URL npx prisma migrate deploy

✅ 预期：All migrations have been successfully applied.

⚠️ 对于大表迁移（> 1M 行），使用 pg_repack 或单独添加带 DEFAULT 的列以避免表锁。

清理 (Vacuum) 与重建索引

# 在决定前检查膨胀情况
psql $DATABASE_URL -c "
SELECT schemaname, tablename, 
       pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS total_size,
       n_dead_tup, n_live_tup,
       ROUND(n_dead_tup::numeric / NULLIF(n_live_tup + n_dead_tup, 0) * 100, 1) AS dead_ratio
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC LIMIT 10;"

# 对高膨胀表进行清理（非阻塞）
psql $DATABASE_URL -c "VACUUM ANALYZE users;"
psql $DATABASE_URL -c "VACUUM ANALYZE events;"

# 重建索引（使用 CONCURRENTLY 避免锁表）
psql $DATABASE_URL -c "REINDEX INDEX CONCURRENTLY users_email_idx;"

✅ 预期：清理后 dead_ratio 降至 5% 以下。

---

## 过期检测 (Staleness Detection)

在每份手册顶部添加过期检查页眉：

```markdown
## 过期检查
本手册引用了以下配置文件。如果自“最后验证日期”以来它们发生了更改，请审阅受影响的步骤。

| 配置文件 | 最后修改时间 | 影响步骤 |
|-------------|--------------|---------------|
| vercel.json | `git log -1 --format=%ci -- vercel.json` | 步骤 3, 回滚 |
| prisma/schema.prisma | `git log -1 --format=%ci -- prisma/schema.prisma` | 步骤 2, 数据库维护 |
| .github/workflows/deploy.yml | `git log -1 --format=%ci -- .github/workflows/deploy.yml` | 步骤 1, 步骤 3 |
| docker-compose.yml | `git log -1 --format=%ci -- docker-compose.yml` | 所有扩容步骤 |

自动化： 添加一个每周运行一次的 CI 任务，如果任何引用文件的修改时间晚于手册的“最后验证日期”，则在该手册文档上发表评论提醒。

---

手册测试方法论

在分段环境 (Staging) 进行演练

在生产环境信任手册之前，先在分段环境验证每个步骤：

# 1. 创建分段环境镜像
vercel env pull .env.staging
source .env.staging

# 2. 使用分段环境凭据运行每个步骤
# 将所有 $DATABASE_URL 替换为 $STAGING_DATABASE_URL
# 将所有生产环境 URL 替换为分段环境 URL

# 3. 验证预期输出是否匹配
# 记录任何差异并更新手册

# 4. 记录每个步骤的时间 — 更新手册中的预计耗时
time npx prisma migrate deploy

每季度审阅机制

每季度安排 1 小时的审阅时间：

1. 在分段环境运行每个命令 — 它们还管用吗？
2. 检查配置漂移 — 比较“最后修改时间”与“最后验证日期”。
3. 测试回滚程序 — 真的在分段环境执行一次回滚。
4. 更新联系信息 — L1/L2/L3 可能已经变动。
5. 添加过去一个季度发现的新故障模式。
6. 更新手册顶部的“最后验证日期”。

---

常见坑点

坑点	解决方法
命令需要手动复制动态值	使用环境变量 — 使用 $DATABASE_URL 而非 postgres://user:pass@host/db
未指定预期输出	在每个验证步骤后添加带有确切预期字符串的 ✅
缺失回滚步骤	每个破坏性步骤都需要有对应的撤销操作
手册从不测试	在团队日历中安排每季度的分段环境演练
L3 升级联系人是前任 CTO	每季度审阅一次联系信息
迁移手册未提及表锁	明确指出大表操作的锁风险

---

最佳实践

1. 每个命令必须是可复制粘贴的 — 不要使用占位符文本，使用环境变量。
2. 每一步后都要有 ✅ — 明确预期输出，而不是“应该可以工作”。
3. 时间预估是强制性的 — 工程师需要知道在违反 SLA 前是否有时间修复。
4. 部署前先想好回滚 — 在执行前规划好撤销方案。
5. 手册存放在代码仓库中 — 存放在 docs/runbooks/，随代码进行版本管理。
6. 事后分析 → 手册更新 — 每次事故都应该让手册变得更好。
7. 链接而非复制 — 引用权威的配置文件，不要将其内容复制到手册中。
8. 像测试代码一样测试手册 — 未经测试的手册比没有手册更糟（会产生虚假的安全感）。