feat:更新readme
This commit is contained in:
lsy committed
1 parent
512a1fa45e
commit
584b5c3bda
1 file changed
+122
-117
@@ -9,7 +9,54 @@
|
||||
- `apps/ui` 管理台 (Vite)
|
||||
- `tests` 基础单元测试
|
||||
|
||||
## 本地开发
|
||||
## 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（`new_api_lite`），在 CI 内写入 `apps/worker/wrangler.toml` 的 `database_id`
|
||||
- 按需执行远程迁移
|
||||
- `wrangler deploy` 部署 Worker
|
||||
|
||||
## 本地开发流程
|
||||
|
||||
### 0) 前置要求
|
||||
|
||||
- Bun 1.3.9（见 `package.json` 的 `packageManager`）
|
||||
- Cloudflare Wrangler（通过 `bunx wrangler` 使用）
|
||||
|
||||
### 1) 安装依赖
|
||||
|
||||
@@ -17,15 +64,21 @@
|
||||
bun install
|
||||
```
|
||||
|
||||
### 2) Worker
|
||||
### 2) 启动 Worker（后端）
|
||||
|
||||
```bash
|
||||
bun run dev:worker
|
||||
```
|
||||
|
||||
环境变量（`apps/worker/wrangler.toml` 或 `wrangler secret put`）：
|
||||
说明：
|
||||
|
||||
- `CORS_ORIGIN` 允许的管理台来源
|
||||
- 默认使用 `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）
|
||||
|
||||
@@ -35,144 +88,96 @@ bun run dev:worker
|
||||
- 会话时长（小时，默认 12）
|
||||
- 管理员密码（首次登录自动初始化，可在系统设置中修改）
|
||||
|
||||
### 3) UI
|
||||
### 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 fix
|
||||
```
|
||||
|
||||
用于自动修正 package.json 常见问题（等价于 `bun pm pkg fix`）。
|
||||
|
||||
## New API 兼容接口
|
||||
|
||||
为了支持 all-api-hub 等插件同步渠道，Worker 提供 New API 风格的渠道管理接口：
|
||||
|
||||
- 路径前缀：`/api/channel`
|
||||
- 认证方式：`Authorization: Bearer {管理员密码}`（或管理台登录 token）
|
||||
- 可选请求头：`New-Api-User: 1`
|
||||
|
||||
支持的常用接口：
|
||||
- `GET /api/channel` 渠道列表
|
||||
- `GET /api/channel/` 渠道列表（兼容尾斜杠）
|
||||
- `GET /api/group` 渠道分组列表
|
||||
- `GET /api/channel/search` 渠道搜索
|
||||
- `POST /api/channel` 新增渠道（单条）
|
||||
- `PUT /api/channel` 更新渠道
|
||||
- `DELETE /api/channel/:id` 删除渠道
|
||||
- `GET /api/channel/test/:id` 渠道连通性测试
|
||||
- `GET /api/channel/fetch_models/:id` 拉取渠道模型
|
||||
- `GET /api/user/models` 用户可用模型列表
|
||||
|
||||
## D1 数据库
|
||||
|
||||
在 `apps/worker/migrations/0001_init.sql` 定义表结构，使用 Wrangler 迁移。
|
||||
本地开发使用本地数据库，云端部署使用 `--remote`：
|
||||
### 4) 本地数据库迁移（可选/首次启动推荐）
|
||||
|
||||
```bash
|
||||
bun run --filter api-worker db:migrate
|
||||
```
|
||||
|
||||
云端（Cloudflare D1）请使用：
|
||||
### 5) 常用命令
|
||||
|
||||
```bash
|
||||
bunx wrangler d1 migrations apply DB --remote
|
||||
```
|
||||
- `bun run test`
|
||||
- `bun run typecheck`
|
||||
- `bun run lint`
|
||||
- `bun run format`
|
||||
|
||||
## 忘记管理员密码
|
||||
## API 接口
|
||||
|
||||
管理员密码存储为哈希，可通过删除设置记录来重置，下一次登录会用输入的密码重新初始化：
|
||||
### 鉴权方式概览
|
||||
|
||||
```bash
|
||||
bunx wrangler d1 execute DB --command "DELETE FROM settings WHERE key = 'admin_password_hash';"
|
||||
```
|
||||
- 管理台接口（`/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` 无鉴权
|
||||
|
||||
## 云端部署（Cloudflare Workers + D1）
|
||||
### 管理台接口（/api/\*）
|
||||
|
||||
说明：
|
||||
- 管理台静态资源来自 `apps/ui/dist`
|
||||
- `/api/*` 与 `/v1/*` 会优先走 Worker 逻辑
|
||||
- 部署顺序：先构建管理台，再部署 Worker
|
||||
- 下述 `wrangler deploy` 与 `--remote` 均为云端部署/迁移（非本地模拟）
|
||||
- `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` 更新系统设置（日志保留/会话时长/管理员密码）
|
||||
|
||||
### 1) 新建部署
|
||||
### New API 兼容接口（/api/channel /api/group /api/user）
|
||||
|
||||
1. 安装依赖：
|
||||
渠道管理（`/api/channel`）：
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
- `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
|
||||
|
||||
2. 创建 D1 数据库并回填 `apps/worker/wrangler.toml` 的 `database_id`：
|
||||
|
||||
```bash
|
||||
bunx wrangler d1 create new_api_lite
|
||||
```
|
||||
|
||||
3. 设置 Worker 变量与密钥（如 CORS_ORIGIN）：
|
||||
|
||||
其他变量可继续放在 `apps/worker/wrangler.toml` 的 `[vars]` 中，`CORS_ORIGIN` 需指向管理台域名。
|
||||
|
||||
4. 构建管理台并上传静态资源：
|
||||
|
||||
```bash
|
||||
bun run --filter api-worker-ui build
|
||||
```
|
||||
|
||||
5. 执行远程迁移：
|
||||
|
||||
```bash
|
||||
bunx wrangler d1 migrations apply DB --remote
|
||||
```
|
||||
|
||||
6. 部署 Worker：
|
||||
|
||||
```bash
|
||||
bun run --filter api-worker deploy
|
||||
```
|
||||
|
||||
### 2) 更新前端（仅管理台变更）
|
||||
|
||||
```bash
|
||||
bun run --filter api-worker-ui build
|
||||
bun run --filter api-worker deploy
|
||||
```
|
||||
|
||||
### 3) 更新后端（仅 Worker 变更）
|
||||
|
||||
```bash
|
||||
bun run --filter api-worker deploy
|
||||
```
|
||||
|
||||
### 4) 数据库更新
|
||||
|
||||
1. 添加新的迁移文件到 `apps/worker/migrations/`。
|
||||
2. 执行远程迁移：
|
||||
|
||||
```bash
|
||||
bunx wrangler d1 migrations apply DB --remote
|
||||
```
|
||||
|
||||
### 5) 自动部署（GitHub Actions）
|
||||
|
||||
工作流默认在 `main` 分支推送时触发，步骤为：安装依赖 → 构建管理台 → 部署 Worker。
|
||||
|
||||
需要在仓库 Secrets 中配置：
|
||||
- `CLOUDFLARE_API_TOKEN`：具有 Workers 与 D1 权限的 API Token
|
||||
- `CLOUDFLARE_ACCOUNT_ID`：Cloudflare 账户 ID（若 token 无法自动识别账户）
|
||||
|
||||
确保 `apps/worker/wrangler.toml` 中已填写 `database_id`。
|
||||
可选：仓库级 Actions 变量 `SPA_DEPLOY` 可用于控制自动部署开关（未设置时默认启用）。
|
||||
分组与用户（只读）：
|
||||
|
||||
- `GET /api/group` 渠道分组列表
|
||||
- `GET /api/user/models` 用户可用模型列表
|
||||
|
||||
### OpenAI 兼容代理（/v1/\*）
|
||||
|
||||
- `ALL /v1/*` 转发到渠道 `base_url + 请求路径`
|
||||
- 当请求路径为 `/v1/responses` 且上游 400/404 时自动回退到 `/responses`
|
||||
- 流式请求会自动补齐 `stream_options.include_usage = true` 以收集用量
|
||||
Reference in new issue
Block a user