Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
281 lines (192 loc) · 8.44 KB

ARCHITECTURE.md

File metadata and controls

281 lines (192 loc) · 8.44 KB
Raw

ARCHITECTURE

本文档说明 CodexManager 当前仓库结构、运行关系和发布链路，目标是帮助协作者快速判断改动应该落在哪一层。

1. 总体形态

CodexManager 由两类运行模式组成：

  1. 桌面模式：Tauri 桌面端 + 本地 service 进程
  2. Service 模式：独立 service + web UI，可用于服务器、Docker 或无桌面环境

统一目标：

  • 管理账号、用量、平台 Key
  • 提供本地网关能力
  • 对外兼容 OpenAI 风格入口，并适配多种上游协议

2. 目录结构与职责

.
├─ apps/                  # 前端与 Tauri 桌面端
│  ├─ src/                # Vite + 原生 JavaScript 前端
│  ├─ src-tauri/          # Tauri 桌面壳与原生命令桥接
│  ├─ tests/              # 前端 UI/结构测试
│  └─ dist/               # 前端构建产物
├─ crates/
│  ├─ core/               # 数据库迁移、存储基础、认证/用量底层能力
│  ├─ service/            # 本地 HTTP/RPC 服务、网关、协议适配、设置持久化
│  ├─ web/                # Web UI 服务壳，可嵌入前端静态资源
│  └─ start/              # Service 一键启动器（拉起 service + web）
├─ scripts/               # 本地构建、统一版本、测试探针、发布辅助脚本
├─ docker/                # Dockerfile 与 compose 配置
├─ assets/                # README 图片、Logo 等静态资源
└─ .github/workflows/     # CI / release workflow

3. 核心复杂域入口索引

3.1 前端总控入口

  • apps/src/main.js：前端启动装配入口
  • apps/src/runtime/app-bootstrap.js：界面初始化编排
  • apps/src/runtime/app-runtime.js：刷新流程与运行期协同
  • apps/src/settings/controller.js：设置域门面，继续向子模块分发

3.2 桌面端壳层入口

  • apps/src-tauri/src/lib.rs：Tauri 应用装配入口
  • apps/src-tauri/src/settings_commands.rs：桌面端设置桥接命令
  • apps/src-tauri/src/service_runtime.rs：桌面内嵌 service 生命周期
  • apps/src-tauri/src/rpc_client.rs：桌面端 RPC 调用基础设施

3.3 service 网关与协议入口

  • crates/service/src/lib.rs：service 总入口与运行时装配
  • crates/service/src/http/：HTTP 路由入口
  • crates/service/src/rpc_dispatch/：RPC 分发入口
  • crates/service/src/gateway/mod.rs：网关聚合入口
  • crates/service/src/gateway/observability/http_bridge.rs：请求追踪、协议桥接、日志写入
  • crates/service/src/gateway/protocol_adapter/request_mapping.rs：OpenAI/Codex 输入映射
  • crates/service/src/gateway/protocol_adapter/response_conversion.rs：非流式结果总转换入口
  • crates/service/src/gateway/protocol_adapter/response_conversion/sse_conversion.rs：流式 SSE 转换入口
  • crates/service/src/gateway/protocol_adapter/response_conversion/openai_chat.rs：OpenAI Chat 结果适配
  • crates/service/src/gateway/protocol_adapter/response_conversion/tool_mapping.rs：工具名缩短与还原

3.4 设置与运行配置入口

  • crates/service/src/app_settings/：设置持久化、环境变量覆盖、运行时同步
  • crates/service/src/web_access.rs：Web 访问密码与会话令牌

4. 运行关系

4.1 桌面模式

桌面模式由以下部分组成：

  • apps/src/：前端 UI
  • apps/src-tauri/：桌面壳
  • crates/service/：本地 service

运行方式：

  1. 用户启动桌面应用。
  2. Tauri 壳负责窗口、托盘、更新、单实例、设置桥接等桌面行为。
  3. 桌面端通过 RPC 或本地地址与 codexmanager-service 通信。
  4. 前端 UI 展示账号、用量、请求日志、设置等页面。

4.2 Service 模式

Service 模式由以下二进制组成：

  • codexmanager-service
  • codexmanager-web
  • codexmanager-start

职责：

  • codexmanager-service：核心服务进程，提供账号管理、网关转发、请求日志、设置持久化、RPC/HTTP 接口。
  • codexmanager-web：Web UI 服务壳，可直接提供前端页面，并代理到本地 service。
  • codexmanager-start：面向发布包的一键启动器，负责同时拉起 service 和 web。

5. 模块职责

5.1 apps/src/

主要负责：

  • 页面渲染
  • 用户交互
  • 状态管理
  • 调用本地 API / Tauri command
  • 设置页与账号页的前端逻辑

