starred/codex-proxy-rs
1
0
Fork 0
mirror of https://github.com/zyycn/codex-proxy-rs.git synced 2026-11-06 08:06:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README

Browse Source
This commit is contained in:
Zyy
2026-07-13 19:09:22 +08:00
parent 2d9510d9e3
commit f4d0576e6b
1 changed files with 129 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+129 -144
View File
@@ -1,58 +1,48 @@
<div align="center">
<h1>Codex Proxy RS</h1>
<p>OpenAI Responses 兼容的 Codex 多账号网关</p>
<p>
<a href="https://www.rust-lang.org/"><img alt="Rust 1.97" src="https://img.shields.io/badge/Rust-1.97-000?style=flat-square&amp;logo=rust" /></a>
<a href="https://github.com/tokio-rs/axum"><img alt="Axum 0.8" src="https://img.shields.io/badge/Axum-0.8-2f7d95?style=flat-square" /></a>
<a href="https://vuejs.org/"><img alt="Vue 3.5" src="https://img.shields.io/badge/Vue-3.5-42b883?style=flat-square&amp;logo=vuedotjs&amp;logoColor=white" /></a>
<a href="https://vite.dev/"><img alt="Vite 8" src="https://img.shields.io/badge/Vite-8-646cff?style=flat-square&amp;logo=vite&amp;logoColor=white" /></a>
<a href="https://www.postgresql.org/"><img alt="PostgreSQL 18" src="https://img.shields.io/badge/PostgreSQL-18-4169e1?style=flat-square&amp;logo=postgresql&amp;logoColor=white" /></a>
<a href="https://redis.io/"><img alt="Redis 8" src="https://img.shields.io/badge/Redis-8-ff4438?style=flat-square&amp;logo=redis&amp;logoColor=white" /></a>
<a href="https://opensource.org/license/mit"><img alt="MIT License" src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" /></a>
</p>
<p>
<a href="#快速部署">快速部署</a>
·
<a href="#客户端接入">客户端接入</a>
·
<a href="docs/architecture.md">架构说明</a>
</p>
<img src="frontend/public/favicon.svg" alt="Codex Proxy RS" width="88" height="88" />
# Codex Proxy RS
**基于 Rust 的高性能 Codex 多账号网关代理**
[![CI](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/zyycn/codex-proxy-rs/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/zyycn/codex-proxy-rs?display_name=tag&sort=semver)](https://github.com/zyycn/codex-proxy-rs/releases)
[![Rust 1.97](https://img.shields.io/badge/Rust-1.97-000?logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![Vue 3.5](https://img.shields.io/badge/Vue-3.5-42b883?logo=vuedotjs&logoColor=white)](https://vuejs.org/)
[![Vite 8](https://img.shields.io/badge/Vite-8-646cff?logo=vite&logoColor=white)](https://vite.dev/)
[![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
[![MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#开源许可)
[快速开始](#快速开始) · [首次使用](#首次使用) · [客户端接入](#客户端接入) · [常见问题](#常见问题) · [部署文档](deploy/README.md)
</div>
Codex Proxy RS 为多个 Codex 账号提供统一的 Responses API。客户端使用同一个服务地址和 API Key；账号调度、并发限制、额度检查、故障换号和会话续接都在服务端完成。
后端使用 Rust、Tokio 和 Axum，管理界面使用 Vue 3、TypeScript 和 Vite。SSE 数据边收边转发，上游 WebSocket 连接按账号复用；前端构建后由同一个服务直接提供。
> [!NOTE]
> 当前兼容 OpenAI Responses API，不提供 `/v1/chat/completions`。
## 功能
- 兼容 `/v1/responses`、SSE、官方 Responses WebSocket 和模型查询。
- 客户端与上游均可使用 HTTP/SSE 或 WebSocket。
- 提供 `smart`、额度重置优先、轮询和粘性四种账号调度策略。
- 单个账号发生额度、认证、模型或传输故障时，继续使用账号池中的其他可用账号。
- 支持跨账号会话续接，并隔离不同账号的会话状态。
- 提供账号、API Key、模型映射、运行参数、用量、错误记录和系统更新管理界面。
- 使用 PostgreSQL 保存权威业务数据，使用 Redis 保存管理会话、租约、模型快照和响应归属。
- 内置日志轮转、遥测保留期清理和 PostgreSQL/Redis 健康检查。
- 支持 Responses HTTP、SSE 和官方 WebSocket 请求。
- 提供智能调度、额度重置优先、轮询和粘滞四种账号策略。
- 某个账号遇到额度、认证、模型或传输错误时，继续尝试其他账号。
- 在网页中管理账号、客户端 Key、模型别名和运行参数。
- 按请求、模型、账号或客户端 Key 查看 Token、费用、缓存、TTFT、延迟和错误。
- 支持账号 OAuth、Token 导入以及 CPR、Sub2API、CLIProxyAPI JSON 导入。
- 可直接生成 Codex CLI 配置，或通过 deeplink 导入 CCSwitch。
除账号调度和会话恢复外，请求与响应尽量保持原有语义。
## 快速开始
## 快速部署
Docker Compose 是最简单的启动方式。开始前请安装 Docker Engine 和 Docker Compose Plugin。
需要 Docker Engine 和 Docker Compose Plugin。下面的 Compose 默认使用：
- 应用镜像：`ghcr.io/zyycn/codex-proxy-rs:latest`
- PostgreSQL 18
- Redis 8
- 管理端地址：`http://127.0.0.1:8080`
### 1. 获取项目
### 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
@@ -62,61 +52,67 @@ chmod 0600 deploy/.env
编辑 `deploy/.env`：
```dotenv
CPR_ADMIN_DEFAULT_PASSWORD='<管理员密码，至少 12 个字符>'
CPR_ADMIN_DEFAULT_PASSWORD='<至少 12 个字符的管理员密码>'
CPR_POSTGRES_PASSWORD='<PostgreSQL 密码>'
CPR_REDIS_PASSWORD='<Redis 密码>'
```
`deploy/.env` 已被 Git 忽略。应用会安全地把 PostgreSQL 和 Redis 密码写入运行时连接 URL，不需要把真实密码填入 `.runtime/config.yaml`。
> [!IMPORTANT]
> 应用容器以非 root 用户 `10001:10001` 运行。Linux Bind Mount 会保留宿主机权限，因此需要允许容器用户组读取配置并写入数据和日志目录：
>
> ```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
> ```
>
> macOS 和 Windows 的 Docker Desktop 通常不需要设置这些权限。
Linux 宿主机需要保证容器用户 `10001:10001` 可以读写数据和日志目录：
### 2. 启动服务
```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 config --quiet
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`。随后打开 <http://127.0.0.1:8080>：
`/healthz` 返回 `204 No Content` 即表示服务正常。管理端地址为 <http://127.0.0.1:8080>。
- 用户名：`admin@cpr.local`
- 密码：`deploy/.env` 中的 `CPR_ADMIN_DEFAULT_PASSWORD`
## 首次使用
首次登录后导入账号，在“API 密钥”页面创建客户端 Key。
1. 使用 `admin@cpr.local` 和 `CPR_ADMIN_DEFAULT_PASSWORD` 中设置的密码登录。
2. 打开“账号”，用 OAuth、Access/Refresh Token 或 JSON 文件添加账号。
3. 点一次连接测试，能看到模型和额度即可。
4. 打开“API 密钥”，创建一个 `sk_...` 客户端 Key。
5. 点击“使用密钥”复制 Codex CLI 配置，或一键导入 CCSwitch。
### 本地构建镜像
需要验证当前源码时，不拉取 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
```
> [!TIP]
> `CPR_ADMIN_DEFAULT_PASSWORD` 只用于首次创建管理员。已有管理员后修改该变量不会重置登录密码，但 Compose 启动时仍要求提供有效值。
## 客户端接入
OpenAI 兼容客户端填写：
| 配置 | 值 |
| -------- | ---------------------------------------- |
| Base URL | `http://127.0.0.1:8080/v1` |
| API Key | 管理端创建的 `sk_...` 客户端 Key |
| 鉴权 | `Authorization: Bearer <client-api-key>` |
- Base URL：`http://127.0.0.1:8080/v1`
- API Key：管理端创建的 `sk_...` 客户端 Key
先查询当前可用模型：
Responses 请求示例：
```bash
curl http://127.0.0.1:8080/v1/models \
-H 'Authorization: Bearer <client-api-key>'
```
发送一个非流式 Responses 请求：
```bash
curl http://127.0.0.1:8080/v1/responses \
@@ -129,98 +125,87 @@ curl http://127.0.0.1:8080/v1/responses \
}'
```
可用接口：
<details>
<summary>查看全部客户端 API 路由</summary>
| 路由 | 说明 |
| --- | --- |
| `POST /v1/responses` | Responses 非流式或 SSE 流式请求 |
| `GET /v1/responses` | 官方 Responses WebSocket |
| `POST /v1/responses/review` | Review 请求 |
| `GET /v1/models` | 模型列表 |
| `GET /v1/models/catalog` | 模型目录 |
| `GET /v1/models/{model_id}` | 模型详情 |
| `GET /v1/models/{model_id}/info` | 模型运行信息 |
| 路由 | 说明 |
| -------------------------------- | ------------------------------- |
| `POST /v1/responses` | Responses 非流式或 SSE 流式请求 |
| `GET /v1/responses` | 官方 Responses WebSocket |
| `POST /v1/responses/review` | Review 请求 |
| `GET /v1/models` | OpenAI 格式的模型列表 |
| `GET /v1/models/catalog` | 完整模型目录 |
| `GET /v1/models/{model_id}` | 模型详情 |
| `GET /v1/models/{model_id}/info` | 模型运行信息 |
Compose 默认只监听宿主机 `127.0.0.1`。需要从其他设备访问时，应在前面配置 HTTPS 反向代理，不要直接暴露 PostgreSQL 和 Redis 端口。
所有 `/v1/*` 路由都需要客户端 API Key。
</details>
## 管理端
管理端提供以下页面：
| 页面 | 内容 |
| -------- | ---------------------------------------------------------------------- |
| 概览 | 查看服务状态、请求趋势、Token、账号池容量、请求健康和最近调用 |
| 账号 | 添加、导入、导出、测试、启停账号，以及刷新 Token 和额度 |
| API 密钥 | 创建、复制、启停或删除 Key，生成 Codex CLI 配置并导入 CCSwitch |
| 使用统计 | 按时间、模型、账号和客户端 Key 查看用量、费用、缓存、延迟和错误 |
| 系统设置 | 配置模型别名、调度策略、单账号并发、请求间隔、刷新参数和管理员 API Key |
| 系统更新 | 查看版本和发布说明；Release 版本可以在线更新并重启 |
- 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` 的权限。
### 从当前源码构建
## 架构
```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
```
模块边界、请求链路、存储归属和后台任务见 [架构说明](docs/architecture.md)。
> [!WARNING]
> 不要使用 `docker compose down -v` 进行普通升级，它会删除 PostgreSQL 和 Redis 数据卷。请同时备份 PostgreSQL 与 `.runtime/data/identity_hmac_secret`；数据库备份中包含客户端凭据，应按敏感数据保管。
## License
## 常见问题
MIT
### `/healthz` 返回 `503`
检查 PostgreSQL 和 Redis 容器是否健康：
```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 postgres redis
```
### 容器反复重启
检查 `deploy/.env` 是否填写完整，以及 `.runtime/config.yaml`、`.runtime/data`、`.runtime/logs` 的权限是否正确。
### 需要从其他设备访问
Compose 默认仅绑定 `127.0.0.1`。请在服务前配置 HTTPS 反向代理，并正确转发 WebSocket 升级和真实客户端 IP 请求头。不要直接暴露 PostgreSQL 或 Redis。
## 相关链接
- [发布版本](https://github.com/zyycn/codex-proxy-rs/releases)
- [容器镜像](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
- [详细部署说明](deploy/README.md)
- [架构说明](docs/architecture.md)
Docker 镜像支持 Linux amd64/arm64。Release 压缩包另有 macOS arm64 和 Windows amd64 版本。
## 开源许可
Codex Proxy RS 基于 [MIT License](https://opensource.org/license/mit) 开源。