diff --git a/README.md b/README.md index 5ab347567..dc343be3d 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,48 @@
-

Codex Proxy RS

-

OpenAI Responses 兼容的 Codex 多账号网关

-

- Rust 1.97 - Axum 0.8 - Vue 3.5 - Vite 8 - PostgreSQL 18 - Redis 8 - MIT License -

-

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

+ + Codex Proxy RS + +# 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) +
-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='' CPR_REDIS_PASSWORD='' ``` -`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`。随后打开 ： +`/healthz` 返回 `204 No Content` 即表示服务正常。管理端地址为 。 -- 用户名：`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 ` | -- 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 ' +``` + +发送一个非流式 Responses 请求： ```bash curl http://127.0.0.1:8080/v1/responses \ @@ -129,98 +125,87 @@ curl http://127.0.0.1:8080/v1/responses \ }' ``` -可用接口： +
+查看全部客户端 API 路由 -| 路由 | 说明 | -| --- | --- | -| `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。 + +
## 管理端 -管理端提供以下页面： +| 页面 | 内容 | +| -------- | ---------------------------------------------------------------------- | +| 概览 | 查看服务状态、请求趋势、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) 开源。