okooooooo/one-api-workers
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): 更新&丰富项目文档

Browse Source
This commit is contained in:
Jeff Gu committed 2026-04-15 11:20:06 +08:00
1 parent 3cf62c89db
commit 3781bd9061
5 files changed
+511 -367
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.gitignore
-1
View File
@@ -33,4 +33,3 @@ lerna-debug.log*
public*/
bun.lock
*.local.jsonc
docs/
README.md
+101 -366
View File
@@ -3,86 +3,78 @@
一个基于 Cloudflare Workers 分布式、低延迟、高性能的 AI 统一网关，支持多渠道管理、负载均衡、用量统计和追踪。
</div>
<div align="right">
本项目基于 <a href="https://github.com/dreamhunter2333/awsl-one-api" target="_blank">awsl-one-api</a>
</div>
## ✨ 功能特性
## 项目概览
- 🚀 **基于 Cloudflare Workers**：全球分布式网络、低延迟、高性能
- 🔐 **多渠道**：支持 OpenAI、Gemini、Azure OpenAI、Claude 等多种 AI 服务商
- 🎫 **负载均衡**：支持按权重多渠道路由、单渠道多密钥重试/轮换，以及跨渠道 fallback
- 📊 **用量统计**：Analytics Engine 实时统计，支持日志回溯便于成本分析
- 💰 **定价管理**：灵活的模型定价配置
- 🎨 **Web 管理界面**：直观的 Web 界面进行配置管理
- 🧪 **API 测试工具**：内置 API 测试功能，支持实时调试
- 基于 Cloudflare Workers：全球分布式网络、低延迟、高性能
- 统一代理入口：支持 `/v1/chat/completions`、`/v1/messages`、`/v1/responses`、`/v1/audio/speech`、`/v1/models`
- 负载均衡路由：支持按权重路由，单渠道多 Key，失败重试、Key 轮换和跨渠道 fallback
- 配额与计费：支持 Token 级额度控制、全局模型定价、渠道级模型定价
- 观测能力：写入 Cloudflare Analytics Engine，后台提供概览、趋势、分布和用量日志检索
- 管理后台：React + Vite 管理界面，覆盖渠道、令牌、定价、API 测试、系统设置
- 管理员安全：默认管理员令牌登录，可选 Telegram 二次验证，后台登录链路带限速与 session cookie
- API 文档：基于 Chanfana 暴露 Swagger、ReDoc、OpenAPI JSON，可在系统设置中开关
## 🏗️ 系统架构
## 支持范围
```mermaid
flowchart LR
subgraph Clients["客户端"]
A[Client Apps]
end
### 代理接口
subgraph CF["Cloudflare Workers"]
B[One API on Workers]
D1[(Cloudflare<br/>D1 Database)]
D2[(Cloudflare<br/>Analytics Engine)]
end
| 路由 | 说明 | 对应渠道类型 |
| --- | --- | --- |
| `/v1/chat/completions` | OpenAI Chat Completions 兼容代理 | `openai`、`azure-openai`、`gemini` |
| `/v1/messages` | Anthropic Claude Messages 兼容代理 | `claude`、`claude-to-openai` |
| `/v1/responses` | OpenAI / Azure Responses 代理 | `openai-responses`、`azure-openai-responses` |
| `/v1/audio/speech` | TTS 语音生成代理 | `openai-audio`、`azure-openai-audio` |
| `/v1/models` | 按 Token 权限和额度过滤后的模型列表 | 根据 Token 可访问渠道动态返回 |
subgraph Providers["AI 服务商"]
C1[Anthropic]
C2[OpenAI]
end
### 管理后台
A -->|API Request| B
B -->|Proxy| C1
B -->|Proxy| C2
B <-->|Read/Write| D1
B -->|Write| D2
```
当前后台页面包括：
<details>
<summary><h2>📁 项目结构</h2></summary>
- `Dashboard`：总请求数、成功率、成本、耗时、Token/渠道/模型/提供商分布
- `Usage Logs`：按时间范围、维度、关键字和结果筛选明细日志
- `Channels`：渠道配置、权重、自动重试/轮换、模型映射、拉取上游模型列表
- `Tokens`：API Token 管理、渠道访问范围、额度限制、用量重置
- `Pricing`：全局模型定价编辑，支持按量和按次计费
- `API Test`：直接在后台测试 `/v1/chat/completions`、`/v1/messages`、`/v1/responses`、`/v1/audio/speech`
- `System Settings`：Telegram 管理员验证、金额显示精度、API 文档开关
## 项目结构
```text
one-api-workers/
├── src/ # 源代码目录
│ ├── admin/ # 管理接口
│ │ ├── channel_api.ts # 渠道管理 API
│ │ ├── token_api.ts # Token 管理 API
│ │ ├── pricing_api.ts # 定价管理 API
│ │ ├── db_api.ts # 数据库初始化 API
│ │ └── index.ts # 管理接口路由
│ ├── providers/ # AI 服务商
│ │ ├── azure-openai-proxy.ts # Azure OpenAI 代理
│ │ ├── openai-proxy.ts # OpenAI / Gemini 兼容代理
│ │ ├── claude-proxy.ts # Claude 代理
│ │ ├── openai-responses-proxy.ts # OpenAI Responses 代理
│ │ ├── azure-openai-responses-proxy.ts # Azure Responses 代理
│ │ └── index.ts # 渠道路由
│ ├── db/ # 数据库相关
│ ├── model/ # 数据模型
│ ├── constants.ts # 常量定义
│ ├── utils.ts # 工具函数
│ └── index.ts # 主入口文件
├── public/ # 静态文件
│ └── index.html # Web 管理界面
├── type.d.ts # 类型定义
├── wrangler.jsonc # 生产/部署配置
├── wrangler.local.jsonc # 本地开发配置
└── package.json # 项目配置
├── src/
│ ├── admin/ # 管理接口：auth / channel / token / pricing / analytics / system
│ ├── analytics/ # Analytics Engine 写入与查询
│ ├── db/ # D1 初始化与迁移
│ ├── providers/ # 各类上游代理实现
│ ├── billing.ts # 计费与金额精度
│ ├── channel-config.ts # 渠道配置归一化
│ ├── system-config.ts # 系统配置与 Telegram 安全配置
│ └── index.ts # Worker 入口
├── frontend/
│ ├── src/pages/ # Dashboard / Channels / Tokens / Pricing / Usage Logs / Settings
│ ├── src/components/ # 布局、图表、UI 组件
│ └── package.json # 前端构建与 lint
├── public/ # 前端构建产物，由 Worker 直接托管
├── docs/ # 使用文档与安全文档
├── tests/ # Mock upstream + 本地 E2E 脚本
├── wrangler.jsonc # 生产配置
├── wrangler.local.jsonc # 本地 Worker 配置
├── type.d.ts # Worker 绑定与共享类型
└── package.json # 根 workspace 与开发命令
```
</details>
## 🚀 快速开始
## 快速开始
### 环境要求
- Bun 1.3+
- Cloudflare Workers 账户
- Cloudflare 账户，Workers + D1 database + Analytics Engine (`usage_events_by_token`)
### 安装依赖
@@ -90,346 +82,89 @@ one-api-workers/
bun install
```
仓库已配置为 Bun workspaces，根目录一次安装会同时安装 Worker 和 `frontend/` 的依赖。
### 配置 Cloudflare 绑定
### 配置环境
当前仓库里的 `wrangler.jsonc` / `wrangler.local.jsonc` 已经包含运行所需绑定结构，但你需要替换成自己的环境信息：
1. 修改 `wrangler.jsonc`，用于生产部署：
- `d1_databases[].database_name` / `database_id`：替换为自己的 D1
- `analytics_engine_datasets[].dataset`：默认使用 `usage_events_by_token`
- `vars.FRONTEND_DEV_SERVER_URL`：仅本地联调时使用，默认 `http://127.0.0.1:5173`
- `assets`：保持 `public/` 与 `ASSETS` 绑定即可
```jsonc
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "one-api-workers",
"main": "src/index.ts",
"compatibility_date": "2025-04-28",
"workers_dev": false,
"vars": {
"ADMIN_TOKEN": "your-secure-admin-token-here"
},
"assets": {
"directory": "./public",
"binding": "ASSETS",
"run_worker_first": true
},
"d1_databases": [
{
"binding": "DB",
"database_name": "your-database-name",
"database_id": "your-database-id"
}
]
}
```
当前配置中的关键 secrets：
2. 修改 `wrangler.local.jsonc`，用于本地开发：
- `ADMIN_TOKEN`：管理员登录令牌，必需
- `CF_API_TOKEN`：用于查询 Analytics Engine SQL，支持后台分析看板和用量日志
- `CF_ACCOUNT_ID`：与 `CF_API_TOKEN` 配套，用于 Cloudflare Analytics 查询
```jsonc
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "one-api-workers",
"main": "src/index.ts",
"compatibility_date": "2025-04-28",
"workers_dev": false,
"vars": {
"ADMIN_TOKEN": "your-local-admin-token",
"FRONTEND_DEV_SERVER_URL": "http://127.0.0.1:5173"
}
}
```
3. 创建 Cloudflare D1 数据库：
示例：
```bash
wrangler d1 create one-api-workers
wrangler secret put ADMIN_TOKEN
wrangler secret put CF_API_TOKEN
wrangler secret put CF_ACCOUNT_ID
```
4. 在 Cloudflare Dashboard 中手动绑定生产域名：
本地开发可以用 `.dev.vars` 提供这些值；`tests/` 下的脚本也会优先读取这个文件。
1. 进入 `Workers & Pages`
2. 选择当前 Worker
3. 打开 `Settings > Domains & Routes`
4. 选择 `Add > Custom Domain`
5. 添加你的生产域名
### 数据库初始化与迁移
如果你选择在 Dashboard 管理生产域名，就不要再把 `routes` / `custom_domain` 写回 `wrangler.jsonc`，否则下次 `wrangler deploy` 会用配置文件覆盖 Dashboard 中的路由设置。
项目会在首次请求时自动执行 D1 schema 初始化和迁移，不需要额外手动跑 SQL。
如果你希望在部署后主动触发初始化，也可以在通过管理员认证后访问：
```text
POST /api/admin/db_initialize
```
### 本地开发
启动前后端联调：
```bash
bun run dev
```
- 前端 Vite 开发服务器：`http://127.0.0.1:5173`
- Cloudflare Worker 本地服务：`http://127.0.0.1:8788`（入口）
常用地址：
### 部署到生产环境
- 前端 Vite 开发服务器：`http://127.0.0.1:5173`
- Worker 本地服务：`http://127.0.0.1:8787`
其他常用命令：
```bash
bun run dev:worker
bun run build
bun run cf-typegen
cd frontend && bun run lint
```
### 部署
```bash
bun run deploy
```
部署前会自动构建前端资源到 `public/`。
部署流程会先构建前端，再执行 `wrangler deploy --config wrangler.jsonc`。
<details>
<summary><h2>📖 使用与配置</h2></summary>
如果你在 Cloudflare Dashboard 中管理自定义域名，不要再把 `routes` / `custom_domain` 写回 `wrangler.jsonc`，否则下次部署会覆盖 Dashboard 中的域名配置。
### 使用指南
## 文档
#### 渠道配置
- [使用与配置](docs/usage-and-configuration.md)
- [管理员认证与防护](docs/security/admin-auth-protection.md)
- [测试与验证](docs/testing.md)
1. 访问 `https://your-domain.com`
2. 使用管理员 Token 登录
3. 进入 **🔗 渠道管理** 页面
4. 点击 **➕ 添加渠道** 按钮
5. 选择渠道类型（OpenAI、Azure OpenAI、Claude、Responses）
6. 填写渠道标识和配置信息（名称、端点、API 密钥、模型映射）
7. 点击 **💾 保存渠道** 按钮
## 贡献
**提示**：系统会根据选择的渠道类型自动显示相应的配置字段。
欢迎提交 Issue 和 Pull Request。
#### Token 创建和使用
1. 在 Web 界面切换到 **🔑 令牌管理** 标签
2. 点击 **➕ 添加令牌** 按钮
3. 填写令牌名称，系统会自动生成 `sk-` 开头的 Token
4. 配置允许访问的渠道和配额
5. 点击 **💾 保存令牌** 按钮
6. 使用 **📋 复制** 按钮获取 Token 用于 API 调用
#### OpenAI 兼容 API
本项目提供完全兼容的 OpenAI API 接口：
```bash
curl https://your-domain.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"model": "gpt-4",
"messages": [
{
"role": "user",
"content": "Hello, world!"
}
]
}'
```
#### Responses API（OpenAI / Azure）
```bash
curl https://your-domain.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"model": "gpt-5.1-codex-max",
"input": "Hello, Responses API!"
}'
```
#### API 测试工具
管理界面内置了强大的 API 测试工具，无需额外工具即可进行 API 调试：
**功能特性**
- **🚀 一键测试**：直接在 Web 界面中测试 API 调用
- **📝 JSON 编辑器**：支持 JSON 格式验证和语法高亮
- **⚡ 实时响应**：显示响应时间、状态码和完整响应内容
- **🔍 错误诊断**：自动区分 HTTP 错误和 JSON 响应，便于排查问题
- **📋 一键复制**：支持复制 Token 和响应内容
**使用步骤**
1. 访问管理界面，切换到 **🧪 API 测试** 标签
2. 输入你的 API Token（可从令牌管理页面复制）
3. 编辑请求 JSON（预填充标准格式）
4. 点击 **🚀 发送请求** 按钮
5. 查看响应结果和状态信息
### 管理功能
#### Web 管理界面
访问 `https://your-domain.com` 即可使用 Web 管理界面，功能包括：
- **🔗 渠道管理**：添加、编辑、删除 AI 服务商（支持 OpenAI、Azure OpenAI、Claude、OpenAI Responses、Azure Responses）
- **🔑 API Token 管理**：生成、管理和监控 API Token 使用情况
- **💰 定价配置**：灵活配置不同模型的定价策略
- **🧪 API 测试工具**：内置 API 测试界面，支持实时调试和错误排查
**管理界面特性**
- **现代化 UI**：响应式设计，支持桌面和移动设备
- **实时反馈**：操作结果即时显示，支持悬浮提示
- **智能表单**：自动生成 Token、JSON 格式验证、一键复制功能，根据渠道类型智能显示配置字段
- **安全认证**：管理员 Token 认证，数据安全保护
### 配置说明
#### 渠道配置
目前支持以下 AI 服务商：
**OpenAI 配置**
```json
{
"name": "My OpenAI Channel",
"type": "openai",
"endpoint": "https://api.openai.com/v1/",
"api_key": "sk-your-openai-api-key",
"deployment_mapper": {
"gpt-4": "gpt-4",
"gpt-3.5-turbo": "gpt-3.5-turbo"
}
}
```
**Gemini 配置**
Gemini 通过官方 OpenAI 兼容层接入，建议将 `endpoint` 配置为 `https://generativelanguage.googleapis.com/v1beta/openai/`。
```json
{
"name": "My Gemini Channel",
"type": "gemini",
"endpoint": "https://generativelanguage.googleapis.com/v1beta/openai/",
"api_key": "AIza-your-gemini-api-key",
"deployment_mapper": {
"gemini-2.5-flash": "gemini-2.5-flash",
"gemini-2.5-pro": "gemini-2.5-pro"
}
}
```
**Azure OpenAI 配置**
```json
{
"name": "My Azure OpenAI",
"type": "azure-openai",
"endpoint": "https://your-resource.openai.azure.com/",
"api_key": "your-azure-api-key",
"api_version": "2024-02-15-preview",
"deployment_mapper": {
"gpt-4": "gpt-4-deployment-name",
"gpt-3.5-turbo": "gpt-35-turbo-deployment-name"
}
}
```
**Claude 配置**
```json
{
"name": "My Claude Channel",
"type": "claude",
"endpoint": "https://api.anthropic.com/v1/",
"api_key": "sk-your-claude-api-key",
"api_version": "2023-06-01",
"deployment_mapper": {
"claude-3-5-sonnet-20241022": "claude-3-5-sonnet-20241022"
}
}
```
**OpenAI Responses 配置**
```json
{
"name": "My OpenAI Responses",
"type": "openai-responses",
"endpoint": "https://api.openai.com/v1/",
"api_key": "sk-your-openai-api-key",
"deployment_mapper": {
"gpt-5.1-codex-max": "gpt-5.1-codex-max"
}
}
```
**Azure OpenAI Responses 配置（v1）**
```json
{
"name": "My Azure Responses",
"type": "azure-openai-responses",
"endpoint": "https://your-resource.openai.azure.com/",
"api_key": "your-azure-api-key",
"deployment_mapper": {
"gpt-5.1-codex-max": "your-deployment-name"
}
}
```
**配置字段说明**：
- `name`: 渠道显示名称
- `type`: 服务商类型（`openai`、`gemini`、`azure-openai`、`claude`、`openai-responses`、`azure-openai-responses`）
- `endpoint`: API 端点地址
- `api_key`: API 密钥
- `api_version`: API 版本（Azure OpenAI / Claude 可用；Azure Responses v1 请留空）
- `deployment_mapper`: 模型名称映射关系（用于自定义模型名称映射）
### Token 配置
支持详细的 Token 配置，包括名称、访问权限和配额管理：
```json
{
"name": "用户令牌1",
"channel_keys": ["azure-openai-1", "azure-openai-2"],
"total_quota": 1000000
}
```
**配置字段说明**：
- `name`: Token 名称，便于管理识别
- `channel_keys`: 允许访问的渠道列表，空数组表示允许所有渠道
- `total_quota`: 总配额（基础单位：1百万 token = $1.00）
### 监控与统计
- **使用量统计**：自动记录每次 API 调用的 Token 使用量
- **费用计算**：基于模型定价自动计算费用
- **配额管理**：支持 Token 级别的配额限制
- **实时监控**：Web 界面实时显示使用情况和剩余配额
### 核心优势
- **零配置部署**：基于 Cloudflare Workers，无需服务器维护
- **全球加速**：利用 Cloudflare 全球边缘网络，低延迟访问
- **成本优化**：按需计费，无固定服务器成本
- **高可用性**：Cloudflare 基础设施保证 99.9% 可用性
- **安全可靠**：内置 Token 认证和配额管理机制
### 安全性
- **Token 认证**：所有 API 调用需要有效的 Bearer Token
- **管理员认证**：管理接口使用独立的管理员 Token
- **CORS 支持**：配置跨域访问策略
### API 文档
部署后可访问以下地址查看完整 API 文档：
- Swagger UI: `https://your-domain.com/api/docs`
- ReDoc: `https://your-domain.com/api/redocs`
- OpenAPI JSON: `https://your-domain.com/api/openapi.json`
</details>
## 🤝 贡献
欢迎提交 Issue 和 Pull Request！
## 📄 许可证
## 许可证
MIT License
鸣谢：<a href="https://github.com/dreamhunter2333/awsl-one-api" target="_blank">awsl-one-api</a>
## 🙋‍♂️ 支持
## 支持
如有问题或建议，请创建 Issue 或联系维护者。
docs/security/admin-auth-protection.md
+81
View File
@@ -0,0 +1,81 @@
# 管理员认证与防护
本文档聚焦管理后台的认证方式、当前已启用的应用层保护，以及生产环境建议补齐的边缘层防护。
## 认证模式
当前版本支持两种后台认证模式：
- 基础模式：仅校验 `ADMIN_TOKEN`
- 增强模式：在系统设置中配置并验证 Telegram `Bot Token` / `Chat ID` 后，启用 Telegram 验证码登录
当前实现的认证与安全要点：
- 管理后台使用 session cookie，而不是每次请求直接传管理员令牌
- 登录、验证码验证和 Telegram 通知都带应用层限速
- API 文档可在系统设置中关闭；关闭后 `/api/docs`、`/api/redocs`、`/api/openapi.json` 会直接返回 `404`
生产环境不要只依赖应用层逻辑，仍应额外配置 Cloudflare WAF / Rate Limiting。
## 应用层
当前版本已在应用层启用以下保护：
- `/api/admin/auth/login` 按 IP 统计请求频率，超限后返回 `429`
- 管理员令牌连续失败达到阈值后进入冻结窗口
- `/api/admin/auth/verify` 按 IP 统计请求频率，超限后返回 `429`
- 验证码连续失败达到阈值后进入冻结窗口
- 验证码 challenge 绑定首次请求 IP，来源变化后要求重新获取验证码
- Telegram 验证码通知按 IP 和全局双层节流
- Telegram 登录结果通知按 IP 和全局双层节流，超限后静默跳过
## 相关配置
认证与防护相关设置主要位于管理后台的 `System Settings` 页面：
- Telegram 管理员验证开关
- Telegram `Bot Token` / `Chat ID`
- API 文档开关
建议流程：
1. 先配置 `ADMIN_TOKEN`
2. 在系统设置中填写 Telegram 配置
3. 发送测试消息并完成验证
4. 再启用 Telegram 二次验证
5. 根据暴露面决定是否关闭 API 文档
## 边缘层
应用层限速不能替代 Cloudflare 边缘层拦截。生产环境至少再加一层 WAF / Rate Limiting：
- 保护路径：
- `POST /api/admin/auth/login`
- `POST /api/admin/auth/verify`
- 推荐匹配表达式：
```txt
http.request.method eq "POST" and (
http.request.uri.path eq "/api/admin/auth/login" or
http.request.uri.path eq "/api/admin/auth/verify"
)
```
- 推荐计数维度：
- `ip.src`
- `cf.colo.id`
- 推荐动作：
- 首选 `Managed Challenge`
- 高频攻击场景可改为 `Block`
- 推荐起始阈值：
- `login`: 1 分钟内 5 次
- `verify`: 1 分钟内 8 次
- 缓解时长：15 分钟
## 落地顺序
1. 先在 Cloudflare 控制台或 API 建立登录限速规则
2. 再观察应用层 `429` 是否仍大量出现
3. 完成 Telegram 验证配置并确认 session 登录链路正常
4. 根据实际暴露情况决定是否关闭 API 文档
5. 若仍有 Telegram 刷屏或管理口扫号，再继续收紧边缘层阈值
docs/testing.md
+77
View File
@@ -0,0 +1,77 @@
# 测试与验证
本文档汇总仓库当前可用的基础验证方式与本地 E2E 测试脚本。
## 最小验证
日常改动后，至少执行以下检查：
```bash
bun run build
cd frontend && bun run lint
```
说明：
- `bun run build`：构建前端产物到 `public/`
- `cd frontend && bun run lint`：执行前端 ESLint 检查
## 本地 E2E
仓库内置了一套基于 mock upstream 的本地端到端验证脚本：
- `tests/mock-upstream.ts`：启动本地模拟上游服务
- `tests/setup-test-data.sh`：向本地 D1 写入测试渠道和 Token
- `tests/run-e2e.sh`：验证代理链路、模型列表、认证失败、请求头清洗等行为
### 覆盖范围
当前 E2E 主要覆盖：
- `/v1/models`
- `/v1/chat/completions`
- `/v1/messages`
- `/v1/responses`
- 上游请求头白名单与敏感头剥离
- 管理员登录相关限速与系统配置场景
### 前置条件
执行前请确保以下服务可用：
- 本地 Worker 已启动
- 本地 mock upstream 已启动在 `:9999`
- `.dev.vars` 或当前 shell 中已提供必要环境变量
- 本地 D1 可通过 `wrangler.local.jsonc` 正常访问
### 推荐执行顺序
1. 启动 mock upstream
```bash
bun run tests/mock-upstream.ts
```
2. 启动本地 Worker
```bash
bun run dev:worker
```
3. 写入测试数据
```bash
bash tests/setup-test-data.sh
```
4. 运行 E2E
```bash
bash tests/run-e2e.sh
```
## 注意事项
- 测试脚本默认依赖本地端口和 `wrangler.local.jsonc`
- `tests/setup-test-data.sh` 会写入并清理部分本地测试数据，不要直接对生产库执行
- 如果只改了文档或纯前端静态内容，通常不需要跑完整 E2E
docs/usage-and-configuration.md
+252
View File
@@ -0,0 +1,252 @@
# 使用与配置
本文档整理了项目的日常使用方式、渠道与 Token 配置要点，以及监控、安全和 API 文档入口。
## 使用指南
### 渠道配置
1. 访问 `https://your-domain.com`
2. 使用管理员 Token 登录
3. 进入 **渠道管理** 页面
4. 点击 **添加渠道**
5. 选择渠道类型（OpenAI、Azure OpenAI、Claude、Responses）
6. 填写渠道标识和配置信息（名称、端点、API 密钥、模型映射）
7. 点击 **保存渠道**
提示：系统会根据选择的渠道类型自动显示相应的配置字段。
### Token 创建和使用
1. 在 Web 界面切换到 **令牌管理**
2. 点击 **添加令牌**
3. 填写令牌名称，系统会自动生成 `sk-` 开头的 Token
4. 配置允许访问的渠道和配额
5. 点击 **保存令牌**
6. 使用复制按钮获取 Token，用于 API 调用
### OpenAI 兼容 API
本项目提供兼容 OpenAI 的接口：
```bash
curl https://your-domain.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"model": "gpt-4",
"messages": [
{
"role": "user",
"content": "Hello, world!"
}
]
}'
```
### Responses API
支持 OpenAI / Azure Responses：
```bash
curl https://your-domain.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"model": "gpt-5.1-codex-max",
"input": "Hello, Responses API!"
}'
```
### API 测试工具
管理界面内置 API 测试工具，无需额外工具即可调试请求。
功能特性：
- 一键测试：直接在 Web 界面中测试 API 调用
- JSON 编辑器：支持 JSON 格式验证和语法高亮
- 实时响应：显示响应时间、状态码和完整响应内容
- 错误诊断：自动区分 HTTP 错误和 JSON 响应，便于排查问题
- 一键复制：支持复制 Token 和响应内容
使用步骤：
1. 访问管理界面，切换到 **API 测试**
2. 输入 API Token
3. 编辑请求 JSON
4. 点击 **发送请求**
5. 查看响应结果和状态信息
## 管理功能
### Web 管理界面
访问 `https://your-domain.com` 即可使用 Web 管理界面，主要包括：
- 渠道管理：添加、编辑、删除 AI 服务商
- API Token 管理：生成、管理和监控 API Token 使用情况
- 定价配置：灵活配置不同模型的定价策略
- API 测试工具：内置测试界面，支持实时调试和错误排查
管理界面特性：
- 现代化 UI：响应式设计，支持桌面和移动设备
- 实时反馈：操作结果即时显示，支持悬浮提示
- 智能表单：自动生成 Token、JSON 格式验证、一键复制，并根据渠道类型智能显示配置字段
- 安全认证：管理员 Token 认证，保护管理数据
## 配置说明
### 渠道配置
目前支持以下 AI 服务商：
#### OpenAI
```json
{
"name": "My OpenAI Channel",
"type": "openai",
"endpoint": "https://api.openai.com/v1/",
"api_key": "sk-your-openai-api-key",
"deployment_mapper": {
"gpt-4": "gpt-4",
"gpt-3.5-turbo": "gpt-3.5-turbo"
}
}
```
#### Gemini
Gemini 通过官方 OpenAI 兼容层接入，建议将 `endpoint` 配置为 `https://generativelanguage.googleapis.com/v1beta/openai/`。
```json
{
"name": "My Gemini Channel",
"type": "gemini",
"endpoint": "https://generativelanguage.googleapis.com/v1beta/openai/",
"api_key": "AIza-your-gemini-api-key",
"deployment_mapper": {
"gemini-2.5-flash": "gemini-2.5-flash",
"gemini-2.5-pro": "gemini-2.5-pro"
}
}
```
#### Azure OpenAI
```json
{
"name": "My Azure OpenAI",
"type": "azure-openai",
"endpoint": "https://your-resource.openai.azure.com/",
"api_key": "your-azure-api-key",
"api_version": "2024-02-15-preview",
"deployment_mapper": {
"gpt-4": "gpt-4-deployment-name",
"gpt-3.5-turbo": "gpt-35-turbo-deployment-name"
}
}
```
#### Claude
```json
{
"name": "My Claude Channel",
"type": "claude",
"endpoint": "https://api.anthropic.com/v1/",
"api_key": "sk-your-claude-api-key",
"api_version": "2023-06-01",
"deployment_mapper": {
"claude-3-5-sonnet-20241022": "claude-3-5-sonnet-20241022"
}
}
```
#### OpenAI Responses
```json
{
"name": "My OpenAI Responses",
"type": "openai-responses",
"endpoint": "https://api.openai.com/v1/",
"api_key": "sk-your-openai-api-key",
"deployment_mapper": {
"gpt-5.1-codex-max": "gpt-5.1-codex-max"
}
}
```
#### Azure OpenAI Responses（v1）
```json
{
"name": "My Azure Responses",
"type": "azure-openai-responses",
"endpoint": "https://your-resource.openai.azure.com/",
"api_key": "your-azure-api-key",
"deployment_mapper": {
"gpt-5.1-codex-max": "your-deployment-name"
}
}
```
渠道配置字段说明：
- `name`：渠道显示名称
- `type`：服务商类型，支持 `openai`、`gemini`、`azure-openai`、`claude`、`openai-responses`、`azure-openai-responses`
- `endpoint`：API 端点地址
- `api_key`：API 密钥
- `api_version`：API 版本，Azure OpenAI / Claude 可用；Azure Responses v1 请留空
- `deployment_mapper`：模型名称映射关系，用于自定义外部模型名与上游部署名的映射
### Token 配置
支持详细的 Token 配置，包括名称、访问权限和配额管理：
```json
{
"name": "用户令牌1",
"channel_keys": ["azure-openai-1", "azure-openai-2"],
"total_quota": 1000000
}
```
Token 配置字段说明：
- `name`：Token 名称，便于管理识别
- `channel_keys`：允许访问的渠道列表，空数组表示允许所有渠道
- `total_quota`：总配额，基础单位为 1,000,000 tokens = $1.00
## 监控与安全
### 监控与统计
- 使用量统计：自动记录每次 API 调用的 Token 使用量
- 费用计算：基于模型定价自动计算费用
- 配额管理：支持 Token 级别的配额限制
- 实时监控：Web 界面实时显示使用情况和剩余配额
### 核心优势
- 零配置部署：基于 Cloudflare Workers，无需服务器维护
- 全球加速：利用 Cloudflare 全球边缘网络，低延迟访问
- 成本优化：按需计费，无固定服务器成本
- 高可用性：依托 Cloudflare 基础设施保证可用性
- 安全可靠：内置 Token 认证和配额管理机制
### 安全性
- Token 认证：所有 API 调用需要有效的 Bearer Token
- 管理员认证：管理接口使用独立的管理员 Token
- CORS 支持：支持按需配置跨域访问策略
## API 文档
部署后可访问以下地址查看 API 文档：
- Swagger UI：`https://your-domain.com/api/docs`
- ReDoc：`https://your-domain.com/api/redocs`
- OpenAPI JSON：`https://your-domain.com/api/openapi.json`