KeyNexus/README.md

OpenAI 路由代理（SQLite + 可视化管理）

这是一个面向个人和小团队的 OpenAI 兼容代理，重点是：

1. 不依赖 MySQL，单文件 SQLite 即可运行。
2. 一个统一入口接入多个上游 API。
3. 上游失败时自动切换，减少手工改配置。
4. 提供中文可视化后台，支持上游管理、统计查看、连通性测试、日志清理。

适用场景

1. 你有多个免费/限额 API key，想统一管理。
2. 客户端（如 Cherry Studio / OpenClaw）只想配一个地址和一个 key。
3. 希望某个上游挂了能自动切到下一个上游。

快速开始

1. 安装依赖

pip install flask requests

2. 复制配置模板

Copy-Item .env.example .env

3. 打开 .env，至少修改这三项

4. OPENAI_PROXY_AUTH：客户端访问代理用的 key（建议填 token 本体）。

5. OPENAI_PROXY_ADMIN_TOKEN：后台登录口令。

6. OPENAI_PROXY_SECRET_KEY：Flask 会话密钥（建议随机长字符串）。

7. 初始化数据库（首次一次）

python openai_route.py --init-db

5. 启动服务

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。