byy/qiming

Files

2026-06-01 13:54:52 +08:00

14 KiB

Raw Permalink Blame History

变更日志

**本文引用的文件** - [README.md](file://README.md) - [Cargo.toml](file://Cargo.toml) - [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs) - [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs) - [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs) - [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs) - [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs) - [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs) - [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs) - [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs) - [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md)

简介

本文件旨在系统化梳理 RCoder 项目在版本迭代中的变更，围绕功能更新、缺陷修复与架构演进，结合代码库中的实际实现，解释变更日志在版本控制、升级路径与向后兼容性中的作用，并提供升级评估与问题排查的最佳实践。由于仓库未包含 CHANGELOG.md 文件，本文将基于现有 README 与源码，对 v0.1.0 版本的现状与关键特性进行总结，并给出面向未来的变更日志模板与生成建议，以便团队在后续版本中持续完善。

项目结构

RCoder 采用多 crate 的工作区组织，核心模块包括：

主应用与路由：rcodes/rcoder
Pingora 反向代理封装：crates/pingora-proxy
Docker 容器管理：crates/docker_manager
共享类型与协议：crates/shared_types
代理适配器与示例：acp_adapter、claude-code-agent、codex-acp-agent 等

graph TB
subgraph "工作区"
A["crates/rcoder<br/>主应用/路由/配置/代理启动"]
B["crates/pingora-proxy<br/>Pingora 反向代理库"]
C["crates/docker_manager<br/>Docker 管理器/镜像选择/全局实例"]
D["crates/shared_types<br/>共享模型/多镜像配置"]
E["crates/acp_adapter<br/>ACP 协议适配"]
F["crates/claude-code-agent<br/>Claude 代理示例"]
G["crates/codex-acp-agent<br/>Codex 代理示例"]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G

图表来源

章节来源

核心组件

主应用与配置系统：命令行参数、环境变量、配置文件三段式优先级，支持代理与 Docker 配置的加载与覆盖。
Pingora 反向代理：Axum + Pingora 的双服务架构，主服务提供 API/SSE，Pingora 独立监听代理端口，路径前缀路由到目标后端。
Docker 管理器：全局单例、镜像选择策略、容器生命周期管理、清理任务与网络/挂载配置。
共享类型：多镜像配置结构、服务类型枚举、镜像选择器与缓存策略。

章节来源

架构总览

RCoder 采用“主服务 + Pingora 代理”的双服务架构：

主服务（Axum）：提供健康检查、聊天、SSE 实时进度、代理状态/配置/统计等接口。
Pingora 代理：独立监听代理端口，按路径前缀 /proxy/{port}/{path} 转发到指定后端，支持动态后端发现与健康检查。

graph TB
Client["客户端"] --> Axum["主服务(Axum)<br/>端口: config.port"]
Client --> Pingora["Pingora 代理<br/>端口: proxy_config.listen_port"]
Axum --> API["业务 API/SSE"]
Axum --> ProxyDocs["/proxy/* 文档接口"]
Pingora --> Backend["后端服务<br/>127.0.0.1:{port}"]

图表来源

章节来源

详细组件分析

变更日志模板与生成建议

为保证变更日志的可追溯性与可维护性，建议采用如下模板（示例，非仓库既有内容）：

版本号：vX.Y.Z
发布日期：YYYY-MM-DD
关键变更
- 新增：新增 API 端点、代理支持类型扩展、配置系统优化、可观测性增强等
- 修复：缺陷修复、兼容性问题修正、性能回归修复等
- 变更：架构调整、依赖升级、行为变更、弃用项等
升级指引：影响范围、破坏性变更、迁移步骤、兼容性说明
问题排查：常见问题、诊断方法、相关日志位置

说明：本仓库未包含 CHANGELOG.md 文件，本文基于现有 README 与源码总结 v0.1.0 的现状与关键特性，作为后续版本变更日志的参考。

章节来源

README.md

v0.1.0 版本要点（基于现有 README 与源码）

新增功能
- 基于 ACP 协议的 AI 代理统一管理（Codex、Claude Code）
- HTTP API 接口与统一 SSE 进度流
- 多层配置系统（命令行 > 环境变量 > 配置文件 > 默认）
- OpenTelemetry 集成与分布式追踪
- Swagger UI API 文档
- 项目文件解析器（Nuwax Parser）
技术特性
- 基于 Rust 2024 Edition
- 异步架构（Tokio）
- 模块化设计（Workspace Crates）
- 实时通信（SSE）
- 结构化日志（Tracing）

章节来源

README.md

Pingora 反向代理能力与变更要点

能力概述
- 独立监听代理端口，路径前缀路由到目标后端
- 支持动态后端发现与健康检查
- 提供状态、配置、统计等查询接口（Axum 文档接口）
关键实现
- 主应用在启动时根据配置创建 Pingora 服务器管理器，并在后台启动
- 路由中提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
- 代理库提供便捷函数与错误类型，支持快速启动与错误处理

sequenceDiagram
participant Client as "客户端"
participant Axum as "主服务(Axum)"
participant Router as "路由"
participant Pingora as "Pingora 代理"
participant Backend as "后端服务"
Client->>Axum : "GET /proxy/status"
Axum->>Router : "匹配 /proxy/*"
Router-->>Client : "返回状态/配置/统计(文档接口)"
Client->>Pingora : "GET /proxy/{port}/{path}"
Pingora->>Backend : "转发到 127.0.0.1 : {port}"
Backend-->>Pingora : "响应"
Pingora-->>Client : "返回代理响应"

图表来源

章节来源

Docker 容器管理与镜像选择能力

能力概述
- 全局 DockerManager 单例，支持自动检测平台、镜像选择与缓存
- 多镜像配置结构，支持服务类型（rcoder/agent-runner）与架构（arm64/amd64）选择
- 项目级镜像覆盖与环境变量注入
关键实现
- DockerManagerConfig 默认配置与全局初始化
- ImageSelector 选择策略（ServiceOnly），支持缓存与校验
- 容器生命周期管理、清理任务与网络/挂载配置

classDiagram
class DockerManager {
+new(config)
+create_container(config)
+get_multi_image_config()
}
class DockerManagerConfig {
+docker_host
+default_image
+default_platform
+default_network_mode
+default_work_dir
+auto_cleanup
+container_ttl_seconds
+multi_image_config
}
class ImageSelector {
+select_image(service_type, project_overrides)
+get_service_config(service_type)
}
class MultiImageConfig {
+services
+global_defaults
+selection_strategy
+cache_config
}
DockerManager --> DockerManagerConfig : "使用"
DockerManager --> ImageSelector : "创建并使用"
ImageSelector --> MultiImageConfig : "读取配置"

图表来源

章节来源

配置系统与升级影响评估

配置优先级
- 命令行参数 > 环境变量 > 配置文件 > 默认配置
代理配置
- 主应用根据命令行与配置文件决定是否启用 Pingora 代理及其监听端口、默认后端端口等
升级影响评估
- 若新增代理端口参数或健康检查配置项，需确保命令行与环境变量覆盖逻辑一致
- Docker 配置新增字段时，应提供默认值与校验逻辑，避免破坏性变更

flowchart TD
Start(["启动"]) --> ParseCLI["解析命令行参数"]
ParseCLI --> LoadFile["加载配置文件(若存在)"]
LoadFile --> ApplyEnv["应用环境变量覆盖"]
ApplyEnv --> MergeProxy["合并代理配置(端口/默认后端)"]
MergeProxy --> Validate["验证配置(含 Docker 多镜像)"]
Validate --> InitDocker["初始化 DockerManager(全局单例)"]
InitDocker --> StartProxy{"是否启用代理?"}
StartProxy --> |是| RunProxy["启动 Pingora 代理服务"]
StartProxy --> |否| RunMain["启动主服务(Axum)"]
RunProxy --> Done(["完成"])
RunMain --> Done

图表来源

章节来源

依赖关系分析

工作区与依赖
- 工作区包含多个 crate，主应用默认成员包含 rcoder、agent_runner、shared_types、docker_manager、acp_adapter、claude-code-agent、pingora-proxy
- 依赖包括 axum、tokio、clap、utoipa、pingora、bollard 等
组件耦合
- rcoder 依赖 pingora-proxy 与 docker_manager，通过配置与全局实例进行解耦
- 共享类型在 rcoder 与 docker_manager 之间传递，避免重复定义

graph LR
rcoder["rcoder"] --> pingora_proxy["pingora-proxy"]
rcoder --> docker_manager["docker_manager"]
rcoder --> shared_types["shared_types"]
docker_manager --> shared_types

图表来源

Cargo.toml

章节来源

Cargo.toml

性能考量

双服务架构
- 主服务与 Pingora 代理并行运行，互不阻塞，提高吞吐与隔离性
代理性能
- 基于 Rust 异步 I/O 的高性能代理，支持动态后端发现与健康检查
观测性
- OpenTelemetry 与 Tracing 集成，便于定位性能瓶颈与异常

章节来源

故障排查指南

代理请求未转发
- 确认请求是否发送到 Pingora 监听端口，而非主服务端口
- 检查路径前缀是否符合 /proxy/{port}/{path}
后端不可达
- 确认目标后端端口已启动且可访问
Docker 相关
- 检查 Docker socket 路径、权限与挂载
- 查看全局 DockerManager 初始化日志与清理任务输出

章节来源

结论

v0.1.0 版本已具备核心能力：统一 AI 代理接入、HTTP API 与 SSE、Pingora 反向代理、Docker 容器管理与多镜像配置、可观测性与文档化。
变更日志应聚焦于功能新增、缺陷修复与架构变更，并提供升级指引与兼容性说明。
建议在后续版本中补充 CHANGELOG.md，并建立自动化生成与校验流程，确保变更可追溯、可审计。

附录

变更日志生成最佳实践

自动化生成
- 使用 Git 标签与提交信息生成候选条目
- 通过 CI 校验变更类型（feat/fix/refactor/chore）与语义化版本
人工审核
- 评审破坏性变更与迁移成本
- 补充升级指引与兼容性说明
模板字段
- 版本号、发布日期、变更类型、影响范围、修复问题、相关 PR/Issue

代码级变更示例（基于现有实现）

代理端口与默认后端端口
- 主应用根据配置创建 Pingora 服务器管理器并启动
- 路由提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
Docker 镜像选择
- ImageSelector 采用 ServiceOnly 策略，优先使用服务特定镜像，支持缓存与校验
- DockerManagerConfig 默认配置与全局初始化，支持项目级镜像覆盖

章节来源

14 KiB Raw Permalink Blame History Unescape Escape

变更日志

目录

简介

项目结构

核心组件

架构总览

详细组件分析

变更日志模板与生成建议

v0.1.0 版本要点（基于现有 README 与源码）

Pingora 反向代理能力与变更要点

Docker 容器管理与镜像选择能力

配置系统与升级影响评估

依赖关系分析

性能考量

故障排查指南

结论

附录

变更日志生成最佳实践

代码级变更示例（基于现有实现）

14 KiB

Raw Permalink Blame History