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

docs: refresh project documentation

Browse Source 
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
zyycn
2026-07-05 22:39:26 +08:00
co-authored by Codex
parent af8b691e7f
commit bf5021965b
6 changed files with 52 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+18 -16
View File
@@ -15,11 +15,11 @@
## 概览
Codex Proxy RS 是一个单进程服务：
Codex Proxy RS 是一个单进程网关：
- Rust/Axum 后端提供 OpenAI 兼容 `/v1/*` 代理、管理端 API、SQLite 持久化和静态前端托管。
- Vue 管理端用于账号导入、API Key、用量统计、请求记录、运行参数、模型映射和系统更新。
- 运行数据默认收敛到仓库 `.runtime/`，Docker 也使用同一套宿主机目录做 bind mount。
- Rust/Axum 后端提供 Responses 兼容代理、管理端 API、SQLite 持久化和静态前端托管。
- Vue 管理端负责账号导入、API Key、用量统计、请求记录、运行参数、模型映射和系统更新。
- 运行数据默认写入仓库 `.runtime/`；Docker 部署也使用这套宿主机目录挂载。
## 环境
@@ -55,7 +55,7 @@ mkdir -p .runtime/data .runtime/logs
CPR_CONFIG_FILE=.runtime/config.yaml cargo run --manifest-path backend/Cargo.toml
```
服务默认监听 `http://0.0.0.0:8080`。
服务默认监听 `0.0.0.0:8080`。本机访问通常使用 `http://127.0.0.1:8080`。
## Docker 部署
@@ -106,8 +106,11 @@ docker compose -f deploy/docker-compose.yml up -d
| 端点 | 说明 |
| --- | --- |
| `POST /v1/responses` | OpenAI Responses 兼容接口 |
| `POST /v1/responses/review` | Review 模型请求入口 |
| `POST /v1/responses/compact` | Compact 请求入口 |
| `GET /v1/models` | 模型列表 |
| `GET /v1/models/{id}` | 模型详情 |
| `GET /v1/models/{id}/info` | 模型运行信息 |
| `GET /v1/models/catalog` | 管理端可见模型目录 |
| `/api/admin/*` | 管理端 API |
@@ -136,11 +139,11 @@ pnpm --dir frontend build
CPR_CONFIG_FILE=.runtime/config.yaml cargo run --manifest-path backend/Cargo.toml
```
管理端主要功能：
管理端功能：
- 账号导入、OAuth 授权、连接测试、quota 刷新、token 刷新。
- 客户端 API Key 管理。
- 请求记录、Token 用量、模型用量和账号额度。
- Dashboard、请求记录、Token 用量、模型用量和账号额度。
- 运行参数、模型别名、账号选择策略。
- 版本检查、在线更新、更新日志、重启和回滚。
@@ -151,7 +154,7 @@ CPR_CONFIG_FILE=.runtime/config.yaml cargo run --manifest-path backend/Cargo.tom
`.runtime` 约定：
```text
.runtime/config.yaml # 本地或 Docker 启动配置，按实际运行环境写路径
.runtime/config.yaml # 本地或 Docker 启动配置，路径按运行环境写
.runtime/data/codex-proxy-rs.sqlite # SQLite 数据库
.runtime/data/installation_id # 上游 installation id
.runtime/data/update-state.json # 在线更新状态
@@ -161,22 +164,21 @@ CPR_CONFIG_FILE=.runtime/config.yaml cargo run --manifest-path backend/Cargo.tom
## 发布与更新
版本信息在 `release/version.yaml`，发布平台在 `release/platforms.yaml`。
当前版本记录在 `release/version.yaml`，发布平台记录在 `release/platforms.yaml`。
发布命令：
```bash
release/publish 0.1.5
release/publish 1.0.4
```
该命令会更新版本文件、生成版本提交、创建 `v<version>` tag 并推送，随后 GitHub Actions 构建 Release 归档和 GHCR 多平台镜像。
该命令会更新版本文件、生成版本提交、创建 `v<version>` tag 并推送。GitHub Actions 随后构建 Release 归档和 GHCR 多平台镜像。
在线更新由主服务处理，管理端调用 `/api/admin/system/*`：
- 检查 GitHub Release。
- 下载匹配当前平台的归档和 `checksums.txt`。
- 校验 checksum。
- 替换二进制和 `web/dist`。
- 查询 GitHub Release。
- 下载当前平台对应的归档和 `checksums.txt`。
- 校验 checksum 后替换二进制和 `web/dist`。
- 重启时，Docker 模式依赖 `restart: unless-stopped` 拉起新容器进程；非 Docker 模式会先安排新进程延迟启动，再关闭当前进程。
## 项目结构
@@ -185,7 +187,7 @@ release/publish 0.1.5
backend/ Rust/Axum 后端、SQLite migration、集成测试
frontend/ Vue 3 管理端
deploy/ Dockerfile、Compose、部署配置模板
docs/ 架构、审计和维护文档
docs/ 架构和维护文档
release/ 版本、平台和发布脚本
skills/ 项目本地 Codex skill
```
deploy/README.md
+11 -10
View File
@@ -1,6 +1,6 @@
# Deploy
# 部署
Docker 部署入口集中在本目录。
本目录包含 Dockerfile、Compose 文件和 Docker 配置模板。
## Compose
@@ -11,16 +11,17 @@ mkdir -p .runtime/data .runtime/logs
cp deploy/config.example.yaml .runtime/config.yaml
```
`deploy/config.example.yaml` 是 Docker 部署模板。Compose 默认把配置、数据和日志都放在仓库 `.runtime/` 下：
`deploy/config.example.yaml` 是 Docker 部署模板。Compose 默认使用仓库根目录的 `.runtime/`：
- `.runtime/config.yaml` -> `/app/config.yaml`
- `.runtime/data` -> `/app/data`
- `.runtime/logs` -> `/app/logs`
复制后必须设置 `admin.default_password`，空值或常见弱口令会被后端拒绝启动。
如果前面还有 Nginx、Caddy、Cloudflare Tunnel 等反向代理，建议把后端实际看到的代理 peer IP 或 CIDR 写入 `server.trusted_proxies`。Docker 端口映射经宿主反代访问时，这个 peer 通常是 Compose 网络网关，例如 `172.18.0.1/32`，不是宿主 `127.0.0.1/32`。
复制后必须设置 `admin.default_password`。空值、长度不足 12 位或常见弱口令会被后端拒绝。
`server.trusted_proxies` 非空时，只有这些 peer 的 `CF-Connecting-IP` / `X-Real-IP` / `X-Forwarded-For` 会被采信；为空时进入兼容自动模式，按同一组头解析真实 IP。
如果前面还有 Nginx、Caddy、Cloudflare Tunnel 等反向代理，把后端实际看到的代理 peer IP 或 CIDR 写入 `server.trusted_proxies`。经宿主机反代访问 Docker 端口时，这个 peer 通常是 Compose 网络网关，例如 `172.18.0.1/32`，不是宿主 `127.0.0.1/32`。
`server.trusted_proxies` 非空时，只有这些 peer 的 `CF-Connecting-IP` / `X-Real-IP` / `X-Forwarded-For` 会被采信；为空时进入自动解析模式，按同一组头解析真实 IP。
构建并启动：
@@ -29,7 +30,7 @@ docker compose -f deploy/docker-compose.yml build
docker compose -f deploy/docker-compose.yml up -d
```
可以通过环境变量覆盖宿主机路径；容器内会通过 `CPR_CONFIG_FILE=/app/config.yaml` 显式读取挂载后的配置：
可以通过环境变量覆盖宿主机路径。容器内始终通过 `CPR_CONFIG_FILE=/app/config.yaml` 读取挂载后的配置：
```bash
CPR_CONFIG_FILE=/path/to/config.yaml \
@@ -38,7 +39,7 @@ CPR_LOG_DIR=/path/to/logs \
docker compose -f deploy/docker-compose.yml up -d
```
## Build
## 构建
Docker 构建上下文保持仓库根目录：
@@ -46,13 +47,13 @@ Docker 构建上下文保持仓库根目录：
docker build -f deploy/Dockerfile -t codex-proxy-rs:latest .
```
也可以通过 Compose 构建：
也可以用 Compose 构建：
```bash
docker compose -f deploy/docker-compose.yml build
```
需要注入版本信息时：
需要写入版本元数据时：
```bash
CPR_VERSION="$(ruby -ryaml -e 'puts YAML.load_file("release/version.yaml").fetch("version").delete_prefix("v")')" \
deploy/config.example.yaml
+1 -1
View File
@@ -6,7 +6,7 @@ server:
# 可信反向代理 IP 或 CIDR。非空时只有这些 peer 的转发 IP 头会被采信。
# Docker 端口映射经宿主反代访问时，后端看到的 peer 通常是 Compose 网络网关
# （例如 172.18.0.1），不是宿主 127.0.0.1。
# 为空时进入兼容自动模式，按 CF-Connecting-IP / X-Real-IP / X-Forwarded-For 解析。
# 为空时进入自动解析模式，按 CF-Connecting-IP / X-Real-IP / X-Forwarded-For 解析。
trusted_proxies: []
api:
docs/architecture.md
+12 -12
View File
@@ -1,17 +1,17 @@
# Codex Proxy RS 架构说明
# Codex Proxy RS 架构
## 总览
Codex Proxy RS 是一个单主进程应用。Rust 后端同时承担 OpenAI 兼容代理、管理端 API、SQLite 持久化、后台任务、静态前端托管和在线更新；Vue 管理端作为 SPA 由同一个后端进程服务。
Codex Proxy RS 是单进程应用。Rust 后端同时处理 Responses 兼容代理、管理端 API、SQLite 持久化、后台任务、静态前端托管和在线更新；Vue 管理端作为 SPA 由同一个进程托管。
```mermaid
flowchart LR
Client["客户端 / OpenAI SDK"] -->|"Authorization: Bearer<br/>/v1/*"| Http["Axum Router"]
Client["客户端 / OpenAI SDK"] -->|"Authorization: Bearer<br/>/v1/responses"| Http["Axum Router"]
Browser["浏览器"] -->|"管理端 SPA"| Web["web/dist"]
Browser -->|"/api/admin/*"| Http
subgraph App["codex-proxy-rs"]
Http --> Proxy["proxy<br/>OpenAI 兼容入口<br/>客户端 API Key 鉴权"]
Http --> Proxy["proxy<br/>Responses / Models 入口<br/>客户端 API Key 鉴权"]
Http --> Admin["admin<br/>账号 / Key / 设置 / 监控 / 系统更新"]
Http --> Web
@@ -36,11 +36,11 @@ flowchart LR
- `backend/`：Rust/Axum 后端、SQLite migration、构建脚本和集成测试。
- `frontend/`：Vue 3 管理端，使用 Vite 8、Tailwind v4、Pinia、Vue Router、ECharts 和 lucide 图标。
- `deploy/`：Dockerfile、Compose 和 Docker 部署配置模板。
- `docs/`：长期维护文档和审计记录，只记录当前有效结构与决策。
- `docs/`：长期维护文档，记录当前有效结构与决策。
- `release/`：版本号、平台矩阵和发布脚本。
- `skills/`：项目本地 Codex skill。
当前后端是 `backend/` 单 crate。不要在文档里保留旧迁移布局或兼容性重导出约束，除非代码重新引入对应结构。
当前后端是 `backend/` 单 crate。历史迁移布局不再作为当前架构的一部分记录。
## 后端结构
@@ -54,7 +54,7 @@ flowchart LR
主要模块：
- `admin/`：管理端 API，包括登录 session、账号、API Key、监控、运行设置和系统更新。
- `proxy/`：OpenAI 兼容 HTTP 入口、客户端 API Key 鉴权、请求分派。
- `proxy/`：Responses/Models HTTP 入口、客户端 API Key 鉴权、请求分派。
- `proxy/openai/`：Responses 和 Models 的协议入口。
- `proxy/dispatch/`：账号选择、quota/限流处理、错误映射、session affinity 和失败回退。
- `upstream/`：ChatGPT/Codex 上游账号、模型、协议、传输、token 刷新和 fingerprint。
@@ -103,14 +103,14 @@ Docker 也使用宿主机 `.runtime`，但容器内配置路径仍然写 `/app/d
## 代理请求链路
客户端请求进入 `/v1/*`：
客户端请求进入 `/v1/responses`、`/v1/responses/review`、`/v1/responses/compact` 或 `/v1/models*`：
1. `proxy/auth` 校验客户端 API Key，并记录调用上下文。
2. `proxy/openai` 解析 OpenAI 兼容请求。
2. `proxy/openai` 解析 Responses 或 Models 请求。
3. `proxy/dispatch` 按模型、quota、账号状态和选择策略挑选账号。
4. `upstream/protocol` 转换为 ChatGPT/Codex 上游协议。
5. `upstream/transport` 使用 HTTP、SSE 或 WebSocket 访问上游。
6. 响应和错误被转换回 OpenAI 兼容格式。
6. 响应和错误被转换回 OpenAI Responses/Models 兼容格式。
7. 用量、模型维度统计、请求记录、账号窗口和失败状态写回 SQLite/账号池。
账号状态由 SQLite 恢复到内存账号池，并在请求、token 刷新、quota 刷新、Cloudflare 处理和失败回退时同步更新。
@@ -132,7 +132,7 @@ Docker 也使用宿主机 `.runtime`，但容器内配置路径仍然写 `/app/d
- 账号管理：导入、OAuth、连接测试、额度、模型、调度状态、刷新能力。
- API Key 管理：客户端 Key 和管理员 API Key。
- Dashboard：请求趋势、账号概览、服务状态。
- Dashboard：核心指标、请求趋势、账号概览、服务状态和健康时间线。
- 请求明细：网关调用、上游状态、Token 消耗、错误和详情。
- 设置：运行参数、模型映射、账号选择策略。
- 系统更新：版本、检查更新、SSE 更新日志、更新、重启、回滚。
@@ -148,7 +148,7 @@ Docker 也使用宿主机 `.runtime`，但容器内配置路径仍然写 `/app/d
发布命令：
```bash
release/publish 0.1.5
release/publish 1.0.4
```
发布 workflow 校验触发 tag 必须等于 `v` + `release/version.yaml`。构建时注入：
skills/codex-proxy-rs/SKILL.md
+2 -2
View File
@@ -5,7 +5,7 @@ description: Codex Proxy RS 项目专用指南。Use when working in the codex-p
# Codex Proxy RS
使用这个 skill 来开发 Codex Proxy RS，避免每次重新摸索项目结构、开发流程和约束。
这个 skill 记录 Codex Proxy RS 的仓库结构、开发命令和约束。
## 开始前
@@ -20,7 +20,7 @@ description: Codex Proxy RS 项目专用指南。Use when working in the codex-p
- 后端：遵循 `backend/src` 里的 Rust/Axum 模式；集成测试放 `backend/tests`，禁止把测试代码放进 `backend/src`。
- 前端：使用 Vue 3 `<script setup>`、TypeScript、Tailwind v4 utilities 和已有 CSS 主题 token。
- Docker / 发布：保持 runtime 镜像最小化，并维护现有 GitHub Release、GHCR、在线更新契约。
- 文档：文档要短、准、和真实行为一致；除非用户要求，不新增冗余文档文件。
- 文档：短、准、和真实行为一致；除非用户要求，不新增冗余文档文件。
## 验证
skills/codex-proxy-rs/references/repo-guide.md
+8 -7
View File
@@ -18,7 +18,7 @@
- `backend/tests/`：集成测试和 fixtures。测试代码只放这里，禁止放进 `backend/src`。
- `frontend/`：Vue 3 管理端 SPA，使用 Vite 8、Tailwind v4、Pinia、Vue Router、Axios、lucide icons、ECharts。
- `deploy/`：Dockerfile、Dockerfile 专用 ignore 文件、Compose 文件、`config.example.yaml`。
- `docs/`：只放长期维护文档，例如架构说明；不要保留过程型迁移文档作为开发约束。
- `docs/`：长期维护文档；不要保留过程型迁移文档作为开发约束。
- `skills/`：项目本地 Codex skills。
## 后端规范
@@ -75,15 +75,16 @@ cargo run --manifest-path backend/Cargo.toml --bin codex-proxy-rs
- 本地 Docker 首次部署命令：
```bash
cp deploy/config.example.yaml deploy/config.yaml
mkdir -p .runtime/data .runtime/logs
cp deploy/config.example.yaml .runtime/config.yaml
docker compose -f deploy/docker-compose.yml build
docker compose -f deploy/docker-compose.yml up -d
```
- 运行时挂载关系：
- `deploy/config.yaml` -> `/app/config.yaml`
- `deploy/data` -> `/app/data`
- `deploy/logs` -> `/app/logs`
- `.runtime/config.yaml` -> `/app/config.yaml`
- `.runtime/data` -> `/app/data`
- `.runtime/logs` -> `/app/logs`
## 发布和版本契约
@@ -99,7 +100,6 @@ docker compose -f deploy/docker-compose.yml up -d
```text
codex-proxy-rs_<version>_linux_amd64.tar.gz
codex-proxy-rs_<version>_linux_arm64.tar.gz
codex-proxy-rs_<version>_darwin_amd64.tar.gz
codex-proxy-rs_<version>_darwin_arm64.tar.gz
codex-proxy-rs_<version>_windows_amd64.zip
checksums.txt
@@ -114,10 +114,11 @@ checksums.txt
- 后端接口：
- `GET /api/admin/system/version`
- `GET /api/admin/system/check-updates`
- `GET /api/admin/system/update-detail`
- `GET /api/admin/system/update-events`
- `GET /api/admin/system/update-status`
- `POST /api/admin/system/update`
- `POST /api/admin/system/rollback`
- `POST /api/admin/system/restart`
- 前端更新 UI：`frontend/src/layout/components/SystemUpdateModal.vue`。
- SSE 日志由后端生成中文消息；前端只负责展示，不做状态文案映射。