ops-assistant/docs/cf-commands-design.md

CF 命令设计（ops-assistant v1）

目标

为 ops-assistant 提供 Cloudflare DNS 管理能力，保证幂等、安全、可审计。

---

1. 命令清单

• /cf zones

  • 列出可用 Zone（name/id）

• /cf dnslist <zone> [name] [type]

  • 示例：/cf dnslist example.com
  • 示例：/cf dnslist example.com www A

• /cf dnsadd <fqdn> <ip> [--type A/AAAA/CNAME] [--ttl 120] [--proxied on/off]

  • 示例：/cf dnsadd test.fnos.xx.kg 1.2.3.4

• /cf dnsset <fqdn> <ip> [--type A/AAAA/CNAME] [--ttl 120] [--proxied on/off]

  • 存在则更新，不存在则创建

• /cf dnsdel <fqdn> --type <A/AAAA/CNAME>

  • 必须带 --type
  • 需二次确认 YES

• /cf dnsproxy <fqdn> on|off

  • 仅更新 proxied

• /cf health

  • Token/权限可用性检查

---

2. 权限与安全

• read 角色：仅允许 zones / dnslist / health
• admin 角色：允许所有命令
• dnsdel 必须二次确认 YES

---

3. 参数校验

• fqdn 必须属于某个 Zone（<sub>.<zone>）
• ip 校验：
  • A → IPv4
  • AAAA → IPv6
• type 默认 A
• ttl 默认 120
• proxied 默认保持原值（仅 dnsproxy/dnsset 明确修改）

---

4. 幂等与更新规则

/cf dnsadd

1. 查询同名同类型记录
2. 存在 → 返回“已存在”
3. 不存在 → 创建

/cf dnsset

• 若任一字段不同则更新：
  • content
  • ttl
  • proxied
• content 相同但 ttl/proxied 不同 → 仍执行更新

/cf dnsdel

• 必须带 --type
• 仅删除指定 type 记录

---

5. 输出规范

成功

✅ DNS操作成功
- name: <fqdn>
- type: <type>
- content: <ip>
- ttl: <ttl>
- proxied: <true/false>
- id: <record_id>

已存在

ℹ️ DNS记录已存在（未变更）
- name: <fqdn>
- type: <type>
- content: <ip>
- id: <record_id>

失败

❌ DNS操作失败
- reason: <鉴权/参数/CF错误>
- detail: <error_message>

---

6. 审计日志（必写）

字段：

• ts / actor / cmd / zone / fqdn / action / record_id / result / detail

示例：

{
  "ts": "2026-03-14T15:02:10+08:00",
  "actor": "kory",
  "cmd": "/cf dnsadd test.fnos.xx.kg 1.2.3.4",
  "zone": "fnos.xx.kg",
  "record_id": "xxxxx",
  "action": "create",
  "result": "ok",
  "detail": {"type":"A","ttl":120,"proxied":false}
}