Codex2API

Codex2API 是一个基于 Go + Gin + PostgreSQL + Redis + React/Vite 的 Codex 反向代理与管理后台项目。

它对外提供兼容 OpenAI 风格的接口，并在内部维护一套基于 Refresh Token 账号池 的调度、刷新、测试、限流恢复、用量观测与后台管理能力。

本项目在设计与实现思路上参考并鸣谢 router-for-me/CLIProxyAPI 与 Wei-Shaw/sub2api。

---

快速部署

部署模式总览

模式	文件	适用场景
Docker 镜像部署	docker-compose.yml	推荐，服务器 / 测试环境，直接拉取预构建镜像
本地源码容器构建	docker-compose.local.yml	本地改代码后做完整容器验证
本地开发	go run . + npm run dev	前后端联调与调试

方案一：Docker 镜像部署（推荐）

# 1. 克隆仓库并创建环境配置
git clone https://github.com/james-6-23/codex2api.git
cd codex2api
cp .env.example .env

# 2. 按需编辑 .env 中的端口、数据库和 Redis 参数

# 3. 拉取镜像并启动
docker compose pull
docker compose up -d

# 4. 查看日志
docker compose logs -f codex2api

启动后访问：

• 管理台：http://localhost:8080/admin/
• 健康检查：http://localhost:8080/health

升级命令：

git pull && docker compose pull && docker compose up -d && docker compose logs -f codex2api

方案二：本地源码构建容器

cp .env.example .env
docker compose -f docker-compose.local.yml up -d --build
docker compose -f docker-compose.local.yml logs -f codex2api

方案三：本地开发模式

后端：

cp .env.example .env
cd frontend && npm ci && npm run build && cd ..
go run .

首次启动需要先构建前端，因为 Go 使用 go:embed 嵌入 frontend/dist 。

前端开发服务器（联调）：

cd frontend && npm ci && npm run dev

Vite 会自动代理 /api 和 /health 到后端，开发时访问 http://localhost:5173/admin/。

---

环境配置

.env 环境变量

变量	说明
CODEX_PORT	HTTP 端口，默认 8080
DATABASE_HOST	PostgreSQL 主机
DATABASE_PORT	PostgreSQL 端口，默认 5432
DATABASE_USER	PostgreSQL 用户
DATABASE_PASSWORD	PostgreSQL 密码
DATABASE_NAME	PostgreSQL 数据库名
DATABASE_SSLMODE	SSL 模式，默认 disable
REDIS_ADDR	Redis 地址，例如 redis:6379
REDIS_PASSWORD	Redis 密码
REDIS_DB	Redis DB 库号
TZ	时区，例如 Asia/Shanghai

业务运行配置

以下参数保存在数据库 SystemSettings 中，通过管理台设置页面修改：

MaxConcurrency、GlobalRPM、TestModel、TestConcurrency、ProxyURL、PgMaxConns、RedisPoolSize、AdminSecret、自动清理开关等。

首次启动时程序会自动写入默认设置。

API Key 与管理密钥

