domainflare/domainflare API调用文档.md

# Domainflare HTTP API 调用文档

本文描述已部署的 **Domainflare**（Cloudflare Worker）对外 HTTP 接口。文中 **BASE** 表示 Worker 的**根 URL**（协议 + 主机，**无末尾斜杠**），例如 `https://domainflare.example.workers.dev`。

**相关文件**（仓库根目录）：

| 文件 | 用途 |
|------|------|
| `imports/Domainflare.environment.postman.json` | 环境变量模板（`BASE`、`PANEL_TOKEN` 等），Postman / Apifox 可导入 |
| `imports/Domainflare.postman_collection.json` | Postman 集合 |
| `imports/Domainflare.apifox.openapi.json` | OpenAPI 3.0，供 Apifox 等导入 |

---

## 目录

- [0. Postman / Apifox 与环境变量](#0-postman--apifox-与环境变量)
- [1. 快速发现](#1-快速发现)
- [2. 认证方式](#2-认证方式)
- [3. 管理接口](#3-管理接口)
- [4. Cloudflare API 透传](#4-cloudflare-api-透传)
- [5. 错误响应](#5-错误响应)
- [6. CORS](#6-cors)
- [7. 集成建议](#7-集成建议)
- [8. 安全提示](#8-安全提示)

---

## 0. Postman / Apifox 与环境变量

建议在 Shell、CI 或 API 工具中使用**同名**变量，便于对照：

```bash
export BASE="https://你的 Worker 域名"      # 无末尾 /
export PANEL_TOKEN="你的 APP_ACCESS_TOKEN" # 与 Worker 的 APP_ACCESS_TOKEN 一致
# 调用 /api/cf/* 时还需要 Cloudflare API Token，文档示例里用 CF_TOKEN；导入环境文件里对应键名为 cfToken，含义相同。
```

**导入步骤概要**

1. **环境**：导入 `imports/Domainflare.environment.postman.json`（Postman：`导入` →选择环境文件；Apifox：`导入` → `Postman` → 选同一文件）。按实际修改 `BASE`、`PANEL_TOKEN`。
2. **Postman**：再导入 `imports/Domainflare.postman_collection.json`；选中上述环境后请求中 `{{BASE}}`、`{{PANEL_TOKEN}}` 会生效。
3. **Apifox**：在环境就绪后，`导入` → `OpenAPI` → 选择 `imports/Domainflare.apifox.openapi.json`（服务地址模板为 `{BASE}`，需在环境中定义 `BASE`）。在认证方案中：`PanelHeader` / `PanelBearer` 使用 `{{PANEL_TOKEN}}`，`CfBearer` 使用 `{{cfToken}}`。

---

## 1. 快速发现

| 方法 | 路径 | 鉴权 | 说明 |
|------|------|:----:|------|
| GET | `/api` | 否 | 返回 API 目录 JSON（`service`、`version`、路由说明等） |
| GET | `/api/health` | 否 | 健康检查，可用于探活 |

示例：

```bash
curl -sS "https://你的 Worker 域名/api/health"
```

使用环境变量时：

```bash
curl -sS "$BASE/api/health"
```

---

## 2. 认证方式

Worker 配置项 **`APP_ACCESS_TOKEN`**（面板口令）用于保护需鉴权的管理接口。

### 2.1 管理类接口（校验、账号 CRUD）

以下**二选一**即可（勿在同一条请求里混用两种含义的 Bearer，见下节）：

| 方式 | 请求头 |
|------|--------|
| A | `X-App-Token: <APP_ACCESS_TOKEN>` |
| B | `Authorization: Bearer <APP_ACCESS_TOKEN>` |

适用于：`GET /api/verify`，`GET/POST/PATCH/DELETE /api/accounts` 等。

### 2.2 Cloudflare API 透传（`/api/cf/*`）

须**同时**携带：

| 请求头 | 值 |
|--------|-----|
| `X-App-Token` | `<APP_ACCESS_TOKEN>`（**仅**用此头传面板口令，避免与 CF 的 Bearer 冲突） |
| `Authorization` | `Bearer <Cloudflare API Token>` |

转发规则：请求 `BASE` + `/api/cf` + 子路径与查询串 → `https://api.cloudflare.com/client/v4` + 同一子路径与查询串。HTTP 方法及 Body（如 JSON）原样转发，响应状态码与正文与官方 API 一致。

---

## 3. 管理接口

以下示例假定已设置 `BASE`、`PANEL_TOKEN`（见第 0 节）。

### 3.1 校验面板口令

```http
GET /api/verify
```

| 结果 | HTTP | 响应体（示例） |
|------|------|----------------|
| 成功 | 200 | `{"ok":true}` |
| 失败 | 401 | `{"success":false,"errors":[{"message":"Invalid app access token"}]}` |

```bash
curl -sS -H "X-App-Token: $PANEL_TOKEN" "$BASE/api/verify"
curl -sS -H "Authorization: Bearer $PANEL_TOKEN" "$BASE/api/verify"
```

### 3.2 列出已保存的 Cloudflare 账号

```http
GET /api/accounts
```

**响应示例：**

```json
{
  "accounts": [
    {
      "id": "uuid",
      "name": "显示名",
      "token": "Cloudflare API Token 全文",
      "created_at": 1712345678
    }
  ]
}
```

> 响应含**完整** CF Token，仅允许在可信网络与可信客户端使用。

```bash
curl -sS -H "Authorization: Bearer $PANEL_TOKEN" "$BASE/api/accounts"
```

### 3.3 新增账号

```http
POST /api/accounts
Content-Type: application/json
```

```json
{
  "name": "我的账号",
  "token": "Cloudflare API Token"
}
```

- `name`：可选；`token`：**必填**。  
- **成功**：`201`，响应体为 `{"account":{...}}`。

```bash
curl -sS -X POST "$BASE/api/accounts" \
  -H "Authorization: Bearer $PANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"生产","token":"YOUR_CF_API_TOKEN"}'
```

### 3.4 更新账号

```http
PATCH /api/accounts/:id
Content-Type: application/json
```

```json
{ "name": "新名称", "token": "新 Token" }
```

字段可选；未出现的字段保持不变。成功：`200`，`{"account":{...}}`。

```bash
curl -sS -X PATCH "$BASE/api/accounts/ACCOUNT_ID" \
  -H "X-App-Token: $PANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"新名称"}'
```

### 3.5 删除账号

```http
DELETE /api/accounts/:id
```

成功：`200`，`{"ok":true}`。

```bash
curl -sS -X DELETE "$BASE/api/accounts/ACCOUNT_ID" \
  -H "X-App-Token: $PANEL_TOKEN"
```

---

## 4. Cloudflare API 透传

本节对应 Worker 路径前缀 **`/api/cf/*`**，转发至 `https://api.cloudflare.com/client/v4/*`。

### 4.1 路径映射示例

| 客户端请求 | 等价 Cloudflare 端点 |
|------------|----------------------|
| `GET $BASE/api/cf/zones` | `GET https://api.cloudflare.com/client/v4/zones` |
| `GET $BASE/api/cf/zones/{zone_id}/dns_records` | `GET .../client/v4/zones/{zone_id}/dns_records` |

### 4.2 列出 Zones

```bash
export CF_TOKEN="你的 Cloudflare API Token"

curl -sS "$BASE/api/cf/zones?per_page=50&direction=desc" \
  -H "X-App-Token: $PANEL_TOKEN" \
  -H "Authorization: Bearer $CF_TOKEN"
```

### 4.3 列出 DNS 记录

将 `ZONE_ID` 换为实际 Zone ID：

```bash
curl -sS "$BASE/api/cf/zones/ZONE_ID/dns_records?per_page=100&page=1" \
  -H "X-App-Token: $PANEL_TOKEN" \
  -H "Authorization: Bearer $CF_TOKEN"
```

### 4.4 创建 DNS 记录

```bash
curl -sS -X POST "$BASE/api/cf/zones/ZONE_ID/dns_records" \
  -H "X-App-Token: $PANEL_TOKEN" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","name":"www","content":"192.0.2.1","ttl":1,"proxied":true}'
```

### 4.5 官方参考

路径、字段与错误码以 Cloudflare 为准：  
[Cloudflare API v4 Documentation](https://developers.cloudflare.com/api/)

---

## 5. 错误响应

面板侧校验失败通常返回：

```json
{
  "success": false,
  "errors": [{ "message": "说明文字" }]
}
```

常见 HTTP 状态：`401`（面板口令错误）、`400`（如 `/api/cf/*` 未带 CF Bearer）。  
经透传返回的响应可能与 Cloudflare 官方错误结构一致，不一定包含 `success` 字段。

---

## 6. CORS

`/api/*` 已配置 `Access-Control-Allow-Origin: *`，浏览器跨域可调用；令牌仍须保密，勿写入前端公开代码或日志。

---

## 7. 集成建议

1. 在密钥管理或 CI 中保存 `BASE`、`PANEL_TOKEN`；调用 `/api/cf/*` 时再提供 `CF_TOKEN`（或先 `GET /api/accounts` 取用已存 Token，注意泄漏风险）。  
2. 启动或定时执行 `GET $BASE/api/health` 做探活。  
3. 可用 `GET $BASE/api` 获取机器可读目录与 `version`，便于对接升级。  
4. 所有 DNS 变更走 `/api/cf/...`，路径与官方 v4 一一对应。

---

## 8. 安全提示

- 生产环境对 `APP_ACCESS_TOKEN` 使用强随机值，推荐使用 `wrangler secret put APP_ACCESS_TOKEN`，勿将明文口令提交到公开仓库。  
- `GET /api/accounts` 返回明文 CF Token，勿记录到公开日志或通过不可信代理。  
- CF API Token 遵守最小权限；面板口令与 CF Token 应保存在不同轮转策略的凭据系统中。