docs: refresh project setup guide

Co-authored-by: Codex <noreply@openai.com>
2026-11-06 16:06:08 +00:00 · 2026-07-01 18:27:45 +08:00
parent 1b838ded4c
commit c859f1dc91
3 changed files with 74 additions and 107 deletions
@@ -7,8 +7,7 @@
 /frontend/dist/

 # Application runtime state.
-/backend/.runtime/
-/logs/
+*.runtime
 *.sqlite
 *.sqlite3
 *.db
@@ -1,135 +1,80 @@
-<p align="center">
-  <img src="frontend/public/favicon.svg" width="88" height="88" alt="Codex Proxy RS" />
-</p>
-
 <h1 align="center">Codex Proxy RS</h1>

 <p align="center">
-  ChatGPT / Codex 账号池网关，提供 OpenAI 兼容接口和本地管理控制台。
+  OpenAI 兼容的 ChatGPT / Codex 多账号代理网关
 </p>

 <p align="center">
-  <img alt="Rust" src="https://img.shields.io/badge/Rust-1.95-000?style=flat-square&logo=rust" />
-  <img alt="Axum" src="https://img.shields.io/badge/Axum-0.8-2f7d95?style=flat-square" />
-  <img alt="Vue" src="https://img.shields.io/badge/Vue-3-42b883?style=flat-square&logo=vuedotjs&logoColor=white" />
-  <img alt="SQLite" src="https://img.shields.io/badge/SQLite-local-003b57?style=flat-square&logo=sqlite" />
-  <img alt="License" src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" />
+  <img src="https://img.shields.io/badge/Rust-1.95-000?style=flat-square&logo=rust" />
+  <img src="https://img.shields.io/badge/Axum-0.8-2f7d95?style=flat-square" />
+  <img src="https://img.shields.io/badge/Vue-3-42b883?style=flat-square&logo=vuedotjs&logoColor=white" />
+  <img src="https://img.shields.io/badge/SQLite-local-003b57?style=flat-square&logo=sqlite" />
+  <img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" />
 </p>

-<p align="center">
-  <code>/v1/responses</code>
-  ·
-  <code>/v1/chat/completions</code>
-  ·
-  <code>/v1/models</code>
-  ·
-  <code>/api/admin</code>
-</p>
+## 环境

-## ✦ 功能清单
+- Rust ≥ 1.95
+- Node ≥ 20，pnpm ≥ 9（仅开发管理端前端时需要）

-| 部分 | 内容 |
-| --- | --- |
-| ⚡ OpenAI 兼容接口 | `responses`、`chat completions`、模型列表、流式输出 |
-| 🔐 账号池 | OAuth、refresh token、CPR / Sub2API 导入、状态管理 |
-| 🧭 调度 | 账号轮转、并发限制、请求间隔、会话亲和性 |
-| 📡 上游传输 | Codex Desktop 风格 headers、HTTP SSE、WebSocket、连接池 |
-| 📊 记录 | 使用记录、Token、成本、延迟、失败原因、请求轨迹 |
-| 🛠 管理端 | 账号、API Key、仪表盘、使用记录、运行时设置 |
-| 💾 本地持久化 | SQLite 数据库，运行数据默认写入 `.runtime` |
-
-## ✦ 快速启动
-
-本地源码启动：
+## 快速开始

 ```bash
 cargo run --manifest-path backend/Cargo.toml
 ```

-默认监听：
+启动后监听 `http://0.0.0.0:8080`，配置从运行目录下的 `config.yaml` 读取。首次启动会自动创建管理端账号（默认用户名密码见配置文件）。

-```text
-http://0.0.0.0:8080
-```
-
-默认配置文件：
-
-```text
-config.yaml
-```
-
-首次启动会初始化管理端账号。默认账号来自运行目录下的 `config.yaml`。
-
-Docker 首次本地构建和启动：
+Docker 部署：

 ```bash
 cp deploy/config.example.yaml deploy/config.yaml
+# 编辑 deploy/config.yaml，至少改掉 admin.default_password
 docker compose -f deploy/docker-compose.yml build
 docker compose -f deploy/docker-compose.yml up -d
 ```

-`deploy/config.example.yaml` 是 Docker 部署样例配置，复制为 `deploy/config.yaml` 后再修改。默认挂载关系：
+挂载关系：`deploy/config.yaml` → `/app/config.yaml`，`deploy/data` → `/app/data`，`deploy/logs` → `/app/logs`。

