90 lines
5.1 KiB
Markdown
90 lines
5.1 KiB
Markdown
# RUNBOOKS — 仓库级规范
|
||
|
||
本文件统一所有 Runbook 的字段、命名、评审与变更规则。上游参考：[docs/archive/agent-runbook-guide.md](docs/archive/agent-runbook-guide.md)。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
runbooks/
|
||
├── README.md # 意图 → 文件 路由索引（本目录的入口）
|
||
├── _template.md # 新建 runbook 的标准模板（复制后填写）
|
||
├── <intent>.md # 每份 runbook 只描述一种可识别的操作意图
|
||
└── ...
|
||
```
|
||
|
||
## 最小字段模型
|
||
|
||
每份 runbook 必须显式包含以下控制信息，否则盲目执行或错误恢复的风险会升高：
|
||
|
||
| 字段 | 作用 | 写作要求 |
|
||
|---|---|---|
|
||
| **Action** | 定义当前要执行的动作 | 可观察、可执行的动词；避免“检查一下”“适当调整” |
|
||
| **Expected** | 描述正常状态或预期输出 | 具体信号、阈值、状态码、测试结果或页面表现 |
|
||
| **Decision** | 定义分支与下一跳 | “条件 → 下一步”；无法判断时指向 `STOP` |
|
||
| **Verification** | 确认变更真正生效 | 每个有副作用的步骤后执行，不可跳过 |
|
||
| **Stop condition** | 规定何时不得继续 | 列出信息缺失、状态冲突、权限不足、验证失败等 |
|
||
| **Rollback** | 如何恢复到变更前状态 | 触发条件、前提、撤销步骤、回滚后验证 |
|
||
|
||
> 只读类 runbook 不产生副作用，可省略 Rollback；但必须保留 Stop condition（状态与预期冲突即 `STOP` 并记录证据）。
|
||
|
||
**只读类变体（read-only variant）**：只读 runbook（health 类、参考类）不强制
|
||
六字段模型，但必须包含以下最小结构，否则不视为达标：
|
||
|
||
- `## Purpose`（1–2 行）+ `## Scope`（适用/不适用）
|
||
- `## Safety` 或等效章节，其中**必须**含显式 Stop condition（状态与预期冲突即
|
||
`STOP` 并记录证据；不得在执行中自行"顺手修复"）
|
||
- 只读健康类另含可观察的 `## Pass criteria`（或等效的 Expected 信号）
|
||
- 每份 runbook 顶部/元信息区必须标注 `Last reviewed: <YYYY-MM-DD>`
|
||
|
||
## 命名与拆分规则
|
||
|
||
- 文件名采用小写连字符，反映**操作意图**而非目标主机，例如 `mailcow-health.md`、`release.md`。
|
||
- 一份文件只描述一种意图。流程出现明显分叉时拆分为独立文件，不堆叠“万能流程”。
|
||
- 只读诊断与变更操作应分离：health 类 runbook 保持只读，变更走 `ansible-operations.md`、`release.md`、`rollback.md` 或对应 gated playbook。
|
||
|
||
## 章节约定
|
||
|
||
- 每份 runbook 顶部含 `## Purpose`（1–2 行）与 `## Scope`（适用/不适用情形）。
|
||
- 变更型 runbook 必须记录明确的审批门：门控命令式使用 `## Approval gates` 表；
|
||
流程式在步骤中记录审批动作、证据位置和未批准时的 `STOP`。破坏性/不可逆操作必须获得明确批准。
|
||
- 语言约定：**runbook 正文统一使用英文**（由 agent 逐字执行，降低二义性）；
|
||
元规范文件（AGENTS.md / RUNBOOKS.md / 模板注释）可保留中文。
|
||
- 变更型 runbook 的两种形态：
|
||
- **流程式（Procedure 型）**：使用六字段模型，适用多分支/多步骤变更
|
||
（现有：`fix-ci.md`、`issue-to-merge.md`、`network-change.md`、
|
||
`network-recovery.md`、`release.md`、`rollback.md`）。
|
||
- **门控命令式（gated command reference）**：已稳定、低歧义、可验证的
|
||
操作以命令集 + 门控呈现（现有：`mailcow-update.md`、
|
||
`ansible-operations.md`、`home-assistant-maintenance.md`、
|
||
`matrix-e2ee-update.md`、`vaultwarden-sqlite-to-postgres.md`），必须含 Approval gates 或确认变量
|
||
要求 + 显式 STOP，不替代流程式形态。新写的变更 runbook 默认用流程式。
|
||
- 统一在 `## Safety` 或正文中复用以下通用安全规则（更严格要求优先）。
|
||
|
||
```markdown
|
||
## Safety Rules
|
||
|
||
- Never delete an existing configuration as the first recovery action.
|
||
- Prefer read-only diagnosis before mutation.
|
||
- After every mutation, verify the expected state.
|
||
- If actual state conflicts with this runbook, STOP.
|
||
- Do not invent missing parameters.
|
||
- Do not bypass failed tests.
|
||
- Destructive actions require explicit approval.
|
||
```
|
||
|
||
## 评审与变更规则
|
||
|
||
- 新建/修改 runbook 与代码同仓评审，随系统演进更新。
|
||
- 每份 runbook 标注 `Last reviewed`；流程执行过程中发现的偏差记入对应的 Linear `vps` 项目 issue。
|
||
- 破坏性流程（迁移、删除、DNS 变更、网络变更）保持人工审批，不自动下沉。
|
||
|
||
## 成熟路径
|
||
|
||
1. **人工处理** → 现场处置与复盘，记录证据。
|
||
2. **Markdown runbook** → 固化步骤与证据要求，Agent 可辅助诊断。
|
||
3. **Agent + runbook** → 严格按流程执行，受 Stop/Approval 约束。
|
||
4. **Script / Ansible / Skill** → 把已稳定、低歧义、可验证的操作程序化（本仓库的执行层是 Ansible playbook）。
|
||
5. **人工审批 + 自动执行** → 审批门控下的自动变更（如 gated playbook + 确认变量）。
|
||
|
||
原则：先证据后变更，先小范围后扩大，先验证后结束，不确定则停止。
|