124 lines
2.3 KiB
Markdown
124 lines
2.3 KiB
Markdown
# 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`
|
||
|
||
示例：
|
||
```json
|
||
{
|
||
"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}
|
||
}
|
||
```
|