# 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。