mirror of https://github.com/zyycn/codex-proxy-rs.git synced 2026-11-06 16:06:08 +00:00

Files

T

Zyy f7f59103a3 fix: harden request lifecycles and align repository documentation

Preserve request evidence and cold middleware boundaries across cancellation. Make backup auditing atomic, retain committed account-group results, and serialize restart operations.

Unify frontend stream authentication and session recovery, clear stale secrets, and remove redundant runtime paths. Correct CI permissions and database test URL handling.

Align documentation with current module responsibilities, APIs, and validation workflows, including both submodules.

2026-10-22 22:06:01 +08:00

7.6 KiB

Raw Permalink Blame History

开发与源码联调

本文说明开发环境、服务启动与跨仓库联调，命令均从宿主仓库根目录执行

协作与检查要求见贡献与审查，部署实例的配置与数据维护见部署与运维

任务	入口
修改宿主前后端	环境与依赖 → 启动宿主
定位模块与共享实现	源码入口
同时修改 UI 或插件	源码联调 → 启动与检查
验证本地 SDK	本地 SDK 验证
提交跨仓库改动	编辑与提交

环境与依赖

需要 Node.js 26.12.0、pnpm、Rust 工具链、PostgreSQL 和 Redis

各前端的 packageManager 固定 pnpm 版本，宿主 CI 和 Docker 从 frontend/package.json 读取

Rust 工具链声明位于 backend/rust-toolchain.toml，从仓库根目录运行 Cargo 时显式选择该工具链； --manifest-path 只选择 manifest，不切换 rustup 按当前目录选定的工具链

git clone https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs
pnpm --dir frontend install --frozen-lockfile

前端依赖、锁文件与 ESLint 配置由 frontend/ 管理，根目录不维护 Node 包

版本固定：@codex-proxy/ui 使用固定 GitHub 标签或提交，锁文件记录实际提交、源码归档地址及完整性摘要
安装与构建：pnpm 按 UI 自身锁文件准备依赖，执行 prepack 生成 JS、CSS 和类型声明，普通 dev、build、发行 CI 和 Docker 使用编译产物，无需初始化子模块
构建许可：frontend/pnpm-workspace.yaml 的 allowBuilds 按仓库放行自有 UI 包脚本，升级时核对源码并更新锁文件，无需逐次修改许可，不开放全部依赖脚本

启动宿主

使用源码仓库自带的 Compose 与配置模板，按手动安装中的配置与权限要求准备 deploy/config.yaml 和 .runtime/ 目录

数据库及 Redis 可由 Compose 启动：

docker compose -f deploy/compose.yaml up -d postgres redis
cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-rs --locked

后端从当前目录向上查找 deploy/config.yaml，本机运行时数据库与 Redis 地址应指向可访问的本机端口

host.runtime_data_dir 和日志的相对路径以该配置文件所在目录解析

另开终端启动管理端：

pnpm --dir frontend dev

后端代理由 frontend/vite.config.ts 配置，验证 WebSocket 时直接连接后端

前后端检查见贡献与审查，数据库集成测试使用专用测试库

源码入口

后端职责和依赖方向见 Workspace 边界，页面与共享逻辑见前端模块职责。先按所属模块定位，再跟踪请求、状态与展示的调用关系

共享 UI 的命名与目录见组件架构

源码联调

宿主、组件库和官方插件保留独立仓库，通过 Git 子模块在同一目录开发：

目录	仓库与职责
`frontend` / `backend`	宿主管理端与 Rust 网关
`modules/ui`	`codex-proxy-ui`，共用组件与主题
`modules/plugins`	`codex-proxy-plugins`，官方插件示例

检出与安装

首次检出可同时下载子模块：

git clone --recurse-submodules https://github.com/zyycn/codex-proxy-rs.git
cd codex-proxy-rs

已有仓库运行 git submodule update --init --recursive。子模块固定到具体提交；拉取宿主更新后，同样用此命令对齐。执行前先保存子模块中的改动，避免切换正在开发的分支

