list

.env.example

@@ -0,0 +1,32 @@
+# 代理接口鉴权 建议直接填 token 本体
+# 例如 sk-abc123
+# 客户端可填 sk-abc123，系统会自动兼容 Bearer 格式
+OPENAI_PROXY_AUTH=请改成你的代理令牌
+
+# 可视化后台管理员口令 访问 /admin/login 使用
+OPENAI_PROXY_ADMIN_TOKEN=请改成你的后台口令
+
+# Flask 会话密钥 建议改成随机长字符串
+OPENAI_PROXY_SECRET_KEY=请改成随机长密钥
+
+# 数据库文件路径
+OPENAI_PROXY_SQLITE_PATH=./data/openai_proxy.db
+
+# 监听地址和端口
+OPENAI_PROXY_LISTEN_HOST=0.0.0.0
+OPENAI_PROXY_LISTEN_PORT=8056
+
+# 失败自动切换相关
+OPENAI_PROXY_MAX_FAILOVER_ATTEMPTS=5
+OPENAI_PROXY_FAILURE_COOLDOWN_SEC=300
+OPENAI_PROXY_AUTO_GROUP_FALLBACK=true
+
+# 后台开关 true 或 false
+OPENAI_PROXY_ADMIN_ENABLED=true
+
+# 日志策略
+OPENAI_PROXY_LOG_FULL_PAYLOAD=false
+OPENAI_PROXY_LOG_TEXT_LIMIT=100000
+
+# 调试开关 生产建议 false
+OPENAI_PROXY_DEBUG=false

README.md

@@ -0,0 +1,140 @@
+# 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。