ops-assistant/docs/cf-dns-runbook-incident-20260313.md

CF DNS Runbook 事故复盘（2026-03-13）

背景

在 ops-assistant 中新增 CF 模块命令（/cf dnsadd/dnsset/dnsdel/dnsproxy）并进行自测时，出现多次失败与反复修复，导致进度延误。

现象

• /cf dnsadd test.fnos.xx.kg 127.0.0.1 连续失败多次。
• Cloudflare API 返回 Invalid request headers。
• runbook 步骤日志只回显脚本文本，未见真实 API 返回。

根因

1. 认证方式误判

• 将 API Token 误当作 API Key，使用了 X-Auth-Email/X-Auth-Key 方式，导致 CF 返回 Invalid request headers。
• 修复后改回 Bearer 才验证 token 可用。

2. runbook 执行方式不稳定（ssh heredoc/转义）

• runbook 使用 ssh.exec 远端执行，命令通过 bash -lc + ssh "..." 传递。
• heredoc 在多层转义/引用中被破坏，脚本未执行或被 shell 解释掉，stderr 只回显脚本内容。
• python3 -c 内联也因换行/转义导致 SyntaxError。

卡点分析

• 卡点本质不是 Token，而是 远端执行链路中的脚本传递/转义失效。
• 缺少一条稳定的“文本脚本传递”方式，导致同一命令多次失败、定位耗时。

最终解决

• 改为 base64 + python3 -c exec(...) 的方式传递脚本，避免多层引用与换行问题。
• /cf dnsadd test.fnos.xx.kg 127.0.0.1 成功创建记录。
  • record id: acd49e048bc74c1b16d935b69f5aac54
  • job: 27

经验与改进

1. 认证方式先验确认：明确 Token vs Key 的调用差异。
2. 避免 heredoc 跨 ssh：优先 base64|python3 或 python3 -c 单行命令。
3. 失败输出必须可见：stderr/stdout 要确保能返回实际 API 响应，禁止“只回显脚本文本”。
4. 阶段性汇报必须带证据：无日志/产物不使用“完成/已执行”。

待办

• 将 dnsset/dnsdel/dnsproxy 全部切换为稳定执行方式（base64 + python3 -c）。
• 评估是否引入 local.exec，避免本地项目走 ssh 远端执行。