Files

shumengya d7ef0c3549 chore: sync local changes to Gitea

2026-06-24 22:10:24 +08:00

8.0 KiB

Raw Permalink Blame History

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 与环境变量

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

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

导入步骤概要

环境：导入 imports/Domainflare.environment.postman.json（Postman：导入 →选择环境文件；Apifox：导入 → Postman → 选同一文件）。按实际修改 BASE、PANEL_TOKEN。
Postman：再导入 imports/Domainflare.postman_collection.json；选中上述环境后请求中 {{BASE}}、{{PANEL_TOKEN}} 会生效。
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`	否	健康检查，可用于探活

示例：

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

使用环境变量时：

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 校验面板口令

GET /api/verify

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

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

3.2 列出已保存的 Cloudflare 账号

GET /api/accounts

响应示例：

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

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

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

3.3 新增账号

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

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

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

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 更新账号

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

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

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

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

3.5 删除账号

DELETE /api/accounts/:id

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

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

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：

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 记录

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

5. 错误响应

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

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

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

6. CORS

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

7. 集成建议

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

8. 安全提示

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

8.0 KiB Raw Permalink Blame History Unescape Escape