5.2 apps/src-tauri/

主要负责：

  • Tauri 应用启动
  • 单实例控制
  • 系统托盘与窗口事件
  • 桌面更新与安装器行为
  • 将前端操作桥接到 service / 本地运行时

5.3 crates/core/

主要负责：

  • SQLite 迁移
  • 存储底层能力
  • 认证 / usage 等核心基础逻辑
  • 可被 service 复用的数据访问能力

5.4 crates/service/

主要负责：

  • HTTP / RPC 入口
  • 账号、用量、API Key 管理
  • 本地网关能力
  • 协议适配与上游转发
  • 请求日志与设置持久化
  • 运行时配置同步

重点子目录：

  • src/gateway/：网关、协议适配、流式与非流式转换
  • src/http/：HTTP 路由入口
  • src/rpc_dispatch/：RPC 分发
  • src/account/、src/apikey/、src/requestlog/、src/usage/：领域逻辑

5.5 crates/web/

主要负责：

  • 提供 Web UI 静态资源
  • 挂载或代理到 service
  • 可选把 apps/dist 内嵌到二进制，形成单文件发布物

5.6 crates/start/

主要负责：

  • 在 Service 发布包里提供一个更直接的启动入口
  • 协调 service 与 web 的生命周期

6. 数据与配置

6.1 数据库

当前项目使用 SQLite。 数据库迁移位于：

  • crates/core/migrations/

数据库里不只存账号，也已经承担：

  • API Key
  • 请求日志
  • token 统计
  • app settings

6.2 运行配置

配置主要来源包括：

  • 环境变量 CODEXMANAGER_*
  • 应用运行目录下的 .env / codexmanager.env
  • app_settings 持久化表
  • 桌面端设置页

当前约定：

  • 启动前必须生效的配置保留在环境变量层。
  • 运行时可调配置优先通过设置页 + app_settings 管理。
  • 设置变更不应无边界地散落在桌面端、前端和 service 各处。

7. 请求链路概览

典型请求链路如下：

  1. 客户端或 UI 发起请求。
  2. 请求进入 crates/service 的 HTTP / RPC 层。
  3. 网关模块决定转发策略、账号、头部策略、上游代理等。
  4. 协议适配层负责处理：
    • /v1/chat/completions
    • /v1/responses
    • 流式 SSE
    • 非流式 JSON
    • tool_calls / tools 映射与聚合
  5. 结果回写请求日志和统计信息，再返回给调用方。

8. 构建与发布链路

8.1 本地开发构建

前端：

  • pnpm -C apps run dev
  • pnpm -C apps run build
  • pnpm -C apps run check

Rust：

  • cargo test --workspace
  • cargo build -p codexmanager-service --release
  • cargo build -p codexmanager-web --release
  • cargo build -p codexmanager-start --release

桌面端：

  • scripts/rebuild.ps1
  • scripts/rebuild-linux.sh
  • scripts/rebuild-macos.sh

8.2 版本管理

版本目前由根工作区统一维护：

  • 根 Cargo.toml 的 [workspace.package].version

桌面端额外同步：

  • apps/src-tauri/Cargo.toml
  • apps/src-tauri/tauri.conf.json

统一修改入口：

  • scripts/bump-version.ps1

8.3 GitHub Release

主要发布入口：

  • .github/workflows/release-all.yml

职责：

  • 构建 Windows / macOS / Linux 桌面产物
  • 构建 Service 版本产物
  • 上传 GitHub Release 附件
  • 根据 tag / prerelease 输入决定发布类型

9. 当前结构风险

当前仓库需要重点关注以下问题：

  1. apps/src-tauri/src/lib.rs 仍偏厚，桌面壳层装配与命令实现尚需继续拆开。
  2. crates/service/src/lib.rs 配置、运行时同步、副作用边界不够清晰。
  3. crates/service/src/gateway/protocol_adapter/response_conversion.rs 兼容分支较多，回归风险高。
  4. .github/workflows/release-all.yml 仍然较长，多平台逻辑需要持续约束。

10. 建议的改动落点

为了减少结构污染，新增需求尽量按以下原则落点：

  • 新页面或前端交互：优先落在 apps/src/views/、apps/src/services/、apps/src/ui/
  • 新桌面能力：优先落在 apps/src-tauri/src/ 的独立模块，而不是全部继续塞进 lib.rs
  • 新设置项：先判断属于环境变量、持久化配置还是运行时状态
  • 新协议兼容：优先落在 gateway / protocol adapter 子模块，不要把条件分支继续无序堆叠
  • 新发布逻辑：优先抽成脚本或复用步骤，不要三平台重复改三份