Codex Proxy RS

OpenAI Responses 兼容的 Codex 多账号网关

快速部署 · 客户端接入 · 架构说明

Codex Proxy RS 为多个 Codex 账号提供统一的 Responses API。客户端使用同一个服务地址和 API Key；账号调度、并发限制、额度检查、故障换号和会话续接都在服务端完成。

功能

• 兼容 /v1/responses、SSE 流式响应、Review、Compact 和模型查询。
• 支持 HTTP/SSE 与 WebSocket 上游连接。
• 提供 smart、额度重置优先、轮询和粘性四种账号调度策略。
• 单个账号发生额度、认证、模型或传输故障时，继续使用账号池中的其他可用账号。
• 使用会话亲和和受限历史重放处理 previous_response_not_found 与跨账号续接。
• 为每个账号派生稳定且隔离的 installation、session、thread、turn 和 cache 标识。
• 提供账号、API Key、模型映射、运行参数、用量、错误记录和系统更新管理界面。
• 使用 PostgreSQL 保存权威业务数据，使用 Redis 保存会话、租约、模型快照和会话亲和数据。
• 内置日志轮转、遥测保留期清理和 PostgreSQL/Redis 健康检查。

代理只补充账号凭据、上游请求头和账号作用域身份，并在必要时执行会话恢复；其余请求与响应尽量保持上游语义。

快速部署

需要 Docker Engine 和 Docker Compose Plugin。下面的 Compose 默认使用：

• 应用镜像：ghcr.io/zyycn/codex-proxy-rs:latest
• PostgreSQL 18
• Redis 8
• 管理端地址：http://127.0.0.1:8080

1. 获取项目

git clone https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs

2. 创建配置

mkdir -p .runtime/data .runtime/logs
cp deploy/config.example.yaml .runtime/config.yaml
cp deploy/.env.example deploy/.env
chmod 0600 deploy/.env

编辑 deploy/.env：

CPR_ADMIN_DEFAULT_PASSWORD='<管理员密码，至少 12 个字符>'
CPR_POSTGRES_PASSWORD='<PostgreSQL 密码>'
CPR_REDIS_PASSWORD='<Redis 密码>'

deploy/.env 已被 Git 忽略。应用会安全地把 PostgreSQL 和 Redis 密码写入运行时连接 URL，不需要把真实密码填入 .runtime/config.yaml。

Linux 宿主机需要保证容器用户 10001:10001 可以读写数据和日志目录：

sudo chown -R "$(id -u):10001" .runtime/data .runtime/logs
chmod 0770 .runtime/data .runtime/logs
sudo chown "$(id -u):10001" .runtime/config.yaml
chmod 0640 .runtime/config.yaml

3. 启动

docker compose --env-file deploy/.env -f deploy/docker-compose.yml config
docker compose --env-file deploy/.env -f deploy/docker-compose.yml pull
docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d --no-build

检查服务：

docker compose --env-file deploy/.env -f deploy/docker-compose.yml ps
curl -i http://127.0.0.1:8080/healthz

/healthz 正常时返回 204 No Content。随后打开 http://127.0.0.1:8080：

• 用户名：admin@cpr.local
• 密码：deploy/.env 中的 CPR_ADMIN_DEFAULT_PASSWORD

首次登录后导入账号，在“API 密钥”页面创建客户端 Key。

本地构建镜像

需要验证当前源码时，不拉取 GHCR 镜像，直接构建：

docker compose --env-file deploy/.env -f deploy/docker-compose.yml build codex-proxy-rs
docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d

客户端接入

OpenAI 兼容客户端填写：

• Base URL：http://127.0.0.1:8080/v1
• API Key：管理端创建的 sk_... 客户端 Key

Responses 请求示例：

curl http://127.0.0.1:8080/v1/responses \
  -H 'Authorization: Bearer <client-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model-id>",
    "input": "Reply with pong.",
    "stream": false
  }'

可用接口：

路由	说明
POST /v1/responses	Responses 非流式或 SSE 流式请求
POST /v1/responses/review	Review 请求
POST /v1/responses/compact	Compact 请求
GET /v1/models	模型列表
GET /v1/models/catalog	模型目录
GET /v1/models/{model_id}	模型详情
GET /v1/models/{model_id}/info	模型运行信息

Compose 默认只监听宿主机 127.0.0.1。需要从其他设备访问时，应在前面配置 HTTPS 反向代理，不要直接暴露 PostgreSQL 和 Redis 端口。

管理端

管理端提供以下页面：

• Dashboard：请求趋势、服务状态、账号概览和最近请求。
• 账号：导入、导出、OAuth、连接测试、quota 和 token 刷新。
• API 密钥：创建、停用、删除和客户端接入信息。
• 用量：请求记录、token、延迟、模型分布和运维错误。
• 设置：模型别名、账号调度策略、单账号并发、请求间隔和刷新参数。
• 系统：版本检查、更新、重启和回滚。

管理端登录会话保存在 Redis，并按 admin.session_ttl_minutes 自动过期。

配置

启动配置位于 .runtime/config.yaml，模板见 deploy/config.example.yaml。

配置段	用途
server	HTTP 监听地址和端口
api	Codex 上游地址
database、redis	PostgreSQL 与 Redis 连接
quota	quota 刷新周期和耗尽账号过滤
tls	上游 HTTP 协议偏好
ws_pool	WebSocket 连接池与首事件超时
fingerprint	Codex Desktop 请求指纹
admin	默认管理员和登录会话 TTL
logging	日志级别、目录、大小和保留期
telemetry	请求事实记录开关

模型别名、调度策略、单账号并发、请求间隔和刷新参数由管理端保存到 PostgreSQL，可在运行中更新。请求事实、运维错误和聚合时间桶由后台任务按各自保留期自动清理。

数据与升级

数据	默认位置
账号、API Key、设置、用量和错误记录	Compose 命名卷 postgres-data
管理会话、租约、模型快照和会话亲和	Compose 命名卷 redis-data
身份派生密钥和更新状态	.runtime/data
文件日志	.runtime/logs
启动配置	.runtime/config.yaml
Docker 密钥	deploy/.env

普通升级只替换应用镜像：

docker compose --env-file deploy/.env -f deploy/docker-compose.yml pull codex-proxy-rs
docker compose --env-file deploy/.env -f deploy/docker-compose.yml up -d --no-build

更新镜像不会删除数据库卷，但仍应在升级前备份 PostgreSQL 和 .runtime/data。

不要使用 docker compose down -v 做普通升级，该命令会删除 PostgreSQL 与 Redis 命名卷。

.runtime/data/identity_hmac_secret 必须长期保留。丢失该文件会改变全部账号的 installation ID 和账号作用域身份。

查看状态

# 容器状态
docker compose --env-file deploy/.env -f deploy/docker-compose.yml ps

# 应用日志
docker compose --env-file deploy/.env -f deploy/docker-compose.yml logs -f codex-proxy-rs

# PostgreSQL 和 Redis 日志
docker compose --env-file deploy/.env -f deploy/docker-compose.yml logs postgres redis

# 展开并检查最终 Compose 配置
docker compose --env-file deploy/.env -f deploy/docker-compose.yml config

/healthz 返回 503 时，先检查 PostgreSQL 和 Redis 的健康状态。容器反复重启时，再检查 .runtime/config.yaml、deploy/.env 和 .runtime/data、.runtime/logs 的权限。

架构

模块边界、请求链路、换号条件、previous response 恢复、存储归属和后台任务见 架构说明。

License

MIT