2. Runbook概述

Runbook（运行手册）是 CI/CD 流水线运维中最重要的知识载体。它把“人知道怎么做”变成“系统可执行、团队可查阅”的标准化文档。在失败复测场景下，Runbook 直接决定 MTTR（平均修复时间）能从小时级降到分钟级。

2.1 Runbook 的定义

Runbook 是一套结构化的操作指令集，用于指导运维或开发人员完成特定任务。它包含：

• 触发条件：什么情况下执行该 Runbook（如流水线失败、告警触发）。
• 前置检查：执行前必须确认的状态（如环境变量、权限、依赖服务）。
• 操作步骤：按顺序执行的命令、脚本或界面操作。
• 预期结果：每一步完成后应看到的输出或状态。
• 回滚方案：操作失败或异常时的恢复路径。

2.2 Runbook 的作用

2.3 Runbook 的常见类型

根据触发场景和执行目标，Runbook 分为三大类：

2.3.1 操作型 Runbook

用于执行常规、重复性的运维操作，不涉及故障或变更审批。典型场景：

• 重启流水线 Agent 节点
• 清理构建缓存与历史制品
• 手动触发特定阶段的重新执行
• 查看和导出流水线日志

2.3.2 故障型 Runbook

针对已知故障模式设计的恢复流程，是失败复测课程的核心关注点。典型场景：

• 编译失败：检查依赖版本、清理缓存、重试
• 单元测试失败：定位失败用例、回滚代码、重新触发
• 部署超时：检查资源配额、重启服务、回滚版本
• 环境不一致：对比配置差异、同步环境变量

2.3.3 变更型 Runbook

用于计划内的系统变更，需要审批、窗口期和回滚计划。典型场景：

• 升级 CI/CD 工具版本（如 Jenkins → GitLab CI）
• 修改流水线触发规则或分支策略
• 调整构建资源规格（CPU/内存）
• 新增或废弃制品仓库

2.4 三类 Runbook 对比

2.5 Runbook 在失败复测中的典型结构

一个面向流水线失败复测的 Runbook 通常包含以下字段：

# Runbook 模板：流水线失败复测
---
title: "编译阶段失败复测"
type: 故障型
trigger: "流水线 job:build 返回非零退出码"
precheck:
  - "确认构建节点磁盘剩余 > 10GB"
  - "确认基础镜像标签存在"
  - "确认 Git 分支未锁定"
steps:
  - step: 1
    action: "获取失败日志"
    command: "kubectl logs -n ci $(kubectl get pod -n ci -l job=build -o jsonpath='{.items[0].metadata.name}') --tail=200"
    expected: "看到具体编译错误行"
  - step: 2
    action: "清理构建缓存"
    command: "rm -rf /var/cache/ci/build/*"
    expected: "目录清空"
  - step: 3
    action: "重新触发流水线"
    command: "curl -X POST https://ci.example.com/api/pipelines/${PIPELINE_ID}/retry"
    expected: "返回 202 Accepted"
rollback:
  - "如果重试后仍失败，标记为 '需人工介入' 并通知 SRE 值班组"

2.6 Runbook 生命周期与 CI/CD 集成

下图展示 Runbook 从创建到持续优化的完整生命周期，以及它与 CI/CD 流水线的集成关系：

2.7 失败复测场景的 Runbook 选择策略

当流水线失败时，值班人员应按照以下优先级选择 Runbook：

1. 匹配故障型 Runbook：检查是否有针对该失败模式的已知 Runbook（如“编译失败”、“测试超时”）。
2. 执行操作型 Runbook：若无专用故障 Runbook，先执行“环境检查”和“日志收集”操作型 Runbook 获取上下文。
3. 触发变更型 Runbook：若确认是环境或配置变更导致失败，执行对应的变更回滚 Runbook。
4. 创建新 Runbook：若以上均不匹配，记录失败模式并在修复后创建新的故障型 Runbook。