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. 获取项目
```bash
git clone https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
```
### 2. 创建配置
```bash
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`：
```dotenv
CPR_ADMIN_DEFAULT_PASSWORD='<管理员密码，至少 12 个字符>'
CPR_POSTGRES_PASSWORD=''
CPR_REDIS_PASSWORD=''
```
`deploy/.env` 已被 Git 忽略。应用会安全地把 PostgreSQL 和 Redis 密码写入运行时连接 URL，不需要把真实密码填入 `.runtime/config.yaml`。
Linux 宿主机需要保证容器用户 `10001:10001` 可以读写数据和日志目录：
```bash
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. 启动
```bash
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
```
检查服务：
```bash
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`。随后打开 ：
- 用户名：`admin@cpr.local`
- 密码：`deploy/.env` 中的 `CPR_ADMIN_DEFAULT_PASSWORD`
首次登录后导入账号，在“API 密钥”页面创建客户端 Key。
### 本地构建镜像
需要验证当前源码时，不拉取 GHCR 镜像，直接构建：
```bash
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 请求示例：
```bash
curl http://127.0.0.1:8080/v1/responses \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json' \
-d '{
"model": "",
"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](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` |
普通升级只替换应用镜像：
```bash
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 和账号作用域身份。
## 查看状态
```bash
# 容器状态
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 恢复、存储归属和后台任务见 [架构说明](docs/architecture.md)。
## License
MIT
