132 lines
4.8 KiB
Markdown
132 lines
4.8 KiB
Markdown
# Domainflare
|
||
|
||
基于 **Cloudflare Workers** 的 **多账号 DNS 解析管理**：Web 面板 + **D1** 存储账号，HTTP **透传**官方 **API v4**（`/api/cf/*`），并提供与 `X-App-Token` / Bearer 一致的 **管理 API**，便于脚本与第三方工具集成。
|
||
|
||
## 功能概览
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| Web 面板 | **React + Vite**；多 Zone、DNS 筛选与分页、增删改、DNSSEC、导出 JSON；响应式布局（由 Workers Static Assets 下发，不进入 Worker 脚本包体） |
|
||
| 存储 | **D1** 表 `cf_accounts` 持久化账号名称与 Cloudflare API Token |
|
||
| HTTP API | `GET /api` 目录、`GET /api/health` 探活、`/api/accounts` CRUD、`/api/cf/*` → `https://api.cloudflare.com/client/v4/*` |
|
||
|
||
完整接口说明、curl 与安全约定见：**[domainflare API调用文档.md](./domainflare%20API调用文档.md)**。
|
||
|
||
## 仓库结构（节选）
|
||
|
||
```
|
||
domainflare/
|
||
├── src/ # Worker：模块化 Hono API（仅 /api）
|
||
│ ├── index.ts
|
||
│ ├── app.ts
|
||
│ ├── routes/ # meta、accounts、cf 代理
|
||
│ ├── lib/ # 鉴权、HTTP 工具
|
||
│ └── types/
|
||
├── frontend/ # React + Vite 面板（构建产物 → Workers Static Assets）
|
||
│ ├── src/
|
||
│ └── dist/ # wrangler `[assets].directory`，由 `npm run build:frontend` 生成
|
||
├── migrations/ # D1 SQL 迁移
|
||
├── imports/ # Postman / OpenAPI / 环境模板
|
||
├── wrangler.toml
|
||
├── domainflare API调用文档.md
|
||
└── README.md
|
||
```
|
||
|
||
## 环境要求
|
||
|
||
- **Node.js** 18+（建议 LTS）
|
||
- **Wrangler** 4.x（见根目录 `package.json` devDependencies）
|
||
- Cloudflare 账号（**Workers** + **D1**）
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
git clone <仓库 URL>
|
||
cd domainflare
|
||
npm install
|
||
npm --prefix frontend install
|
||
npx wrangler login
|
||
```
|
||
|
||
### 首次：创建 D1 并迁移
|
||
|
||
```bash
|
||
npx wrangler d1 create domainflare
|
||
```
|
||
|
||
将命令输出中的 `database_id` 写入 `wrangler.toml` 的 `[[d1_databases]]` 对应项，然后：
|
||
|
||
```bash
|
||
npm run db:migrate:remote # 远程 D1
|
||
npm run db:migrate:local # 本地 wrangler dev 使用的 SQLite
|
||
```
|
||
|
||
### 本地开发
|
||
|
||
需要先同时跑 **Worker** 与 **Vite 开发服务器**（根目录脚本已用 `concurrently` 封装）：
|
||
|
||
```bash
|
||
npm install
|
||
npm --prefix frontend install # 首次克隆后安装前端依赖
|
||
npm run dev
|
||
```
|
||
|
||
- **Worker** 默认：`http://127.0.0.1:8787`（`wrangler dev`）
|
||
- **面板**：`http://127.0.0.1:5173`（Vite），已通过 `vite.config.ts` 将 `/api` 代理到 Worker
|
||
|
||
在浏览器打开 **5173** 端口即可。默认 **`APP_ACCESS_TOKEN`** 可在 `wrangler.toml` 的 `[vars]` 中查看；**勿在生产依赖默认示例值**。
|
||
|
||
### 生产部署
|
||
|
||
一键先构建前端再上传 Worker + Static Assets：
|
||
|
||
```bash
|
||
npm run deploy
|
||
```
|
||
|
||
等价于 `npm run build:frontend && wrangler deploy`。仅更新 Worker 代码而不改前端时，仍可直接 `npx wrangler deploy`（需已存在 `frontend/dist`）。
|
||
|
||
生产环境推荐通过 **Secret** 配置面板口令，避免把 `APP_ACCESS_TOKEN` 写在配置文件中：
|
||
|
||
```bash
|
||
npx wrangler secret put APP_ACCESS_TOKEN
|
||
```
|
||
|
||
部署完成后，将 Worker 的**根 URL**（无末尾 `/`）作为 API 文档中的 **`BASE`**。
|
||
|
||
## 配置说明
|
||
|
||
| 配置项 | 说明 |
|
||
|--------|------|
|
||
| `APP_ACCESS_TOKEN` | 保护管理接口与 `/api/cf/*` 中的面板身份；**不**应用于 `GET /api`、`GET /api/health` |
|
||
| D1 `cf_accounts` | 由迁移创建；字段 `id`、`name`、`token`、`created_at` |
|
||
|
||
## API 与导入工具
|
||
|
||
- **环境变量约定**（与文档一致）
|
||
- `BASE`：Worker 根 URL，无末尾 `/`
|
||
- `PANEL_TOKEN`：即 `APP_ACCESS_TOKEN`
|
||
|
||
- **Postman**
|
||
1. 导入 `imports/Domainflare.environment.postman.json` 并填写变量。
|
||
2. 导入 `imports/Domainflare.postman_collection.json`，选中该环境。
|
||
|
||
- **Apifox**
|
||
1. `导入` → `Postman` → `Domainflare.environment.postman.json`。
|
||
2. `导入` → `OpenAPI` → `Domainflare.apifox.openapi.json`；认证中 `PanelHeader` / `PanelBearer` 使用 `{{PANEL_TOKEN}}`，`CfBearer` 使用 `{{cfToken}}`。
|
||
|
||
**鉴权速记**
|
||
|
||
- **管理类**（`/api/verify`、`/api/accounts`…）：`X-App-Token: <口令>` **或** `Authorization: Bearer <口令>`。
|
||
- **透传** `/api/cf/*`：**必须** `X-App-Token` + `Authorization: Bearer <Cloudflare API Token>`。
|
||
|
||
## 安全提示
|
||
|
||
- 使用强随机 `APP_ACCESS_TOKEN`；生产用 Secret 管理；限制 Worker 暴露面（例如配合 **Cloudflare Access**）。
|
||
- `GET /api/accounts` 返回完整 CF Token，仅在内网或可信环境使用。
|
||
- Cloudflare Token 遵循**最小权限**（如仅 Zone DNS 编辑）。
|
||
|
||
## 许可
|
||
|
||
仓库未包含 `LICENSE` 时，由维护者自行补充；使用本代码请遵守适用法律法规与 Cloudflare 服务条款。
|