-```text
-deploy/config.yaml -> /app/config.yaml
-deploy/data        -> /app/data
-deploy/logs        -> /app/logs
+## API
+
+所有接口通过 Authorization Bearer header 鉴权，API Key 在管理端创建和管理。
+
+| 端点 | 说明 |
+| --- | --- |
+| `POST /v1/responses` | OpenAI responses 接口 |
+| `POST /v1/chat/completions` | Chat completions 接口 |
+| `GET /v1/models` | 模型列表 |
+| `GET /v1/models/catalog` | 模型目录 |
+| `/api/admin/*` | 管理端 API（前端调用） |
+
+```bash
+curl http://127.0.0.1:8080/v1/responses \
+  -H 'Authorization: Bearer <your-api-key>' \
+  -H 'Content-Type: application/json' \
+  -d '{"model": "gpt-5.5", "input": "Say hello", "stream": true}'
 ```

-样例配置中的默认管理端账号：
+## 管理控制台

-```yaml
-admin:
-  default_username: admin
-  default_password: admin
-```
-
-正式使用前请改掉默认密码。
-
-## ✦ 管理控制台
-
-前端代码在 `frontend/`。
-
-开发模式：
+前端是 Vue 3 单页应用，源码在 `frontend/`。开发时：

 ```bash
 pnpm --dir frontend dev
 ```

-生产构建：
+生产构建后由后端直接托管：

 ```bash
 pnpm --dir frontend build
 cargo run --manifest-path backend/Cargo.toml
 ```

-构建后的控制台由后端直接提供，API 路由优先于静态资源。
+管理端功能包括账号管理、API Key 管理、用量仪表盘、请求记录和运行时设置。账号、Key、模型路由等运行时配置在管理端操作，不写在 YAML 里。

-## ✦ OpenAI 兼容入口
+## 配置

-```http
-POST /v1/responses
-POST /v1/chat/completions
-GET  /v1/models
-GET  /v1/models/catalog
-```
-
-示例：
-
-```bash
-curl http://127.0.0.1:8080/v1/responses \
-  -H 'Authorization: Bearer <client-api-key>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "gpt-5.5",
-    "input": "Say hello",
-    "stream": true
-  }'
-```
-
-## ✦ config.yaml
-
-示例：
+最小 `config.yaml`：

 ```yaml
 server:
@@ -147,29 +92,49 @@ logging:
  retention_days: 14
 ```

-运行数据：
+完整配置项见 `deploy/config.example.yaml`，包括 TLS、WebSocket 连接池、请求指纹、账号额度策略等。
+
+运行数据目录：

 ```text
-.runtime/data/
-.runtime/logs/
+.runtime/data/   # SQLite 数据库
+.runtime/logs/   # 日志文件
 ```

-账号、API Key、模型路由和运行时设置在管理端修改，不写进 YAML。
+## 架构

-## ✦ 项目结构
+```mermaid
+flowchart LR
+    Client["客户端 / SDK"] -->|OpenAI API| Proxy["/v1/*"]
+    Browser["浏览器"] -->|Web| Admin["/api/admin/*"]
+
+    subgraph Gateway["codex-proxy-rs"]
+        Proxy --> Auth["API Key 鉴权"]
+        Auth --> Dispatch["调度层<br/>选账号 · 限并发 · 亲和性"]
+        Dispatch --> Transport["上游传输<br/>HTTP SSE / WebSocket"]
+        Dispatch --> Pool["账号池<br/>内存状态 + SQLite"]
+        Admin --> SQLite[("SQLite")]
+        Pool --> SQLite
+    end
+
+    Transport --> Upstream["ChatGPT / Codex API"]
+    Proxy -.->|静态资源| SPA["Vue 3 管理端"]
+    Admin -.-> SPA
+```
+
+## 项目结构

 ```text
 backend/
-  build/      构建脚本与版本元信息
-  src/        Rust 后端源码
-  tests/      集成测试与 fixture
-
-frontend/     Vue 管理控制台
-deploy/       Dockerfile、Compose、部署样例配置
+  src/        Rust 源码
+  tests/      集成测试
+  build/      构建脚本
+frontend/     Vue 3 管理控制台
+deploy/       Dockerfile、Compose、示例配置
 docs/         设计与迁移文档
 ```

-## ✦ 开发命令
+## 开发

 ```bash
 cargo fmt --manifest-path backend/Cargo.toml --check
@@ -178,6 +143,6 @@ cargo test --manifest-path backend/Cargo.toml --test main
 pnpm --dir frontend build
 ```

-## ✦ License
+## License

 MIT
@@ -26,6 +26,9 @@ export default defineConfig({
    assetsDir: 'assets',
    chunkSizeWarningLimit: 600,
    rolldownOptions: {
+      treeshake: {
+        annotations: false,
+      },
      output: {
        codeSplitting: {
          groups: [