217 lines
7.0 KiB
Markdown
217 lines
7.0 KiB
Markdown
# api-worker
|
||
|
||
简易版 new-api：Cloudflare Workers + D1 后端，Vite 静态管理台。
|
||
管理台构建产物通过 Worker Static Assets 与 Worker 一起部署。
|
||
|
||
## 目录结构
|
||
|
||
- `apps/worker` Cloudflare Worker (Hono)
|
||
- `apps/ui` 管理台 (Vite)
|
||
|
||
## Action 自动部署流程（GitHub Actions）
|
||
|
||
工作流名称：`Deploy SPA CF Workers[Worker一体化部署]`
|
||
|
||
### 1) 配置 GitHub Secrets
|
||
|
||
在仓库 Settings → Secrets and variables → Actions 中新增：
|
||
|
||
- `CLOUDFLARE_API_TOKEN`：需包含 Workers + D1 的读写权限
|
||
- `CLOUDFLARE_ACCOUNT_ID`：Cloudflare 账户 ID
|
||
|
||
### 2) 可选配置 Actions 变量
|
||
|
||
- `SPA_DEPLOY`：自动部署开关（`true`/`false`），未设置时默认启用
|
||
|
||
### 3) 触发方式
|
||
|
||
- 自动触发：push 到 `main` 或 `master`，且变更命中 `apps/ui/**` 或 `apps/worker/**`
|
||
- 受 `SPA_DEPLOY` 控制
|
||
- 手动触发：Actions 页面选择工作流并 Run workflow
|
||
- 默认不受 `SPA_DEPLOY` 影响（除非设置 `from_panel=true`）
|
||
- 外部触发：`repository_dispatch`（type = `deploy-spa-button`）
|
||
- 不受 `SPA_DEPLOY` 影响
|
||
|
||
### 4) 触发参数（workflow_dispatch）
|
||
|
||
- `deploy_target`：`frontend`/`backend`/`both`/`auto`（默认 auto）
|
||
- `frontend` 仍会部署 Worker（静态资源随 Worker 发布）
|
||
- `auto` 在 push 时按变更范围决定，手动触发默认部署前后端
|
||
- `apply_migrations`：`true`/`false`/`auto`（默认 auto）
|
||
- `auto` 仅在 push 且迁移文件变更时执行
|
||
- `from_panel`：`true`/`false`（是否由控制面板触发；为 true 时会尊重 `SPA_DEPLOY`）
|
||
|
||
### 5) 部署步骤摘要
|
||
|
||
- Checkout → 安装 Bun 1.3.9 → `bun install`
|
||
- 构建管理台（`apps/ui/dist`），并校验产物
|
||
- 关闭 wrangler telemetry
|
||
- 创建/校验 D1（`api-worker`），在 CI 内写入 `apps/worker/wrangler.toml` 的 `database_id`
|
||
- 按需执行远程迁移
|
||
- `wrangler deploy` 部署 Worker
|
||
|
||
## 本地开发流程
|
||
|
||
### 0) 前置要求
|
||
|
||
- Bun 1.3.9（见 `package.json` 的 `packageManager`）
|
||
- Cloudflare Wrangler（通过 `bunx wrangler` 使用）
|
||
|
||
### 1) 安装依赖
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
### 2) 启动 Worker（后端）
|
||
|
||
```bash
|
||
bun run dev:worker
|
||
```
|
||
|
||
说明：
|
||
|
||
- 默认使用 `apps/worker/wrangler.toml`
|
||
- 本地端口通常为 8787（wrangler 默认）
|
||
- D1 使用本地数据库
|
||
|
||
环境变量/配置（`apps/worker/wrangler.toml` 或 `wrangler secret put`）：
|
||
|
||
- `CORS_ORIGIN` 允许的管理台来源（如 UI 使用 4173 端口，请同步调整）
|
||
- `PROXY_RETRY_ROUNDS` 代理失败轮询次数（默认 2）
|
||
- `PROXY_RETRY_DELAY_MS` 轮询间隔（毫秒，默认 200）
|
||
|
||
系统设置（管理台 → 系统设置）：
|
||
|
||
- 日志保留天数（默认 30）
|
||
- 会话时长（小时，默认 12）
|
||
- 管理员密码（首次登录在登录页输入密码将自动设置，可在系统设置中修改）
|
||
- 运行时配置（以数据库为准，可在系统设置中修改）
|
||
|
||
### 3) 启动管理台 UI
|
||
|
||
```bash
|
||
bun run dev:ui
|
||
```
|
||
|
||
说明：
|
||
|
||
- 默认端口为 4173（见根目录脚本）
|
||
|
||
前端配置（`apps/ui/.env` 可选）：
|
||
|
||
- `VITE_API_BASE` 管理 API 基址（默认同域）
|
||
- `VITE_API_TARGET` 本地开发代理目标（默认 http://localhost:8787）
|
||
|
||
### 4) 本地数据库迁移（可选/首次启动推荐）
|
||
|
||
```bash
|
||
bun run --filter api-worker db:migrate
|
||
```
|
||
|
||
### 5) 常用命令
|
||
|
||
- `bun run test`
|
||
- `bun run typecheck`
|
||
- `bun run lint`
|
||
- `bun run format`
|
||
- `bun run dev` 同时启动 Worker 与 UI
|
||
|
||
## 本地一键部署脚本
|
||
|
||
脚本位置：`scripts/deploy.mjs`，用于在本地复刻 GitHub Actions 的 init/update 部署流程。
|
||
|
||
前置环境：
|
||
|
||
- Bun（确保 `bun`/`bunx` 可用）
|
||
- Wrangler（通过 `bunx wrangler` 使用）
|
||
- `.env.example` 可作为本地环境变量模板（可选）
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
node scripts/deploy.mjs init
|
||
node scripts/deploy.mjs update --target auto --migrate auto
|
||
```
|
||
|
||
或使用 package scripts：
|
||
|
||
```bash
|
||
bun run deploy:init
|
||
bun run deploy:update -- --target auto --migrate auto
|
||
```
|
||
|
||
说明：
|
||
|
||
- 该脚本仅执行本地流程（构建 + 本地迁移），不会触发远程部署
|
||
- `init` 会强制执行本地迁移
|
||
- `update` 默认按变更范围决定是否迁移（无法检测时会默认迁移）
|
||
- `bun run deploy` 会进入交互选择（init/update、部署目标、迁移策略）
|
||
- 若 `.env` 不存在，会自动从 `.env.example` 生成（或创建空文件）
|
||
|
||
## API 接口
|
||
|
||
### 鉴权方式概览
|
||
|
||
- 管理台接口（`/api/*`）：
|
||
- 管理员登录后获取会话 token，推荐使用 `Authorization: Bearer {token}`
|
||
- 也支持 `x-admin-token` 或 `x-api-key` 作为备选头
|
||
- New API 兼容接口（`/api/channel`、`/api/group`、`/api/user`）：
|
||
- `Authorization: Bearer {管理员密码}` 或管理员登录 token
|
||
- 可选请求头：`New-Api-User: 1`
|
||
- OpenAI 兼容代理（`/v1/*`）：
|
||
- 使用 `Authorization: Bearer {API Token}`（或 `x-api-key`）
|
||
- API Token 由 `/api/tokens` 创建与管理
|
||
- 健康检查：`GET /health` 无鉴权
|
||
|
||
### 管理台接口（/api/\*）
|
||
|
||
- `POST /api/auth/login` 管理员登录
|
||
- `POST /api/auth/logout` 管理员登出
|
||
- `GET /api/channels` 渠道列表
|
||
- `POST /api/channels` 新增渠道
|
||
- `PATCH /api/channels/:id` 更新渠道
|
||
- `DELETE /api/channels/:id` 删除渠道
|
||
- `POST /api/channels/:id/test` 渠道连通性测试并刷新模型
|
||
- `GET /api/models` 汇总所有渠道模型
|
||
- `GET /api/tokens` 令牌列表
|
||
- `POST /api/tokens` 新建令牌（返回明文 token）
|
||
- `PATCH /api/tokens/:id` 更新令牌（配额/状态/允许渠道等）
|
||
- `GET /api/tokens/:id/reveal` 查看令牌明文
|
||
- `DELETE /api/tokens/:id` 删除令牌
|
||
- `GET /api/usage` 使用日志（支持 `from/to/model/channel_id/token_id/limit`）
|
||
- `GET /api/dashboard` 面板聚合指标（支持 `from/to`）
|
||
- `GET /api/settings` 读取系统设置
|
||
- `PUT /api/settings` 更新系统设置（日志保留/会话时长/管理员密码）
|
||
|
||
### New API 兼容接口（/api/channel /api/group /api/user）
|
||
|
||
渠道管理（`/api/channel`）：
|
||
|
||
- `GET /api/channel` 渠道列表（支持分页与筛选）
|
||
- `GET /api/channel/search` 渠道搜索（keyword/group/model/status/type）
|
||
- `GET /api/channel/:id` 渠道详情
|
||
- `POST /api/channel` 新增渠道（单条）
|
||
- `PUT /api/channel` 更新渠道
|
||
- `DELETE /api/channel/:id` 删除渠道
|
||
- `GET /api/channel/test/:id` 渠道连通性测试
|
||
- `POST /api/channel/test` 渠道连通性测试（body 传 id）
|
||
- `GET /api/channel/fetch_models/:id` 拉取渠道模型
|
||
- `POST /api/channel/fetch_models` 拉取模型（body 传 base_url/key）
|
||
- `GET /api/channel/models` 模型列表
|
||
- `GET /api/channel/models_enabled` 启用模型列表
|
||
- `PUT /api/channel/tag` 批量更新 tag 权重/优先级
|
||
- `POST /api/channel/tag/enabled` 批量启用 tag
|
||
- `POST /api/channel/tag/disabled` 批量停用 tag
|
||
|
||
分组与用户（只读）：
|
||
|
||
- `GET /api/group` 渠道分组列表
|
||
- `GET /api/user/models` 用户可用模型列表
|
||
|
||
### OpenAI 兼容代理（/v1/\*）
|
||
|
||
- `ALL /v1/*` 转发到渠道 `base_url + 请求路径`
|
||
- 当请求路径为 `/v1/responses` 且上游 400/404 时自动回退到 `/responses`
|
||
- 流式请求会自动补齐 `stream_options.include_usage = true` 以收集用量
|