mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-17 00:06:34 +00:00
ci: complete release pipeline
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
# Codex Proxy RS 架构说明
|
||||
|
||||
## 总览
|
||||
|
||||
Codex Proxy RS 是一个单主服务应用:Rust 后端提供 OpenAI 兼容代理、管理端 API、SQLite 持久化、静态前端托管和在线更新能力;Vue 管理端作为 SPA 由同一个后端进程托管。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Client["客户端 / SDK"] -->|"OpenAI API /v1/*"| Http["Axum HTTP Router"]
|
||||
Browser["浏览器"] -->|"管理端 SPA"| Web["web 静态资源托管"]
|
||||
Browser -->|"/api/admin/*"| Http
|
||||
|
||||
subgraph App["codex-proxy-rs 单主进程"]
|
||||
Http --> Proxy["proxy<br/>API Key 鉴权<br/>OpenAI 兼容协议"]
|
||||
Http --> Admin["admin<br/>账号 / Key / 设置 / 监控 / 系统更新"]
|
||||
Http --> Web
|
||||
|
||||
Proxy --> Dispatch["dispatch<br/>账号选择 / 限流 / 亲和性 / 失败回退"]
|
||||
Dispatch --> Protocol["upstream protocol<br/>请求转换 / SSE 转换"]
|
||||
Protocol --> Transport["upstream transport<br/>HTTP SSE / WebSocket"]
|
||||
|
||||
Admin --> Runtime["runtime services<br/>账号池 / 后台任务 / 更新状态"]
|
||||
Dispatch --> Runtime
|
||||
Runtime --> Store[("SQLite<br/>账号 / 会话 / 使用记录 / 设置")]
|
||||
Admin --> Store
|
||||
end
|
||||
|
||||
Transport --> Upstream["ChatGPT / Codex Upstream"]
|
||||
Web --> Frontend["frontend/dist<br/>Vue 3 管理端"]
|
||||
|
||||
Release["GitHub Release<br/>tar.gz + checksums"] --> Update["在线更新<br/>下载 / 校验 / 替换 / 重启"]
|
||||
Update --> Admin
|
||||
GHCR["GHCR<br/>linux/amd64 + linux/arm64"] --> Docker["Docker Compose<br/>restart: unless-stopped"]
|
||||
```
|
||||
|
||||
## 仓库边界
|
||||
|
||||
- `backend/`:Rust/Axum 后端、SQLite schema、运行时服务、集成测试和 Cargo 构建脚本。
|
||||
- `frontend/`:Vue 3 管理端,使用 Vite、Tailwind v4、Pinia、Vue Router 和 ECharts。
|
||||
- `deploy/`:Dockerfile、Compose 文件、Docker ignore 文件和部署样例配置。
|
||||
- `docs/`:长期维护文档,只记录当前真实架构和约定,不保留迁移过程作为开发约束。
|
||||
- `skills/`:项目本地 Codex skill。
|
||||
|
||||
## 后端结构
|
||||
|
||||
后端入口是 `backend/src/main.rs`,公共库入口是 `backend/src/lib.rs`。运行时由 `runtime::bootstrap` 初始化,服务集合在 `runtime::services` 构造,并通过 `AppState` 注入到路由。
|
||||
|
||||
主要模块:
|
||||
|
||||
- `admin/`:管理端 API,包括认证、账号、API Key、监控、设置和系统更新。
|
||||
- `proxy/`:OpenAI 兼容代理入口、鉴权、请求转换和账号调度。
|
||||
- `upstream/`:ChatGPT/Codex 上游协议、传输层、账号模型、token 刷新、quota 刷新和 fingerprint。
|
||||
- `config/`:配置加载、运行时设置和配置类型。
|
||||
- `infra/`:数据库、日志、时间、格式化、JSON 和 schema。
|
||||
- `http/`:HTTP router、中间件和统一请求上下文。
|
||||
- `web/`:前端静态资源和 SPA fallback 托管。
|
||||
|
||||
测试只放在 `backend/tests/`,不要在 `backend/src/` 中新增测试模块。
|
||||
|
||||
## 数据和运行时
|
||||
|
||||
后端以 SQLite 作为主要持久化存储。默认运行时数据位于 `.runtime/`,Docker 部署时通过 Compose 挂载到 `/app/data` 和 `/app/logs`。
|
||||
|
||||
运行时状态分两类:
|
||||
|
||||
- 持久化状态:账号、cookie、API Key、session、使用记录、时间桶、fingerprint、运行时设置等。
|
||||
- 内存状态:账号池、调度状态、运行中任务、SSE 更新日志广播、缓存的 release 检查结果等。
|
||||
|
||||
运行时设置通过管理端 API 修改后写入数据库,并同步到内存服务。
|
||||
|
||||
## 代理请求链路
|
||||
|
||||
客户端请求进入 `/v1/*`:
|
||||
|
||||
1. `proxy/auth` 校验客户端 API Key。
|
||||
2. `proxy/openai` 解析 OpenAI 兼容请求。
|
||||
3. `proxy/dispatch` 选择账号、处理限流、亲和性和失败回退。
|
||||
4. `upstream/protocol` 转换 Codex/ChatGPT 上游协议。
|
||||
5. `upstream/transport` 使用 HTTP SSE 或 WebSocket 访问上游。
|
||||
6. 响应被转换回 OpenAI 兼容格式,并记录使用数据。
|
||||
|
||||
账号运行时状态由 SQLite 快照恢复,并在请求、刷新、quota 检查和失败回退时更新。
|
||||
|
||||
## 管理端
|
||||
|
||||
管理端 API 位于 `/api/admin/*`,使用 session cookie 保护。前端入口由后端托管,不单独部署 Node 服务。
|
||||
|
||||
前端结构:
|
||||
|
||||
- `frontend/src/api/modules`:管理端 API 客户端。
|
||||
- `frontend/src/components/base`:基础 UI 组件。
|
||||
- `frontend/src/layout`:主布局、侧边栏、系统更新入口和更新弹窗。
|
||||
- `frontend/src/views`:各业务页面。
|
||||
- `frontend/src/stores`:Pinia 状态。
|
||||
- `frontend/src/styles/tokens.css`:亮色/暗色主题 token。
|
||||
|
||||
前端只展示后端返回的版本、状态和更新日志,不在前端做状态文案映射。
|
||||
|
||||
## 版本和发布
|
||||
|
||||
版本只有两个来源层级:
|
||||
|
||||
- 源码默认版本:`backend/Cargo.toml` 的 `[package].version`。
|
||||
- 发布版本:Git tag 去掉 `v` 前缀后得到的版本。
|
||||
|
||||
发布 workflow 会校验 tag 版本必须等于 `backend/Cargo.toml` 的 package version。发布构建时通过 `CPR_VERSION`、`CPR_GIT_SHA`、`CPR_BUILD_TIME` 和 `CPR_BUILD_TYPE=release` 注入编译期元数据。
|
||||
|
||||
`backend/build/build.rs` 负责把这些值写入二进制。没有 `CPR_VERSION` 时,版本回落到 Cargo 的 `CARGO_PKG_VERSION`。不要重新引入独立 `VERSION` 文件。
|
||||
|
||||
GitHub Release 产物:
|
||||
|
||||
```text
|
||||
codex-proxy-rs_<version>_linux_amd64.tar.gz
|
||||
codex-proxy-rs_<version>_linux_arm64.tar.gz
|
||||
checksums.txt
|
||||
```
|
||||
|
||||
GHCR 镜像发布为 `linux/amd64` 和 `linux/arm64` 多平台 manifest。
|
||||
|
||||
## 在线更新
|
||||
|
||||
在线更新由主服务自己处理,不依赖独立 updater sidecar。核心接口:
|
||||
|
||||
- `GET /api/admin/system/version`
|
||||
- `GET /api/admin/system/check-updates`
|
||||
- `GET /api/admin/system/update-events`
|
||||
- `GET /api/admin/system/update-status`
|
||||
- `POST /api/admin/system/update`
|
||||
- `POST /api/admin/system/restart`
|
||||
|
||||
更新流程:
|
||||
|
||||
1. 后端检查 GitHub latest release。
|
||||
2. 按当前 OS/arch 选择匹配 asset,兼容 `amd64/x86_64` 和 `arm64/aarch64` 命名。
|
||||
3. 下载 release tar 包并用 `checksums.txt` 校验。
|
||||
4. 解压二进制和 `web/dist`。
|
||||
5. 替换当前二进制和前端静态资源。
|
||||
6. 前端通过 SSE 实时展示后端推送的中文更新日志。
|
||||
7. Docker 部署依靠 `restart: unless-stopped` 在自重启后拉起新进程。
|
||||
|
||||
替换逻辑必须支持跨文件系统 fallback,因为容器文件系统里 `rename` 可能遇到 `Invalid cross-device link`。
|
||||
|
||||
## Docker 部署
|
||||
|
||||
Docker 构建入口是 `deploy/Dockerfile`,上下文保持仓库根目录。
|
||||
|
||||
构建阶段:
|
||||
|
||||
- `frontend-builder`:构建 Vue SPA。
|
||||
- `backend-builder`:构建 Rust release 二进制,并复制前端 dist。
|
||||
- `release-asset`:导出 GitHub Release tar 包。
|
||||
- `runtime`:最小运行镜像,基于 `debian:bookworm-slim`,只包含 CA、后端二进制和 `web/dist`。
|
||||
|
||||
Compose 文件是 `deploy/docker-compose.yml`。示例配置只保留 `deploy/config.example.yaml`,用户复制为 `deploy/config.yaml` 后部署。
|
||||
|
||||
## CI 和安全扫描
|
||||
|
||||
常规 CI 位于 `.github/workflows/ci.yml`:
|
||||
|
||||
- Rust fmt、clippy、集成测试。
|
||||
- 前端依赖安装和 build。
|
||||
- Compose 配置校验。
|
||||
|
||||
安全扫描位于 `.github/workflows/security-scan.yml`:
|
||||
|
||||
- `cargo audit` 扫描 Rust 依赖。
|
||||
- `pnpm audit --prod --audit-level=high` 扫描前端生产依赖。
|
||||
- 每周定时运行,同时覆盖 push 和 pull request。
|
||||
|
||||
发布流程位于 `.github/workflows/release.yml`,只由 `v*` tag 或手动指定 tag 触发。
|
||||
@@ -1,237 +0,0 @@
|
||||
# Project Layout Restructure
|
||||
|
||||
## 背景
|
||||
|
||||
项目目录已按 Sub2API 的边界收敛:
|
||||
|
||||
- `backend/` 承载后端应用、后端构建元信息和后端测试。
|
||||
- `frontend/` 承载前端应用。
|
||||
- `deploy/` 承载 Docker、Compose、部署脚本和部署示例配置。
|
||||
|
||||
根目录只保留仓库级入口和文档,不再承载后端源码、前端源码或具体部署实现。
|
||||
|
||||
## 完成后结构
|
||||
|
||||
```text
|
||||
codex-proxy-rs/
|
||||
├── backend/
|
||||
│ ├── Cargo.toml
|
||||
│ ├── Cargo.lock
|
||||
│ ├── build/
|
||||
│ │ ├── build.rs
|
||||
│ │ └── VERSION
|
||||
│ ├── rust-toolchain.toml
|
||||
│ ├── src/
|
||||
│ └── tests/
|
||||
├── frontend/
|
||||
│ ├── package.json
|
||||
│ ├── pnpm-lock.yaml
|
||||
│ ├── pnpm-workspace.yaml
|
||||
│ ├── vite.config.ts
|
||||
│ └── src/
|
||||
├── deploy/
|
||||
│ ├── Dockerfile
|
||||
│ ├── docker-compose.yml
|
||||
│ ├── config.example.yaml
|
||||
│ └── README.md
|
||||
├── docs/
|
||||
├── README.md
|
||||
└── .github/
|
||||
```
|
||||
|
||||
说明:
|
||||
|
||||
- `backend/build/VERSION` 是唯一的源码默认版本文件。它对应 Sub2API 的 `backend/cmd/server/VERSION`,但本项目的 Rust 入口仍保留在 `backend/src/main.rs`,所以版本元信息归入 `backend/build/`。
|
||||
- `backend/build/build.rs` 读取 `CPR_VERSION`,否则读取 `backend/build/VERSION`,最后才回落到 `CARGO_PKG_VERSION`。
|
||||
- `frontend/` 替代原 `web/`。前端只负责展示后端返回的版本、构建类型、部署类型和更新进度。
|
||||
- `deploy/` 替代根目录里的部署文件归属。根目录只保留仓库级入口和文档,不承载具体部署实现。
|
||||
- 测试代码继续放在测试目录,禁止放入 `backend/src`。
|
||||
|
||||
## 路径映射
|
||||
|
||||
| 原路径 | 新路径 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| `src/` | `backend/src/` | Rust 后端源码。 |
|
||||
| `tests/` | `backend/tests/` | Rust 集成测试,仍在测试目录,不进入源码目录。 |
|
||||
| `Cargo.toml` | `backend/Cargo.toml` | 后端 package manifest。 |
|
||||
| `Cargo.lock` | `backend/Cargo.lock` | 后端锁文件,随后端移动。 |
|
||||
| `build.rs` | `backend/build/build.rs` | 后端构建脚本。 |
|
||||
| `VERSION` | `backend/build/VERSION` | 后端应用版本源。 |
|
||||
| `rust-toolchain.toml` | `backend/rust-toolchain.toml` | 后端工具链配置。 |
|
||||
| `web/` | `frontend/` | 前端应用。 |
|
||||
| `Dockerfile` | `deploy/Dockerfile` | 生产镜像构建入口。 |
|
||||
| `docker-compose.yml` | `deploy/docker-compose.yml` | Docker 部署入口。 |
|
||||
| `config.yaml` | `deploy/config.example.yaml` | 根目录不保留本地运行配置。 |
|
||||
|
||||
## Cargo 组织方式
|
||||
|
||||
优先采用 Sub2API 风格:后端是自包含子项目。
|
||||
|
||||
```text
|
||||
backend/
|
||||
├── Cargo.toml
|
||||
├── Cargo.lock
|
||||
├── build/
|
||||
│ ├── build.rs
|
||||
│ └── VERSION
|
||||
├── src/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
后续命令从:
|
||||
|
||||
```bash
|
||||
cargo test --test main admin::system --locked
|
||||
cargo clippy --all-targets --all-features --locked -- -D warnings
|
||||
```
|
||||
|
||||
调整为:
|
||||
|
||||
```bash
|
||||
cargo test --manifest-path backend/Cargo.toml --test main admin::system --locked
|
||||
cargo clippy --manifest-path backend/Cargo.toml --all-targets --all-features --locked -- -D warnings
|
||||
```
|
||||
|
||||
如果后续需要根目录统一调度,可以再加一个很薄的 root workspace `Cargo.toml`,但不要让根目录重新成为后端版本源。
|
||||
|
||||
根目录 `target/` 不是项目构建目标目录。迁移后后端构建产物位于 `backend/target/`;如果本地编辑器或 rust-analyzer 在根目录生成 `target/flycheck*`,它只是本地检查临时产物,可以直接删除,且已被 `.gitignore` 忽略。
|
||||
|
||||
## 前端迁移点
|
||||
|
||||
`web/` 已迁移到 `frontend/`,同步点:
|
||||
|
||||
- `.github/workflows/release.yml` 中所有 `pnpm --dir web ...` 改为 `pnpm --dir frontend ...`。
|
||||
- Dockerfile 中所有 `web/package.json`、`web/pnpm-lock.yaml`、`web/dist` 改为 `frontend/...`。
|
||||
- README、部署文档和开发命令里的 `web` 改为 `frontend`。
|
||||
- 前端 API 类型和更新弹窗不做业务重写,只做路径迁移。
|
||||
|
||||
## 部署迁移点
|
||||
|
||||
`deploy/` 负责部署相关文件:
|
||||
|
||||
- `deploy/Dockerfile`
|
||||
- `deploy/docker-compose.yml`
|
||||
- `deploy/config.example.yaml`
|
||||
- `deploy/README.md`
|
||||
|
||||
Docker 构建上下文仍建议使用仓库根目录:
|
||||
|
||||
```bash
|
||||
docker build -f deploy/Dockerfile -t codex-proxy-rs .
|
||||
```
|
||||
|
||||
这样 Dockerfile 可以同时访问 `backend/` 和 `frontend/`,避免把构建上下文拆散。
|
||||
|
||||
Compose 文件迁移到 `deploy/` 后,默认挂载路径随 Compose 文件落在 `deploy/` 目录,保持部署文件和部署状态集中;需要接入外部配置或数据目录时,通过环境变量覆盖:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
codex-proxy-rs:
|
||||
volumes:
|
||||
- ${CPR_CONFIG_FILE:-./config.yaml}:/app/config.yaml:ro
|
||||
- ${CPR_DATA_DIR:-./data}:/app/data
|
||||
- ${CPR_LOG_DIR:-./logs}:/app/logs
|
||||
```
|
||||
|
||||
使用 `deploy/config.example.yaml` 作为样例,运行时配置由用户复制为 `deploy/config.yaml` 或通过 `CPR_CONFIG_FILE` 挂载提供。
|
||||
|
||||
## 发布链路调整
|
||||
|
||||
发布版本必须只有一个来源:
|
||||
|
||||
1. Git tag,例如 `v0.1.1`。
|
||||
2. CI 去掉前缀 `v`,得到 `0.1.1`。
|
||||
3. CI 写入 `backend/build/VERSION`。
|
||||
4. CI 构建后端时传入:
|
||||
- `CPR_VERSION=0.1.1`
|
||||
- `CPR_GIT_SHA=<sha>`
|
||||
- `CPR_BUILD_TIME=<utc>`
|
||||
- `CPR_BUILD_TYPE=release`
|
||||
5. `backend/build/build.rs` 将这些值注入二进制。
|
||||
6. 后端 `/api/admin/system/version` 和 `/api/admin/system/check-updates` 使用二进制内的版本值。
|
||||
7. 前端只展示后端返回的数据,不做版本映射。
|
||||
|
||||
需要同步修改:
|
||||
|
||||
- `.github/workflows/release.yml`
|
||||
- `deploy/Dockerfile`
|
||||
- `backend/build/build.rs`
|
||||
- `backend/src/admin/system/routes.rs`
|
||||
- `backend/tests/admin/system/mod.rs`
|
||||
|
||||
## Dockerfile 调整
|
||||
|
||||
目标 Dockerfile 阶段:
|
||||
|
||||
```dockerfile
|
||||
FROM node:24-bookworm-slim AS frontend-builder
|
||||
WORKDIR /app/frontend
|
||||
COPY frontend/package.json frontend/pnpm-lock.yaml frontend/pnpm-workspace.yaml ./
|
||||
RUN corepack enable && pnpm install --frozen-lockfile
|
||||
COPY frontend ./
|
||||
RUN pnpm build
|
||||
|
||||
FROM rust:1.95-bookworm AS backend-builder
|
||||
WORKDIR /app/backend
|
||||
COPY backend/Cargo.toml backend/Cargo.lock ./
|
||||
COPY backend/build ./build
|
||||
COPY backend/src ./src
|
||||
COPY --from=frontend-builder /app/frontend/dist ./web/dist
|
||||
RUN cargo build --release --locked --bin codex-proxy-rs
|
||||
|
||||
FROM debian:bookworm-slim AS runtime
|
||||
WORKDIR /app
|
||||
ENV CPR_DEPLOYMENT_MODE=docker
|
||||
COPY --from=backend-builder /app/backend/target/release/codex-proxy-rs /usr/local/bin/codex-proxy-rs
|
||||
COPY --from=frontend-builder /app/frontend/dist ./web/dist
|
||||
CMD ["codex-proxy-rs"]
|
||||
```
|
||||
|
||||
注意:
|
||||
|
||||
- Docker runtime 镜像不设置 `CPR_VERSION`,避免运行时环境变量成为第二版本源。
|
||||
- Docker runtime 仍只包含主服务,不恢复 updater sidecar。
|
||||
- `deploy/Dockerfile` 的构建上下文应保持仓库根目录。
|
||||
|
||||
## 迁移记录
|
||||
|
||||
本次迁移执行项:
|
||||
|
||||
1. 新建 `backend/`,用 `git mv` 移动 `src/`、`tests/`、`Cargo.toml`、`Cargo.lock`、`rust-toolchain.toml`,并将 `build.rs`、`VERSION` 归入 `backend/build/`。
|
||||
2. 新建 `frontend/`,用 `git mv web frontend`。
|
||||
3. 新建 `deploy/`,用 `git mv Dockerfile deploy/Dockerfile`、`git mv docker-compose.yml deploy/docker-compose.yml`,并移动部署样例配置。
|
||||
4. 修改 `.github/workflows/release.yml` 的工作目录、构建路径、打包路径和 Dockerfile 路径。
|
||||
5. 修改 `deploy/Dockerfile` 的 `COPY` 路径。
|
||||
6. 修改 `.dockerignore` 和 `.gitignore`,使用 `frontend/node_modules`、`frontend/dist`、`backend/target`。
|
||||
7. 修改文档和 README 中的开发、测试、构建命令。
|
||||
|
||||
## 验收命令
|
||||
|
||||
迁移完成后至少运行:
|
||||
|
||||
```bash
|
||||
cargo test --manifest-path backend/Cargo.toml --test main admin::system --locked
|
||||
cargo clippy --manifest-path backend/Cargo.toml --all-targets --all-features --locked -- -D warnings
|
||||
pnpm --dir frontend build
|
||||
docker build -f deploy/Dockerfile -t codex-proxy-rs:latest .
|
||||
docker compose -f deploy/docker-compose.yml config
|
||||
git diff --check
|
||||
```
|
||||
|
||||
如果保留 root workspace,则还需要确认:
|
||||
|
||||
```bash
|
||||
cargo metadata --format-version 1
|
||||
```
|
||||
|
||||
输出中不能重新出现旧的 updater binary,也不能把根 `VERSION` 当成版本源。
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 顶层不再有 `src/` 和 `web/`。
|
||||
- 后端源码、测试和版本源都归属 `backend/`。
|
||||
- 前端应用归属 `frontend/`。
|
||||
- Dockerfile、Compose 和部署样例归属 `deploy/`。
|
||||
- `backend/build/VERSION` 是唯一源码默认版本文件。
|
||||
- 发布 tag、release asset、Docker image label、后端 `/version`、前端更新弹窗显示同一个版本。
|
||||
- Docker 部署仍是单主服务模式,不恢复 updater sidecar。
|
||||
Reference in New Issue
Block a user