From 3781bd90617f1ce37e5cf2fa82ae1c6b7a67a46b Mon Sep 17 00:00:00 2001 From: Jeff Gu Date: Wed, 15 Apr 2026 11:20:06 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0&=E4=B8=B0?= =?UTF-8?q?=E5=AF=8C=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 - README.md | 467 ++++++------------------- docs/security/admin-auth-protection.md | 81 +++++ docs/testing.md | 77 ++++ docs/usage-and-configuration.md | 252 +++++++++++++ 5 files changed, 511 insertions(+), 367 deletions(-) create mode 100644 docs/security/admin-auth-protection.md create mode 100644 docs/testing.md create mode 100644 docs/usage-and-configuration.md diff --git a/.gitignore b/.gitignore index 26d670b..2350960 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,3 @@ lerna-debug.log* public*/ bun.lock *.local.jsonc -docs/ diff --git a/README.md b/README.md index b2fe254..4d8b01f 100644 --- a/README.md +++ b/README.md @@ -3,86 +3,78 @@ 一个基于 Cloudflare Workers 分布式、低延迟、高性能的 AI 统一网关，支持多渠道管理、负载均衡、用量统计和追踪。 +
本项目基于 awsl-one-api
-## ✨ 功能特性 +## 项目概览 -- 🚀 **基于 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
D1 Database)] - D2[(Cloudflare
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 -``` +当前后台页面包括： -
-

📁 项目结构

 +- `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 与开发命令 ``` -
- -## 🚀 快速开始 +## 快速开始 ### 环境要求 - 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`。 -
-

📖 使用与配置

 +如果你在 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` - -
- -## 🤝 贡献 - -欢迎提交 Issue 和 Pull Request！ - -## 📄 许可证 +## 许可证 MIT License 鸣谢：awsl-one-api -## 🙋‍♂️ 支持 +## 支持 如有问题或建议，请创建 Issue 或联系维护者。 diff --git a/docs/security/admin-auth-protection.md b/docs/security/admin-auth-protection.md new file mode 100644 index 0000000..b096ca3 --- /dev/null +++ b/docs/security/admin-auth-protection.md @@ -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 刷屏或管理口扫号，再继续收紧边缘层阈值 diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..2b45387 --- /dev/null +++ b/docs/testing.md @@ -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 diff --git a/docs/usage-and-configuration.md b/docs/usage-and-configuration.md new file mode 100644 index 0000000..668d780 --- /dev/null +++ b/docs/usage-and-configuration.md @@ -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`