vps/RUNBOOKS.md

RUNBOOKS — 仓库级规范

本文件统一所有 Runbook 的字段、命名、评审与变更规则。上游参考：docs/agent-runbook-guide.md。

目录结构

runbooks/
├── README.md                 # 意图 → 文件 路由索引（本目录的入口）
├── _template.md              # 新建 runbook 的标准模板（复制后填写）
├── <intent>.md               # 每份 runbook 只描述一种可识别的操作意图
└── ...

最小字段模型

每份 runbook 必须显式包含以下控制信息，否则盲目执行或错误恢复的风险会升高：

字段	作用	写作要求
Action	定义当前要执行的动作	可观察、可执行的动词；避免“检查一下”“适当调整”
Expected	描述正常状态或预期输出	具体信号、阈值、状态码、测试结果或页面表现
Decision	定义分支与下一跳	“条件 → 下一步”；无法判断时指向 STOP
Verification	确认变更真正生效	每个有副作用的步骤后执行，不可跳过
Stop condition	规定何时不得继续	列出信息缺失、状态冲突、权限不足、验证失败等
Rollback	如何恢复到变更前状态	触发条件、前提、撤销步骤、回滚后验证

只读类 runbook 不产生副作用，可省略 Rollback；但必须保留 Stop condition（状态与预期冲突即 STOP 并记录证据）。

命名与拆分规则

• 文件名采用小写连字符，反映操作意图而非目标主机，例如 mailcow-health.md、release.md。
• 一份文件只描述一种意图。流程出现明显分叉时拆分为独立文件，不堆叠“万能流程”。
• 只读诊断与变更操作应分离：health 类 runbook 保持只读，变更走 ansible-operations.md、release.md、rollback.md 或对应 gated playbook。

章节约定

• 每份 runbook 顶部含 ## Purpose（1–2 行）与 ## Scope（适用/不适用情形）。
• 变更型 runbook 额外含 ## Approval gates 表；破坏性/不可逆操作必须获得明确批准。
• 统一在 ## Safety 或正文中复用以下通用安全规则（更严格要求优先）。

## 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 + 确认变量）。

原则：先证据后变更，先小范围后扩大，先验证后结束，不确定则停止。