141 lines
4.2 KiB
Markdown
141 lines
4.2 KiB
Markdown
# OpenAI 路由代理（SQLite + 可视化管理）
|
||
|
||
这是一个面向个人和小团队的 OpenAI 兼容代理，重点是：
|
||
|
||
1. 不依赖 MySQL，单文件 SQLite 即可运行。
|
||
2. 一个统一入口接入多个上游 API。
|
||
3. 上游失败时自动切换，减少手工改配置。
|
||
4. 提供中文可视化后台，支持上游管理、统计查看、连通性测试、日志清理。
|
||
|
||
## 适用场景
|
||
|
||
1. 你有多个免费/限额 API key，想统一管理。
|
||
2. 客户端（如 Cherry Studio / OpenClaw）只想配一个地址和一个 key。
|
||
3. 希望某个上游挂了能自动切到下一个上游。
|
||
|
||
## 快速开始
|
||
|
||
1. 安装依赖
|
||
|
||
```bash
|
||
pip install flask requests
|
||
```
|
||
|
||
2. 复制配置模板
|
||
|
||
```powershell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
3. 打开 `.env`，至少修改这三项
|
||
|
||
1. `OPENAI_PROXY_AUTH`：客户端访问代理用的 key（建议填 token 本体）。
|
||
2. `OPENAI_PROXY_ADMIN_TOKEN`：后台登录口令。
|
||
3. `OPENAI_PROXY_SECRET_KEY`：Flask 会话密钥（建议随机长字符串）。
|
||
|
||
4. 初始化数据库（首次一次）
|
||
|
||
```bash
|
||
python openai_route.py --init-db
|
||
```
|
||
|
||
5. 启动服务
|
||
|
||
```bash
|
||
python openai_route.py
|
||
```
|
||
|
||
启动后访问：
|
||
|
||
1. 首页：`http://127.0.0.1:8056/`
|
||
2. 管理后台：`http://127.0.0.1:8056/admin`
|
||
|
||
## 后台功能
|
||
|
||
后台首页 `/admin` 支持：
|
||
|
||
1. 新增上游
|
||
2. 编辑上游
|
||
3. 启用/停用上游
|
||
4. 删除上游（会自动清理关联日志）
|
||
5. 一键测试单条上游连通性（按钮：`测试连通性`）
|
||
6. 清理历史日志（按钮：`清理日志`）
|
||
7. 查看最近调用命中哪条上游（“最近 50 次调用”）
|
||
|
||
统计页 `/admin/stats` 支持：
|
||
|
||
1. 近 14 天请求统计
|
||
2. 最近失败日志明细
|
||
|
||
## 字段说明（后台）
|
||
|
||
1. 中文别名：客户端可直接填这个值作为 `model`。
|
||
2. 分组编号：用于分组路由，支持数字和英文（例如 `1`、`nvidia_pool`）。
|
||
3. 上游模型名：转发给上游时实际使用的模型名。
|
||
4. 上游地址：上游 `.../v1` 地址。
|
||
5. API 密钥：该上游 key。
|
||
6. 强制参数(JSON)：会覆盖或补充客户端请求参数。
|
||
7. 请求限额：周期内请求数，`0` 表示不限额。
|
||
8. Token 限额：周期内 token，`0` 表示不限额。
|
||
|
||
## 客户端如何填写
|
||
|
||
1. `base_url`：`http://127.0.0.1:8056/v1`
|
||
2. `api_key`：`.env` 里的 `OPENAI_PROXY_AUTH`
|
||
3. `model`：建议填“中文别名”或“分组编号”
|
||
|
||
示例：
|
||
|
||
1. 使用中文别名池：`model=通用聊天`
|
||
2. 使用数字分组：`model=1`
|
||
3. 使用英文分组：`model=group:nvidia_pool`（也支持直接填 `nvidia_pool`）
|
||
|
||
## 路由识别规则
|
||
|
||
`model` 的识别顺序：
|
||
|
||
1. 以 `group:` 开头：按分组路由
|
||
2. 包含逗号：按多分组路由
|
||
3. 纯数字：按分组路由
|
||
4. 其他：先按“中文别名/上游模型名”精确匹配，未命中再按“分组名”匹配
|
||
|
||
## 自动切换规则
|
||
|
||
当命中池子后，系统会在可用上游中选择并自动切换：
|
||
|
||
1. 默认“稳定优先”：按你配置顺序（上游编号从小到大）优先使用，不会每轮都轮换模型。
|
||
2. 仅当本次请求失败时，才会在同一请求内自动切到下一个上游（无须客户端手工改模型）。
|
||
3. 这些状态会触发自动切换：`401/403/404/408/409/425/429/500/502/503/504`。
|
||
4. `400/422` 仅在错误文本明显属于“模型不存在/不可用”时才切换，避免误切换。
|
||
5. 网络异常也会切换到下一个上游。
|
||
|
||
可通过响应头查看命中信息：
|
||
|
||
1. `X-Route-Upstream-Id`
|
||
2. `X-Route-Group`
|
||
3. `X-Route-Model`
|
||
4. `X-Route-Tried-Ids`
|
||
|
||
## 429 常见误解
|
||
|
||
很多客户端会把所有 `429` 翻译成“请求速率超过限制”，但不一定真是限速。
|
||
请以后端返回的 `error.message` 为准，里面会给出详细原因（匹配数、可用数、冷却数、限额阻塞数）。
|
||
|
||
## 常用环境变量
|
||
|
||
1. `OPENAI_PROXY_AUTH`
|
||
2. `OPENAI_PROXY_ADMIN_TOKEN`
|
||
3. `OPENAI_PROXY_SECRET_KEY`
|
||
4. `OPENAI_PROXY_SQLITE_PATH`
|
||
5. `OPENAI_PROXY_MAX_FAILOVER_ATTEMPTS`
|
||
6. `OPENAI_PROXY_FAILURE_COOLDOWN_SEC`
|
||
7. `OPENAI_PROXY_AUTO_GROUP_FALLBACK`
|
||
8. `OPENAI_PROXY_ADMIN_ENABLED`
|
||
|
||
## 生产建议
|
||
|
||
1. 务必修改默认口令。
|
||
2. 后台建议仅内网可访问。
|
||
3. 定期清理日志，避免 SQLite 持续膨胀。
|
||
4. 若后续是多实例高并发，再迁移 MySQL/Postgres。
|