• 对外 API Key：以数据库中的 API Keys 为准。如果没有配置任何 Key，则 /v1/* 跳过鉴权。
• 管理后台 Admin Secret：保存在数据库的 AdminSecret 中。为空时跳过鉴权；已设置时前端通过 X-Admin-Key 头进行认证。

---

对外接口

接口	说明
POST /v1/chat/completions	Chat Completions 风格入口
POST /v1/responses	Responses 风格入口
GET /v1/models	返回可用模型列表
GET /health	健康检查

---

管理后台

浏览器访问 /admin/，提供以下页面：

页面	路径	功能
Dashboard	/admin/	总览指标、请求趋势、延迟趋势、Token 分布、模型排行
账号管理	/admin/accounts	导入、测试、批量处理、调度信息查看
使用统计	/admin/usage	请求日志、统计卡片、图表、日志清空
运维概览	/admin/ops	运行态监控与系统概览
调度看板	/admin/ops/scheduler	调度健康度、惩罚项和评分拆解
系统设置	/admin/settings	业务运行参数与后台密钥配置

---

核心能力

项目定位

这个项目不是单纯的接口转发，而是一套面向长期运行的 Codex 网关与管理后台：

• 对外提供统一的 OpenAI 风格入口，屏蔽上游多账号差异
• 对内维护基于 Refresh Token 的账号池、Access Token 生命周期和运行时调度
• 通过 PostgreSQL 与 Redis 实现配置持久化、运行态缓存和高频协调
• 通过 /admin 管理台提供全面的运维观测能力

架构概览

对外请求链路： 客户端请求 → Gin RPM 限流 → proxy.Handler API Key 校验 → auth.Store 调度选号 → 上游请求 → 响应回传 + 用量写入

管理后台链路： 浏览器 → /admin/ 嵌入式前端 → /api/admin/* 管理接口 → 数据库 / 账号池 / Redis

调度系统

调度核心位于 auth.Store，将账号可用性、健康度、动态并发、历史错误和近期用量综合纳入选择。

运行时状态模型：

• Status：ready / cooldown / error
• HealthTier：healthy / warm / risky / banned
• SchedulerScore：以 100 为基线的实时调度分
• DynamicConcurrencyLimit：按健康层级动态收缩的并发上限

账号选择策略：

1. 过滤不可用账号（error / banned / 冷却中 / 无 AccessToken）
2. 重算健康层级、调度分和动态并发
3. 排除已达并发上限的账号
4. 按 healthy > warm > risky > banned 排序，同层级按调度分和并发数择优
5. 15% 概率随机打散，降低热点与饥饿

动态并发规则：

层级	并发上限
healthy	系统 MaxConcurrency
warm	基础并发 ÷ 2（最少 1）
risky	固定 1
banned	固定 0，不参与调度

调度分惩罚/奖励：

信号	影响
unauthorized	-50，24h 线性衰减
rate_limited	-22，1h 线性衰减
timeout	-18，15min 线性衰减
server error	-12，15min 线性衰减
连续失败	每次 -6，最多 -24
连续成功	每次 +2，最多 +12
近期成功率过低	<75% 扣 8，<50% 扣 15
Free 7d 用量	≥70% 扣 8 → ≥100% 扣 40
延迟 EWMA	≥5s 扣 4 → ≥20s 扣 15

冷却与恢复机制：

• 429：优先解析上游 resets_at，否则按套餐类型推断冷却时间
• 401：直接进入 banned，6h 冷却，24h 内再触发升至 24h
• 冷却状态持久化到 PostgreSQL，重启后自动恢复
• 后台会对 banned 账号做周期性低频恢复探测

调度可观测性：

• GET /api/admin/accounts — 健康层级、调度分、惩罚拆解
• GET /api/admin/ops/overview — 系统运行态与连接池概览
• /admin/ops/scheduler — 前端调度看板

---

目录结构

codex2api/
├─ main.go                      # 程序入口
├─ Dockerfile                   # 多阶段镜像构建
├─ docker-compose.yml           # 镜像部署模板
├─ docker-compose.local.yml     # 本地源码构建模板
├─ .env.example                 # 环境变量示例
├─ admin/                       # 管理后台 API
├─ auth/                        # 账号池、调度与 token 管理
├─ cache/                       # Redis 缓存封装
├─ config/                      # 环境变量加载
├─ database/                    # PostgreSQL 访问层
├─ proxy/                       # 对外代理、转发与限流
└─ frontend/                    # React + Vite 管理后台
   ├─ src/pages/                # Dashboard / Accounts / Usage / Ops / Settings
   ├─ src/components/           # UI 组件
   ├─ src/locales/              # 国际化语言文件 (zh/en)
   └─ vite.config.js            # Vite 配置

---

常见注意事项

• docker-compose.yml 拉取 GHCR 镜像用于部署；docker-compose.local.yml 用 build: . 做本地构建
• 前端基路径固定为 /admin/，本地开发和生产部署一致
• 本地手动构建 Go 二进制前需先执行 frontend/ 的 npm run build
• .env 只负责端口、数据库、Redis 等物理层配置；业务参数在管理台数据库里维护
• API Key 以数据库为准，在管理台中配置

---

免责声明与开源协议

• 本项目仅供学习、研究与技术交流使用。
• 本项目采用 MIT License 开源协议。
• 项目不对任何直接或间接使用后果提供担保；生产环境使用风险由使用者自行承担。