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 统一网关，支持多渠道管理、负载均衡、用量统计和追踪。
+
-## ✨ 功能特性
+## 项目概览
-- 🚀 **基于 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`