From bf5021965b40dec20949d9ba48b5ab12e056efbd Mon Sep 17 00:00:00 2001 From: zyycn Date: Sun, 5 Jul 2026 22:39:26 +0800 Subject: [PATCH] docs: refresh project documentation Co-authored-by: Codex --- README.md | 34 ++++++++++--------- deploy/README.md | 21 ++++++------ deploy/config.example.yaml | 2 +- docs/architecture.md | 24 ++++++------- skills/codex-proxy-rs/SKILL.md | 4 +-- .../codex-proxy-rs/references/repo-guide.md | 15 ++++---- 6 files changed, 52 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 74158c173..63ca35664 100644 --- a/README.md +++ b/README.md @@ -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` tag 并推送，随后 GitHub Actions 构建 Release 归档和 GHCR 多平台镜像。 +该命令会更新版本文件、生成版本提交、创建 `v` 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 ``` diff --git a/deploy/README.md b/deploy/README.md index ce7668943..b55972971 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -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")')" \ diff --git a/deploy/config.example.yaml b/deploy/config.example.yaml index a18899e38..2fa1dbb8d 100644 --- a/deploy/config.example.yaml +++ b/deploy/config.example.yaml @@ -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: diff --git a/docs/architecture.md b/docs/architecture.md index 1e25c4794..a6e9fa100 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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
/v1/*"| Http["Axum Router"] + Client["客户端 / OpenAI SDK"] -->|"Authorization: Bearer
/v1/responses"| Http["Axum Router"] Browser["浏览器"] -->|"管理端 SPA"| Web["web/dist"] Browser -->|"/api/admin/*"| Http subgraph App["codex-proxy-rs"] - Http --> Proxy["proxy
OpenAI 兼容入口
客户端 API Key 鉴权"] + Http --> Proxy["proxy
Responses / Models 入口
客户端 API Key 鉴权"] Http --> Admin["admin
账号 / 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`。构建时注入： diff --git a/skills/codex-proxy-rs/SKILL.md b/skills/codex-proxy-rs/SKILL.md index e95070079..62516437d 100644 --- a/skills/codex-proxy-rs/SKILL.md +++ b/skills/codex-proxy-rs/SKILL.md @@ -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 `