在宿主根目录安装各项目依赖：

pnpm --dir modules/ui install --frozen-lockfile
pnpm --dir frontend install --frozen-lockfile
pnpm --dir modules/plugins/examples/workbench/frontend install --frozen-lockfile

启动与检查

在各自终端启动所需服务：

pnpm --dir frontend dev:source                            # 管理端，引用本地 UI
pnpm --dir modules/plugins/examples/workbench/frontend dev:source  # 插件页面，引用本地 UI
pnpm --dir modules/ui dev                                 # 组件库交互示例

管理端需要已启动的网关。插件独立预览的宿主桥使用模拟数据；已安装插件读取包内静态资源，修改后需重新构建、打包和安装

dev:source 使用 Vite 的 source 模式，由 @codex-proxy/ui/vite 的 CodexProxyUI 适配器将公开入口解析到 modules/ui，并统一处理共享依赖、源码预构建排除与开发服务的文件访问范围。入口映射以 UI 包 exports 中的 codex-proxy-source 条件为准，由 Vite 热更新。插件单独检出时仍用普通 dev；source 模式需要上述子模块目录结构

pnpm --dir frontend build:source
pnpm --dir modules/plugins/examples/workbench/frontend build:source

build:source 用各项目的 tsconfig.source.json 检查源码类型，管理端构建到 frontend/node_modules/.vite/source-dist，示例构建到其前端项目的 .vite/source-dist，不改写正式依赖、锁文件或 dist。源码联调 CI 显式检出子模块、核对 UI 提交锁定并验证这两个命令

本地 SDK 验证

插件正式 SDK 依赖仍由其 Cargo 锁文件固定。需要验证尚未发布的 SDK 修改时，在临时副本运行 Cargo patch，避免改写插件锁文件。以下命令从宿主根目录执行：

(
  set -e
  cpr_sdk_check_dir=$(mktemp -d)
  trap 'rm -rf "$cpr_sdk_check_dir"' EXIT
  mkdir "$cpr_sdk_check_dir/backend"
  cp modules/plugins/examples/workbench/backend/Cargo.{toml,lock} "$cpr_sdk_check_dir/backend/"
  cp -R modules/plugins/examples/workbench/backend/{src,tests} "$cpr_sdk_check_dir/backend/"
  cp modules/plugins/examples/workbench/plugin.json "$cpr_sdk_check_dir/"
  RUST_MIN_STACK=16777216 CARGO_TARGET_DIR="$PWD/backend/target/plugin-development" \
    cargo +1.99.1 test --manifest-path "$cpr_sdk_check_dir/backend/Cargo.toml" \
    --config "patch.\"https://github.com/zyycn/codex-proxy-rs.git\".gateway-plugin-sdk.path=\"$PWD/backend/crates/gateway-plugin/sdk\""
)

独立插件的构建、打包和安装后功能验证见 Workbench 示例。宿主插件集成测试的数据库与 Redis 配置见本地测试库

编辑与提交

直接打开宿主目录即可开发，分别在对应仓库目录操作 Git

在要修改的子模块内先创建分支，例如 git -C modules/ui switch -c feat/select。初次初始化的子模块通常处于 detached HEAD
在子模块运行自身检查，并在宿主根目录运行所需联调检查
分别提交、推送并合并组件库或插件 PR。宿主只记录子模块提交号，不能替代子仓库的提交与推送
UI 更新后，将管理端和插件页面的 UI 依赖同步到同一固定标签或提交，重新生成各自锁文件，再更新宿主的子模块指针；CI 会核对三处是否一致
提交宿主改动及 modules/ui、modules/plugins 指针。指针必须指向远程可取得的提交，不能只存在于开发机

更新子模块指针不会自动升级消费方依赖。正式依赖不能写成开发机路径或浮动分支；SDK 仍由插件仓库固定到包含所需合同的宿主提交

7.6 KiB Raw Permalink Blame History Unescape Escape