# 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 远端执行。