feat: 模块化命令框架 + runbook 严格断言与查询结果回传

- core/module: 命令模板、门控(feature flag/confirm/dry-run)、ecode 错误标签、ResultFormatter
- runbook executor: http.get/http.post/assert.json(expect_success 严格断言)、目标主机管理、任务落库、最终 stdout 直接回传
- cf 模块: /cf dns list 支持域名自动解析 zone_id;dns list/zones/workers list 格式化回传;API success:false 判真失败
- 全部 CF/CPA runbook 接入严格断言,杜绝假阳性 success
- 新增 cpa/cfdav/mail/sub 模块与 runbooks;QQ 订阅到期提醒调度
- Web 后台: 模块设置(CF/CPA/cfdav/AI)、OPS 任务、渠道管理、审计页
This commit is contained in:
2026-09-13 07:42:17 +08:00
parent 9085c490f3
commit 81939825d1
86 changed files with 6885 additions and 467 deletions
+39
View File
@@ -0,0 +1,39 @@
# 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 远端执行。