chore: sync local changes to Gitea

2026-06-24 22:10:24 +08:00
commit d7ef0c3549
49 changed files with 12762 additions and 0 deletions
--- a/API调用文档.md
+++ b/API调用文档.md
@@ -0,0 +1,285 @@
+# 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 应保存在不同轮转策略的凭据系统中。