面向个人开发者、团队与 AI 应用服务商的统一模型接入、账号调度、用量治理与运营管理平台。
当前稳定版本：
v1.0.0线上示例：https://api.carrotche.top
推荐部署方式：Linux 单文件二进制 + PostgreSQL + Redis + Nginx，不依赖 Docker。
十里故清欢 AI API 网关用于把多个 AI 模型渠道收敛为统一入口。应用、IDE 插件或自动化程序只需要维护一个 Base URL 和 API Key，即可按分组、额度、优先级和健康状态使用不同模型渠道。
项目同时提供完整的运营控制台，包括用户、账号、分组、密钥、用量、兑换码、订阅、支付、审计、渠道监控与系统配置。前台、登录注册页和后台控制台均提供协调的深色/浅色赛博朋克主题，并针对桌面和移动设备适配。
| 能力 | 说明 |
|---|---|
| 统一 API 入口 | 提供 OpenAI 兼容接口，并支持 Responses、Chat Completions、Messages、图像和部分视频接口 |
| 多模型接入 | 可管理 OpenAI、Claude、Gemini、Grok、Codex 等模型渠道 |
| 智能调度 | 按分组、优先级、权重、可用状态和并发情况选择账号 |
| 故障切换 | 渠道异常、限流或凭据失效时支持冷却、摘除与重试策略 |
| API Key 管理 | 支持密钥创建、额度、过期时间、模型权限和分组范围管理 |
| 用量与计费 | 记录请求、Token、倍率、费用和趋势，便于核算与审计 |
| 渠道监控 | 提供健康检查、延迟观察、错误状态和调度状态查看 |
| 用户运营 | 支持用户、订阅、兑换码、推广、订单和公告等运营功能 |
| 管理控制台 | 账号列表支持列表、卡片和精简视图，适合不同管理密度 |
| 国际化 | 支持中文和英文界面切换 |
| 响应式主题 | 默认深色主题，可持久化切换浅色主题，适配桌面与移动设备 |
- 为网站、App、机器人或内部系统提供统一 AI API。
- 为团队集中管理不同模型渠道和 API Key。
- 为多个上游账号提供健康检查、负载分配和故障切换。
- 为 AI 服务运营提供用户、额度、计费、兑换码和审计能力。
- 为 Codex、Claude Code、OpenAI SDK 等客户端提供统一 Base URL。
flowchart LR
C["应用 / SDK / IDE"] --> N["Nginx / HTTPS"]
N --> G["十里故清欢 AI API 网关"]
G --> A["鉴权与 API Key"]
G --> R["模型路由与账号调度"]
G --> B["用量、计费与审计"]
A --> P[("PostgreSQL")]
R --> D[("Redis")]
B --> P
R --> U1["OpenAI / Codex"]
R --> U2["Claude"]
R --> U3["Gemini"]
R --> U4["Grok / 其他渠道"]
- 后端：Go
1.26.5、Gin、Ent - 前端：Vue 3、TypeScript、Vite、Pinia、Tailwind CSS
- 数据库：PostgreSQL 15 或更高版本
- 缓存与协调：Redis 7 或更高版本
- 生产入口：Nginx + HTTPS
- 构建形态：前端资源嵌入 Go 二进制，可单文件运行
适合第一次部署和不准备修改源码的用户。完整步骤见：
新手部署教程：Linux、宝塔、Nginx、HTTPS、备份与升级
适合二次开发。Windows 本地需要先安装：
- Go
1.26.5或兼容版本。 - Node.js 20 或更高版本。
- pnpm 9。
- PostgreSQL 15+。
- Redis 7+。
- Air，用于后端热更新。
安装前端依赖和 Air：
cd frontend
pnpm install
cd ..
go install github.com/air-verse/air@latest准备本地 PostgreSQL 数据库，并在 backend/config.yaml 中填写数据库和 Redis 信息。该文件包含密钥，不会被 Git 提交。
启动开发环境：
.\dev.ps1默认地址：
- 前端：
http://127.0.0.1:4173 - 后端健康检查：
http://127.0.0.1:18080/health
停止开发环境：
.\dev-stop.ps1如需同时停止 PostgreSQL 和 Redis：
.\dev-stop.ps1 -StopDataServicescd frontend
pnpm install --frozen-lockfile
pnpm run build前端会输出到 backend/internal/web/dist/。
cd ../backend
CGO_ENABLED=0 go build \
-tags embed \
-trimpath \
-ldflags="-s -w -X main.Version=1.0.0" \
-o sub2api \
./cmd/server-tags embed 不可省略，否则二进制不会包含网页控制台。
./sub2api -version首次运行且数据目录中没有 config.yaml 时，程序会进入安装向导。
sub2api/
|-- backend/ Go 后端、迁移、网关与业务服务
| |-- cmd/server/ 服务入口和版本文件
| |-- ent/ 数据模型与生成代码
| |-- internal/ 核心业务模块
| `-- migrations/ 数据库迁移
|-- frontend/ Vue 3 管理台与公开页面
| |-- public/ Logo 等公开资源
| `-- src/ 页面、组件、状态与主题
|-- deploy/ 配置模板和部署辅助文件
|-- docs/ 专题文档与部署教程
|-- dev.ps1 Windows 本地开发启动脚本
`-- dev-stop.ps1 Windows 本地开发停止脚本
- 完成首次安装向导并创建管理员。
- 登录后台，检查站点名称、Logo、注册策略和邮件配置。
- 创建模型分组，并设置允许的模型和倍率。
- 添加账号或渠道，完成连通性测试。
- 创建测试 API Key，使用
/v1/models和实际请求验证。 - 配置渠道监控和告警策略。
- 配置数据库、配置文件和数据目录的定时备份。
- 正式开放注册或接入业务流量。
curl https://your-domain.example/v1/chat/completions \
-H "Authorization: Bearer sk-your-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [
{"role": "user", "content": "你好，请只回复 OK"}
],
"stream": false
}'查询模型列表：
curl https://your-domain.example/v1/models \
-H "Authorization: Bearer sk-your-key"- 生产环境只开放
80和443，不要把 PostgreSQL、Redis 或8080直接暴露到公网。 - 使用 HTTPS，并设置强数据库密码、JWT 密钥和 TOTP 加密密钥。
config.yaml、数据库备份、账号凭据和日志不得提交到 Git。- 上游地址应优先使用 HTTPS，并限制允许访问的主机范围。
- 管理员账号启用双重验证，并限制后台访问来源。
- 升级前同时备份二进制、
config.yaml、数据目录和 PostgreSQL。 - 对外运营前确认模型供应商规则、隐私政策、数据处理和当地合规要求。
前端：
cd frontend
pnpm run lint:check
pnpm run typecheck
pnpm run test:run
pnpm run build后端：
cd backend
go test ./...- 稳定版本使用
v主版本.次版本.修订号，例如v1.0.0。 - 正式环境建议固定版本，不要直接运行未知提交。
- 升级前阅读 Release 说明，并保留可立即恢复的旧二进制。
- 数据库迁移由程序管理，但仍应在升级前执行
pg_dump。
本仓库保留并遵循 GNU Lesser General Public License v3.0。进行二次分发、修改或商业部署前，请自行阅读许可证及相关依赖的许可要求。
本项目提供的是模型接口管理和技术网关能力，不提供模型本身。部署和运营者应自行确保账号来源、接口使用、内容处理、数据保护、支付结算和对外服务符合适用法律、合同及上游平台规则。