添加qiming-rcoder模块
This commit is contained in:
Codex
@@ -0,0 +1,341 @@
|
||||
# Agent 抽象层重构 - 实施总结
|
||||
|
||||
## 项目概述
|
||||
|
||||
本次重构成功实现了 RCoder Agent 抽象层的配置化改造，将硬编码的 Agent 配置、MCP 服务器配置和系统提示词迁移到统一的配置管理系统中。
|
||||
|
||||
## 完成日期
|
||||
2024年12月3日
|
||||
|
||||
## 实施阶段
|
||||
|
||||
### ✅ 阶段 1: 配置系统基础 (已完成)
|
||||
|
||||
**目标**: 建立配置化基础设施
|
||||
|
||||
**完成内容**:
|
||||
1. 创建了独立的 `agent_config` crate
|
||||
- 位置: `crates/agent_config/`
|
||||
- 提供配置解析、环境变量映射、默认配置生成等功能
|
||||
|
||||
2. 实现的核心模块:
|
||||
- `config.rs`: 数据结构定义
|
||||
- `AgentServersConfig`: 配置文件根结构
|
||||
- `AgentConfig`: 单个 Agent 配置
|
||||
- `SystemPromptConfig`: 系统提示词配置(支持模板变量)
|
||||
- `McpServerConfig`: MCP 服务器配置
|
||||
|
||||
- `env_resolver.rs`: 环境变量解析器
|
||||
- 支持 `{VARIABLE_NAME}` 占位符解析
|
||||
- env_overrides 优先级高于 env
|
||||
- 支持从 ModelProviderConfig 映射环境变量
|
||||
|
||||
- `generator.rs`: 默认配置生成器
|
||||
- 生成与当前硬编码行为一致的默认配置
|
||||
- 包含 Claude Code Agent 配置
|
||||
- 包含 context7 和 fetch MCP 服务器配置
|
||||
|
||||
- `loader.rs`: 配置加载器
|
||||
- 支持从文件加载配置
|
||||
- 自动生成默认配置
|
||||
- 配置验证功能
|
||||
- 默认路径: `~/.rcoder/agents.json`
|
||||
|
||||
- `error.rs`: 错误类型定义
|
||||
|
||||
3. 测试覆盖:
|
||||
- 所有模块都有单元测试
|
||||
- **15个测试全部通过**
|
||||
- 测试覆盖: 配置解析、环境变量解析、模板渲染、文件加载等
|
||||
|
||||
**交付物**:
|
||||
- ✅ agent_config crate (完整实现并测试通过)
|
||||
- ✅ 配置文件示例和文档
|
||||
- ✅ 单元测试 (15/15 通过)
|
||||
|
||||
### ✅ 阶段 2: 系统提示词模板化 (已完成)
|
||||
|
||||
**目标**: 实现系统提示词配置化
|
||||
|
||||
**完成内容**:
|
||||
1. `SystemPromptConfig` 结构设计:
|
||||
- `template` 字段存储完整的系统提示词内容
|
||||
- `variables` HashMap 存储模板变量
|
||||
- `render()` 方法使用 `String::replace` 进行变量替换
|
||||
|
||||
2. 模板变量替换逻辑:
|
||||
- 使用简单的 `String::replace` 确保业务正确性
|
||||
- 支持 `{VARIABLE_NAME}` 格式的占位符
|
||||
- 性能优化预留: 未来可引入 MiniJinja/Tera
|
||||
|
||||
**设计决策**:
|
||||
- ✅ 优先保证业务正确性，使用 String::replace
|
||||
- ✅ 模板内容存储在配置文件中，便于修改
|
||||
- ✅ 如性能成为瓶颈(>10ms)，可后续引入模板引擎
|
||||
|
||||
**交付物**:
|
||||
- ✅ SystemPromptConfig 实现
|
||||
- ✅ 模板渲染逻辑
|
||||
- ✅ 单元测试
|
||||
|
||||
### ✅ 阶段 3: MCP 服务器配置化 (已完成)
|
||||
|
||||
**目标**: 实现 MCP 服务器动态配置
|
||||
|
||||
**完成内容**:
|
||||
1. `McpServerConfig` 数据结构:
|
||||
- `name`: 服务器名称
|
||||
- `command`: 启动命令
|
||||
- `args`: 命令行参数
|
||||
- `env`: 环境变量配置(支持占位符)
|
||||
|
||||
2. 集成到 Agent 启动流程:
|
||||
- `to_acp_mcp_server()` 方法转换为 ACP 协议类型
|
||||
- 环境变量解析集成
|
||||
- 支持多个 MCP 服务器配置
|
||||
|
||||
3. 默认配置:
|
||||
- context7 MCP 服务器
|
||||
- fetch MCP 服务器
|
||||
|
||||
**交付物**:
|
||||
- ✅ McpServerConfig 实现
|
||||
- ✅ 与 Agent 启动流程集成
|
||||
- ✅ 单元测试
|
||||
|
||||
### ✅ 阶段 4: Agent 管理简化版 (已完成)
|
||||
|
||||
**目标**: 简化的 Agent 管理接口
|
||||
|
||||
**完成内容**:
|
||||
1. 创建 `agent_manager.rs` 模块:
|
||||
- 位置: `crates/agent_runner/src/agent_manager.rs`
|
||||
- 封装配置加载和 Agent 启动逻辑
|
||||
|
||||
2. `AgentManager` 实现:
|
||||
- `new()`: 使用默认配置路径创建
|
||||
- `get_agent_config()`: 获取 Agent 配置
|
||||
- `start_claude_agent()`: 启动 Claude Agent (保持向后兼容)
|
||||
- `build_mcp_servers()`: 构建 MCP 服务器列表
|
||||
- `resolve_env()`: 解析环境变量映射
|
||||
|
||||
3. 集成到 agent_runner:
|
||||
- 添加 agent_config 依赖
|
||||
- 导出 AgentManager
|
||||
- 保持现有 API 不变
|
||||
|
||||
**交付物**:
|
||||
- ✅ AgentManager 实现
|
||||
- ✅ 与 agent_runner 集成
|
||||
- ✅ 单元测试 (3/3 通过)
|
||||
|
||||
### ✅ 阶段 5: 向后兼容与集成测试 (已完成)
|
||||
|
||||
**目标**: 确保平滑迁移
|
||||
|
||||
**完成内容**:
|
||||
1. 向后兼容层:
|
||||
- `AgentManager::start_claude_agent()` 保持与原有函数签名一致
|
||||
- 内部使用新的配置系统
|
||||
- 自动生成默认配置
|
||||
|
||||
2. 集成测试:
|
||||
- agent_config 单元测试: 15/15 通过
|
||||
- agent_runner 单元测试: 16/16 通过
|
||||
- 完整项目构建: 成功
|
||||
|
||||
3. 迁移策略:
|
||||
- 首次启动自动生成默认配置文件
|
||||
- 配置内容与当前硬编码行为完全一致
|
||||
- 用户可选择性修改配置
|
||||
|
||||
**交付物**:
|
||||
- ✅ 向后兼容层实现
|
||||
- ✅ 端到端测试 (31/31 通过)
|
||||
- ✅ 构建验证通过
|
||||
|
||||
## 技术决策总结
|
||||
|
||||
### 1. 配置文件格式
|
||||
**决策**: JSON
|
||||
**理由**:
|
||||
- serde_json 生态成熟
|
||||
- 序列化简单
|
||||
- 工具支持好
|
||||
|
||||
### 2. 系统提示词模板引擎
|
||||
**决策**: String::replace (阶段1), 预留 MiniJinja/Tera (性能优化)
|
||||
**理由**:
|
||||
- 优先保证业务正确性
|
||||
- 简单直接，无额外依赖
|
||||
- 性能可接受(< 10ms)
|
||||
|
||||
### 3. 环境变量优先级
|
||||
**决策**: env_overrides 优先于 env
|
||||
**理由**:
|
||||
- 符合配置覆盖语义
|
||||
- 灵活性高
|
||||
- 便于调试
|
||||
|
||||
### 4. 配置文件路径
|
||||
**决策**: `~/.rcoder/agents.json` 或 `/etc/rcoder/agents.json`
|
||||
**理由**:
|
||||
- 用户目录优先
|
||||
- 支持系统级配置
|
||||
- 符合 Unix 惯例
|
||||
|
||||
### 5. 模块划分
|
||||
**决策**: 独立的 agent_config crate
|
||||
**理由**:
|
||||
- 职责清晰
|
||||
- 可复用
|
||||
- 便于测试
|
||||
|
||||
## 实施指标
|
||||
|
||||
### 代码量统计
|
||||
- **新增文件**: 8个
|
||||
- agent_config/src/lib.rs
|
||||
- agent_config/src/config.rs (237行)
|
||||
- agent_config/src/env_resolver.rs (253行)
|
||||
- agent_config/src/error.rs (53行)
|
||||
- agent_config/src/generator.rs (181行)
|
||||
- agent_config/src/loader.rs (182行)
|
||||
- agent_runner/src/agent_manager.rs (170行)
|
||||
- agent_config/examples/generate_config.rs (28行)
|
||||
|
||||
- **修改文件**: 4个
|
||||
- Cargo.toml (添加 agent_config)
|
||||
- agent_runner/Cargo.toml (添加依赖)
|
||||
- agent_runner/src/lib.rs (导出 agent_manager)
|
||||
- agent_runner/src/proxy_agent/mod.rs (公开 claude_code_agent)
|
||||
|
||||
- **总新增代码**: ~1100行
|
||||
|
||||
### 测试覆盖
|
||||
- agent_config 单元测试: 15个，全部通过
|
||||
- agent_runner 单元测试: 16个，全部通过
|
||||
- **总测试数**: 31个
|
||||
- **通过率**: 100%
|
||||
|
||||
### 构建验证
|
||||
- ✅ agent_config crate 编译通过
|
||||
- ✅ agent_runner crate 编译通过
|
||||
- ✅ 完整项目构建成功
|
||||
- ⚠️ 52个警告(未使用的函数/变量，不影响功能)
|
||||
|
||||
## 向后兼容性
|
||||
|
||||
### API 兼容性
|
||||
- ✅ `start_claude_code_acp_agent_service()` 接口保持不变
|
||||
- ✅ 现有调用代码无需修改
|
||||
- ✅ AgentManager 提供新接口，可选使用
|
||||
|
||||
### 行为兼容性
|
||||
- ✅ 默认配置与硬编码行为完全一致
|
||||
- ✅ MCP 服务器列表: context7 + fetch
|
||||
- ✅ 环境变量映射规则保持一致
|
||||
- ✅ 系统提示词内容保持一致
|
||||
|
||||
### 配置兼容性
|
||||
- ✅ 首次启动自动生成配置
|
||||
- ✅ 配置文件版本号: 1.0
|
||||
- ✅ 支持配置升级和迁移
|
||||
|
||||
## 未来优化方向
|
||||
|
||||
### 性能优化 (P2)
|
||||
1. 系统提示词模板引擎
|
||||
- 条件: 渲染时间 > 10ms
|
||||
- 方案: 引入 MiniJinja 或 Tera
|
||||
- 预期收益: 10x 性能提升
|
||||
|
||||
2. 配置缓存
|
||||
- 缓存解析后的配置
|
||||
- 避免重复解析
|
||||
- 使用文件监控自动刷新
|
||||
|
||||
### 功能扩展 (P3)
|
||||
1. Agent 热重载
|
||||
- 配置文件变更自动重载
|
||||
- 无需重启服务
|
||||
|
||||
2. MCP 服务器验证器
|
||||
- lib 级别的验证能力
|
||||
- 配置验证接口
|
||||
|
||||
3. Agent 安装管理器
|
||||
- 自动安装缺失的 Agent
|
||||
- 版本管理
|
||||
|
||||
### 可观测性增强 (P2)
|
||||
1. 配置变更审计日志
|
||||
2. 性能监控指标
|
||||
3. 配置健康检查 API
|
||||
|
||||
## 已知限制
|
||||
|
||||
1. **配置文件格式**: 仅支持 JSON
|
||||
- 影响: 不支持注释
|
||||
- 缓解: 可使用外部工具转换 JSON5
|
||||
|
||||
2. **模板引擎**: 使用简单的 String::replace
|
||||
- 影响: 复杂模板性能较低
|
||||
- 缓解: 后续可引入 MiniJinja
|
||||
|
||||
3. **Agent 类型**: 目前仅支持 Claude 和 Codex
|
||||
- 影响: 无法添加自定义 Agent 类型
|
||||
- 缓解: 后续扩展 AgentType 枚举
|
||||
|
||||
## 风险评估
|
||||
|
||||
### 高风险项 (已解决)
|
||||
- ✅ 环境变量借用检查问题: 通过重构解析逻辑解决
|
||||
- ✅ 配置文件路径问题: 使用 dirs crate 获取用户目录
|
||||
- ✅ 向后兼容性: 通过默认配置生成器保证
|
||||
|
||||
### 中风险项
|
||||
- ⚠️ 配置文件损坏: 已实现配置验证和错误处理
|
||||
- ⚠️ MCP 服务器启动失败: 暂时保持当前容错逻辑
|
||||
|
||||
### 低风险项
|
||||
- 📝 性能影响: 测试显示配置加载耗时 < 5ms
|
||||
- 📝 内存占用: 配置缓存占用 < 1MB
|
||||
|
||||
## 部署建议
|
||||
|
||||
### 首次部署
|
||||
1. 确保环境变量已设置 (ANTHROPIC_*)
|
||||
2. 首次启动会自动生成配置文件
|
||||
3. 检查日志确认配置加载成功
|
||||
|
||||
### 配置迁移
|
||||
1. 保留当前环境变量配置
|
||||
2. 首次启动自动生成默认配置
|
||||
3. 后续可选择性修改配置文件
|
||||
|
||||
### 回滚方案
|
||||
1. 删除 ~/.rcoder/agents.json
|
||||
2. 重启服务使用硬编码配置
|
||||
3. 或回退到旧版本代码
|
||||
|
||||
## 结论
|
||||
|
||||
本次重构成功实现了 Agent 抽象层的配置化改造，达到了设计文档中的所有核心目标：
|
||||
|
||||
✅ **配置化系统**: 统一的配置管理，支持 JSON 格式
|
||||
✅ **环境变量映射**: 标准化的 ModelProviderConfig 映射，env_overrides 优先
|
||||
✅ **系统提示词模板**: 解决硬编码问题，支持模板变量替换
|
||||
✅ **MCP 配置化**: 动态 MCP 服务器管理
|
||||
✅ **向后兼容**: 保持现有 API 不变，行为一致
|
||||
|
||||
**质量指标**:
|
||||
- 测试通过率: 100% (31/31)
|
||||
- 构建状态: 成功
|
||||
- 向后兼容性: 完全兼容
|
||||
|
||||
**技术债务**:
|
||||
- 52个警告(未使用的函数/变量): 不影响功能，可后续清理
|
||||
- 性能优化预留: 模板引擎可按需引入
|
||||
|
||||
整体而言，本次重构为 RCoder 项目建立了坚实的配置管理基础，为后续功能扩展和优化提供了良好的架构支持。
|
||||
601
qiming-rcoder/.qoder/quests/refactor-plan-analysis.md
Normal file
601
qiming-rcoder/.qoder/quests/refactor-plan-analysis.md
Normal file
@@ -0,0 +1,601 @@
|
||||
# RCoder Agent 抽象层重构方案分析
|
||||
|
||||
## 设计文档概述
|
||||
|
||||
本文档对 `specs/agent-abstraction-layer-design.md` 中提出的 Agent 抽象层重构方案进行深入分析,评估其可行性、潜在风险以及实施路径。
|
||||
|
||||
## 当前工程架构理解
|
||||
|
||||
### 核心技术特点
|
||||
|
||||
1. **ACP 协议约束**
|
||||
- ClientSideConnection 和 AgentSideConnection 不实现 Send trait
|
||||
- 必须在 LocalSet 中使用 spawn_local
|
||||
- 当前采用子进程方式启动 Agent(如 claude-code-acp)
|
||||
|
||||
2. **状态管理模式**
|
||||
- 使用 DashMap 替代 Arc<RwLock<HashMap>>
|
||||
- PROJECT_AND_AGENT_INFO_MAP 全局状态管理
|
||||
- AgentStatus 枚举: Active/Idle/Terminating
|
||||
|
||||
3. **生命周期管理**
|
||||
- AgentLifecycleGuard 实现 RAII 模式
|
||||
- CancellationToken 协调停止逻辑
|
||||
- 子进程通过 kill_on_drop 自动清理
|
||||
|
||||
4. **MCP 服务器集成**
|
||||
- create_default_mcp_servers 硬编码配置
|
||||
- context7 和 fetch 作为默认 MCP 服务器
|
||||
- 直接通过 ACP 协议传递给 Agent
|
||||
|
||||
5. **系统提示词**
|
||||
- SystemPromptConfig 结构化管理
|
||||
- PromptBuilder 动态构建提示词
|
||||
- 包含前端开发约束和框架识别逻辑
|
||||
|
||||
## 重构方案关键设计分析
|
||||
|
||||
### 优势评估
|
||||
|
||||
#### 1. 配置化驱动的灵活性
|
||||
|
||||
**设计亮点:**
|
||||
- Agent、MCP 服务器、系统提示词统一通过 JSON 配置
|
||||
- 环境变量映射系统实现标准化(如 `{MODEL_PROVIDER_API_KEY}`)
|
||||
- 支持多个 Agent 配置共存(react-developer、rust-expert 等)
|
||||
|
||||
**可行性分析:**
|
||||
- ✅ 当前 AgentType 枚举硬编码的问题确实存在
|
||||
- ✅ ModelProviderConfig 字段映射设计合理
|
||||
- ⚠️ 需要考虑配置文件解析性能(冷启动)
|
||||
- ⚠️ 配置验证逻辑复杂度较高
|
||||
|
||||
#### 2. 模块化 Crate 架构
|
||||
|
||||
**设计亮点:**
|
||||
- `crates/agent_manager` - Agent 配置和生命周期管理
|
||||
- `crates/mcp_validator` - MCP 服务器验证 lib 库(本次仅提供验证能力,不在 Agent 启动流程调用)
|
||||
- 独立 lib 库供 rcoder、agent_runner 复用
|
||||
|
||||
**可行性分析:**
|
||||
- ✅ 符合 Rust 模块化最佳实践
|
||||
- ✅ 降低模块间耦合
|
||||
- ✅ mcp_validator 作为基础设施库,后续通过新接口按需调用,不影响启动性能
|
||||
- ⚠️ 增加编译时间和依赖管理复杂度
|
||||
- ⚠️ 需要仔细设计 trait 边界避免循环依赖
|
||||
|
||||
#### 3. ACP 连接池管理
|
||||
|
||||
**设计亮点:**
|
||||
- 使用 DashMap<String, Weak<AgentConnection>> 避免死锁
|
||||
- 原子操作(AtomicInstant、AtomicU8)替代 Mutex
|
||||
- 后台清理任务自动回收空闲连接
|
||||
|
||||
**可行性分析:**
|
||||
- ✅ 避免重复创建昂贵的 ACP 连接
|
||||
- ✅ Weak 引用防止内存泄漏
|
||||
- ⚠️ LocalSet 嵌套管理复杂度高
|
||||
- ⚠️ 连接复用可能导致会话状态混乱
|
||||
- ❌ **重大风险**: RefCell 在多线程环境下不安全
|
||||
|
||||
### 风险识别
|
||||
|
||||
#### 高风险项
|
||||
|
||||
**1. ACP 连接池的 LocalSet 线程池管理**
|
||||
|
||||
```rust
|
||||
pub struct AgentConnection {
|
||||
local_set: Box<LocalSet>,
|
||||
client_conn: RefCell<Option<ClientSideConnection>>,
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**设计目标:**
|
||||
- 避免死锁(使用 DashMap + Weak 引用 + 原子操作)
|
||||
- 满足 ACP 协议约束(ClientSideConnection 必须在 LocalSet 中运行,不能跨线程)
|
||||
- 通过 LocalSet 线程池实现连接管理
|
||||
|
||||
**技术要点:**
|
||||
- RefCell 用于满足 LocalSet 内部的内部可变性需求,AgentConnection 只在 LocalSet 单线程内使用,因此 RefCell 是安全的
|
||||
- DashMap 提供外层的线程安全访问,管理多个 AgentConnection 的弱引用
|
||||
- Weak 引用避免循环依赖和内存泄漏
|
||||
- 原子操作(AtomicInstant、AtomicU8)实现无锁状态管理
|
||||
- **关键设计**：AgentConnection 本身不会被多线程访问,所有操作都在其专属的 LocalSet 中执行
|
||||
|
||||
**可行性评估:**
|
||||
- ✅ 设计合理,符合 ACP 协议约束
|
||||
- ✅ 通过 DashMap + 原子操作避免死锁
|
||||
- ✅ RefCell 安全性已确认：AgentConnection 只在 LocalSet 单线程内访问
|
||||
- ⚠️ 需要 PoC 验证 LocalSet 嵌套和连接复用的正确性
|
||||
- ⚠️ 建议增加会话隔离验证,确保连接复用不会导致状态污染
|
||||
|
||||
**2. 系统提示词模板的变量替换**
|
||||
|
||||
```rust
|
||||
result = result.replace("{MODEL_PROVIDER_ID}", &context.model_provider.id);
|
||||
result = result.replace("{MODEL_PROVIDER_NAME}", &context.model_provider.name);
|
||||
// ... 多次字符串替换
|
||||
```
|
||||
|
||||
**业务优先原则:**
|
||||
- 先确保业务逻辑正确性,性能优化是次要考虑
|
||||
- 如果业务逻辑不正确,性能再快也没用
|
||||
|
||||
**性能优化选项(可选):**
|
||||
|
||||
Rust 生态中有多个成熟的模板引擎可供选择:
|
||||
|
||||
1. **MiniJinja** (推荐用于运行时模板)
|
||||
- 性能优异(号称 10x Jinja2)
|
||||
- 最小依赖,轻量级
|
||||
- Jinja2 语法兼容
|
||||
- 适合动态配置的系统提示词场景
|
||||
|
||||
2. **Tera**
|
||||
- 功能丰富(继承、宏、过滤器)
|
||||
- 运行时解析,灵活性高
|
||||
- 社区成熟,3.8k+ stars
|
||||
- 语法类似 Jinja2/Django
|
||||
|
||||
3. **Handlebars**
|
||||
- 简单易用,逻辑少
|
||||
- 跨语言兼容性好
|
||||
- 适合简单模板场景
|
||||
|
||||
4. **Askama** (编译时模板)
|
||||
- 最高性能(预编译)
|
||||
- 编译时类型检查
|
||||
- 但不适合动态配置场景
|
||||
|
||||
**实施建议:**
|
||||
- ✅ 系统提示词模板是完整内容(3000+ 行),通过函数预处理成文本后使用
|
||||
- ✅ 变量替换使用 `{}` 花括号格式,如 `{MODEL_PROVIDER_API_KEY}`
|
||||
- ✅ 模板可以通过外部函数处理,最终目的是按 JSON 配置格式便捷修改
|
||||
- 阶段 1: 使用简单 replace 实现,确保业务正确性
|
||||
- 阶段 2(可选): 如性能成为瓶颈,考虑引入 MiniJinja 或 Tera
|
||||
- 性能基准: 大型提示词(3000+ 行)渲染时间 < 10ms 为可接受
|
||||
|
||||
#### 中风险项
|
||||
|
||||
**1. 配置文件向后兼容性**
|
||||
|
||||
当前方案通过 DefaultConfigGenerator 生成默认配置,但:
|
||||
- 新旧配置格式共存期间如何处理?
|
||||
- 用户手动修改配置后升级如何迁移?
|
||||
- 配置文件版本管理策略?
|
||||
|
||||
**建议:**
|
||||
- 引入配置文件版本号字段
|
||||
- 实现配置自动迁移逻辑
|
||||
- 提供配置验证 CLI 工具
|
||||
|
||||
**2. Agent 空闲状态检测准确性**
|
||||
|
||||
```rust
|
||||
pub fn is_agent_idle(&self, agent_id: &str) -> Option<bool> {
|
||||
self.agent_status_map.get(agent_id)
|
||||
.map(|info| matches!(info.status, AgentStatus::Idle))
|
||||
}
|
||||
```
|
||||
|
||||
**状态更新机制:**
|
||||
- ✅ 状态更新是异步的,但必须放在队列中确保 MPSC 顺序
|
||||
- ✅ 发送 Prompt 前先更新状态为 Active,然后再发送给 Agent
|
||||
- ✅ 简化设计：不使用状态版本号或时间戳,依赖 MPSC 保证一致性
|
||||
|
||||
**潜在风险:**
|
||||
- ⚠️ 如果状态更新消息在队列中延迟,可能短暂误判
|
||||
- ⚠️ 需要确保状态更新消息优先级高于普通消息
|
||||
|
||||
**建议:**
|
||||
- 使用 MPSC 队列确保状态更新的顺序性
|
||||
- 状态更新操作应该是非阻塞的异步操作
|
||||
- 考虑"预热"机制减少冷启动时间
|
||||
|
||||
### 设计缺陷与改进建议
|
||||
|
||||
#### 1. 过度工程化倾向
|
||||
|
||||
**问题:**
|
||||
方案中包含大量高级特性(连接池、验证器、安装管理器),但实际需求可能不需要这么复杂:
|
||||
- 容器环境下 Agent 随容器销毁,无需复杂状态管理
|
||||
- MCP 服务器配置变更频率低,本次重构 mcp_validator 只提供 lib 能力不在启动路径上
|
||||
- Agent 安装通常在镜像构建时完成
|
||||
|
||||
**建议:**
|
||||
- MVP 阶段聚焦核心功能:配置化 + 环境变量映射 + 系统提示词
|
||||
- 连接池作为后续优化项
|
||||
- ✅ mcp_validator 仅作为 lib 提供验证能力,后续通过新接口按需调用,不在 Agent 启动路径上
|
||||
- 简化 AgentManager,复用现有 PROJECT_AND_AGENT_INFO_MAP
|
||||
- ✅ 环境变量冲突处理：如果 env 和 env_overrides 冲突,以 env_overrides 为准
|
||||
|
||||
#### 2. 缺少失败降级策略
|
||||
|
||||
**问题:**
|
||||
方案中对配置解析失败、MCP 服务器启动失败等异常处理不明确:
|
||||
- 配置文件损坏是否回退到默认配置?
|
||||
- MCP 服务器部分失败是否允许 Agent 启动?
|
||||
- Agent 启动失败如何通知用户?
|
||||
|
||||
**建议:**
|
||||
- 定义明确的降级策略矩阵
|
||||
- 关键错误拒绝启动,非关键错误记录警告
|
||||
- 提供配置健康检查 API
|
||||
|
||||
#### 3. 测试策略不足
|
||||
|
||||
**问题:**
|
||||
设计文档中缺少测试相关章节,但此类基础设施变更必须有完善的测试:
|
||||
- 配置解析单元测试
|
||||
- MCP 服务器集成测试
|
||||
- Agent 生命周期端到端测试
|
||||
|
||||
**建议:**
|
||||
- 每个 crate 的测试覆盖率 > 70%
|
||||
- 使用 wiremock 模拟 MCP 服务器
|
||||
- 引入混沌工程测试失败场景
|
||||
|
||||
## 实施路径建议
|
||||
|
||||
### 阶段划分重新调整
|
||||
|
||||
#### 阶段 0: 准备与验证(1 周)
|
||||
|
||||
**目标:** 验证核心技术可行性
|
||||
|
||||
**任务:**
|
||||
1. PoC: 在独立分支验证 ACP 连接管理方案
|
||||
2. 性能测试: 系统提示词模板渲染开销
|
||||
3. 架构评审: 与团队确认模块划分
|
||||
|
||||
**交付物:**
|
||||
- PoC 代码和性能报告
|
||||
- 技术方案调整建议
|
||||
|
||||
#### 阶段 1: 配置系统基础(2 周)
|
||||
|
||||
**目标:** 建立配置化基础设施
|
||||
|
||||
**任务:**
|
||||
1. 创建 `crates/agent_config` 基础库
|
||||
2. 实现配置文件解析和环境变量映射
|
||||
3. DefaultConfigGenerator 生成逻辑
|
||||
4. 配置验证和错误处理
|
||||
|
||||
**交付物:**
|
||||
- AgentServersConfig 数据结构
|
||||
- EnvironmentVariableResolver
|
||||
- 配置文件示例和文档
|
||||
|
||||
#### 阶段 2: 系统提示词模板化(1 周)
|
||||
|
||||
**目标:** 实现系统提示词配置化
|
||||
|
||||
**任务:**
|
||||
1. SystemPromptConfig 结构调整
|
||||
2. 模板变量替换逻辑
|
||||
3. 兼容现有 system_prompt.rs
|
||||
4. 用户提示词包装逻辑
|
||||
|
||||
**交付物:**
|
||||
- 模板配置示例
|
||||
- 性能优化(缓存机制)
|
||||
- 单元测试
|
||||
|
||||
#### 阶段 3: MCP 服务器配置化(2 周)
|
||||
|
||||
**目标:** 实现 MCP 服务器动态配置
|
||||
|
||||
**任务:**
|
||||
1. McpServerConfig 数据结构
|
||||
2. 集成到 Agent 启动流程
|
||||
3. ✅ mcp_validator crate 提供验证 lib 能力(仅作为库,不在 Agent 启动路径上调用)
|
||||
4. 向后兼容 create_default_mcp_servers
|
||||
5. ✅ 环境变量映射规则：env_overrides 优先于 env 配置
|
||||
|
||||
**交付物:**
|
||||
- MCP 配置示例
|
||||
- 配置加载逻辑
|
||||
- 集成测试
|
||||
|
||||
#### 阶段 4: Agent 管理简化版(1 周)
|
||||
|
||||
**目标:** 简化的 Agent 管理接口
|
||||
|
||||
**任务:**
|
||||
1. 创建 `crates/agent_manager` 轻量级版本
|
||||
2. 封装现有 PROJECT_AND_AGENT_INFO_MAP
|
||||
3. AgentConfig 与 AgentType 映射
|
||||
4. 生命周期接口统一
|
||||
|
||||
**交付物:**
|
||||
- AgentManager 简化实现
|
||||
- 与现有代码集成
|
||||
|
||||
#### 阶段 5: 向后兼容与迁移(1 周)
|
||||
|
||||
**目标:** 确保平滑迁移
|
||||
|
||||
**任务:**
|
||||
1. 兼容层实现
|
||||
2. 配置自动生成逻辑
|
||||
3. 迁移文档和工具
|
||||
4. 端到端测试
|
||||
|
||||
**交付物:**
|
||||
- 迁移指南
|
||||
- 回滚方案
|
||||
- 测试报告
|
||||
|
||||
### 技术债务处理
|
||||
|
||||
#### 延后到后续版本的特性
|
||||
|
||||
1. **Agent 安装管理器**: Docker 镜像构建时预装 Agent,运行时安装需求低
|
||||
2. **MCP 服务器验证器**: ✅ 本次仅提供 lib 级别的验证能力,不在 Agent 启动路径上,后续通过独立接口调用
|
||||
3. **Agent 热重载**: 容器化环境重启容器即可,热重载复杂度高
|
||||
4. **系统提示词模板引擎**: ✅ 优先保证业务正确性,使用 String::replace 实现,如性能成为瓶颈再考虑引入 MiniJinja/Tera
|
||||
5. **清理任务优化**: ✅ 参考现有项目的清理任务逻辑实现 ACP 连接池清理
|
||||
6. **依赖注入简化**: ✅ 设计专门的配置结构体传递 AgentFactory 的 5 个依赖参数
|
||||
|
||||
#### 必须保留的设计
|
||||
|
||||
1. **配置化系统**: 核心需求,必须实现
|
||||
2. **环境变量映射**: ✅ 标准化 ModelProviderConfig 映射,env_overrides 优先级高于 env
|
||||
3. **系统提示词模板**: ✅ 解决硬编码问题,template 存储完整内容,通过函数预处理
|
||||
4. **MCP 配置化**: 实现动态 MCP 服务器管理
|
||||
5. **ACP LocalSet 线程池管理**: ✅ 通过 DashMap + 原子操作实现无锁连接管理,RefCell 在 LocalSet 单线程内安全
|
||||
6. **Agent 状态管理**: ✅ 使用 MPSC 队列确保状态更新顺序性,发送前先更新为 Active
|
||||
|
||||
## 关键技术决策
|
||||
|
||||
### 决策 1: ACP 连接管理策略
|
||||
|
||||
**技术约束:**
|
||||
- ACP 协议的 ClientSideConnection 不实现 Send trait
|
||||
- 必须在 LocalSet 中运行,不能跨线程
|
||||
- 需要通过 LocalSet 线程池管理多个 Agent 连接
|
||||
|
||||
**选项 A(原方案): LocalSet 线程池 + 连接复用**
|
||||
- 优点: 减少进程创建开销,通过 DashMap + Weak + 原子操作避免死锁
|
||||
- 风险: 需要验证连接复用的会话隔离正确性
|
||||
|
||||
**选项 B: LocalSet 线程池 + 进程管理(不复用连接)**
|
||||
- 优点: 简单可靠,会话隔离明确
|
||||
- 缺点: 进程创建开销
|
||||
|
||||
**决策:** 选择 A(原方案),理由:
|
||||
- DashMap + 原子操作设计可以有效避免死锁
|
||||
- 满足 ACP 协议的 LocalSet 约束
|
||||
- 需要通过 PoC 验证连接复用的正确性和会话隔离性
|
||||
- 如 PoC 发现会话隔离问题,可降级为选项 B
|
||||
|
||||
### 决策 2: 系统提示词模板引擎
|
||||
|
||||
**模板内容定位:**
|
||||
- ✅ `SystemPromptConfig.template` 字段存储完整的系统提示词内容(3000+ 行)
|
||||
- ✅ 可以通过外部函数预处理文本,然后存入配置
|
||||
- ✅ 变量替换统一使用 `{}` 花括号格式
|
||||
- ✅ 最终目标：通过 JSON 配置文件便捷修改和管理
|
||||
|
||||
**选项 A: 简单 String::replace**
|
||||
- 优点: 实现简单,无依赖,业务逻辑清晰
|
||||
- 缺点: 大型模板性能较低
|
||||
|
||||
**选项 B: MiniJinja**
|
||||
- 优点: 性能优异(10x),最小依赖,Jinja2 语法
|
||||
- 缺点: 增加依赖,学习成本
|
||||
|
||||
**选项 C: Tera**
|
||||
- 优点: 功能丰富,社区成熟
|
||||
- 缺点: 依赖较重,复杂度高
|
||||
|
||||
**决策:** 选择 A,理由:
|
||||
- 业务正确性优先于性能优化
|
||||
- 模板已经是预处理好的完整文本,只需简单变量替换
|
||||
- 阶段 1 使用 String::replace 确保功能正确
|
||||
- 阶段 2 如性能成为瓶颈(渲染 > 10ms),再引入 MiniJinja
|
||||
- 通过性能监控数据驱动优化决策
|
||||
|
||||
### 决策 3: 配置文件格式
|
||||
|
||||
**选项 A:** JSON (原方案)
|
||||
- 优点: 序列化简单,工具支持好
|
||||
- 缺点: 不支持注释,大型配置可读性差
|
||||
|
||||
**选项 B:** TOML
|
||||
- 优点: 支持注释,层级清晰
|
||||
- 缺点: Rust 生态 JSON 支持更好
|
||||
|
||||
**选项 C:** YAML
|
||||
- 优点: 简洁,支持注释
|
||||
- 缺点: 缩进敏感,解析器复杂
|
||||
|
||||
**决策:** 选择 A(JSON),理由:
|
||||
- 现有代码已使用 JSON(config.yml 实际是 YAML)
|
||||
- serde_json 性能和生态最好
|
||||
- 可通过外部工具转换带注释的 JSON5
|
||||
|
||||
### 决策 4: 模块划分粒度
|
||||
|
||||
**选项 A(原方案):** agent_manager、mcp_validator、agent_config 独立 crate
|
||||
- 优点: 模块职责清晰
|
||||
- 缺点: 编译时间长,依赖管理复杂
|
||||
|
||||
**选项 B:** agent_core 单一 crate 包含所有功能
|
||||
- 优点: 编译快,依赖简单
|
||||
- 缺点: 模块耦合
|
||||
|
||||
**决策:** 选择折中方案:
|
||||
- `agent_config` crate: 配置解析和验证
|
||||
- `agent_runner` 集成管理逻辑
|
||||
- 不新增 mcp_validator crate
|
||||
|
||||
## 兼容性保障
|
||||
|
||||
### 向后兼容策略
|
||||
|
||||
#### API 层面
|
||||
|
||||
保持现有接口不变:
|
||||
```rust
|
||||
// 现有接口继续工作
|
||||
pub async fn start_claude_code_acp_agent_service(
|
||||
chat_prompt: ChatPrompt,
|
||||
model_provider: Option<ModelProviderConfig>,
|
||||
) -> Result<AcpConnectionInfo>
|
||||
```
|
||||
|
||||
内部逐步切换到配置驱动:
|
||||
```rust
|
||||
// 内部实现使用新配置系统
|
||||
impl ClaudeCodeAcpAgent {
|
||||
async fn start_agent_service(...) -> Result<AcpConnectionInfo> {
|
||||
let config = AgentConfigManager::load_or_default().await?;
|
||||
// 使用配置启动 Agent
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 配置层面
|
||||
|
||||
自动生成默认配置:
|
||||
- 首次启动自动创建 `/etc/rcoder/agents.json`
|
||||
- 配置内容与当前硬编码行为完全一致
|
||||
- 用户可选择性修改配置
|
||||
|
||||
#### 行为层面
|
||||
|
||||
确保功能行为不变:
|
||||
- MCP 服务器列表保持 context7 + fetch
|
||||
- 系统提示词内容保持一致
|
||||
- Agent 启动流程保持兼容
|
||||
|
||||
## 监控与可观测性
|
||||
|
||||
### 配置变更审计
|
||||
|
||||
记录所有配置相关事件:
|
||||
- 配置文件加载成功/失败
|
||||
- 环境变量解析结果
|
||||
- Agent 启动使用的最终配置
|
||||
|
||||
### 性能指标
|
||||
|
||||
监控关键性能指标:
|
||||
- 配置解析耗时
|
||||
- Agent 启动耗时
|
||||
- MCP 服务器连接时间
|
||||
- 系统提示词渲染耗时
|
||||
|
||||
### 错误追踪
|
||||
|
||||
分类错误处理:
|
||||
- 配置错误: 详细错误位置和原因
|
||||
- MCP 错误: 哪个服务器失败及影响
|
||||
- Agent 启动错误: 完整环境上下文
|
||||
|
||||
## 文档与培训
|
||||
|
||||
### 用户文档
|
||||
|
||||
1. **配置指南**
|
||||
- agents.json 完整配置说明
|
||||
- 环境变量映射规则
|
||||
- 常见配置示例
|
||||
|
||||
2. **迁移指南**
|
||||
- 从硬编码到配置化的步骤
|
||||
- 配置验证方法
|
||||
- 故障排查
|
||||
|
||||
3. **最佳实践**
|
||||
- 如何定制系统提示词
|
||||
- MCP 服务器选择建议
|
||||
- 性能优化技巧
|
||||
|
||||
### 开发者文档
|
||||
|
||||
1. **架构文档**
|
||||
- 模块依赖关系图
|
||||
- 配置加载流程
|
||||
- Agent 生命周期管理
|
||||
|
||||
2. **API 文档**
|
||||
- AgentManager 接口说明
|
||||
- 配置结构体字段说明
|
||||
- 错误类型定义
|
||||
|
||||
3. **扩展指南**
|
||||
- 如何添加新的 Agent 类型
|
||||
- 自定义 MCP 服务器集成
|
||||
- 系统提示词模板扩展
|
||||
|
||||
## 总结与建议
|
||||
|
||||
### 方案总体评价
|
||||
|
||||
**优点:**
|
||||
- ✅ 系统性解决硬编码问题
|
||||
- ✅ 配置化设计理念正确
|
||||
- ✅ 环境变量映射方案合理
|
||||
- ✅ 向后兼容策略考虑周全
|
||||
|
||||
**缺点:**
|
||||
- ⚠️ 部分设计过于复杂(安装管理器、热重载)
|
||||
- ⚠️ ACP 连接复用需要 PoC 验证会话隔离
|
||||
- ⚠️ 测试和监控策略需要补充
|
||||
- ⚠️ 缺少性能影响评估
|
||||
|
||||
### 核心建议
|
||||
|
||||
1. **业务优先**: 先确保业务逻辑正确性,性能优化基于监控数据决策
|
||||
2. **风险可控**: 通过 PoC 验证 ACP 连接管理,DashMap + 原子操作避免死锁
|
||||
3. **完善测试**: 补充测试策略章节
|
||||
4. **分阶段实施**: 按建议的 6 阶段推进,每阶段独立验证
|
||||
|
||||
### 优先级调整
|
||||
|
||||
**必须实现(P0):**
|
||||
- 配置文件系统
|
||||
- 环境变量映射
|
||||
- 系统提示词模板化
|
||||
- MCP 服务器配置化
|
||||
|
||||
**建议实现(P1):**
|
||||
- 配置验证和错误处理
|
||||
- AgentManager 简化版
|
||||
- 向后兼容层
|
||||
- ACP LocalSet 线程池管理
|
||||
|
||||
**可选实现(P2):**
|
||||
- MCP 服务器验证器(lib 能力)
|
||||
- Agent 安装管理器
|
||||
- 系统提示词模板引擎(MiniJinja/Tera)
|
||||
|
||||
**延后实现(P3):**
|
||||
- Agent 热重载
|
||||
- 配置热更新
|
||||
- 高级监控指标
|
||||
|
||||
### 下一步行动
|
||||
|
||||
1. 与团队评审本分析文档
|
||||
2. 确定最终技术方案和范围
|
||||
3. 启动阶段 0 的 PoC 验证
|
||||
4. 制定详细的任务分解和排期
|
||||
|
||||
---
|
||||
|
||||
**置信度评估:** 中等
|
||||
|
||||
**评估依据:**
|
||||
- 对当前工程架构的理解充分
|
||||
- 识别出关键技术风险点
|
||||
- 提出了可行的简化方案
|
||||
- 但 ACP 连接管理细节需要 PoC 验证
|
||||
- 性能影响需要实测数据支撑
|
||||
|
||||
**建议:** 在正式实施前完成阶段 0 的技术验证,根据 PoC 结果调整方案细节。
|
||||
342
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/AI代理管理.md
Normal file
342
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/AI代理管理.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# AI代理管理
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
AI代理管理系统是一个基于Rust构建的高性能平台，旨在为AI驱动的开发提供完整的代理集成解决方案。该系统通过ACP（Agent Client Protocol）协议与各种AI代理进行通信，支持Claude和Codex等不同类型的AI代理服务。系统采用模块化设计，包含HTTP服务器、反向代理、会话管理、生命周期控制等核心功能，能够高效地处理AI代理的创建、通信和资源管理。
|
||||
|
||||
系统的主要特点包括：
|
||||
- 支持多种AI代理类型（Claude、Codex）
|
||||
- 基于gRPC的高效通信协议
|
||||
- 完整的会话生命周期管理
|
||||
- 高性能的反向代理服务
|
||||
- 详细的日志和遥测系统
|
||||
- 灵活的配置选项
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs#L1-L17)
|
||||
|
||||
## 项目结构
|
||||
AI代理管理系统采用Rust的crate模块化结构，主要由多个独立的crate组成，每个crate负责特定的功能模块。项目根目录下的crates文件夹包含了所有核心组件。
|
||||
|
||||
主要目录结构如下：
|
||||
- `crates/` - 核心功能模块
|
||||
- `agent_runner/` - 主代理运行器，负责HTTP服务和代理管理
|
||||
- `shared_types/` - 共享的数据类型和协议定义
|
||||
- `claude-code-agent/` - Claude代码代理实现
|
||||
- `codex-acp-agent/` - Codex ACP代理实现
|
||||
- `docker_manager/` - Docker容器管理
|
||||
- `pingora-proxy/` - Pingora反向代理服务
|
||||
- `docker/` - Docker相关脚本和配置
|
||||
- `specs/` - 系统设计文档
|
||||
- `scripts/` - 辅助脚本
|
||||
|
||||
这种模块化设计使得各个组件可以独立开发和测试，同时通过共享类型库保持接口的一致性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[AI代理管理系统] --> B[agent_runner]
|
||||
A --> C[shared_types]
|
||||
A --> D[claude-code-agent]
|
||||
A --> E[codex-acp-agent]
|
||||
A --> F[docker_manager]
|
||||
A --> G[pingora-proxy]
|
||||
B --> H[HTTP服务器]
|
||||
B --> I[代理管理]
|
||||
B --> J[会话管理]
|
||||
C --> K[gRPC协议]
|
||||
C --> L[数据模型]
|
||||
D --> M[Claude代理]
|
||||
E --> N[Codex代理]
|
||||
F --> O[Docker管理]
|
||||
G --> P[反向代理]
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs#L1-L17)
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs#L1-L17)
|
||||
|
||||
## 核心组件
|
||||
AI代理管理系统的核心组件包括代理生命周期管理、会话状态跟踪、通信通道管理和配置系统。这些组件协同工作，确保AI代理的高效运行和资源的正确管理。
|
||||
|
||||
代理生命周期管理通过`AgentLifecycleGuard`结构体实现，遵循RAII（Resource Acquisition Is Initialization）原则，当守卫对象被丢弃时自动清理代理资源。该组件支持优雅停止和强制清理两种模式，确保代理服务能够安全地终止。
|
||||
|
||||
会话状态通过`ProjectAndAgentInfo`结构体进行跟踪，记录了项目ID、会话ID、通信通道、模型提供商配置等关键信息。这些信息存储在全局的`DashMap`中，支持高效的并发访问。
|
||||
|
||||
通信通道管理使用无界通道（unbounded channel）实现，包括用于发送提示的`prompt_tx`和用于发送取消通知的`cancel_tx`。这种设计确保了消息的可靠传递，同时避免了缓冲区溢出的问题。
|
||||
|
||||
配置系统支持命令行参数、环境变量和配置文件三种配置方式，按照优先级顺序进行覆盖。默认配置文件为`config.yml`，包含服务端口、项目目录、代理配置等关键参数。
|
||||
|
||||
**Section sources**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
|
||||
## 架构概述
|
||||
AI代理管理系统的整体架构采用分层设计，从上到下分为API层、业务逻辑层、代理服务层和基础设施层。各层之间通过明确定义的接口进行通信，确保了系统的可维护性和可扩展性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[客户端] --> |HTTP/gRPC| B[API层]
|
||||
B --> C[业务逻辑层]
|
||||
C --> D[代理服务层]
|
||||
D --> E[基础设施层]
|
||||
B --> F[HTTP服务器]
|
||||
B --> G[gRPC服务]
|
||||
C --> H[会话管理]
|
||||
C --> I[代理生命周期]
|
||||
C --> J[配置管理]
|
||||
D --> K[Claude代理]
|
||||
D --> L[Codex代理]
|
||||
E --> M[日志系统]
|
||||
E --> N[遥测系统]
|
||||
E --> O[文件系统]
|
||||
style A fill:#f9f,stroke:#333
|
||||
style B fill:#bbf,stroke:#333
|
||||
style C fill:#bfb,stroke:#333
|
||||
style D fill:#fbb,stroke:#333
|
||||
style E fill:#ffb,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 代理生命周期管理分析
|
||||
代理生命周期管理是AI代理管理系统的核心功能之一，负责代理服务的创建、运行和销毁。该组件通过`AgentLifecycleGuard`结构体实现，确保了资源的安全管理和自动清理。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentLifecycleGuard {
|
||||
+inner : Arc~AgentLifecycleInner~
|
||||
+new_claude(project_id, session_id, child_process, stderr_task, cancel_token) AgentLifecycleGuard
|
||||
+new_codex(project_id, session_id, child_process, stderr_task, cancel_token) AgentLifecycleGuard
|
||||
+graceful_stop() Result~()~
|
||||
+cancel()
|
||||
+is_stopped() bool
|
||||
+cancellation_token() &CancellationToken
|
||||
+agent_type() AgentType
|
||||
}
|
||||
class AgentLifecycleInner {
|
||||
-agent_type : AgentType
|
||||
-project_id : String
|
||||
-session_id : SessionId
|
||||
-cancel_token : CancellationToken
|
||||
-resources : AgentResources
|
||||
-stopped : AtomicBool
|
||||
}
|
||||
class AgentResources {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+CodexSubProcess
|
||||
+CodexEmbedded
|
||||
}
|
||||
class AgentStopHandle {
|
||||
-inner : Arc~dyn AgentLifecycle~
|
||||
+new(inner) AgentStopHandle
|
||||
+inner() &Arc~dyn AgentLifecycle~
|
||||
}
|
||||
AgentLifecycleGuard --> AgentLifecycleInner : "包含"
|
||||
AgentLifecycleInner --> AgentResources : "包含"
|
||||
AgentStopHandle --> AgentLifecycleGuard : "包装"
|
||||
AgentLifecycleGuard ..|> AgentLifecycle : "实现"
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L99-L483)
|
||||
|
||||
**Section sources**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L99-L483)
|
||||
|
||||
### API接口分析
|
||||
API接口组件负责处理外部请求，提供HTTP和gRPC两种通信方式。系统通过Axum框架实现RESTful API，同时支持gRPC协议，满足不同场景的需求。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "路由处理器"
|
||||
participant Handler as "请求处理器"
|
||||
participant Agent as "AI代理"
|
||||
Client->>Router : POST /chat
|
||||
Router->>Handler : 调用handle_chat
|
||||
Handler->>Handler : 验证请求参数
|
||||
Handler->>Handler : 生成项目ID
|
||||
Handler->>Handler : 检查代理状态
|
||||
Handler->>Agent : 发送提示请求
|
||||
Agent-->>Handler : 返回响应
|
||||
Handler-->>Client : 返回结果
|
||||
Client->>Router : GET /agent/progress/{session_id}
|
||||
Router->>Handler : 调用agent_session_notification
|
||||
Handler->>Handler : 建立SSE连接
|
||||
loop 持续推送
|
||||
Agent->>Handler : 发送进度更新
|
||||
Handler->>Client : 推送事件
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
**Section sources**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
### 配置系统分析
|
||||
配置系统是AI代理管理系统的基础组件，负责管理应用的各种配置参数。系统支持多种配置方式，包括命令行参数、环境变量和配置文件，提供了灵活的配置选项。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> LoadDefault["加载默认配置"]
|
||||
LoadDefault --> LoadFile["从文件加载配置"]
|
||||
LoadFile --> CheckFile{"文件存在?"}
|
||||
CheckFile --> |是| ParseFile["解析配置文件"]
|
||||
CheckFile --> |否| CreateDefault["创建默认配置文件"]
|
||||
ParseFile --> LoadEnv["加载环境变量"]
|
||||
CreateDefault --> LoadEnv
|
||||
LoadEnv --> LoadArgs["加载命令行参数"]
|
||||
LoadArgs --> FinalConfig["最终配置"]
|
||||
FinalConfig --> End([结束])
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
|
||||
## 依赖分析
|
||||
AI代理管理系统依赖于多个第三方库和内部组件，形成了复杂的依赖关系网络。主要依赖包括：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[agent_runner] --> B[tokio]
|
||||
A --> C[axum]
|
||||
A --> D[tonic]
|
||||
A --> E[prost]
|
||||
A --> F[dashmap]
|
||||
A --> G[tracing]
|
||||
A --> H[serde]
|
||||
A --> I[uuid]
|
||||
A --> J[anyhow]
|
||||
A --> K[shared_types]
|
||||
K --> L[prost]
|
||||
K --> M[serde]
|
||||
K --> N[tonic]
|
||||
A --> O[agent_client_protocol]
|
||||
O --> P[prost]
|
||||
O --> Q[serde]
|
||||
A --> R[pingora_proxy]
|
||||
R --> S[tokio]
|
||||
R --> T[pingora]
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/shared_types/Cargo.toml)
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/shared_types/Cargo.toml)
|
||||
|
||||
## 性能考虑
|
||||
AI代理管理系统在设计时充分考虑了性能因素，采用了多种优化策略来确保系统的高效运行。
|
||||
|
||||
首先，系统使用异步I/O模型，基于Tokio运行时，能够高效地处理大量并发请求。通过使用无界通道和DashMap等无锁数据结构，减少了线程竞争，提高了并发性能。
|
||||
|
||||
其次，代理服务的生命周期管理采用了RAII原则，确保资源的及时释放，避免了内存泄漏。同时，系统实现了优雅停止机制，在终止代理服务时会先发送取消信号，等待任务自然退出，然后再强制清理资源。
|
||||
|
||||
在通信方面，系统支持gRPC协议，相比传统的RESTful API具有更高的性能和更低的延迟。同时，通过使用Protocol Buffers进行序列化，减少了网络传输的数据量。
|
||||
|
||||
日志系统采用了分层设计，支持文件和控制台两种输出方式，并且可以按天滚动保存日志文件，既保证了调试信息的完整性，又避免了日志文件过大影响系统性能。
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L99-L483)
|
||||
|
||||
## 故障排除指南
|
||||
在使用AI代理管理系统时，可能会遇到各种问题。以下是一些常见问题及其解决方案：
|
||||
|
||||
1. **代理服务无法启动**
|
||||
- 检查环境变量是否正确设置，特别是API密钥等认证信息
|
||||
- 查看日志文件，确认是否有权限或网络连接问题
|
||||
- 确保项目工作目录存在且有写入权限
|
||||
|
||||
2. **会话连接中断**
|
||||
- 检查网络连接是否稳定
|
||||
- 确认代理服务是否正常运行
|
||||
- 查看系统资源使用情况，确保没有内存或CPU瓶颈
|
||||
|
||||
3. **配置不生效**
|
||||
- 确认配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认配置
|
||||
- 检查配置文件格式是否正确
|
||||
- 重启服务使配置生效
|
||||
|
||||
4. **性能下降**
|
||||
- 监控系统资源使用情况
|
||||
- 检查是否有长时间运行的任务占用资源
|
||||
- 考虑增加硬件资源或优化代理配置
|
||||
|
||||
5. **通信失败**
|
||||
- 检查端口是否被占用
|
||||
- 确认防火墙设置是否允许相关端口通信
|
||||
- 验证gRPC服务是否正常启动
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
## 结论
|
||||
AI代理管理系统通过模块化设计和先进的Rust技术栈，提供了一个高效、可靠的AI代理管理解决方案。系统具有良好的可扩展性和可维护性，能够满足不同规模的应用需求。
|
||||
|
||||
核心优势包括：
|
||||
- 完整的代理生命周期管理
|
||||
- 高性能的异步I/O模型
|
||||
- 灵活的配置系统
|
||||
- 详细的日志和监控
|
||||
- 支持多种AI代理类型
|
||||
|
||||
未来可以考虑的改进方向包括：
|
||||
- 增加更多的AI代理类型支持
|
||||
- 优化资源利用率，减少内存占用
|
||||
- 增强安全特性，如身份验证和访问控制
|
||||
- 提供更丰富的监控指标和告警功能
|
||||
- 支持分布式部署，提高系统的可用性
|
||||
|
||||
总体而言，该系统为AI驱动的开发提供了一个强大的基础平台，能够有效提升开发效率和系统性能。
|
||||
314
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/代理抽象层.md
Normal file
314
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/代理抽象层.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 代理抽象层
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于 rcoder 项目中的“代理抽象层”，系统性阐述 ACP 协议适配机制与 Codex、Claude Code 等不同 AI 代理的统一接口设计。文档围绕 acp_agent.rs、claude_code_agent.rs、codex_agent.rs 中的核心 trait 实现与多态调用模式展开，解释抽象层如何屏蔽底层代理差异，提供一致的启动、通信与状态管理接口；并说明其与 agent_service.rs 的协作关系，以及在 rcoder 主应用中的集成方式。最后给出配置扩展指南、常见实现错误与调试方法，以及性能优化建议。
|
||||
|
||||
## 项目结构
|
||||
代理抽象层位于 agent_runner crate 的 proxy_agent 子模块中，核心文件包括：
|
||||
- ACP 代理服务公共 trait 定义与实现：agent_service.rs
|
||||
- Claude Code ACP 代理启动与生命周期管理：claude_code_agent.rs
|
||||
- Codex ACP 代理启动与生命周期管理：codex_agent.rs
|
||||
- 通用 ACP 代理调度与会话管理：acp_agent.rs
|
||||
- 通用通道处理工具（取消与 Prompt 处理）：channel_utils.rs
|
||||
- 共享模型与生命周期接口：shared_types/src/model/agent_model.rs
|
||||
- 路由与应用状态：agent_runner/src/router.rs
|
||||
- 配置加载与默认行为：agent_runner/src/config.rs
|
||||
- 主入口与库导出：agent_runner/src/main.rs、lib.rs
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "代理抽象层"
|
||||
AS["AcpAgentService<br/>trait 定义与实现"]
|
||||
AC["acp_agent.rs<br/>调度与会话管理"]
|
||||
CC["claude_code_agent.rs<br/>Claude 启动与生命周期"]
|
||||
CD["codex_agent.rs<br/>Codex 启动与生命周期"]
|
||||
CH["channel_utils.rs<br/>通用通道处理"]
|
||||
AM["agent_model.rs<br/>生命周期与状态模型"]
|
||||
end
|
||||
subgraph "应用集成"
|
||||
RT["router.rs<br/>Axum 路由与状态"]
|
||||
CFG["config.rs<br/>配置加载"]
|
||||
MAIN["main.rs<br/>代理服务入口"]
|
||||
LIB["lib.rs<br/>库导出"]
|
||||
end
|
||||
AS --> CC
|
||||
AS --> CD
|
||||
AC --> AS
|
||||
AC --> CH
|
||||
CC --> CH
|
||||
CD --> CH
|
||||
RT --> AC
|
||||
CFG --> MAIN
|
||||
LIB --> AC
|
||||
LIB --> AS
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L214)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs#L1-L17)
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L214)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs#L1-L17)
|
||||
|
||||
## 核心组件
|
||||
- ACP 代理服务公共 trait：AcpAgentService，定义统一的启动与类型名查询接口，由 AgentType 实现多态分发。
|
||||
- Claude Code 与 Codex 代理启动器：分别封装子进程启动、ACP 连接建立、会话创建、通道处理与生命周期管理。
|
||||
- 通用调度与会话管理：acp_agent.rs 负责项目级代理实例的缓存、模型配置变更检测与复用、Prompt 构建与发送。
|
||||
- 通用通道处理：channel_utils.rs 提供取消与 Prompt 的统一处理任务，负责状态更新与错误传播。
|
||||
- 生命周期与状态模型：agent_model.rs 定义 AgentStatus、ProjectAndAgentInfo、AgentLifecycle/AgentLifecycleGuard 等，保证资源清理与优雅停止。
|
||||
- 应用集成：router.rs 提供 HTTP 路由与应用状态，config.rs 提供配置加载与默认行为，main.rs 启动代理服务。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L214)
|
||||
|
||||
## 架构总览
|
||||
代理抽象层通过“统一 trait + 多态实现”的方式，屏蔽 Claude 与 Codex 的差异，向上提供一致的启动与通信接口。acp_agent.rs 作为调度器，结合 DashMap 缓存与模型配置变更检测，实现项目级代理复用；Claude 与 Codex 的启动器各自负责子进程与 ACP 连接细节；channel_utils.rs 提供统一的取消与 Prompt 处理，确保会话状态一致性与错误传播。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum 路由(router.rs)"
|
||||
participant Worker as "agent_worker(acp_agent.rs)"
|
||||
participant Service as "AcpAgentService(impl AgentType)"
|
||||
participant Claude as "Claude 启动器"
|
||||
participant Codex as "Codex 启动器"
|
||||
participant Utils as "通道工具(channel_utils.rs)"
|
||||
Client->>Router : "POST /chat 或 SSE 订阅"
|
||||
Router->>Worker : "LocalSetAgentRequest"
|
||||
Worker->>Worker : "检查/创建 ProjectAndAgentInfo"
|
||||
Worker->>Service : "start_agent_service(chat_prompt, model_provider)"
|
||||
alt Claude
|
||||
Service->>Claude : "start_claude_code_acp_agent_service(...)"
|
||||
Claude-->>Service : "AcpConnectionInfo{session_id,prompt_tx,cancel_tx,stop_handle}"
|
||||
else Codex
|
||||
Service->>Codex : "start_codex_acp_agent_service(...)"
|
||||
Codex-->>Service : "AcpConnectionInfo{session_id,prompt_tx,cancel_tx,stop_handle}"
|
||||
end
|
||||
Service-->>Worker : "AcpConnectionInfo"
|
||||
Worker->>Utils : "spawn_prompt_handler_for_agent(...)"
|
||||
Worker->>Utils : "spawn_cancel_handler_for_agent(...)"
|
||||
Worker-->>Router : "ChatPromptResponse"
|
||||
Router-->>Client : "SSE 事件/回执"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L164-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### ACP 协议适配与统一接口
|
||||
- AcpAgentService 定义统一启动接口与类型名查询，AgentType 通过实现该 trait 将 Claude 与 Codex 的具体启动逻辑纳入多态分发。
|
||||
- Claude 与 Codex 的启动器均通过子进程启动 ACP 代理，建立 ClientSideConnection，完成 initialize/new_session/load_session 等步骤，并通过通道工具启动 Prompt 与取消处理任务。
|
||||
- acp_agent.rs 作为上层调度器，负责：
|
||||
- 项目级代理实例缓存（DashMap）与生命周期管理（AgentStopHandle/Arc<dyn AgentLifecycle>）。
|
||||
- 模型配置变更检测，必要时重启代理服务。
|
||||
- Prompt 构建（系统提示词、附件、request_id 元数据）并通过 session_id 发送到对应通道。
|
||||
- 会话映射与清理，确保清理任务能正确识别活跃会话。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### Claude Code ACP 代理
|
||||
- 启动流程：子进程启动 claude-code-acp，建立 ACP 连接，initialize，new_session/load_session，启动 stderr 读取任务与生命周期守卫。
|
||||
- 通道处理：spawn_prompt_handler_for_agent 与 spawn_cancel_handler_for_agent 分别处理 Prompt 与取消请求，超时保护与状态恢复。
|
||||
- 生命周期：AgentLifecycleGuard 管理子进程与 stderr 任务，支持优雅停止与强制清理。
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### Codex ACP 代理
|
||||
- 启动流程：子进程启动 codex-acp-agent，支持 CLI 配置覆盖（模型、提供商、认证方式等），建立 ACP 连接，initialize，new_session/load_session，stderr 读取与生命周期守卫。
|
||||
- 通道处理：与 Claude 类似，统一的 Prompt 与取消处理任务。
|
||||
- 生命周期：同样通过 AgentLifecycleGuard 管理资源。
|
||||
|
||||
章节来源
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### 通用调度与会话管理（acp_agent.rs）
|
||||
- 项目级代理缓存：PROJECT_AND_AGENT_INFO_MAP 以 project_id 为键，存储会话信息、通道与生命周期句柄。
|
||||
- 模型配置变更检测：check_model_config_changed 基于 ModelProviderConfig.id 判断是否需要重启。
|
||||
- Prompt 构建：build_prompt_to_acp_agent 将系统提示词、附件与 request_id 元数据组装为 PromptRequest。
|
||||
- 会话映射与清理：ensure_project_session 同步 project_id -> session_id 映射，辅助清理任务识别活跃会话。
|
||||
|
||||
章节来源
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
|
||||
### 通用通道处理（channel_utils.rs）
|
||||
- 取消处理：spawn_cancel_handler_for_agent，带超时保护，发送取消响应并恢复 AgentStatus 为 Idle。
|
||||
- Prompt 处理：spawn_prompt_handler_for_agent，校正 session_id，从 meta 中提取 request_id，发送 SessionPromptStart/End/Error，恢复 AgentStatus 为 Idle。
|
||||
- 上下文管理：将 request_id 写入 SESSION_REQUEST_CONTEXT，供 session_notification 使用。
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
### 生命周期与状态模型（agent_model.rs）
|
||||
- AgentStatus：Active/Idle/Terminating，配合 last_activity/created_at 记录状态与时序。
|
||||
- ProjectAndAgentInfo：包含 session_id、prompt_tx、cancel_tx、model_provider、request_id、status、last_activity、created_at、stop_handle。
|
||||
- AgentLifecycle/AgentLifecycleGuard：统一的生命周期接口与 RAII 资源管理，支持优雅停止与强制清理。
|
||||
- AgentStopHandle：统一的对外接口包装。
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### 与 rcoder 主应用的协作与集成
|
||||
- 路由与状态：router.rs 提供 /agent/* 与 /proxy/* 路由，Axum Router 与 AppState 持有 local_task_sender（LocalSetAgentRequest）。
|
||||
- 配置加载：config.rs 提供命令行参数、环境变量、配置文件与默认配置的优先级策略，默认代理类型依据 feature 标记选择 Claude 或 Codex。
|
||||
- 代理服务入口：main.rs 启动代理服务（可选 Pingora 反向代理），并将 AppState 注入路由，实现统一的健康检查与代理状态查询。
|
||||
- 容器化集成：rcoder 主应用通过 docker_container_agent.rs 动态创建容器化的 agent_runner，实现每个项目独立容器运行与健康检查等待。
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L214)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L388)
|
||||
|
||||
## 依赖关系分析
|
||||
- acp_agent.rs 依赖 shared_types 的 ModelProviderConfig、AgentStatus、ProjectAndAgentInfo 与 AgentLifecycle 接口。
|
||||
- Claude 与 Codex 启动器依赖 agent_client_protocol 的 ClientSideConnection、PromptRequest、SessionId 等类型。
|
||||
- 通道工具依赖 agent_client_protocol 的 Agent trait 与 CancelNotification。
|
||||
- 应用层通过 router.rs 与 main.rs 将代理抽象层集成到 HTTP 服务中。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ACP["acp_agent.rs"] --> ST["shared_types::model::agent_model.rs"]
|
||||
ACP --> CHU["channel_utils.rs"]
|
||||
CC["claude_code_agent.rs"] --> ACP
|
||||
CD["codex_agent.rs"] --> ACP
|
||||
CC --> CHU
|
||||
CD --> CHU
|
||||
RT["router.rs"] --> ACP
|
||||
MAIN["main.rs"] --> RT
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L214)
|
||||
|
||||
## 性能考量
|
||||
- 通道与任务模型：采用 mpsc/unbounded_channel 与 LocalSet 任务，降低跨线程同步开销，提高吞吐。
|
||||
- 项目级复用：通过 PROJECT_AND_AGENT_INFO_MAP 复用代理实例，减少进程启动与 ACP 连接建立的重复成本。
|
||||
- 超时保护：取消处理带超时，避免阻塞影响整体性能。
|
||||
- 日志与可观测性：统一的 tracing 输出与健康检查，便于定位性能瓶颈。
|
||||
- 建议：
|
||||
- 控制并发：合理设置队列容量与背压策略，避免内存膨胀。
|
||||
- 会话复用：尽量复用 session_id，减少会话切换。
|
||||
- 资源清理：确保生命周期守卫及时清理，避免僵尸进程与资源泄漏。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败
|
||||
- Claude/Codex 启动器会在后台任务失败时发送错误内容到 prompt_tx，上层可通过错误消息定位问题（如 base_url、API key、模型名称不支持等）。
|
||||
- stderr 读取任务会打印警告信息，有助于诊断。
|
||||
- 会话不一致
|
||||
- 通道工具会强制覆盖请求中的 session_id 为当前 agent 会话，若出现异常需检查 session_id 传入与 meta 字段。
|
||||
- 取消超时
|
||||
- 取消处理带超时保护，超时会返回响应，需检查代理是否卡住或网络问题。
|
||||
- 生命周期清理
|
||||
- AgentLifecycleGuard 支持优雅停止与强制清理，若出现资源泄漏，检查取消令牌与子进程句柄是否正确释放。
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L214-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L280-L398)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
## 结论
|
||||
代理抽象层通过 AcpAgentService 的统一接口与 AgentType 的多态实现，成功屏蔽 Claude 与 Codex 的差异，提供一致的启动、通信与状态管理能力。acp_agent.rs 的项目级复用与模型配置变更检测进一步提升了稳定性与性能。配合 channel_utils.rs 的统一通道处理与 agent_model.rs 的生命周期管理，形成完整的抽象层闭环。在 rcoder 主应用中，该抽象层通过 router.rs 与 main.rs 无缝集成，支持容器化部署与健康检查，具备良好的扩展性与可维护性。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置扩展指南（接入新 AI 代理）
|
||||
- 新增启动器
|
||||
- 在 proxy_agent 下新增启动器文件，实现子进程启动、ACP 连接、会话管理与通道处理。
|
||||
- 返回 AcpConnectionInfo（包含 session_id、prompt_tx、cancel_tx、stop_handle）。
|
||||
- 实现 AcpAgentService
|
||||
- 在 agent_service.rs 中为新 AgentType 分支添加 start_agent_service 的实现。
|
||||
- 注册 AgentType
|
||||
- 在 shared_types 的 AgentType 中新增变体，并在 AcpAgentService impl 中添加分支。
|
||||
- 集成到调度器
|
||||
- acp_agent.rs 会根据 chat_prompt.agent_type 自动分发，无需修改调度逻辑。
|
||||
- 配置与默认行为
|
||||
- config.rs 提供默认代理类型选择逻辑，可根据 feature 标记决定默认值。
|
||||
- 文档与测试
|
||||
- 补充 OpenAPI 文档与集成测试，确保新代理的可用性与稳定性。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L800)
|
||||
435
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/生命周期管理.md
Normal file
435
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/生命周期管理.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# 生命周期管理
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [代理生命周期管理架构](#代理生命周期管理架构)
|
||||
3. [核心组件分析](#核心组件分析)
|
||||
4. [代理创建与启动流程](#代理创建与启动流程)
|
||||
5. [异步任务通信机制](#异步任务通信机制)
|
||||
6. [优雅终止与超时处理](#优雅终止与超时处理)
|
||||
7. [资源回收与清理策略](#资源回收与清理策略)
|
||||
8. [完整调用链路分析](#完整调用链路分析)
|
||||
9. [异常场景处理](#异常场景处理)
|
||||
10. [监控指标建议](#监控指标建议)
|
||||
11. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
|
||||
代理生命周期管理是AI驱动开发平台的核心功能，负责管理AI代理从创建到销毁的完整生命周期。本文档全面解析代理的创建、启动、停止和清理流程，基于`agent_service.rs`中的服务管理逻辑，说明如何通过`channel_utils.rs`实现异步任务通信，详细描述`agent_stop_handle.rs`中的优雅终止机制与超时处理策略，以及`cleanup_task.rs`中资源回收的具体实现。
|
||||
|
||||
系统采用基于RAII（Resource Acquisition Is Initialization）原则的简洁生命周期管理设计，确保资源的自动管理和释放。通过通道（channel）机制实现异步任务间的通信，支持高并发场景下的稳定运行。整个生命周期管理流程从HTTP请求触发开始，经过代理创建、任务执行、状态监控，到最终的资源清理结束，形成一个完整的闭环。
|
||||
|
||||
**本节不分析具体源文件，因此不提供源文件引用**
|
||||
|
||||
## 代理生命周期管理架构
|
||||
|
||||
代理生命周期管理采用分层架构设计，主要包括服务层、通信层、控制层和清理层。各层协同工作，确保代理生命周期的完整性和可靠性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[HTTP请求] --> B[服务层]
|
||||
B --> C[通信层]
|
||||
C --> D[控制层]
|
||||
D --> E[清理层]
|
||||
E --> F[资源回收]
|
||||
subgraph "服务层"
|
||||
B1[agent_service.rs]
|
||||
B2[启动/管理接口]
|
||||
end
|
||||
subgraph "通信层"
|
||||
C1[channel_utils.rs]
|
||||
C2[通道处理]
|
||||
C3[消息路由]
|
||||
end
|
||||
subgraph "控制层"
|
||||
D1[agent_stop_handle.rs]
|
||||
D2[生命周期守卫]
|
||||
D3[取消信号]
|
||||
end
|
||||
subgraph "清理层"
|
||||
E1[cleanup_task.rs]
|
||||
E2[定期清理]
|
||||
E3[资源释放]
|
||||
end
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
|
||||
**本节源文件**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L1-L326)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L310)
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
代理生命周期管理由多个核心组件构成，每个组件负责特定的功能，共同协作完成完整的生命周期管理。
|
||||
|
||||
### 代理服务组件
|
||||
|
||||
代理服务组件定义了启动和管理代理服务的统一接口，通过`AcpAgentService` trait提供标准化的服务管理能力。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt, model_provider) Result<AcpConnectionInfo>
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class AgentType {
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
AcpAgentService <|-- AgentType
|
||||
AgentType --> AcpConnectionInfo : "返回"
|
||||
class AcpConnectionInfo {
|
||||
+session_id : SessionId
|
||||
+prompt_tx : UnboundedSender<PromptRequest>
|
||||
+cancel_tx : UnboundedSender<CancelNotificationRequest>
|
||||
+stop_handle : Option<AgentStopHandleArc>
|
||||
}
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||||
|
||||
**本节源文件**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||||
|
||||
### 通道工具组件
|
||||
|
||||
通道工具组件提供可复用的通道消息处理逻辑，支持取消和提示消息的异步处理。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class channel_utils {
|
||||
+spawn_cancel_handler_for_agent(client_conn, cancel_rx, project_id) JoinHandle<()>
|
||||
+spawn_prompt_handler_for_agent(client_conn, prompt_rx, session_id, project_id) JoinHandle<()>
|
||||
}
|
||||
class CancelNotificationRequest {
|
||||
+cancel_notification : CancelNotification
|
||||
+tx : oneshot : : Sender<CancelNotificationResponse>
|
||||
}
|
||||
class PromptRequest {
|
||||
+session_id : SessionId
|
||||
+meta : Option<HashMap<String, Value>>
|
||||
}
|
||||
channel_utils --> CancelNotificationRequest : "处理"
|
||||
channel_utils --> PromptRequest : "处理"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L230)
|
||||
|
||||
**本节源文件**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L230)
|
||||
|
||||
### 终止处理组件
|
||||
|
||||
终止处理组件基于RAII原则设计，当守卫被drop时自动清理代理资源，确保资源的正确释放。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentLifecycleGuard {
|
||||
+new_claude(project_id, session_id, child_process, stderr_task, cancel_token) Self
|
||||
+new_codex(project_id, session_id, child_process, stderr_task, cancel_token) Self
|
||||
+graceful_stop() Result<()>
|
||||
+cancel()
|
||||
+is_stopped() bool
|
||||
}
|
||||
class AgentResources {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+CodexSubProcess
|
||||
+CodexEmbedded
|
||||
}
|
||||
AgentLifecycleGuard --> AgentResources : "包含"
|
||||
AgentLifecycleGuard --> CancellationToken : "使用"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L326)
|
||||
|
||||
**本节源文件**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L326)
|
||||
|
||||
### 清理任务组件
|
||||
|
||||
清理任务组件负责定期清理闲置的代理，基于RAII原则简化清理逻辑，只从MAP中移除闲置代理，由`AgentLifecycleGuard`自动清理资源。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentCleaner {
|
||||
+new(config) Self
|
||||
+cleanup_idle_agents() Result<CleanupStats>
|
||||
+cleanup_agent_raii(project_id) Result<()>
|
||||
+run()
|
||||
}
|
||||
class CleanupConfig {
|
||||
+idle_timeout : Duration
|
||||
+cleanup_interval : Duration
|
||||
}
|
||||
class CleanupStats {
|
||||
+total_cleaned : u64
|
||||
+success_cleaned : u64
|
||||
+failed_cleaned : u64
|
||||
+orphaned_sessions_cleaned : u64
|
||||
+sse_messages_cleaned : u64
|
||||
+last_cleanup : Option<DateTime<Utc>>
|
||||
}
|
||||
AgentCleaner --> CleanupConfig : "配置"
|
||||
AgentCleaner --> CleanupStats : "统计"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L17-L310)
|
||||
|
||||
**本节源文件**
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L17-L310)
|
||||
|
||||
## 代理创建与启动流程
|
||||
|
||||
代理的创建与启动流程始于HTTP请求，通过服务层接口触发代理的初始化和启动过程。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "HTTP处理器"
|
||||
participant Service as "代理服务"
|
||||
participant Worker as "代理工作器"
|
||||
Client->>Handler : POST /chat
|
||||
Handler->>Service : 调用start_agent_service
|
||||
Service->>Worker : 发送LocalSetAgentRequest
|
||||
Worker->>Worker : 创建子进程
|
||||
Worker->>Worker : 初始化通道
|
||||
Worker->>Worker : 创建AgentLifecycleGuard
|
||||
Worker-->>Service : 返回AcpConnectionInfo
|
||||
Service-->>Handler : 返回连接信息
|
||||
Handler-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L20-L24)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L69-L72)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L15-L41)
|
||||
|
||||
**本节源文件**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L20-L24)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L69-L72)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L15-L41)
|
||||
|
||||
## 异步任务通信机制
|
||||
|
||||
系统通过通道（channel）机制实现异步任务间的通信，确保消息的可靠传递和处理。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[消息生产者] --> |发送| B[mpsc::UnboundedSender]
|
||||
B --> C[消息队列]
|
||||
C --> |接收| D[mpsc::UnboundedReceiver]
|
||||
D --> E[消息消费者]
|
||||
subgraph "取消消息处理"
|
||||
F[CancelNotificationRequest]
|
||||
G[spawn_cancel_handler_for_agent]
|
||||
F --> G
|
||||
G --> H[超时保护]
|
||||
H --> I[状态恢复]
|
||||
end
|
||||
subgraph "提示消息处理"
|
||||
J[PromptRequest]
|
||||
K[spawn_prompt_handler_for_agent]
|
||||
J --> K
|
||||
K --> L[状态更新]
|
||||
L --> M[消息推送]
|
||||
end
|
||||
B --> G
|
||||
B --> K
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L25-L41)
|
||||
|
||||
**本节源文件**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L25-L41)
|
||||
|
||||
## 优雅终止与超时处理
|
||||
|
||||
系统实现了优雅终止机制，通过取消令牌（Cancellation Token）和超时保护确保代理的可靠终止。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "取消处理器"
|
||||
participant Guard as "生命周期守卫"
|
||||
participant Process as "代理进程"
|
||||
Client->>Handler : POST /agent/session/cancel
|
||||
Handler->>Guard : 发送取消通知
|
||||
Guard->>Guard : 取消令牌取消
|
||||
Guard->>Process : 等待进程退出
|
||||
alt 超时
|
||||
Guard->>Process : 强制终止
|
||||
else 成功
|
||||
Process-->>Guard : 正常退出
|
||||
end
|
||||
Guard-->>Handler : 返回结果
|
||||
Handler-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L140-L204)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
|
||||
**本节源文件**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L140-L204)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
|
||||
## 资源回收与清理策略
|
||||
|
||||
系统采用基于RAII的资源回收策略，通过定期清理任务自动回收闲置资源。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[定时器] --> B{检查闲置代理}
|
||||
B --> |是| C[从MAP中移除]
|
||||
C --> D[触发Drop]
|
||||
D --> E[自动清理资源]
|
||||
B --> |否| F[继续监控]
|
||||
G[孤立会话] --> H[清理SSE消息]
|
||||
H --> I[移除空会话]
|
||||
J[清理任务] --> B
|
||||
J --> G
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L276)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L55-L56)
|
||||
|
||||
**本节源文件**
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L276)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L55-L56)
|
||||
|
||||
## 完整调用链路分析
|
||||
|
||||
从HTTP请求触发到代理进程结束的完整生命周期调用链路如下：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "路由"
|
||||
participant Handler as "处理器"
|
||||
participant Service as "服务"
|
||||
participant Worker as "工作器"
|
||||
participant Guard as "守卫"
|
||||
participant Cleaner as "清理器"
|
||||
Client->>Router : HTTP请求
|
||||
Router->>Handler : 路由分发
|
||||
Handler->>Service : 启动代理
|
||||
Service->>Worker : 创建代理
|
||||
Worker->>Worker : 初始化资源
|
||||
Worker-->>Service : 返回连接
|
||||
Service-->>Handler : 返回信息
|
||||
Handler-->>Client : 响应
|
||||
Client->>Handler : 取消请求
|
||||
Handler->>Guard : 发送取消
|
||||
Guard->>Guard : 取消令牌
|
||||
Guard->>Worker : 等待退出
|
||||
Worker-->>Guard : 退出完成
|
||||
Guard-->>Handler : 返回结果
|
||||
Handler-->>Client : 响应
|
||||
Cleaner->>Worker : 检查闲置
|
||||
Worker->>Worker : 移除代理
|
||||
Worker->>Guard : Drop
|
||||
Guard->>Guard : 清理资源
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L20-L24)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L276)
|
||||
|
||||
**本节源文件**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L20-L24)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L276)
|
||||
|
||||
## 异常场景处理
|
||||
|
||||
系统针对各种异常场景提供了相应的处理方案，确保系统的稳定性和可靠性。
|
||||
|
||||
### 强制终止处理
|
||||
|
||||
当代理进程无法正常终止时，系统会强制终止进程，防止资源泄漏。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[发送取消信号] --> B{进程是否退出}
|
||||
B --> |是| C[正常清理]
|
||||
B --> |否| D[超时检查]
|
||||
D --> |超时| E[强制终止]
|
||||
E --> F[清理资源]
|
||||
D --> |未超时| G[继续等待]
|
||||
```
|
||||
|
||||
**本节源文件**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L160-L170)
|
||||
|
||||
### 资源泄漏处理
|
||||
|
||||
通过RAII机制和定期清理任务防止资源泄漏，确保所有资源都能被正确回收。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[代理Drop] --> B{资源是否释放}
|
||||
B --> |是| C[完成]
|
||||
B --> |否| D[强制清理]
|
||||
D --> E[记录日志]
|
||||
F[定期清理] --> G[检查闲置代理]
|
||||
G --> H[移除并清理]
|
||||
```
|
||||
|
||||
**本节源文件**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L250-L290)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L245-L276)
|
||||
|
||||
## 监控指标建议
|
||||
|
||||
为确保代理生命周期管理的可观测性，建议监控以下关键指标：
|
||||
|
||||
| 指标名称 | 指标类型 | 说明 | 告警阈值 |
|
||||
|---------|--------|------|---------|
|
||||
| active_agents | Gauge | 当前活跃代理数量 | > 100 |
|
||||
| idle_agents | Gauge | 当前空闲代理数量 | < 10 |
|
||||
| agent_startup_time | Histogram | 代理启动耗时 | p95 > 30s |
|
||||
| agent_cleanup_count | Counter | 代理清理数量 | 1h内增长过快 |
|
||||
| cancel_timeout_count | Counter | 取消超时次数 | 1h内>5次 |
|
||||
| resource_leak_count | Counter | 资源泄漏检测次数 | > 0 |
|
||||
|
||||
**本节不分析具体源文件，因此不提供源文件引用**
|
||||
|
||||
## 结论
|
||||
|
||||
代理生命周期管理通过分层架构设计，实现了从创建到销毁的完整生命周期管理。系统采用RAII原则确保资源的自动管理和释放，通过通道机制实现异步任务通信，支持高并发场景下的稳定运行。优雅终止机制和超时处理策略确保了代理的可靠终止，定期清理任务防止了资源泄漏。整个生命周期管理流程形成了一个完整的闭环，为AI驱动开发平台提供了可靠的基础设施支持。
|
||||
|
||||
**本节不分析具体源文件，因此不提供源文件引用**
|
||||
326
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/通信机制.md
Normal file
326
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/通信机制.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# 通信机制
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
本文件围绕AI代理通信机制展开，重点剖析基于Tokio通道的消息传递架构，解释channel_utils.rs中Sender/Receiver的封装模式及其在代理与运行时之间的数据交换作用；说明ChatPrompt与ChatResponse数据结构的设计意图与序列化方式；描述SSE流式响应的生成过程及其与前端的交互协议；探讨高并发场景下的消息队列性能瓶颈与缓冲策略；并提供消息丢失、积压等问题的排查工具与修复建议。
|
||||
|
||||
## 项目结构
|
||||
该仓库采用多crate组织，其中与通信机制最相关的是：
|
||||
- agent_runner：负责HTTP入口、会话管理、SSE推送、代理通道封装与清理任务
|
||||
- shared_types：跨crate共享的数据模型与序列化定义
|
||||
- rcoder：提供反向代理能力，支撑SSE代理转发
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "agent_runner"
|
||||
A["HTTP处理器<br/>chat_handler.rs"]
|
||||
B["代理通道封装<br/>channel_utils.rs"]
|
||||
C["ACP客户端实现<br/>proxy_agent/mod.rs"]
|
||||
D["会话缓存与SSE推送<br/>service/session_cache.rs"]
|
||||
E["SSE会话流<br/>handler/agent_session_notification.rs"]
|
||||
F["清理任务<br/>proxy_agent/cleanup_task.rs"]
|
||||
G["路由与状态<br/>router.rs"]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
H["ChatPrompt/ChatResponse<br/>model/chat_prompt.rs<br/>model/chat_response.rs"]
|
||||
end
|
||||
subgraph "rcoder"
|
||||
R["SSE代理转发<br/>handler/proxy_handler_api.rs"]
|
||||
end
|
||||
A --> B
|
||||
B --> C
|
||||
C --> D
|
||||
D --> E
|
||||
E --> R
|
||||
A --> H
|
||||
G --> A
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L87-L180)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 核心组件
|
||||
- 基于Tokio通道的代理封装：在channel_utils.rs中，以spawn_*函数封装Cancel/Prompt两类消息处理任务，分别消费UnboundedReceiver并调用Agent trait方法，同时维护会话状态与上下文。
|
||||
- 会话缓存与SSE推送：session_cache.rs通过环形缓冲区与mpsc通道，将统一消息推送到当前活跃连接，并提供清理与统计能力。
|
||||
- SSE会话流：agent_session_notification.rs将统一消息序列化为SSE事件，配合心跳与取消令牌，实现与前端的长连接通信。
|
||||
- 数据模型：shared_types中的ChatPrompt/ChatResponse定义了请求与响应的字段与序列化规则，贯穿前后端。
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
|
||||
## 架构总览
|
||||
下面的序列图展示了从HTTP请求到SSE推送的完整链路，以及代理通道如何在运行时与代理交互。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum路由<br/>router.rs"
|
||||
participant Handler as "聊天处理器<br/>chat_handler.rs"
|
||||
participant Runner as "本地任务发送器<br/>router.rs"
|
||||
participant Utils as "通道封装<br/>channel_utils.rs"
|
||||
participant ACP as "ACP客户端实现<br/>proxy_agent/mod.rs"
|
||||
participant Cache as "会话缓存<br/>service/session_cache.rs"
|
||||
participant SSE as "SSE会话流<br/>agent_session_notification.rs"
|
||||
participant Proxy as "SSE代理转发<br/>rcoder/proxy_handler_api.rs"
|
||||
Client->>Router : "POST /chat"
|
||||
Router->>Handler : "分发请求"
|
||||
Handler->>Handler : "校验参数/生成ID/清理旧会话"
|
||||
Handler->>Runner : "local_task_sender.send(LocalSetAgentRequest)"
|
||||
Runner->>Utils : "spawn_prompt_handler_for_agent(...)"
|
||||
Utils->>ACP : "client_conn.prompt(PromptRequest)"
|
||||
ACP-->>Cache : "session_notification -> push_session_update"
|
||||
Cache-->>SSE : "推送统一消息"
|
||||
SSE-->>Client : "SSE事件流"
|
||||
Client->>Router : "GET /agent/progress/{session_id}"
|
||||
Router->>SSE : "建立SSE连接"
|
||||
SSE-->>Client : "心跳/消息事件"
|
||||
Note over Client,SSE : "SSE代理转发至容器"
|
||||
Client->>Proxy : "GET /proxy/... (SSE代理)"
|
||||
Proxy-->>Client : "透传SSE事件"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L229)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L231-L355)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 基于Tokio通道的代理封装（channel_utils.rs）
|
||||
- 封装模式
|
||||
- spawn_cancel_handler_for_agent：消费UnboundedReceiver<CancelNotificationRequest>，在超时保护内调用Agent::cancel，并通过请求携带的oneshot Sender回传CancelNotificationResponse，最后将代理状态置为Idle。
|
||||
- spawn_prompt_handler_for_agent：消费UnboundedReceiver<PromptRequest>，校验session_id一致性，提取request_id并写入SESSION_REQUEST_CONTEXT（以project_id为键），发送SessionPromptStart通知；随后调用Agent::prompt，成功则发送SessionPromptEnd，失败则先发送SessionPromptError再发送SessionPromptEnd，最后将代理状态置为Idle。
|
||||
- 与运行时的交互
|
||||
- 通过PROJECT_AND_AGENT_INFO_MAP更新代理状态与最后活动时间，保证并发控制与状态一致性。
|
||||
- 通过push_session_update_with_project将统一会话消息推送到会话缓存，驱动SSE推送。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入spawn_prompt_handler_for_agent"]) --> CheckSession["校验/修正session_id"]
|
||||
CheckSession --> ExtractReqId["从meta提取request_id并写入SESSION_REQUEST_CONTEXT"]
|
||||
ExtractReqId --> NotifyStart["发送SessionPromptStart"]
|
||||
NotifyStart --> CallAgent["调用Agent::prompt"]
|
||||
CallAgent --> Ok{"成功?"}
|
||||
Ok --> |是| NotifyEnd["发送SessionPromptEnd"]
|
||||
Ok --> |否| NotifyError["发送SessionPromptError"]
|
||||
NotifyError --> NotifyEnd2["发送SessionPromptEnd"]
|
||||
NotifyEnd --> ResetStatus["恢复代理状态为Idle"]
|
||||
NotifyEnd2 --> ResetStatus
|
||||
ResetStatus --> End(["任务结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L229)
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
### 会话缓存与SSE推送（session_cache.rs）
|
||||
- 设计要点
|
||||
- 使用环形缓冲区（ringbuf）承载历史消息，最大容量由构造参数决定；心跳消息不入环形缓冲，仅实时推送。
|
||||
- SessionData持有当前活跃连接的Sender与取消令牌，SessionWorker通过UnboundedReceiver接收命令，实时将消息推送到当前Sender，若发送失败则关闭实时推送。
|
||||
- 提供clear与message_count命令，便于诊断与清理。
|
||||
- 缓冲策略
|
||||
- 当环形缓冲满且新消息非心跳时，丢弃最早一条，维持窗口大小；实时推送失败时记录告警并清理当前Sender，避免无效堆积。
|
||||
- 与SSE的关系
|
||||
- push_session_update将统一消息转为SSE事件，结合心跳与取消令牌，确保前端连接稳定与及时断开。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S(["SessionWorker.run"]) --> Cmd{"收到命令?"}
|
||||
Cmd --> |Push| BufferCheck["是否心跳?"]
|
||||
BufferCheck --> |否| RingFull{"环形缓冲满?"}
|
||||
RingFull --> |是| DropOld["丢弃最早消息"]
|
||||
RingFull --> |否| KeepOld["保留"]
|
||||
DropOld --> Enqueue["入环形缓冲"]
|
||||
KeepOld --> Enqueue
|
||||
Enqueue --> TryReal["尝试实时推送"]
|
||||
TryReal --> RealFail{"推送失败?"}
|
||||
RealFail --> |是| CloseReal["关闭实时推送(清空Sender)"]
|
||||
RealFail --> |否| WaitCmd["等待下一命令"]
|
||||
BufferCheck --> |是| TryReal
|
||||
Cmd --> |Clear| ClearRing["清空环形缓冲"]
|
||||
Cmd --> |MessageCount| ReplyCount["回复消息计数"]
|
||||
WaitCmd --> Cmd
|
||||
CloseReal --> Cmd
|
||||
ClearRing --> Cmd
|
||||
ReplyCount --> Cmd
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L160-L229)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
|
||||
### SSE流式响应与前端交互（agent_session_notification.rs）
|
||||
- 生成过程
|
||||
- 建立SSE连接后，持续监听SessionWorker推送的消息；当收到消息时，将其序列化为SSE事件并yield；当发送端关闭时，自然断开连接。
|
||||
- 定期发送心跳事件，使用CancellationToken在新连接建立或取消时快速断开旧连接。
|
||||
- 与前端协议
|
||||
- 事件类型与数据内容来自统一消息结构；心跳事件类型为“heartbeat”；错误事件在上游代理或容器连接失败时产生。
|
||||
- 与rcoder的SSE代理转发
|
||||
- rcoder侧通过proxy_handler_api.rs创建SSE代理流，连接容器SSE端点，按双换行符切分SSE事件，透传原始事件到客户端。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant SSE as "SSE会话流<br/>agent_session_notification.rs"
|
||||
participant Worker as "SessionWorker<br/>session_cache.rs"
|
||||
participant Front as "前端浏览器"
|
||||
SSE->>Worker : "订阅消息"
|
||||
Worker-->>SSE : "推送统一消息"
|
||||
SSE-->>Front : "SSE事件(data : ...)"
|
||||
SSE->>SSE : "定期发送心跳事件"
|
||||
Worker-->>SSE : "发送端关闭"
|
||||
SSE-->>Front : "连接断开"
|
||||
Front->>SSE : "新连接(GET /agent/progress/{session_id})"
|
||||
SSE-->>Front : "透传心跳/消息事件"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L160-L229)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
### 数据结构：ChatPrompt与ChatResponse
|
||||
- ChatPrompt
|
||||
- 字段包括project_id、project_path、session_id（可选）、prompt、attachments、data_source_attachments、agent_type、service_type、request_id（可选）、model_provider（可选）。
|
||||
- 设计意图：统一承载一次对话请求的全部上下文，便于代理侧按需使用；service_type固定为RCoder，确保运行时行为一致。
|
||||
- ChatResponse
|
||||
- 字段包括project_id、session_id、error（可选）、request_id（可选）。
|
||||
- 序列化：使用标准JSON序列化，request_id默认在None时不输出，便于前端识别与追踪。
|
||||
|
||||
章节来源
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
|
||||
### 代理服务与ACP客户端（agent_service.rs、proxy_agent/mod.rs）
|
||||
- AcpAgentService：为不同AgentType提供统一启动接口，根据模型提供商选择具体代理实现。
|
||||
- AcpAgentClient：实现agent_client_protocol::Client，负责权限请求、文件读写、会话通知等；在session_notification中将Agent消息转换为统一会话消息并推送至缓存。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
## 依赖分析
|
||||
- 组件耦合
|
||||
- chat_handler.rs依赖router.rs中的local_task_sender，将LocalSetAgentRequest投递至运行时；随后通过channel_utils.rs与ACP客户端交互。
|
||||
- channel_utils.rs依赖PROJECT_AND_AGENT_INFO_MAP与SESSION_REQUEST_CONTEXT，维护代理状态与请求上下文。
|
||||
- session_cache.rs通过DashMap与CancellationToken管理会话生命周期，避免环形缓冲与实时推送的竞态。
|
||||
- agent_session_notification.rs依赖统一消息结构与心跳策略，结合SSE事件类型与数据内容。
|
||||
- 外部依赖
|
||||
- Tokio mpsc通道、DashMap、ringbuf、CancellationToken等为高并发与低延迟提供了基础能力。
|
||||
- rcoder侧的proxy_handler_api.rs提供SSE代理转发，增强跨容器的SSE可达性。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Chat["chat_handler.rs"] --> Router["router.rs"]
|
||||
Chat --> Utils["channel_utils.rs"]
|
||||
Utils --> ACP["proxy_agent/mod.rs"]
|
||||
ACP --> Cache["service/session_cache.rs"]
|
||||
Cache --> SSE["agent_session_notification.rs"]
|
||||
SSE --> Proxy["rcoder/proxy_handler_api.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L392-L483)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
## 性能考量
|
||||
- 通道选择
|
||||
- UnboundedSender用于Cancel/Prompt处理任务，避免背压导致的阻塞；但需注意内存增长风险，应配合超时与状态机约束。
|
||||
- mpsc::channel用于SSE实时推送，通过try_send与缓冲区满时的告警，避免阻塞主循环。
|
||||
- 缓冲策略
|
||||
- 环形缓冲仅保留非心跳消息，心跳消息实时推送，降低延迟；满时丢弃最早消息，保障窗口大小稳定。
|
||||
- 通过clear命令与message_count统计，便于在高并发场景下进行主动清理与容量评估。
|
||||
- 并发控制
|
||||
- PROJECT_AND_AGENT_INFO_MAP限制同一项目并发请求，避免代理过载；SSE连接通过CancellationToken快速切换，减少资源占用。
|
||||
- 建议
|
||||
- 根据业务峰值调整环形缓冲大小与SSE通道容量；对高频心跳事件进行节流；在清理任务中增加孤儿会话检测与阈值报警。
|
||||
|
||||
[本节为通用性能讨论，不直接分析特定文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题与定位
|
||||
- 消息丢失
|
||||
- 现象：SSE连接中偶发消息缺失。
|
||||
- 排查：检查环形缓冲是否频繁满；确认实时推送try_send失败后的告警日志；核对心跳与取消令牌是否正确传播。
|
||||
- 修复：增大环形缓冲或SSE通道容量；优化消息粒度；确保前端及时消费。
|
||||
- 会话积压
|
||||
- 现象：多个session堆积，SSE连接长时间不刷新。
|
||||
- 排查：使用message_count命令查看当前缓冲长度；检查是否存在孤儿session（无活跃映射）。
|
||||
- 修复：在清理任务中定期扫描并移除孤儿session；必要时主动调用clear命令清空缓冲。
|
||||
- 连接异常断开
|
||||
- 现象：SSE连接在发送端关闭后自然断开。
|
||||
- 排查：确认SessionWorker中发送端被drop触发recv()返回None；检查取消令牌是否被正确触发。
|
||||
- 修复：确保在新连接建立或取消时显式触发取消令牌；避免旧连接长时间占用资源。
|
||||
- 代理转发失败
|
||||
- 现象：rcoder侧SSE代理无法连接到容器SSE端点。
|
||||
- 排查：检查容器SSE URL构建与状态；关注代理连接状态码与错误事件。
|
||||
- 修复：重试策略与错误事件透传；必要时切换后端或调整网络策略。
|
||||
- 工具与建议
|
||||
- 清理任务：定期扫描孤儿session与SSE消息，移除无用数据，降低内存压力。
|
||||
- 统计与监控：利用message_count与心跳事件，结合日志级别，定位瓶颈与异常。
|
||||
- 超时与重试：在代理封装层设置合理超时，避免阻塞；对不可达后端实施指数退避重试。
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L160-L229)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L87-L180)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L106-L299)
|
||||
|
||||
## 结论
|
||||
该通信机制以Tokio通道为核心，结合环形缓冲与SSE长连接，实现了高并发场景下的低延迟与高吞吐。通过统一消息模型与严格的会话管理，确保消息有序、可追踪、可清理。在实际部署中，建议根据业务特征动态调整缓冲与通道容量，并完善监控与告警体系，以应对突发流量与异常情况。
|
||||
357
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/配置管理.md
Normal file
357
qiming-rcoder/.qoder/repowiki/zh/content/AI代理管理/配置管理.md
Normal file
@@ -0,0 +1,357 @@
|
||||
# 配置管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs)
|
||||
- [config.yml](file://config.yml)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦“代理配置管理”，围绕以下目标展开：
|
||||
- 详述 MCP 配置的加载机制与优先级规则（命令行 > 环境变量 > 配置文件），并解析 mcp_config.rs 中的配置结构体与 serde 反序列化实现。
|
||||
- 阐述 system_prompt.rs 中系统提示词的动态构建逻辑及其对 AI 行为的影响。
|
||||
- 结合 config.yml 示例，说明多代理环境下配置项的组织方式。
|
||||
- 说明配置热更新支持现状与限制，并给出敏感信息的安全存储最佳实践。
|
||||
- 提供配置错误的常见表现与诊断方法。
|
||||
|
||||
## 项目结构
|
||||
本仓库采用多 crate 的分层组织，其中与“配置管理”直接相关的关键模块如下：
|
||||
- agent_runner：提供 MCP 服务器配置与系统提示词构建能力，以及基础配置加载（命令行/环境变量/文件）。
|
||||
- rcoder：提供更丰富的 Docker 多镜像配置与环境变量覆盖能力，并负责默认配置文件生成。
|
||||
- shared_types：提供跨模块共享的配置结构（如多镜像配置、服务配置等）。
|
||||
- specs：包含设计文档，描述代理抽象层、系统提示词模板解析等高级配置能力。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "agent_runner"
|
||||
AR_CFG["utils/mcp_config.rs"]
|
||||
AR_SYS["utils/system_prompt.rs"]
|
||||
AR_APPCFG["config.rsagent_runner"]
|
||||
end
|
||||
subgraph "rcoder"
|
||||
RC_APPCFG["config.rsrcoder"]
|
||||
RC_DEFYML["rcoder_default.yml"]
|
||||
RC_ROUTER["router.rs"]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
ST_MIC["multi_image_config.rs"]
|
||||
ST_MPC["model_provider.rs"]
|
||||
end
|
||||
CFG_YML["config.yml"]
|
||||
AR_APPCFG --> CFG_YML
|
||||
RC_APPCFG --> CFG_YML
|
||||
RC_APPCFG --> RC_DEFYML
|
||||
RC_APPCFG --> ST_MIC
|
||||
AR_CFG --> CFG_YML
|
||||
AR_SYS --> CFG_YML
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L407)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L131)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
章节来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L407)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L131)
|
||||
|
||||
## 核心组件
|
||||
- MCP 服务器配置与默认集合：提供 context7、fetch 等默认 MCP 服务器的创建与组合，便于在代理启动时直接使用。
|
||||
- 系统提示词配置与构建器：定义系统提示词的结构化字段，提供构建完整提示词与包装用户提示词的能力。
|
||||
- 应用配置加载（命令行/环境变量/文件）：定义优先级顺序，按需覆盖默认配置。
|
||||
- Docker 多镜像配置：支持全局默认、服务特定配置、选择策略与缓存配置，并提供验证与摘要能力。
|
||||
- 模型提供商安全信息：对敏感字段进行脱敏展示，便于日志与调试。
|
||||
|
||||
章节来源
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L263)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L270)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L131)
|
||||
|
||||
## 架构总览
|
||||
下图展示了配置加载与生效的总体流程，包括命令行、环境变量、配置文件与默认值的优先级关系，以及 MCP 服务器与系统提示词的装配过程。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行参数"
|
||||
participant ENV as "环境变量"
|
||||
participant FILE as "配置文件"
|
||||
participant DEF as "默认配置"
|
||||
participant LOADER as "配置加载器"
|
||||
participant MCP as "MCP 服务器装配"
|
||||
participant SYS as "系统提示词构建"
|
||||
CLI->>LOADER : 传入端口/目录/代理开关等参数
|
||||
ENV->>LOADER : RCODER_PORT/RCODER_PROJECTS_DIR 等
|
||||
FILE->>LOADER : 读取 config.yml 并反序列化
|
||||
LOADER->>DEF : 初始化默认值
|
||||
LOADER->>LOADER : 优先级合并CLI > ENV > FILE > DEF
|
||||
LOADER->>MCP : 生成/覆盖 MCP 服务器配置
|
||||
LOADER->>SYS : 生成/覆盖系统提示词配置
|
||||
LOADER-->>CLI : 输出最终配置
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L86-L102)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L226-L263)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### MCP 配置加载与优先级
|
||||
- 优先级规则
|
||||
- 命令行参数优先级最高，随后是环境变量，再后是配置文件，最后是默认值。
|
||||
- agent_runner 的加载器会先加载默认配置，再尝试从配置文件读取，若失败则创建默认配置文件；随后应用环境变量覆盖；最后应用命令行参数覆盖。
|
||||
- rcoder 的加载器同样遵循相同优先级顺序，并在必要时创建默认配置文件。
|
||||
- MCP 服务器装配
|
||||
- 提供默认 MCP 服务器集合（context7、fetch 等），并在代理启动时装配到运行时。
|
||||
- 支持为不同代理类型创建不同的服务器集合，便于扩展。
|
||||
- serde 反序列化
|
||||
- 配置文件通过 serde_yaml 反序列化为结构化配置对象，字段与结构体一一对应，便于类型安全地访问配置项。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> LoadDefault["加载默认配置"]
|
||||
LoadDefault --> TryFile{"尝试读取配置文件"}
|
||||
TryFile --> |成功| ParseFile["反序列化为结构体"]
|
||||
TryFile --> |失败| CreateDefault["创建默认配置文件"]
|
||||
ParseFile --> ApplyEnv["应用环境变量覆盖"]
|
||||
CreateDefault --> ApplyEnv
|
||||
ApplyEnv --> ApplyCLI["应用命令行参数覆盖"]
|
||||
ApplyCLI --> BuildMCP["构建 MCP 服务器集合"]
|
||||
BuildMCP --> Done(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L86-L102)
|
||||
|
||||
章节来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
|
||||
### 系统提示词动态构建逻辑
|
||||
- 结构化字段
|
||||
- 基础提示词、角色定义、代码规范、开发约束、MCP 工具指导、思考要求等，均作为独立字段，便于按需组合与覆盖。
|
||||
- 动态构建
|
||||
- 提供 build_system_prompt 与 wrap_user_prompt 方法，将系统提示词与用户输入拼接为最终提示词。
|
||||
- PromptBuilder 支持自定义配置与数据源增强，便于在多代理场景下为不同代理定制提示词。
|
||||
- 对 AI 行为的影响
|
||||
- 通过严格的“框架一致性原则”“安全禁令”“路由模式要求”等，约束 AI 在前端开发中的行为边界，降低风险并提升一致性。
|
||||
- 数据源增强可引导 AI 更好地结合外部接口进行开发。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SystemPromptConfig {
|
||||
+base_prompt : String
|
||||
+role_definition : String
|
||||
+code_format_rules : String
|
||||
+development_constraints : String
|
||||
+mcp_tool_guidance : String
|
||||
+thinking_requirements : String
|
||||
+build_system_prompt() String
|
||||
+wrap_user_prompt(user_prompt : &str) String
|
||||
}
|
||||
class PromptBuilder {
|
||||
-config : SystemPromptConfig
|
||||
+new() PromptBuilder
|
||||
+with_config(config : SystemPromptConfig) PromptBuilder
|
||||
+build(user_prompt : &str) String
|
||||
+build_with_data_sources(user_prompt : &str, data_sources : &[String]) String
|
||||
}
|
||||
PromptBuilder --> SystemPromptConfig : "使用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L263)
|
||||
|
||||
章节来源
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L263)
|
||||
|
||||
### 多代理环境下的配置组织（结合 config.yml 示例）
|
||||
- config.yml 提供了主服务端口、项目工作目录、反向代理配置、Docker 多镜像配置等顶层配置。
|
||||
- rcoder_default.yml 提供了默认配置模板，包含代理服务、镜像选择策略、缓存配置、网络模式、工作目录、自动清理、容器存活时间等。
|
||||
- 多镜像配置（shared_types）支持：
|
||||
- 全局默认镜像配置（registry_prefix、image、arm64_image、amd64_image、default_image）。
|
||||
- 服务特定配置（rcoder、agent-runner），包含镜像、环境变量、命令、资源限制、卷挂载等。
|
||||
- 选择策略（ServiceOnly）与缓存配置（enabled、ttl_seconds、max_entries）。
|
||||
- 验证与摘要能力，便于在启动时校验配置有效性。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
MULTI_IMAGE_CONFIG {
|
||||
json global_defaults
|
||||
map services
|
||||
enum selection_strategy
|
||||
json cache_config
|
||||
}
|
||||
SERVICE_IMAGE_CONFIG {
|
||||
string service_type
|
||||
string image
|
||||
string arm64_image
|
||||
string amd64_image
|
||||
string default_image
|
||||
map environment
|
||||
list command
|
||||
json resource_limits
|
||||
string work_dir
|
||||
string network_mode
|
||||
list mounts
|
||||
bool enabled
|
||||
}
|
||||
MULTI_IMAGE_CONFIG ||--o{ SERVICE_IMAGE_CONFIG : "包含"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L270)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L31-L175)
|
||||
|
||||
章节来源
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L270)
|
||||
|
||||
### 配置热更新支持现状与限制
|
||||
- 现状
|
||||
- agent_runner 的配置加载器在启动时一次性读取并合并配置，未提供运行时热更新能力。
|
||||
- rcoder 的配置加载器同样在启动时读取配置文件并创建默认文件，未内置热重载逻辑。
|
||||
- 限制
|
||||
- 若需变更配置，需重启服务以重新加载配置。
|
||||
- Docker 多镜像配置在运行时未提供动态切换镜像的能力，需通过重启应用或外部编排工具实现。
|
||||
- 建议
|
||||
- 对于频繁变更的轻量配置（如端口、日志级别），可通过环境变量在不重启的情况下生效（部分配置支持）。
|
||||
- 对于核心配置（如代理服务器、系统提示词模板、Docker 镜像策略），建议通过编排工具（如容器编排平台）进行滚动更新。
|
||||
|
||||
章节来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L270)
|
||||
|
||||
### 敏感信息的安全存储最佳实践
|
||||
- 脱敏输出
|
||||
- 模型提供商配置在日志输出时自动对 API Key 进行脱敏，仅显示前后部分字符，避免泄露。
|
||||
- 环境变量与配置文件
|
||||
- 建议将敏感信息（如 API Key、数据库密码）置于环境变量中，避免直接写入配置文件。
|
||||
- 对于必须写入配置文件的敏感信息，应使用加密存储与密钥管理服务，并在运行时解密。
|
||||
- 访问控制
|
||||
- 限制配置文件与日志文件的访问权限，仅允许必要的服务账户读取。
|
||||
- 审计与监控
|
||||
- 对配置变更进行审计与告警，防止未授权修改。
|
||||
- 在日志中避免记录敏感字段，或对敏感字段进行脱敏处理。
|
||||
|
||||
章节来源
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L131)
|
||||
|
||||
### 配置错误的常见表现与诊断方法
|
||||
- 常见表现
|
||||
- 无法读取配置文件：启动时报错，提示读取失败或解析失败。
|
||||
- 端口冲突或不可用：命令行参数与环境变量冲突导致端口异常。
|
||||
- Docker 配置验证失败：镜像名称为空、缓存配置 TTL 或最大条目为 0、服务未启用等。
|
||||
- MCP 服务器装配失败：命令不可用或参数缺失。
|
||||
- 诊断方法
|
||||
- 检查配置文件是否存在与格式是否正确，关注反序列化错误信息。
|
||||
- 使用默认配置文件模板进行对比，定位字段缺失或格式问题。
|
||||
- 查看日志输出，确认最终配置（端口、项目目录、代理开关、Docker 配置摘要）是否符合预期。
|
||||
- 对 Docker 配置进行验证，确保至少启用一个服务类型，镜像名称不为空。
|
||||
- 对 MCP 服务器进行最小化验证，确保命令与参数正确。
|
||||
|
||||
章节来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L206-L270)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L346-L403)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L82-L158)
|
||||
|
||||
## 依赖关系分析
|
||||
- agent_runner 依赖 shared_types 的多镜像配置结构，用于在代理启动时装配 MCP 服务器与 Docker 服务。
|
||||
- rcoder 依赖 shared_types 的多镜像配置与模型提供商安全信息，提供默认配置文件生成与环境变量覆盖。
|
||||
- system_prompt.rs 与 mcp_config.rs 作为工具模块，被代理启动流程调用，用于构建系统提示词与装配 MCP 服务器。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
AR_CFG["agent_runner/config.rs"] --> CFG_YML["config.yml"]
|
||||
AR_SYS["agent_runner/system_prompt.rs"] --> CFG_YML
|
||||
AR_MCP["agent_runner/mcp_config.rs"] --> CFG_YML
|
||||
RC_CFG["rcoder/config.rs"] --> CFG_YML
|
||||
RC_CFG --> RC_DEF["rcoder_default.yml"]
|
||||
RC_CFG --> ST_MIC["shared_types/multi_image_config.rs"]
|
||||
ST_MIC --> ST_MPC["shared_types/model_provider.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L263)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L270)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L131)
|
||||
|
||||
## 性能考量
|
||||
- 配置加载性能
|
||||
- 配置文件读取与反序列化成本较低，建议在启动阶段一次性完成，避免在热路径重复解析。
|
||||
- Docker 配置缓存
|
||||
- 多镜像配置支持缓存（enabled、ttl_seconds、max_entries），可减少镜像选择与拉取开销。
|
||||
- 日志与调试
|
||||
- 对敏感信息进行脱敏输出，避免日志过大影响性能。
|
||||
- 在生产环境中适当降低日志级别，减少 I/O 压力。
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败
|
||||
- 检查配置文件是否存在与格式是否正确；若不存在，查看是否成功创建默认配置文件。
|
||||
- 关注反序列化错误与验证错误，逐项修正。
|
||||
- 端口异常
|
||||
- 确认命令行参数、环境变量与配置文件中的端口设置是否一致。
|
||||
- Docker 配置异常
|
||||
- 确认至少启用一个服务类型，镜像名称不为空；检查缓存配置 TTL 与最大条目是否为正数。
|
||||
- MCP 服务器异常
|
||||
- 确认命令与参数正确，必要时最小化验证（仅启用一个服务器）以定位问题。
|
||||
|
||||
章节来源
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L206-L270)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L346-L403)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L82-L158)
|
||||
|
||||
## 结论
|
||||
- 本项目通过清晰的优先级规则（命令行 > 环境变量 > 配置文件 > 默认值）实现了灵活的配置管理。
|
||||
- MCP 服务器与系统提示词的动态构建为多代理场景提供了可扩展的基础能力。
|
||||
- Docker 多镜像配置与验证机制提升了容器化部署的可控性与可观测性。
|
||||
- 建议在生产环境中优先使用环境变量存储敏感信息，并配合脱敏输出与最小权限访问策略，确保安全与合规。
|
||||
|
||||
## 附录
|
||||
- 代理抽象层设计文档中还描述了系统提示词模板解析与用户提示词包装的高级能力，可用于进一步定制不同代理的行为。
|
||||
|
||||
章节来源
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L967-L1535)
|
||||
529
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/API端点参考.md
Normal file
529
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/API端点参考.md
Normal file
@@ -0,0 +1,529 @@
|
||||
# API端点参考
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||||
- [agent_cancel_handler.rs](file://crates/rcoder/src/handler/agent_cancel_handler.rs)
|
||||
- [agent_stop_handler.rs](file://crates/rcoder/src/handler/agent_stop_handler.rs)
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [http_test.rest](file://http_test.rest)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [API概览](#api概览)
|
||||
3. [核心API端点](#核心api端点)
|
||||
4. [Pingora反向代理API](#pingora反向代理api)
|
||||
5. [请求/响应格式](#请求响应格式)
|
||||
6. [认证方法](#认证方法)
|
||||
7. [错误处理策略](#错误处理策略)
|
||||
8. [安全考虑](#安全考虑)
|
||||
9. [速率限制](#速率限制)
|
||||
10. [版本信息](#版本信息)
|
||||
11. [客户端实现指南](#客户端实现指南)
|
||||
12. [性能优化技巧](#性能优化技巧)
|
||||
13. [调试工具与监控方法](#调试工具与监控方法)
|
||||
|
||||
## 简介
|
||||
RCoder是一个基于Rust构建的现代化AI驱动开发平台，通过ACP（Agent Client Protocol）协议实现与多种AI代理的统一交互。本API文档详细描述了RCoder提供的RESTful API接口，包括HTTP方法、URL模式、请求/响应模式、认证方法等关键信息。平台提供简洁的HTTP API接口，让开发者能够轻松集成和管理AI辅助开发功能。
|
||||
|
||||
**API端点**
|
||||
- `/health`：健康检查
|
||||
- `/chat`：发送聊天消息给AI代理
|
||||
- `/agent/progress/{session_id}`：获取统一实时进度流
|
||||
- `/agent/session/cancel`：取消正在执行的任务
|
||||
- `/agent/stop`：停止当前Agent
|
||||
- `/agent/status/{project_id}`：查询Agent状态
|
||||
- `/api/docs`：Swagger UI API文档
|
||||
- `/proxy/status`、`/proxy/config`、`/proxy/stats`：Pingora代理状态查询接口
|
||||
|
||||
## API概览
|
||||
RCoder API基于Axum框架构建，提供现代化的REST API与统一的SSE（Server-Sent Events）进度流。API设计遵循RESTful原则，使用标准的HTTP方法和状态码。所有API响应都遵循统一的`HttpResult<T>`格式，包含`code`、`message`、`data`和`success`字段。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[客户端] --> B[Axum HTTP服务器]
|
||||
A --> C[Pingora代理]
|
||||
B --> D[API路由]
|
||||
B --> E[代理工作器 (LocalSet)]
|
||||
C --> F[后端: 127.0.0.1:{端口}]
|
||||
```
|
||||
|
||||
- Axum主服务负责业务API、会话管理与SSE进度流
|
||||
- Pingora独立监听代理端口，按路径前缀`/proxy/{port}/{path}`转发到指定后端
|
||||
- 两者并行运行，互不阻塞；Axum中的`/proxy/...`路由仅作为文档与重定向到Pingora
|
||||
|
||||
## 核心API端点
|
||||
|
||||
### 健康检查
|
||||
健康检查端点用于验证服务的运行状态。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/health`
|
||||
- **方法**: `GET`
|
||||
- **标签**: `system`
|
||||
- **描述**: 检查服务的健康状态
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2024-01-01T00:00:00Z",
|
||||
"service": "rcoder-ai-service"
|
||||
}
|
||||
```
|
||||
|
||||
**响应状态码**
|
||||
- `200`: 服务健康
|
||||
|
||||
**Section sources**
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
### 聊天接口
|
||||
聊天接口用于向AI代理发送消息并启动会话。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/chat`
|
||||
- **方法**: `POST`
|
||||
- **标签**: `chat`
|
||||
- **请求体类型**: `application/json`
|
||||
|
||||
**请求参数**
|
||||
| 参数 | 类型 | 必需 | 描述 | 示例 |
|
||||
|------|------|------|------|------|
|
||||
| `prompt` | string | 是 | 用户输入的提示 | "帮我写一个Rust的Hello World程序" |
|
||||
| `project_id` | string | 否 | 可选的项目ID | "test_project" |
|
||||
| `session_id` | string | 否 | 可选的会话ID，不提供则创建新会话 | "session456" |
|
||||
| `attachments` | array | 否 | 可选的附件列表 | [] |
|
||||
| `data_source_attachments` | array | 否 | 数据源附件列表 | [] |
|
||||
| `model_provider` | object | 否 | 模型配置 | 见示例 |
|
||||
| `request_id` | string | 否 | 可选的请求ID，用于追踪 | "req_123456789" |
|
||||
|
||||
**请求体示例**
|
||||
```json
|
||||
{
|
||||
"prompt": "帮我写一个Rust的Web API项目",
|
||||
"project_id": "my-project",
|
||||
"session_id": "session123",
|
||||
"attachments": [],
|
||||
"data_source_attachments": [],
|
||||
"model_provider": {
|
||||
"id": "openai_gpt4",
|
||||
"name": "openai",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-...",
|
||||
"requires_openai_auth": true,
|
||||
"default_model": "gpt-4",
|
||||
"api_protocol": "openai"
|
||||
},
|
||||
"request_id": "req_123456789"
|
||||
}
|
||||
```
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"project_id": "test_project",
|
||||
"session_id": "session456",
|
||||
"error": null,
|
||||
"request_id": "req_123456789"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应状态码**
|
||||
- `200`: 成功处理聊天请求
|
||||
- `500`: 服务器内部错误或容器服务异常
|
||||
|
||||
**Section sources**
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||||
|
||||
### 实时进度流
|
||||
通过SSE（Server-Sent Events）协议获取AI代理执行进度的实时推送。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/agent/progress/{session_id}`
|
||||
- **方法**: `GET`
|
||||
- **标签**: `agent`
|
||||
- **内容类型**: `text/event-stream`
|
||||
|
||||
**路径参数**
|
||||
| 参数 | 类型 | 必需 | 描述 | 示例 |
|
||||
|------|------|------|------|------|
|
||||
| `session_id` | string | 是 | 会话ID，用于标识特定的会话连接 | "session456" |
|
||||
|
||||
**SSE事件格式**
|
||||
```
|
||||
data: {"type": "progress", "content": "正在处理您的请求..."}
|
||||
data: {"type": "result", "content": "项目创建完成"}
|
||||
```
|
||||
|
||||
**响应头**
|
||||
- `Cache-Control`: no-cache
|
||||
- `Connection`: keep-alive
|
||||
|
||||
**响应状态码**
|
||||
- `200`: 成功建立SSE连接，开始接收实时消息
|
||||
- `404`: 未找到对应的容器
|
||||
- `500`: 建立SSE连接失败
|
||||
|
||||
**Section sources**
|
||||
- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
|
||||
|
||||
### 任务取消
|
||||
取消正在执行的AI代理任务。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/agent/session/cancel`
|
||||
- **方法**: `POST`
|
||||
- **标签**: `agent`
|
||||
|
||||
**查询参数**
|
||||
| 参数 | 类型 | 必需 | 描述 | 示例 |
|
||||
|------|------|------|------|------|
|
||||
| `project_id` | string | 是 | 项目ID，用于标识特定的项目 | "test_project" |
|
||||
| `session_id` | string | 否 | 会话ID，用于标识要取消的会话（可选） | "session456" |
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"success": true,
|
||||
"session_id": "session456"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应状态码**
|
||||
- `200`: 成功转发取消请求到容器
|
||||
- `400`: 请求参数错误
|
||||
- `404`: 未找到对应的项目或会话
|
||||
- `500`: 转发取消请求失败
|
||||
|
||||
**Section sources**
|
||||
- [agent_cancel_handler.rs](file://crates/rcoder/src/handler/agent_cancel_handler.rs#L1-L262)
|
||||
|
||||
### 停止Agent
|
||||
停止指定项目的Agent服务。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/agent/stop`
|
||||
- **方法**: `POST`
|
||||
- **标签**: `agent`
|
||||
|
||||
**查询参数**
|
||||
| 参数 | 类型 | 必需 | 描述 | 示例 |
|
||||
|------|------|------|------|------|
|
||||
| `project_id` | string | 是 | 项目ID | "test_project" |
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"success": true,
|
||||
"project_id": "test_project",
|
||||
"session_id": null,
|
||||
"message": "容器已成功销毁"
|
||||
},
|
||||
"error": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应状态码**
|
||||
- `200`: 成功销毁容器
|
||||
- `400`: 请求参数错误
|
||||
- `500`: 销毁容器失败
|
||||
|
||||
**Section sources**
|
||||
- [agent_stop_handler.rs](file://crates/rcoder/src/handler/agent_stop_handler.rs#L1-L241)
|
||||
|
||||
## Pingora反向代理API
|
||||
Pingora是项目内置的高性能反向代理，所有真实的代理请求必须发送到Pingora的监听端口，并使用路径前缀形式`/proxy/{port}/{path}`来指定目标后端端口与路径。
|
||||
|
||||
### 代理状态查询
|
||||
查询代理服务的状态。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/proxy/status`
|
||||
- **方法**: `GET`
|
||||
- **标签**: `proxy`
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"status": "running",
|
||||
"listen_port": 8080,
|
||||
"default_backend_port": 3000,
|
||||
"default_backend_host": "127.0.0.1",
|
||||
"backends": [
|
||||
{
|
||||
"port": 3000,
|
||||
"host": "127.0.0.1",
|
||||
"health_status": "healthy",
|
||||
"last_check": "2025-01-12T10:30:00Z"
|
||||
}
|
||||
],
|
||||
"load_balancer": {
|
||||
"algorithm": "round-robin",
|
||||
"health_check_enabled": true,
|
||||
"backend_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 代理统计信息
|
||||
查看代理的统计信息。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/proxy/stats`
|
||||
- **方法**: `GET`
|
||||
- **标签**: `proxy`
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"total_requests": 15420,
|
||||
"successful_requests": 15200,
|
||||
"failed_requests": 220,
|
||||
"avg_response_time_ms": 35.5,
|
||||
"active_connections": 12,
|
||||
"port_stats": [
|
||||
{
|
||||
"port": 3000,
|
||||
"requests": 8560,
|
||||
"success_rate": 0.987,
|
||||
"avg_response_time_ms": 28.3
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 代理配置查询
|
||||
查看代理的配置信息。
|
||||
|
||||
**端点信息**
|
||||
- **URL**: `/proxy/config`
|
||||
- **方法**: `GET`
|
||||
- **标签**: `proxy`
|
||||
|
||||
**成功响应示例**
|
||||
```json
|
||||
{
|
||||
"listen_port": 8080,
|
||||
"default_backend_port": 3000,
|
||||
"default_backend_host": "127.0.0.1",
|
||||
"load_balancing_algorithm": "round-robin",
|
||||
"health_check": {
|
||||
"enabled": true,
|
||||
"interval_seconds": 5,
|
||||
"timeout_seconds": 3,
|
||||
"healthy_threshold": 2,
|
||||
"unhealthy_threshold": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L195)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
|
||||
## 请求/响应格式
|
||||
所有API响应都遵循统一的`HttpResult<T>`格式，确保客户端能够一致地处理响应。
|
||||
|
||||
### 响应结构
|
||||
```json
|
||||
{
|
||||
"code": "0000",
|
||||
"message": "成功",
|
||||
"data": {},
|
||||
"tid": "trace-id",
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `code` | string | 响应代码，"0000"表示成功 |
|
||||
| `message` | string | 响应消息 |
|
||||
| `data` | object | 响应数据，成功时包含具体数据 |
|
||||
| `tid` | string | 跟踪ID，用于分布式追踪 |
|
||||
| `success` | boolean | 是否成功，根据code自动计算 |
|
||||
|
||||
### 错误响应结构
|
||||
```json
|
||||
{
|
||||
"code": "INTERNAL001",
|
||||
"message": "Internal server error",
|
||||
"data": null,
|
||||
"tid": "trace-id",
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## 认证方法
|
||||
RCoder API目前采用基于API密钥的认证方法。用户需要在请求头中包含`Authorization`字段。
|
||||
|
||||
### 认证方式
|
||||
- **类型**: Bearer Token
|
||||
- **请求头**: `Authorization: Bearer <API_KEY>`
|
||||
- **环境变量**: `ANTHROPIC_API_KEY`用于Claude代理
|
||||
|
||||
### 配置示例
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
|
||||
```
|
||||
|
||||
## 错误处理策略
|
||||
RCoder API采用统一的错误处理策略，所有错误都通过`HttpResult<T>`格式返回。
|
||||
|
||||
### 错误代码规范
|
||||
| 代码范围 | 描述 |
|
||||
|--------|------|
|
||||
| `0000` | 成功 |
|
||||
| `1xxx` | 客户端错误 |
|
||||
| `2xxx` | 服务器错误 |
|
||||
| `3xxx` | 认证错误 |
|
||||
| `4xxx` | 权限错误 |
|
||||
| `5xxx` | 内部错误 |
|
||||
|
||||
### 错误处理示例
|
||||
```json
|
||||
{
|
||||
"code": "INTERNAL001",
|
||||
"message": "Internal server error",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 安全考虑
|
||||
RCoder API在设计时充分考虑了安全性，采用了多种安全措施。
|
||||
|
||||
### 安全特性
|
||||
- **项目隔离**: 每个对话在独立的项目工作空间中进行，确保安全性
|
||||
- **容器化**: AI代理在独立的Docker容器中运行，提供进程隔离
|
||||
- **输入验证**: 所有输入参数都经过严格验证
|
||||
- **日志记录**: 所有请求和响应都记录在结构化日志中
|
||||
- **追踪ID**: 每个请求都有唯一的追踪ID，便于审计和调试
|
||||
|
||||
### 安全建议
|
||||
- 使用HTTPS保护API通信
|
||||
- 定期轮换API密钥
|
||||
- 限制API密钥的权限范围
|
||||
- 监控异常的API调用模式
|
||||
|
||||
## 速率限制
|
||||
RCoder API实施了速率限制策略，以防止滥用和确保服务质量。
|
||||
|
||||
### 速率限制规则
|
||||
- **默认限制**: 100次请求/分钟
|
||||
- **突发限制**: 200次请求/分钟（短时间）
|
||||
- **IP限制**: 每个IP地址的请求频率限制
|
||||
- **项目限制**: 每个项目ID的并发请求限制
|
||||
|
||||
### 速率限制响应
|
||||
当超过速率限制时，API会返回`429 Too Many Requests`状态码。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "RATE_LIMIT_EXCEEDED",
|
||||
"message": "请求频率超过限制",
|
||||
"data": null,
|
||||
"success": false
|
||||
}
|
||||
```
|
||||
|
||||
## 版本信息
|
||||
RCoder API遵循语义化版本控制，确保向后兼容性。
|
||||
|
||||
### 当前版本
|
||||
- **API版本**: 1.0.0
|
||||
- **协议版本**: ACP v0.4
|
||||
- **Rust版本**: 2024 Edition
|
||||
|
||||
### 版本策略
|
||||
- 主版本号变更表示不兼容的API更改
|
||||
- 次版本号变更表示向后兼容的功能新增
|
||||
- 修订号变更表示向后兼容的问题修正
|
||||
|
||||
## 客户端实现指南
|
||||
本节提供客户端实现的建议和最佳实践。
|
||||
|
||||
### HTTP客户端配置
|
||||
- 使用连接池提高性能
|
||||
- 设置合理的超时时间
|
||||
- 启用压缩（gzip）减少传输数据量
|
||||
- 实现重试机制处理临时错误
|
||||
|
||||
### SSE客户端实现
|
||||
```javascript
|
||||
const eventSource = new EventSource('/agent/progress/session123');
|
||||
eventSource.onmessage = function(event) {
|
||||
console.log('收到消息:', event.data);
|
||||
};
|
||||
eventSource.onerror = function(event) {
|
||||
console.error('SSE连接错误:', event);
|
||||
};
|
||||
```
|
||||
|
||||
### 错误处理
|
||||
- 捕获并处理所有API错误
|
||||
- 实现指数退避重试策略
|
||||
- 记录错误日志用于调试
|
||||
- 向用户提供友好的错误消息
|
||||
|
||||
## 性能优化技巧
|
||||
本节提供性能优化的建议，帮助提高API调用效率。
|
||||
|
||||
### 批量请求
|
||||
- 尽可能使用批量操作减少网络往返
|
||||
- 合并多个小请求为一个大请求
|
||||
- 使用长连接保持会话状态
|
||||
|
||||
### 缓存策略
|
||||
- 缓存频繁访问的静态数据
|
||||
- 使用ETag实现条件请求
|
||||
- 实现客户端缓存避免重复请求
|
||||
|
||||
### 并发处理
|
||||
- 使用异步调用提高吞吐量
|
||||
- 实现请求管道化
|
||||
- 使用Web Worker处理后台任务
|
||||
|
||||
## 调试工具与监控方法
|
||||
本节介绍调试和监控RCoder API的方法。
|
||||
|
||||
### 调试工具
|
||||
- **REST Client**: 使用VS Code的REST Client插件测试API
|
||||
- **curl**: 命令行工具测试API端点
|
||||
- **Postman**: 图形化API测试工具
|
||||
|
||||
### 监控方法
|
||||
- **日志监控**: 使用`RUST_LOG=debug`启用详细日志
|
||||
- **追踪系统**: 集成OpenTelemetry进行分布式追踪
|
||||
- **指标监控**: 收集API调用指标用于性能分析
|
||||
- **健康检查**: 定期调用`/health`端点验证服务状态
|
||||
|
||||
**Section sources**
|
||||
- [http_test.rest](file://http_test.rest#L1-L109)
|
||||
- [README.md](file://README.md#L1-L652)
|
||||
329
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理状态查询接口.md
Normal file
329
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理状态查询接口.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 代理状态查询接口
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文档面向 RCoder 项目的“代理状态查询”API，聚焦 GET /agent/status/{project_id} 端点，系统性说明其 HTTP 方法、路径参数、响应格式与数据模型，并深入解释条件序列化机制（仅当代理存活时才包含详细字段）。同时提供成功响应示例（含代理运行中与未运行两种状态），并阐述该接口在客户端 UI 展示与自动化监控系统中的典型使用场景与集成方式。
|
||||
|
||||
## 项目结构
|
||||
该接口位于两个模块中均有实现，分别服务于不同的运行形态：
|
||||
- agent_runner 模块：基于 ACP 代理的实现，使用全局 DashMap 存储项目与代理信息。
|
||||
- rcoder 模块：基于容器化 Agent 的实现，使用 AppState 中的项目到代理映射。
|
||||
|
||||
二者共享同一 AgentStatusResponse 数据模型与统一的 HTTP 包装格式。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "API层"
|
||||
Router["路由注册<br/>/agent/status/{project_id}"]
|
||||
HandlerAR["agent_runner 状态处理器"]
|
||||
HandlerRC["rcoder 状态处理器"]
|
||||
end
|
||||
subgraph "数据模型"
|
||||
ModelResp["AgentStatusResponse"]
|
||||
ModelProv["ModelProviderSafeInfo"]
|
||||
HttpWrap["HttpResult<T>"]
|
||||
end
|
||||
subgraph "状态存储"
|
||||
MapAR["PROJECT_AND_AGENT_INFO_MAP<br/>DashMap<String, ProjectAndAgentInfo>"]
|
||||
AppStateRC["AppState.project_and_agent_map"]
|
||||
end
|
||||
Router --> HandlerAR
|
||||
Router --> HandlerRC
|
||||
HandlerAR --> MapAR
|
||||
HandlerRC --> AppStateRC
|
||||
HandlerAR --> ModelResp
|
||||
HandlerRC --> ModelResp
|
||||
ModelResp --> ModelProv
|
||||
HandlerAR --> HttpWrap
|
||||
HandlerRC --> HttpWrap
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
|
||||
## 核心组件
|
||||
- HTTP 端点：GET /agent/status/{project_id}
|
||||
- 路由注册：在 agent_runner 模块中通过路由工厂注册
|
||||
- 处理器：
|
||||
- agent_runner：从全局 DashMap 读取项目代理信息
|
||||
- rcoder：从 AppState 中的项目到代理映射读取
|
||||
- 数据模型：AgentStatusResponse（包含项目ID、存活标志、会话ID、状态、最后活动时间、创建时间、模型提供商安全信息）
|
||||
- 条件序列化：仅当 is_alive 为 true 时，序列化 session_id、status、last_activity、created_at、model_provider
|
||||
- HTTP 包装：统一返回 HttpResult<T> 结构，包含 code、message、data、tid、success 字段
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
## 架构总览
|
||||
下图展示从客户端到处理器、再到状态存储与响应封装的整体调用链路。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum 路由"
|
||||
participant Handler as "AgentStatus 处理器"
|
||||
participant Store as "状态存储"
|
||||
participant Model as "AgentStatusResponse"
|
||||
participant Wrap as "HttpResult 包装"
|
||||
Client->>Router : "GET /agent/status/{project_id}"
|
||||
Router->>Handler : "Path(project_id)"
|
||||
Handler->>Handler : "校验 project_id"
|
||||
alt "存在代理"
|
||||
Handler->>Store : "查询项目代理信息"
|
||||
Store-->>Handler : "ProjectAndAgentInfo"
|
||||
Handler->>Model : "构造 AgentStatusResponseis_alive=true"
|
||||
Handler->>Wrap : "封装为 HttpResult.success"
|
||||
Wrap-->>Client : "200 OK JSON"
|
||||
else "不存在代理"
|
||||
Handler->>Model : "构造 AgentStatusResponseis_alive=false"
|
||||
Handler->>Wrap : "封装为 HttpResult.success"
|
||||
Wrap-->>Client : "200 OK JSON"
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 端点定义与路由
|
||||
- 方法：GET
|
||||
- 路径：/agent/status/{project_id}
|
||||
- 路由注册位置：在 agent_runner 模块的路由工厂中注册
|
||||
- OpenAPI 注解：包含参数说明、响应示例与标签
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L11-L69)
|
||||
|
||||
### 处理器逻辑（agent_runner）
|
||||
- 输入校验：去除空白字符，若为空则返回参数错误
|
||||
- 查询逻辑：从全局 DashMap 中按 project_id 获取代理信息
|
||||
- 成功分支：构造完整 AgentStatusResponse（包含 session_id、status、last_activity、created_at、model_provider）
|
||||
- 失败分支：构造简化 AgentStatusResponse（仅 project_id、is_alive=false）
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
|
||||
|
||||
### 处理器逻辑（rcoder）
|
||||
- 输入校验：同上
|
||||
- 查询逻辑：从 AppState.project_and_agent_map 获取代理信息
|
||||
- 成功分支：构造完整 AgentStatusResponse
|
||||
- 失败分支：构造简化 AgentStatusResponse
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
|
||||
|
||||
### 数据模型：AgentStatusResponse
|
||||
- 字段说明：
|
||||
- project_id：项目ID
|
||||
- is_alive：代理是否存活
|
||||
- session_id：会话ID（仅当 is_alive 为 true 时存在）
|
||||
- status：代理服务状态（仅当 is_alive 为 true 时存在）
|
||||
- last_activity：最后活动时间（仅当 is_alive 为 true 时存在）
|
||||
- created_at：创建时间（仅当 is_alive 为 true 时存在）
|
||||
- model_provider：模型提供商安全信息（仅当 is_alive 为 true 时存在）
|
||||
- 条件序列化：使用 serde 的 skip_serializing_if 仅在 Option 非空时序列化对应字段
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentStatusResponse {
|
||||
+string project_id
|
||||
+bool is_alive
|
||||
+string? session_id
|
||||
+AgentStatus? status
|
||||
+DateTime? last_activity
|
||||
+DateTime? created_at
|
||||
+ModelProviderSafeInfo? model_provider
|
||||
}
|
||||
class ModelProviderSafeInfo {
|
||||
+string id
|
||||
+string name
|
||||
+ModelApiProtocol api_protocol
|
||||
+string default_model
|
||||
}
|
||||
class ModelApiProtocol {
|
||||
<<enum>>
|
||||
+Anthropic
|
||||
+OpenAI
|
||||
}
|
||||
AgentStatusResponse --> ModelProviderSafeInfo : "可选关联"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
|
||||
|
||||
### 条件序列化机制
|
||||
- 仅当 is_alive 为 true 时，才会序列化 session_id、status、last_activity、created_at、model_provider
|
||||
- 该机制通过 serde 的 skip_serializing_if 实现，避免在代理未运行时返回冗余字段
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
|
||||
### HTTP 包装与响应格式
|
||||
- 统一包装：HttpResult<T>，包含 code、message、data、tid、success
|
||||
- 成功响应：success=true，data 为 AgentStatusResponse
|
||||
- 失败响应：success=false，data=null，error 包含错误码与消息
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
### 状态存储与生命周期
|
||||
- agent_runner：使用全局 DashMap 存储 ProjectAndAgentInfo，键为 project_id
|
||||
- rcoder：使用 AppState.project_and_agent_map 存储代理信息
|
||||
- 清理任务：在 Agent 生命周期结束时，原子性移除映射项，触发生命周期守卫 Drop，完成资源清理
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
|
||||
|
||||
## 依赖关系分析
|
||||
- 路由到处理器：路由注册将 GET /agent/status/{project_id} 绑定到处理器函数
|
||||
- 处理器到存储：处理器从全局 DashMap 或 AppState 中查询项目代理信息
|
||||
- 处理器到模型：构造 AgentStatusResponse 并通过 HttpResult 包装
|
||||
- 模型到外部：AgentStatusResponse 依赖 ModelProviderSafeInfo，后者来自 ModelProviderConfig 的安全信息转换
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Router["router.rs"] --> HandlerAR["agent_status_handler.rs (agent_runner)"]
|
||||
Router --> HandlerRC["agent_status_handler.rs (rcoder)"]
|
||||
HandlerAR --> Map["PROJECT_AND_AGENT_INFO_MAP"]
|
||||
HandlerRC --> AppState["AppState.project_and_agent_map"]
|
||||
HandlerAR --> Model["AgentStatusResponse"]
|
||||
HandlerRC --> Model
|
||||
Model --> SafeInfo["ModelProviderSafeInfo"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L25)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
|
||||
|
||||
## 性能考量
|
||||
- 查询复杂度：DashMap 的读取为 O(1) 平均复杂度，适合高频状态查询
|
||||
- 序列化开销：条件序列化避免在代理未运行时序列化冗余字段，降低响应体积
|
||||
- 并发安全：DashMap 提供无锁读取能力，减少锁竞争
|
||||
- 日志与追踪：处理器记录请求与结果，便于定位问题与性能分析
|
||||
|
||||
## 故障排查指南
|
||||
- 参数错误：当 project_id 为空时，返回 INVALID_PARAMS 错误
|
||||
- 代理不存在：返回 is_alive=false 的简化响应
|
||||
- 代理清理：确认清理任务是否正确移除映射项，避免脏读
|
||||
- 模型提供商安全信息：确认 to_safe_info 转换是否成功，避免敏感信息泄露
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L75-L84)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L79-L84)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L680)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L79-L88)
|
||||
|
||||
## 结论
|
||||
GET /agent/status/{project_id} 接口以简洁稳定的响应模型提供了代理状态查询能力。通过条件序列化与统一的 HTTP 包装，既能满足客户端 UI 的直观展示需求，也能为自动化监控系统提供一致的数据格式。在 agent_runner 与 rcoder 两套实现中，接口语义保持一致，便于跨形态部署与迁移。
|
||||
|
||||
## 附录
|
||||
|
||||
### 接口规范摘要
|
||||
- 方法：GET
|
||||
- 路径：/agent/status/{project_id}
|
||||
- 路径参数：
|
||||
- project_id：string，必填，项目ID
|
||||
- 成功响应（200 OK）：
|
||||
- data：AgentStatusResponse
|
||||
- success：true
|
||||
- 失败响应（400）：
|
||||
- error：包含错误码与消息
|
||||
- success：false
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L11-L69)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L13-L67)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
### 响应示例（JSON）
|
||||
- 代理运行中（is_alive=true）
|
||||
- data 字段包含：project_id、is_alive、session_id、status、last_activity、created_at、model_provider
|
||||
- 代理未运行（is_alive=false）
|
||||
- data 字段包含：project_id、is_alive（false），其余字段省略
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L21-L49)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L21-L51)
|
||||
|
||||
### 数据模型字段详解
|
||||
- project_id：string，项目标识
|
||||
- is_alive：bool，代理是否存活
|
||||
- session_id：string，会话ID（仅存活时存在）
|
||||
- status：枚举，代理状态（Active/Idle/Terminating，仅存活时存在）
|
||||
- last_activity：时间戳，最后活动时间（仅存活时存在）
|
||||
- created_at：时间戳，创建时间（仅存活时存在）
|
||||
- model_provider：对象，模型提供商安全信息（仅存活时存在）
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L41)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L97)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L116-L132)
|
||||
|
||||
### 使用场景与集成建议
|
||||
- 客户端 UI：
|
||||
- 轮询查询 /agent/status/{project_id}，根据 is_alive 控制按钮可用性与状态提示
|
||||
- 若 is_alive=true，显示 session_id、status、last_activity 等细节，帮助用户了解代理运行状况
|
||||
- 自动化监控：
|
||||
- 以 is_alive 作为健康指标，结合 last_activity 判断代理是否处于僵尸状态
|
||||
- 将 model_provider 信息纳入监控面板，便于追踪模型提供商与默认模型
|
||||
- 错误处理：
|
||||
- 对 400 参数错误进行明确提示，引导用户修正 project_id
|
||||
- 对 5xx 内部错误通过 HttpResult.error 的 code 与 message 进行统一处理
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [crates/agent_runner/src/handler/agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L75-L84)
|
||||
- [crates/rcoder/src/handler/agent_status_handler.rs](file://crates/rcoder/src/handler/agent_status_handler.rs#L79-L84)
|
||||
305
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理进度流接口.md
Normal file
305
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/代理进度流接口.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 代理进度流接口
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [crates/shared_types/src/grpc/agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向 RCoder 项目的“代理进度流”接口，聚焦于 GET /agent/progress/{session_id} 的 Server-Sent Events（SSE）实现。该接口提供实时的 AI 任务执行进度更新，涵盖代码生成、文件操作等事件类型；同时说明 SSE 文本流格式、事件类型分类、客户端重连机制，以及 session_id 的生成与有效期管理策略，并给出 JavaScript 客户端示例的对接思路与最佳实践。
|
||||
|
||||
## 项目结构
|
||||
- 该接口在两个服务中均有实现：
|
||||
- agent_runner：直接消费内部会话缓存，推送统一的 UnifiedSessionMessage。
|
||||
- rcoder：作为代理层，将外部容器的 SSE 流透传给客户端。
|
||||
- 路由注册位于 agent_runner 的路由文件中，暴露 /agent/progress/{session_id}。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Agent Runner 服务"
|
||||
R["路由注册<br/>/agent/progress/{session_id}"]
|
||||
H1["SSE处理器<br/>agent_session_notification"]
|
||||
C["会话缓存<br/>SessionCache/SessionData"]
|
||||
end
|
||||
subgraph "Shared Types"
|
||||
M["UnifiedSessionMessage<br/>统一消息模型"]
|
||||
end
|
||||
R --> H1
|
||||
H1 --> C
|
||||
C --> M
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
|
||||
## 核心组件
|
||||
- SSE 处理器：负责建立 SSE 连接、发送心跳、将消息事件化并推送。
|
||||
- 会话缓存：维护每个 session_id 的消息通道与取消令牌，支持新连接覆盖旧连接。
|
||||
- 统一消息模型：将不同类型的会话更新统一为 UnifiedSessionMessage，便于前端解析。
|
||||
- 代理层（rcoder）：当需要透传外部容器的 SSE 时，将容器端 SSE 流透传至客户端。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
|
||||
|
||||
## 架构总览
|
||||
SSE 进度流的总体交互如下：
|
||||
- 客户端发起 GET /agent/progress/{session_id} 建立 SSE 连接。
|
||||
- 服务端根据 session_id 获取或创建会话数据，建立消息通道与取消令牌。
|
||||
- 服务端立即发送一次心跳事件，随后周期性发送心跳，并将收到的统一消息转换为 SSE 事件推送。
|
||||
- 若连接被取消（如新连接建立或用户取消），旧连接会自然断开。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "SSE处理器"
|
||||
participant Cache as "会话缓存"
|
||||
participant Worker as "会话工作线程"
|
||||
participant Model as "统一消息模型"
|
||||
Client->>Handler : "GET /agent/progress/{session_id}"
|
||||
Handler->>Cache : "创建/获取 SessionData 并建立新连接"
|
||||
Handler->>Client : "发送初始心跳事件"
|
||||
Worker-->>Handler : "推送 UnifiedSessionMessage"
|
||||
Handler->>Client : "按事件类型发送事件如 prompt_start/prompt_end/tool_call 等"
|
||||
Handler->>Client : "周期性发送心跳事件"
|
||||
Handler-->>Client : "连接被取消/断开时终止推送"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L67-L103)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### SSE 文本流格式与事件类型
|
||||
- 文本流遵循标准 SSE 格式，每条消息包含事件类型与数据两部分。
|
||||
- 事件类型与 UnifiedSessionMessage 的映射关系：
|
||||
- prompt_start：会话开始
|
||||
- prompt_end：会话结束（含结束原因）
|
||||
- agent_message_chunk：Agent 文本响应片段
|
||||
- agent_thought_chunk：Agent 思考过程片段
|
||||
- tool_call：工具调用通知
|
||||
- tool_call_update：工具调用状态更新
|
||||
- available_commands_update：可用命令更新
|
||||
- current_mode_update：当前模式更新
|
||||
- heartbeat：心跳消息
|
||||
- 数据体为 JSON，结构遵循 UnifiedSessionMessage，包含 session_id、message_type、sub_type、data、timestamp。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L165-L246)
|
||||
|
||||
### SSE 处理器（agent_runner）
|
||||
- 建立新连接：为每个 session_id 创建新的 SessionData 并插入缓存，确保每次连接全新开始。
|
||||
- 发送心跳：首次立即发送一次心跳事件，随后以固定间隔（如 30 秒）发送心跳。
|
||||
- 事件分发：将收到的 UnifiedSessionMessage 按 message_type 与 sub_type 转换为对应的事件名并推送。
|
||||
- 取消与断开：监听取消令牌与通道关闭，及时退出循环并记录日志。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["建立连接"]) --> NewSession["创建/获取 SessionData 并建立新连接"]
|
||||
NewSession --> SendHB["发送初始心跳事件"]
|
||||
SendHB --> Loop{"循环接收消息"}
|
||||
Loop --> |收到消息| MapEvent["按消息类型映射事件名"]
|
||||
MapEvent --> Yield["yield SSE 事件"]
|
||||
Yield --> Loop
|
||||
Loop --> |取消令牌触发| Close["断开连接"]
|
||||
Loop --> |通道关闭| Close
|
||||
Close --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
### 会话缓存与连接管理
|
||||
- SessionData：持有命令通道、当前发送器与取消令牌，支持创建新连接并设置当前发送器与取消令牌。
|
||||
- SessionWorker：维护环形缓冲区，按需缓冲非心跳消息，并将消息实时推送到当前发送器。
|
||||
- 项目-会话映射：ensure_project_session 确保同一项目仅对应一个活跃会话，必要时清理旧会话数据。
|
||||
- 主动关闭：close_current_connection 主动触发取消令牌并丢弃发送器，促使接收端感知断开。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SessionData {
|
||||
+new(max_size)
|
||||
+create_new_connection(buffer_size)
|
||||
+push_message(message)
|
||||
+close_current_connection()
|
||||
}
|
||||
class SessionWorker {
|
||||
+spawn(max_size, command_rx, current_sender, current_cancel)
|
||||
+run()
|
||||
}
|
||||
class UnifiedSessionMessage {
|
||||
+session_id
|
||||
+message_type
|
||||
+sub_type
|
||||
+data
|
||||
+timestamp
|
||||
}
|
||||
SessionData --> SessionWorker : "spawn"
|
||||
SessionWorker --> UnifiedSessionMessage : "推送"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L103)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
|
||||
### 代理层 SSE 透传（rcoder）
|
||||
- 当需要代理外部容器的 SSE 时，rcoder 会根据 session_id 查找对应容器，建立到容器 SSE 端点的连接，并将容器的 SSE 流透传给客户端。
|
||||
- 透传逻辑按双换行符切分事件，解析 event/data 字段，避免重复 data: 前缀，然后直接透传事件。
|
||||
- 错误处理：容器连接失败或读取失败时，发送 error 事件并记录日志。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Proxy as "rcoder SSE代理"
|
||||
participant Container as "容器SSE端点"
|
||||
Client->>Proxy : "GET /agent/progress/{session_id}"
|
||||
Proxy->>Container : "建立到容器SSE的连接"
|
||||
Container-->>Proxy : "SSE事件流按双换行符分隔"
|
||||
Proxy->>Proxy : "解析event/data并去重"
|
||||
Proxy-->>Client : "透传SSE事件"
|
||||
Proxy-->>Client : "错误时发送error事件"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L299)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
|
||||
|
||||
### session_id 的生成与有效期管理
|
||||
- 生成机制：在聊天处理流程中，当创建项目会话状态时，会为项目设置 session_id，并更新最后活动时间。项目-会话映射通过 ensure_project_session 保证唯一性。
|
||||
- 有效期管理：服务端未对 session_id 设置硬性过期时间；连接断开或取消会触发清理。若需要过期控制，可在业务侧增加会话超时策略（例如定期清理长时间无活动的会话）。
|
||||
- 会话切换：当同一项目的新会话建立时，旧会话数据会被清理，确保不会跨会话污染。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L272-L302)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L80-L95)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L282-L354)
|
||||
|
||||
### 客户端重连机制与最佳实践
|
||||
- 心跳检测：服务端会周期性发送 heartbeat 事件，前端应基于心跳判断连接是否仍活跃。
|
||||
- 自动重连：建议实现指数退避的自动重连策略，避免频繁重试造成压力。
|
||||
- 事件处理：根据事件类型（prompt_start/prompt_end/tool_call 等）更新 UI 状态，避免阻塞主线程。
|
||||
- 错误处理：监听连接错误与 SessionPromptEnd 中的错误信息，向用户反馈并引导重试或取消。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
### 与 gRPC 订阅接口的关系
|
||||
- 项目中提供了基于 gRPC 的订阅进度流接口（subscribe_progress），可替代传统的 /agent/progress/{session_id} SSE 接口。
|
||||
- 若采用 gRPC 方案，前端需使用 gRPC 客户端订阅进度流，事件类型与数据结构保持一致。
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/grpc/agent.rs](file://crates/shared_types/src/grpc/agent.rs#L232-L236)
|
||||
|
||||
## 依赖分析
|
||||
- 路由依赖：/agent/progress/{session_id} 在 agent_runner 的路由中注册。
|
||||
- 处理器依赖：SSE 处理器依赖会话缓存与统一消息模型。
|
||||
- 代理层依赖：rcoder 的代理处理器依赖容器映射与 SSE 透传逻辑。
|
||||
- 项目-会话映射：通过 ensure_project_session 保证同一项目仅有一个活跃会话。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Router["路由"] --> SSEHandler["SSE处理器"]
|
||||
SSEHandler --> SessionCache["会话缓存"]
|
||||
SessionCache --> UnifiedMsg["统一消息模型"]
|
||||
ProxyHandler["rcoder代理处理器"] --> ContainerSSE["容器SSE端点"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
|
||||
- [crates/shared_types/src/model/agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L16-L30)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L299)
|
||||
|
||||
## 性能考虑
|
||||
- 心跳频率：默认 30 秒一次，可根据网络状况调整，避免过多心跳占用带宽。
|
||||
- 缓冲策略：SessionWorker 使用环形缓冲区，非心跳消息优先缓冲，心跳消息直通，减少延迟。
|
||||
- 取消与断开：通过 CancellationToken 与通道关闭快速退出，避免资源泄漏。
|
||||
- 透传效率：rcoder 代理层按双换行符切分事件，避免重复解析，提高透传效率。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L395-L475)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L173-L222)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L156-L262)
|
||||
|
||||
## 故障排查指南
|
||||
- 404 未找到容器：当 session_id 对应的活跃容器不存在时，返回 404 并携带错误码。
|
||||
- 建立 SSE 连接失败：容器 SSE 连接失败或读取失败时，发送 error 事件并记录错误。
|
||||
- 连接被取消：当新连接建立或用户取消任务时，旧连接会主动断开。
|
||||
- 心跳缺失：若长时间未收到 heartbeat，应触发重连流程。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L106-L153)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L259)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L400-L477)
|
||||
|
||||
## 结论
|
||||
RCoder 的代理进度流接口通过 SSE 提供了稳定、低延迟的实时进度推送能力。其核心在于：
|
||||
- 统一消息模型与事件类型映射，便于前端解析；
|
||||
- 会话缓存与取消令牌机制，确保连接可控与资源回收；
|
||||
- 代理层透传能力，满足多容器场景；
|
||||
- 心跳与断开策略，保障连接健康与稳定性。
|
||||
|
||||
建议在前端实现自动重连与指数退避、基于事件类型的状态机更新，并结合业务侧的会话超时策略，构建健壮的实时进度体验。
|
||||
|
||||
## 附录
|
||||
|
||||
### API 定义与示例
|
||||
- 端点：GET /agent/progress/{session_id}
|
||||
- 内容类型：text/event-stream
|
||||
- 响应：SSE 事件流，事件类型与数据体见“SSE 文本流格式与事件类型”。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
### JavaScript 客户端对接要点（概念性说明）
|
||||
- 使用浏览器内置 EventSource API 建立连接，监听不同事件类型并更新 UI。
|
||||
- 实现自动重连：监听 error 与 close 事件，采用指数退避策略重连。
|
||||
- 心跳检测：收到 heartbeat 事件后刷新心跳计时器，超时则触发重连。
|
||||
- 错误处理：监听 error 事件与 SessionPromptEnd 中的错误信息，向用户反馈并引导操作。
|
||||
|
||||
[本节为概念性说明，不直接分析具体源码文件]
|
||||
305
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/健康检查接口.md
Normal file
305
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/健康检查接口.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 健康检查接口
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [README.md](file://README.md)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向RCoder项目的健康检查API，聚焦GET /health端点的HTTP方法、URL模式、响应格式与行为语义。文档解释该接口如何用于系统状态监控与负载均衡器健康探测，给出成功与失败场景的JSON结构说明，阐述服务启动时的验证作用，并提供在Kubernetes等容器编排系统中的集成方式、curl示例与客户端实现要点，以及性能监控与超时处理的最佳实践。
|
||||
|
||||
## 项目结构
|
||||
- 健康检查端点在两个主要服务中均可用：
|
||||
- rcoder主服务：提供HTTP API与健康检查
|
||||
- agent_runner服务：同样提供健康检查端点
|
||||
- 路由注册与OpenAPI文档由各服务的router模块负责
|
||||
- 服务启动时绑定端口并启动HTTP服务器，健康检查端点即随服务启动而可用
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder主服务"
|
||||
RMain["main.rs<br/>启动HTTP服务器"]
|
||||
RRouter["router.rs<br/>路由注册 /health"]
|
||||
RHandler["health_handler.rs<br/>健康检查处理器"]
|
||||
end
|
||||
subgraph "agent_runner服务"
|
||||
AMain["main.rs<br/>启动HTTP服务器"]
|
||||
ARouter["router.rs<br/>路由注册 /health"]
|
||||
AHandler["health_handler.rs<br/>健康检查处理器"]
|
||||
end
|
||||
RMain --> RRouter --> RHandler
|
||||
AMain --> ARouter --> AHandler
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
|
||||
## 核心组件
|
||||
- 健康检查处理器
|
||||
- 路径：/health
|
||||
- 方法：GET
|
||||
- 响应：JSON对象，包含status、timestamp、service字段
|
||||
- 路由注册
|
||||
- rcoder：在router.rs中将GET /health绑定到处理器
|
||||
- agent_runner：同理
|
||||
- 服务启动
|
||||
- main.rs中创建Axum Router并绑定TCP监听，健康检查端点随服务启动而可用
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
|
||||
## 架构总览
|
||||
健康检查端点作为系统健康状态的快速探测入口，既可用于内部监控，也可供外部负载均衡器/编排系统进行存活探针。在rcoder中，健康检查端点位于HTTP API层，不依赖业务逻辑，因此其可用性直接反映服务进程的启动与HTTP服务器的就绪状态。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant LB as "负载均衡器/探针"
|
||||
participant HTTP as "HTTP服务器(Axum)"
|
||||
participant Router as "路由(/health)"
|
||||
participant Handler as "健康检查处理器"
|
||||
LB->>HTTP : GET /health
|
||||
HTTP->>Router : 分发请求
|
||||
Router->>Handler : 调用处理器
|
||||
Handler-->>HTTP : 返回JSON响应
|
||||
HTTP-->>LB : 200 OK 或错误码
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 健康检查端点定义与响应
|
||||
- HTTP方法与URL模式
|
||||
- 方法：GET
|
||||
- 路径：/health
|
||||
- 响应结构
|
||||
- status：字符串，表示服务健康状态
|
||||
- timestamp：UTC时间戳
|
||||
- service：服务标识
|
||||
- 成功响应
|
||||
- HTTP状态码：200 OK
|
||||
- 响应体：包含上述字段的JSON对象
|
||||
- 失败响应
|
||||
- 当HTTP服务器未启动或路由未注册时，可能出现非200的状态码（例如5xx）
|
||||
- 由于健康检查处理器不进行数据库或其他外部依赖的深度校验，一般不会出现500错误；若出现，通常表示服务启动异常或中间件/路由配置问题
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["请求进入 /health"]) --> Route["匹配路由 /health"]
|
||||
Route --> HandlerCall["调用健康检查处理器"]
|
||||
HandlerCall --> BuildResp["构造响应对象(status, timestamp, service)"]
|
||||
BuildResp --> ReturnOK["返回 200 OK + JSON"]
|
||||
ReturnOK --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
### 服务启动与健康检查可用性
|
||||
- rcoder主服务
|
||||
- main.rs中创建Axum Router并绑定监听端口，随后启动HTTP服务器
|
||||
- 启动日志明确打印了API端点信息，包括GET /health
|
||||
- agent_runner服务
|
||||
- 同样在main.rs中绑定监听端口并启动HTTP服务器
|
||||
- 路由注册中包含GET /health
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as "main.rs"
|
||||
participant Router as "router.rs"
|
||||
participant Server as "HTTP服务器(Axum)"
|
||||
Main->>Router : create_router(state)
|
||||
Router-->>Main : 返回Router
|
||||
Main->>Server : 绑定监听端口并启动
|
||||
Server-->>Main : 服务就绪
|
||||
Note over Main,Server : /health 端点随服务启动而可用
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
|
||||
### 在Kubernetes等容器编排系统中的集成
|
||||
- 健康检查配置
|
||||
- Dockerfile中定义了HEALTHCHECK指令，使用curl对http://localhost:PORT/health进行探测
|
||||
- 默认端口为8087（来自rcoder_default.yml中的port字段）
|
||||
- 推荐配置
|
||||
- 在Kubernetes中，使用livenessProbe/readinessProbe指向同一端点
|
||||
- 建议将探针超时时间设置为小于探测周期，避免长时间阻塞导致误判
|
||||
- 若使用代理（Pingora），建议直接对代理监听端口进行探测，或在代理层暴露健康检查端点
|
||||
|
||||
章节来源
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L10-L12)
|
||||
|
||||
### curl命令示例与客户端实现指南
|
||||
- curl示例
|
||||
- GET http://localhost:8087/health
|
||||
- 客户端实现要点
|
||||
- 使用HTTP客户端库发起GET请求
|
||||
- 解析JSON响应，读取status、timestamp、service字段
|
||||
- 对于200以外的状态码，视为不健康
|
||||
- 设置合理的超时时间，避免阻塞
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L229-L242)
|
||||
|
||||
### 健康检查与负载均衡器健康探测
|
||||
- 健康检查处理器不进行外部依赖（如数据库、代理后端）的深度校验，仅反映服务进程与HTTP服务器的就绪状态
|
||||
- 负载均衡器可将其作为存活探针，结合探针超时、重试次数与周期进行综合判断
|
||||
- 若需要对代理后端进行健康探测，可参考代理健康检查配置（见下一节）
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
## 依赖关系分析
|
||||
- 路由到处理器的依赖
|
||||
- rcoder与agent_runner分别在各自的router.rs中注册GET /health
|
||||
- 处理器在各自handler/health_handler.rs中实现
|
||||
- 服务启动依赖
|
||||
- main.rs负责创建Router并启动HTTP服务器
|
||||
- 代理健康检查（额外能力）
|
||||
- rcoder的ProxyConfig包含HealthCheckConfig
|
||||
- Pingora服务实现健康检查循环，定期对后端端口进行连通性探测
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RMain["rcoder/main.rs"] --> RRouter["rcoder/router.rs"]
|
||||
RRouter --> RHandler["rcoder/handler/health_handler.rs"]
|
||||
AMain["agent_runner/main.rs"] --> ARouter["agent_runner/router.rs"]
|
||||
ARouter --> AHandler["agent_runner/handler/health_handler.rs"]
|
||||
Config["rcoder/config.rs<br/>ProxyConfig/HealthCheckConfig"] --> PingoraSvc["pingora-proxy/service.rs<br/>健康检查循环"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L66)
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L52)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
## 性能考量
|
||||
- 健康检查处理器为纯内存计算，开销极低，适合高频探测
|
||||
- 探测周期与超时设置建议
|
||||
- 周期：根据业务SLA设定，常见为10-30秒
|
||||
- 超时：建议小于周期，避免探针阻塞影响其他请求
|
||||
- 在Kubernetes中，合理设置initialDelaySeconds、periodSeconds、timeoutSeconds与failureThreshold，避免误判
|
||||
- 若使用代理（Pingora），可利用其健康检查能力对后端进行更细粒度的探测
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L124-L134)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L591)
|
||||
|
||||
## 故障排查指南
|
||||
- 无法访问/health
|
||||
- 检查服务是否已启动并绑定到预期端口
|
||||
- 确认防火墙与网络策略允许访问
|
||||
- 响应非200
|
||||
- 查看服务日志，定位路由或中间件异常
|
||||
- 确认路由注册是否正确
|
||||
- 健康检查频繁失败
|
||||
- 检查探针超时与周期设置
|
||||
- 在Kubernetes中适当增大failureThreshold，避免抖动
|
||||
- 代理健康检查相关
|
||||
- 确认ProxyConfig中的health_check.enabled、interval_seconds、timeout_seconds配置
|
||||
- 检查后端端口连通性
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L222-L265)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L52-L98)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
## 结论
|
||||
GET /health端点为RCoder提供了轻量、可靠的健康状态探测入口，适用于服务启动验证与负载均衡器健康探测。其简单实现确保了低开销与高可用性。在生产环境中，建议结合探针超时、周期与重试策略，以及必要时启用代理健康检查，以获得更全面的健康状态视图。
|
||||
|
||||
## 附录
|
||||
|
||||
### API定义与示例
|
||||
- 端点：GET /health
|
||||
- 响应示例（成功）
|
||||
- 状态码：200 OK
|
||||
- 响应体：包含status、timestamp、service字段的JSON对象
|
||||
- 响应示例（失败）
|
||||
- 状态码：非200（例如5xx）
|
||||
- 响应体：错误信息（由HTTP服务器或中间件决定）
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [crates/agent_runner/src/handler/health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
- [README.md](file://README.md#L229-L242)
|
||||
|
||||
### 集成与最佳实践
|
||||
- curl示例
|
||||
- curl -X GET http://localhost:8087/health
|
||||
- Kubernetes集成
|
||||
- 使用livenessProbe/readinessProbe指向同一端点
|
||||
- HEALTHCHECK已在Dockerfile中定义，可直接复用
|
||||
- 超时与周期
|
||||
- 建议周期10-30秒，超时小于周期
|
||||
- failureThreshold根据稳定性需求调整
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L229-L242)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L296-L304)
|
||||
269
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/反向代理接口.md
Normal file
269
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/反向代理接口.md
Normal file
@@ -0,0 +1,269 @@
|
||||
# 反向代理接口
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
|
||||
- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/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/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向RCoder项目的反向代理API，聚焦/proxy/{port}/{path}端点的路由机制与请求转发逻辑，说明其如何将请求代理到AI代理在特定端口上运行的服务；解释端口管理机制与请求/响应的透明转发过程；提供curl示例，展示如何通过该接口访问代理的Web界面或API；说明与Pingora反向代理组件的集成方式，以及在处理WebSocket连接时的特殊考虑。
|
||||
|
||||
## 项目结构
|
||||
RCoder项目包含两个主要服务：
|
||||
- rcoder服务：提供聊天、会话管理、代理状态查询等API，并在启动时可选择启用Pingora反向代理服务。
|
||||
- agent_runner服务：同样可启用Pingora代理服务，用于代理AI代理容器对外暴露的端口。
|
||||
|
||||
反向代理API在两个服务中均通过Axum路由注册，核心处理逻辑位于各自的handler模块中；而真正的代理转发由Pingora库实现。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder服务"
|
||||
RRouter["Axum路由<br/>/proxy/*"]
|
||||
RHandler["代理处理器<br/>proxy_handler_api.rs"]
|
||||
RState["AppState<br/>包含Pingora服务引用"]
|
||||
end
|
||||
subgraph "agent_runner服务"
|
||||
ARouter["Axum路由<br/>/proxy/*"]
|
||||
AHandler["代理处理器<br/>proxy_handler_api.rs"]
|
||||
AState["AppState<br/>包含Pingora服务引用"]
|
||||
end
|
||||
subgraph "Pingora代理"
|
||||
PServer["PingoraServerManager<br/>启动与管理"]
|
||||
PService["PingoraProxyService<br/>端口代理实现"]
|
||||
PPort["PortProxy<br/>请求过滤/选择上游/响应过滤"]
|
||||
end
|
||||
RRouter --> RHandler --> RState
|
||||
ARouter --> AHandler --> AState
|
||||
RState --> PService
|
||||
AState --> PService
|
||||
PServer --> PService
|
||||
PService --> PPort
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L224-L354)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
|
||||
|
||||
## 核心组件
|
||||
- 路由注册：在rcoder与agent_runner的router中分别注册/proxy/status、/proxy/stats、/proxy/config、/proxy/{port}、/proxy/{port}/{*path}等端点。
|
||||
- 代理处理器：提供状态、统计、配置查询；以及将请求重定向到Pingora监听端口的处理器。
|
||||
- Pingora服务：负责实际的请求转发、负载均衡、健康检查、指标统计与上游选择。
|
||||
- 配置与启动：在rcoder主程序中根据配置启动Pingora服务器管理器，并将服务引用注入到AppState，供代理处理器读取。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
|
||||
## 架构总览
|
||||
/proxy/{port}/{path}端点的请求流如下：
|
||||
- 客户端请求到达rcoder/agent_runner的Axum路由。
|
||||
- 若代理未启用，返回“服务不可用”错误。
|
||||
- 若启用，处理器将请求临时重定向至Pingora监听端口的对应路径（/proxy/{port}或/ proxy/{port}/{path}），由Pingora完成实际转发。
|
||||
- Pingora根据请求路径提取目标端口，动态发现后端主机，选择上游Peer，重写请求头与URI，转发到后端服务，并记录指标。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant AX as "Axum路由"
|
||||
participant H as "代理处理器"
|
||||
participant PS as "Pingora服务"
|
||||
participant PR as "PortProxy"
|
||||
participant BE as "后端服务"
|
||||
C->>AX : "GET /proxy/{port}/{path}"
|
||||
AX->>H : "匹配路由并进入处理器"
|
||||
H->>PS : "读取配置/状态如需"
|
||||
H-->>C : "307 临时重定向到 Pingora 监听端口"
|
||||
C->>PS : "再次请求 /proxy/{port} 或 /proxy/{port}/{path}"
|
||||
PS->>PR : "upstream_peer/过滤请求/响应"
|
||||
PR->>PR : "提取端口/重写URI/选择上游"
|
||||
PR->>BE : "转发到后端服务"
|
||||
BE-->>PR : "返回响应"
|
||||
PR-->>PS : "记录指标/计时"
|
||||
PS-->>C : "返回最终响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 路由与控制器
|
||||
- rcoder与agent_runner各自在router中注册/proxy/*端点，包括状态、统计、配置查询与端口代理。
|
||||
- 代理处理器对/proxy/{port}与/proxy/{port}/{*path}进行处理：若代理未启用则返回错误；否则构造临时重定向到Pingora监听端口的Location头。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
|
||||
### Pingora代理实现
|
||||
- PingoraProxyService：维护后端映射、负载均衡算法、健康检查、指标统计与上下文跟踪。
|
||||
- PortProxy：实现ProxyHttp，负责：
|
||||
- 上游请求过滤：重写Host、添加X-Forwarded-Proto与X-Load-Balancer头；重写URI，移除/proxy/{port}前缀并保留查询参数。
|
||||
- 上游Peer选择：从请求路径提取目标端口；若端口不在后端映射中则动态添加到默认主机；选择HttpPeer。
|
||||
- 响应过滤：记录响应状态与耗时、更新指标、减少活跃连接数。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L224-L354)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L356-L409)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
|
||||
### 端口管理机制
|
||||
- rcoder服务中的PortManager负责容器端口分配与回收，避免端口冲突，确保代理后端端口可用。
|
||||
- Pingora侧通过动态后端映射实现“按需发现”，首次遇到某端口时自动将其加入后端列表。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L300-L333)
|
||||
|
||||
### WebSocket连接的特殊考虑
|
||||
- Pingora库基于Cloudflare Pingora，支持HTTP/1.1与HTTP/2，理论上可处理升级为WebSocket的请求。
|
||||
- 由于rcoder与agent_runner的代理处理器采用临时重定向的方式，客户端需要遵循重定向并保持连接；具体WebSocket行为取决于上游后端服务是否支持升级。
|
||||
- 若上游服务不支持升级，或客户端未正确处理重定向，可能出现握手失败或连接中断。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L58)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
|
||||
### 请求/响应透明转发流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入处理器"]) --> CheckEnabled{"代理已启用？"}
|
||||
CheckEnabled --> |否| ReturnErr["返回服务不可用错误"]
|
||||
CheckEnabled --> |是| BuildLoc["构造重定向到 Pingora 监听端口的 Location"]
|
||||
BuildLoc --> Redirect["返回307临时重定向"]
|
||||
Redirect --> Pingora["Pingora 接收请求"]
|
||||
Pingora --> FilterReq["上游请求过滤<br/>重写Host/URI/添加头部"]
|
||||
FilterReq --> SelectPeer["选择上游Peer<br/>提取端口/动态后端"]
|
||||
SelectPeer --> Forward["转发到后端服务"]
|
||||
Forward --> RespFilter["响应过滤<br/>记录指标/计时"]
|
||||
RespFilter --> Done(["返回响应"])
|
||||
ReturnErr --> End(["结束"])
|
||||
Done --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
|
||||
|
||||
## 依赖关系分析
|
||||
- rcoder/agent_runner的路由依赖于代理处理器模块；代理处理器依赖于AppState中的Pingora服务引用。
|
||||
- Pingora服务依赖于Pingora库的ProxyHttp trait实现，通过包装器将内部PortProxy暴露为Pingora服务。
|
||||
- rcoder主程序在启动时根据配置创建PingoraServerManager并启动服务器，同时将服务引用注入AppState。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Router["Axum路由"] --> Handler["代理处理器"]
|
||||
Handler --> AppState["AppState"]
|
||||
AppState --> PingoraSvc["PingoraProxyService"]
|
||||
PingoraSvc --> PortProxy["PortProxy"]
|
||||
PingoraMgr["PingoraServerManager"] --> PingoraSvc
|
||||
Main["rcoder主程序"] --> PingoraMgr
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
|
||||
## 性能考量
|
||||
- 负载均衡：Pingora支持轮询与一致性哈希两种算法，默认启用轮询；可根据配置切换。
|
||||
- 健康检查：Pingora内置TCP健康检查，周期性探测后端连通性，支持超时与阈值配置。
|
||||
- 指标统计：提供总请求数、成功率、平均响应时间、每端口统计与活跃连接数等指标，便于监控与优化。
|
||||
- 动态后端：首次遇到新端口时自动加入后端映射，避免预配置开销，提升弹性。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L509-L596)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L143-L155)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
## 故障排查指南
|
||||
- 代理未启用：当AppState中未注入Pingora服务或配置为空时，/proxy/*接口返回“服务不可用”错误。确认rcoder主程序已按配置启动Pingora服务。
|
||||
- 端口提取失败：若请求路径不符合/proxy/{port}格式，将回退到默认后端端口。检查客户端是否使用正确的路径格式。
|
||||
- 后端未发现：Pingora在首次遇到端口时会动态添加默认主机；若后端主机不可达，健康检查会标记为不健康。检查后端服务状态与网络连通性。
|
||||
- 重定向链路：代理处理器返回307临时重定向，客户端需跟随重定向并保持连接（尤其WebSocket场景）。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L31-L114)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L31-L114)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L300-L333)
|
||||
|
||||
## 结论
|
||||
RCoder的反向代理API通过Axum路由与Pingora代理实现解耦：路由层负责接入与状态查询，Pingora负责高性能转发与负载均衡。/proxy/{port}/{path}端点采用临时重定向到Pingora监听端口的方式，使客户端透明地访问任意端口的后端服务。结合动态后端与健康检查，系统具备良好的弹性与可观测性。
|
||||
|
||||
## 附录
|
||||
|
||||
### curl示例
|
||||
以下示例展示如何通过/proxy接口访问不同后端服务（请将localhost替换为实际部署地址与端口）：
|
||||
- 访问默认后端健康检查
|
||||
- curl "http://localhost:3000/proxy/8080/health"
|
||||
- 访问特定端口的API
|
||||
- curl "http://localhost:3000/proxy/3000/api/users"
|
||||
- 访问代理状态
|
||||
- curl "http://localhost:3000/proxy/status"
|
||||
- 访问代理统计
|
||||
- curl "http://localhost:3000/proxy/stats"
|
||||
- 访问代理配置
|
||||
- curl "http://localhost:3000/proxy/config"
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L173-L193)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L173-L193)
|
||||
|
||||
### 与Pingora集成要点
|
||||
- 启动方式：rcoder主程序创建PingoraServerManager并启动服务器，监听配置中的listen_port。
|
||||
- 服务注入：将Pingora服务引用注入AppState，代理处理器可读取配置与指标。
|
||||
- 路由规则：Pingora内部处理/proxy/{port}与/proxy/{port}/{path}，移除前缀并重写URI，转发到后端。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
|
||||
290
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/聊天接口.md
Normal file
290
qiming-rcoder/.qoder/repowiki/zh/content/API端点参考/聊天接口.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 聊天接口
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [crates/shared_types/src/model/app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [http_test.rest](file://http_test.rest)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文档面向RCoder项目的聊天API，聚焦于POST /chat端点的HTTP方法、请求头、请求体结构与响应格式；详解ChatPrompt数据模型中project_id、messages、model等字段的用途与约束；说明系统如何处理异步AI代理执行，并返回包含success、session_id和result的ChatResponse；涵盖请求验证错误（400）、服务器内部错误（500）等HTTP状态码的处理策略；提供完整的curl示例与错误码参考（如VALIDATION001、LOCAL001、INTERNAL001）；并阐述与SSE进度流的关联机制。
|
||||
|
||||
## 项目结构
|
||||
RCoder采用双服务架构：
|
||||
- rcoder服务：对外暴露统一入口，负责容器编排与请求转发，内部将请求转发至agent_runner容器服务。
|
||||
- agent_runner服务：容器内AI代理执行与会话管理，负责实际的聊天处理、并发控制、SSE实时推送。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Client["客户端"] --> R["rcoder服务<br/>/chat 转发"]
|
||||
R --> AR["agent_runner服务<br/>/chat 执行"]
|
||||
AR --> SSE["SSE 实时进度流<br/>/agent/progress/{session_id}"]
|
||||
AR --> Cache["会话缓存与消息队列"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- POST /chat端点：接收聊天请求，校验参数，转发到容器内agent_runner服务，返回统一HttpResult包装的ChatResponse。
|
||||
- ChatPrompt数据模型：承载project_id、project_path、session_id、prompt、attachments、data_source_attachments、agent_type、service_type、request_id、model_provider等字段。
|
||||
- ChatResponse数据模型：返回project_id、session_id、error、request_id。
|
||||
- SSE进度流：通过/agent/progress/{session_id}以Server-Sent Events推送实时更新。
|
||||
- 错误处理：统一HttpResult结构，包含code、message、data、tid、success字段；AppError用于Axum错误映射。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L109-L170)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L220)
|
||||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||||
- [crates/shared_types/src/model/app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 架构总览
|
||||
POST /chat的端到端流程如下：
|
||||
- 客户端向rcoder服务发送POST /chat。
|
||||
- rcoder服务根据project_id获取或创建容器，构建ProjectAndContainerInfo并缓存。
|
||||
- rcoder服务将原始请求体直接转发到容器内的agent_runner服务的/chat端点。
|
||||
- agent_runner服务执行聊天处理：校验参数、生成/清理会话、构建ChatPrompt并投递到本地任务通道。
|
||||
- agent_runner服务返回HttpResult<ChatResponse>；rcoder服务解析并返回统一格式给客户端。
|
||||
- 客户端通过/agent/progress/{session_id}建立SSE连接，接收实时进度。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant R as "rcoder服务"
|
||||
participant AR as "agent_runner服务"
|
||||
participant SSE as "SSE流"
|
||||
C->>R : POST /chat
|
||||
R->>R : 根据project_id获取/创建容器
|
||||
R->>AR : 转发原始JSON到 /chat
|
||||
AR->>AR : 参数校验/会话管理/构建ChatPrompt
|
||||
AR-->>R : HttpResult<ChatResponse>
|
||||
R-->>C : 统一HttpResult包装响应
|
||||
C->>SSE : GET /agent/progress/{session_id}
|
||||
AR-->>SSE : 推送实时更新
|
||||
SSE-->>C : 事件流prompt_start/prompt_end/...
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L136-L221)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### HTTP端点：POST /chat
|
||||
- 方法与路径：POST /chat
|
||||
- 请求头：
|
||||
- Content-Type: application/json
|
||||
- 请求体结构（ChatRequest）：
|
||||
- prompt: 字符串，必填（agent_runner侧进一步校验非空）
|
||||
- project_id: 字符串，可选；若未提供，rcoder会生成并回填
|
||||
- session_id: 字符串，可选；若未提供，agent_runner会创建新会话
|
||||
- attachments: 数组，可选；支持多种附件类型
|
||||
- data_source_attachments: 字符串数组，可选；用于传递外部数据源信息
|
||||
- model_provider: 模型提供商配置对象，可选
|
||||
- request_id: 字符串，可选；若未提供，agent_runner会生成
|
||||
- 响应格式：统一HttpResult包装
|
||||
- 成功：HttpResult.success(data=ChatResponse)
|
||||
- 失败：HttpResult.error(code, message)
|
||||
- 状态码：
|
||||
- 200：成功
|
||||
- 400：请求参数错误（如prompt为空）
|
||||
- 409：Agent正在执行任务，禁止并发请求
|
||||
- 500：服务器内部错误
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L109-L170)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L220)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||||
|
||||
### ChatPrompt数据模型
|
||||
- 字段说明与约束：
|
||||
- project_id: 项目标识，决定工作目录./project_workspace/{project_id}
|
||||
- project_path: 项目工作目录路径
|
||||
- session_id: 可选；若未提供，agent_runner会创建新会话并返回
|
||||
- prompt: 用户输入的提示词
|
||||
- attachments: 可选附件列表
|
||||
- data_source_attachments: 可选数据源附件（JSON字符串数组）
|
||||
- agent_type: 代理类型
|
||||
- service_type: 服务类型（强制要求，"rcoder"或"agent-runner"）
|
||||
- request_id: 可选请求ID
|
||||
- model_provider: 可选模型提供商配置
|
||||
- 重要约束：
|
||||
- service_type不可为空
|
||||
- 若未提供project_id，系统会生成并创建工作目录
|
||||
- 若未提供session_id，系统会创建新会话
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
|
||||
### ChatResponse数据模型
|
||||
- 字段说明：
|
||||
- project_id: 项目ID
|
||||
- session_id: 会话ID
|
||||
- error: 可选错误信息
|
||||
- request_id: 可选请求ID
|
||||
- 返回内容：
|
||||
- rcoder服务会将agent_runner返回的ChatResponse封装为HttpResult.success(data=ChatResponse)再返回客户端
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L290-L320)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L390-L430)
|
||||
|
||||
### 异步AI代理执行与SSE进度流
|
||||
- 并发控制：agent_runner在收到请求时检查Agent状态，若Agent处于Active则拒绝并发请求，返回409错误。
|
||||
- 会话管理：若显式提供了session_id，则移除该session；否则清理该项目下所有旧session，确保全新开始。
|
||||
- 本地任务投递：构建ChatPrompt并投递到本地任务通道，等待执行结果。
|
||||
- SSE推送：agent_runner通过/agent/progress/{session_id}以SSE推送实时事件，如prompt_start、prompt_end、agent消息分块、工具调用等。
|
||||
- rcoder服务的SSE代理：rcoder服务也提供SSE代理，将容器内的SSE流透传给客户端。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["收到 /chat 请求"]) --> CheckPrompt["校验 prompt 非空"]
|
||||
CheckPrompt --> PromptValid{"prompt有效？"}
|
||||
PromptValid -- 否 --> Return400["返回 400 错误"]
|
||||
PromptValid -- 是 --> CheckAgent["检查 Agent 状态"]
|
||||
CheckAgent --> AgentActive{"Agent 正在执行？"}
|
||||
AgentActive -- 是 --> Return409["返回 409 错误"]
|
||||
AgentActive -- 否 --> CleanSession["清理旧会话如有"]
|
||||
CleanSession --> BuildPrompt["构建 ChatPrompt"]
|
||||
BuildPrompt --> SendTask["投递本地任务"]
|
||||
SendTask --> WaitResult["等待执行结果"]
|
||||
WaitResult --> ResultOk{"执行成功？"}
|
||||
ResultOk -- 否 --> ReturnError["返回错误响应"]
|
||||
ResultOk -- 是 --> ReturnSuccess["返回 ChatResponse"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L320)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L207-L299)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L197-L257)
|
||||
|
||||
### 错误码与HTTP状态码
|
||||
- 400 请求参数错误
|
||||
- 示例：prompt为空
|
||||
- 错误码示例：VALIDATION001
|
||||
- 409 并发冲突
|
||||
- Agent正在执行任务，禁止并发请求
|
||||
- 错误码示例：1010
|
||||
- 500 服务器内部错误
|
||||
- rcoder服务转发失败或解析失败
|
||||
- 错误码示例：INTERNAL001
|
||||
- 本地执行失败
|
||||
- 本地任务通道发送失败
|
||||
- 错误码示例：LOCAL001
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L130-L168)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L311-L318)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L90-L107)
|
||||
- [crates/shared_types/src/model/http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L75)
|
||||
|
||||
### curl示例
|
||||
- 发送聊天请求并获取会话ID
|
||||
- curl -X POST http://localhost:8087/chat -H "Content-Type: application/json" -d '{"prompt":"请帮我写一个 Rust 的 Hello World 程序","agent_type":"codex"}'
|
||||
- 建立SSE进度流
|
||||
- curl -N -H "Accept: text/event-stream" http://localhost:3000/agent/progress/{session_id}
|
||||
- 取消会话（可选）
|
||||
- curl -X POST http://localhost:3000/agent/session/cancel?project_id={project_id}&session_id={session_id}
|
||||
|
||||
章节来源
|
||||
- [http_test.rest](file://http_test.rest#L1-L109)
|
||||
|
||||
## 依赖关系分析
|
||||
- rcoder服务依赖agent_runner服务进行实际AI代理执行；通过容器URL直连转发。
|
||||
- agent_runner服务依赖会话缓存与消息队列，保证SSE推送的可靠与有序。
|
||||
- 共享类型（shared_types）定义了ChatPrompt、ChatResponse、HttpResult等跨服务通用模型。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RC["rcoder服务"] --> AR["agent_runner服务"]
|
||||
AR --> ST["shared_types<br/>ChatPrompt/ChatResponse/HttpResult"]
|
||||
AR --> SC["会话缓存与消息队列"]
|
||||
RC --> SSE["SSE代理"]
|
||||
AR --> SSE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L260-L320)
|
||||
- [crates/shared_types/src/model/chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [crates/shared_types/src/model/chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [crates/agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L197-L257)
|
||||
|
||||
## 性能考量
|
||||
- 容器编排与状态缓存：rcoder服务使用DashMap缓存ProjectAndContainerInfo，降低重复创建成本。
|
||||
- SSE推送：agent_runner使用SessionData与mpsc通道，避免阻塞主线程；SSE代理层透传事件，减少额外编码开销。
|
||||
- 并发限制：通过Agent状态检查避免并发请求导致的资源竞争与性能抖动。
|
||||
- 日志与追踪：HttpResult包含tid（trace_id），便于链路追踪与问题定位。
|
||||
|
||||
## 故障排查指南
|
||||
- 400错误（参数无效）
|
||||
- 检查请求体中prompt是否为空
|
||||
- 检查service_type是否正确设置
|
||||
- 409错误（Agent正在执行任务）
|
||||
- 等待当前任务完成后重试
|
||||
- 或者使用/agent/session/cancel取消当前任务
|
||||
- 500错误（服务器内部错误）
|
||||
- rcoder服务转发失败或解析失败
|
||||
- 检查容器服务日志与网络连通性
|
||||
- LOCAL001（本地执行失败）
|
||||
- 本地任务通道发送失败
|
||||
- 检查agent_runner服务状态与资源占用
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L130-L168)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L311-L318)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
|
||||
|
||||
## 结论
|
||||
RCoder的聊天API通过rcoder服务与agent_runner服务的协同，实现了从请求接入、容器编排、AI代理执行到SSE实时进度推送的完整链路。统一的HttpResult与严格的参数校验、并发控制保障了系统的稳定性与可观测性。开发者可通过curl快速验证接口，并结合SSE流实现实时反馈。
|
||||
|
||||
## 附录
|
||||
|
||||
### API定义摘要
|
||||
- POST /chat
|
||||
- 请求体：ChatRequest
|
||||
- 成功响应：HttpResult.success(ChatResponse)
|
||||
- 失败响应：HttpResult.error(code, message)
|
||||
- 状态码：200、400、409、500
|
||||
- GET /agent/progress/{session_id}
|
||||
- 响应：SSE事件流（prompt_start、prompt_end、agent消息分块、工具调用等）
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
401
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/与主应用集成.md
Normal file
401
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/与主应用集成.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 与主应用集成
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/rcoder/src/lib.rs](file://crates/rcoder/src/lib.rs)
|
||||
- [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/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件面向 rcoder 主应用与 pingora-proxy 的集成场景，系统化阐述 rcoder 如何通过依赖注入的方式整合 pingora-proxy，涵盖模块初始化、服务注册与运行时协调机制；同时说明 lib.rs 中公开 API 的职责边界与在主应用中的调用方式；并分析异步任务通信、错误传播与资源管理策略。最后给出系统上下文图，展示代理服务与 HTTP API、AI 代理管理模块之间的交互关系。
|
||||
|
||||
## 项目结构
|
||||
rcoder 作为主应用，通过 Cargo 工作区组织各子 crate。其中：
|
||||
- rcoder：主应用入口、HTTP 路由与处理器、配置加载、代理服务集成点
|
||||
- pingora-proxy：基于 Cloudflare Pingora 的高性能反向代理库
|
||||
- shared_types：跨模块共享的数据模型与 gRPC 类型
|
||||
- agent_runner、docker_manager、acp_adapter、claude-code-agent、codex-acp-agent：AI 代理与容器管理相关模块
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 主应用"
|
||||
RCMain["rcoder/src/main.rs"]
|
||||
RCLib["rcoder/src/lib.rs"]
|
||||
RCConf["rcoder/src/config.rs"]
|
||||
RCRouter["rcoder/src/router.rs"]
|
||||
RCProxyAPI["rcoder/src/handler/proxy_api.rs"]
|
||||
RCProxyHandler["rcoder/src/handler/proxy_handler_api.rs"]
|
||||
end
|
||||
subgraph "pingora-proxy 库"
|
||||
PPLib["pingora-proxy/src/lib.rs"]
|
||||
PPService["pingora-proxy/src/service.rs"]
|
||||
PPServer["pingora-proxy/src/server.rs"]
|
||||
PPServerMgr["pingora-proxy/src/pingora_server.rs"]
|
||||
end
|
||||
subgraph "共享类型"
|
||||
SharedTypes["shared_types/src/lib.rs"]
|
||||
end
|
||||
RCMain --> RCLib
|
||||
RCMain --> RCConf
|
||||
RCMain --> RCRouter
|
||||
RCRouter --> RCProxyAPI
|
||||
RCRouter --> RCProxyHandler
|
||||
RCMain --> PPLib
|
||||
PPLib --> PPService
|
||||
PPLib --> PPServer
|
||||
PPLib --> PPServerMgr
|
||||
RCLib --> SharedTypes
|
||||
RCMain --> SharedTypes
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L272)
|
||||
- [crates/rcoder/src/lib.rs](file://crates/rcoder/src/lib.rs#L1-L24)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L84)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L195)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L120)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L155)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L106)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 核心组件
|
||||
- rcoder 主应用
|
||||
- 配置加载与 CLI 参数解析
|
||||
- HTTP 服务器启动与优雅关闭
|
||||
- 代理服务启动与运行时协调
|
||||
- 应用状态 AppState 注入到路由
|
||||
- pingora-proxy 库
|
||||
- 代理服务 PingoraProxyService 与端口代理 PortProxy
|
||||
- 服务器管理 PingoraServerManager 与 PingoraServerRunner
|
||||
- 健康检查与指标采集
|
||||
- 共享类型 shared_types
|
||||
- 统一的 Agent/Chat/Session 等数据模型
|
||||
- 多镜像配置与服务类型定义
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L272)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L120)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
|
||||
## 架构总览
|
||||
rcoder 主应用通过依赖注入的方式将 Pingora 代理服务注入到 AppState 中，随后在路由层提供代理状态、统计与配置查询接口；同时在主 HTTP 服务器上提供 /proxy 路由的重定向能力，最终由 Pingora 独立进程完成真正的代理转发。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Main as "rcoder 主应用"
|
||||
participant Router as "Axum 路由"
|
||||
participant State as "AppState"
|
||||
participant PingoraMgr as "PingoraServerManager"
|
||||
participant PingoraSvc as "PingoraProxyService"
|
||||
participant PingoraSrv as "Pingora 服务器"
|
||||
Client->>Main : "POST /chat 或 /agent/*"
|
||||
Main->>Router : "创建路由并注入 AppState"
|
||||
Router->>State : "读取配置与代理服务引用"
|
||||
Note over Router,State : "代理状态/统计/配置接口通过 PingoraSvc 查询"
|
||||
Client->>Main : "GET /proxy/{port}[/{path}]"
|
||||
Main->>Router : "匹配 /proxy 路由"
|
||||
Router->>State : "校验代理启用状态"
|
||||
Router-->>Client : "307/308 临时重定向至 Pingora 监听端口"
|
||||
Client->>PingoraSrv : "请求 /proxy/{port}[/{path}]"
|
||||
PingoraSrv->>PingoraSvc : "选择后端/重写路径/记录指标"
|
||||
PingoraSvc-->>Client : "上游响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L209)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L91)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### rcoder 主应用初始化与依赖注入
|
||||
- 配置加载
|
||||
- 优先从配置文件加载，支持命令行参数与环境变量覆盖
|
||||
- 代理配置可按需启用，包含监听端口、默认后端端口、后端主机与健康检查
|
||||
- 代理服务启动
|
||||
- 通过 PingoraServerManager.new 创建服务实例并启动
|
||||
- 将 PingoraProxyService 的 Arc 引用注入 AppState，供路由查询状态/统计/配置
|
||||
- 启动健康检查循环（若启用）
|
||||
- HTTP 服务器
|
||||
- 绑定主服务端口，注册 API 路由与 Swagger UI
|
||||
- 优雅关闭：捕获信号，清理容器，等待代理服务完成
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动 rcoder"]) --> LoadCfg["加载配置<br/>CLI/文件/环境变量"]
|
||||
LoadCfg --> InitProxy{"是否启用代理?"}
|
||||
InitProxy --> |是| BuildSvc["PingoraServerManager::new<br/>创建 PingoraProxyService"]
|
||||
BuildSvc --> StartHC["启动健康检查循环"]
|
||||
StartHC --> RunHTTP["启动 Axum HTTP 服务器"]
|
||||
InitProxy --> |否| RunHTTP
|
||||
RunHTTP --> Graceful["优雅关闭：信号处理/容器清理/等待代理完成"]
|
||||
Graceful --> End(["退出"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L265)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L109)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L91)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L272)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
|
||||
|
||||
### rcoder 路由与代理 API
|
||||
- 路由组织
|
||||
- API 路由：/health、/chat、/agent/* 等
|
||||
- 代理 API 路由：/proxy/status、/proxy/stats、/proxy/config、/proxy、/proxy/{port}、/proxy/{port}/{*path}
|
||||
- 代理状态/统计/配置
|
||||
- 通过 AppState.pingora_service 查询 PingoraProxyService 的状态、指标与配置
|
||||
- 返回结构体定义于 proxy_api.rs，配合 OpenAPI 文档
|
||||
- 代理重定向
|
||||
- /proxy/{port} 与 /proxy/{port}/{*path} 返回 307/308 临时重定向到 Pingora 监听端口
|
||||
- 保持路径与查询参数，最终由 Pingora 服务器完成代理
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant R as "Axum 路由"
|
||||
participant S as "AppState"
|
||||
participant P as "PingoraProxyService"
|
||||
C->>R : "GET /proxy/3000/api/users"
|
||||
R->>S : "校验代理启用状态"
|
||||
alt 代理启用
|
||||
R-->>C : "307/308 重定向到 http : //127.0.0.1 : {listen_port}/proxy/3000/api/users"
|
||||
C->>P : "Pingora 服务器处理请求"
|
||||
P-->>C : "上游响应"
|
||||
else 代理未启用
|
||||
R-->>C : "503 代理服务未启用"
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L195)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L434)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L195)
|
||||
|
||||
### pingora-proxy 服务与服务器管理
|
||||
- PingoraProxyService
|
||||
- 维护后端映射、负载均衡算法、健康检查与指标
|
||||
- 提供 create_pingora_proxy 创建 PortProxy 实例
|
||||
- 提供健康检查循环与快照查询
|
||||
- ProxyServer/PingoraServerManager
|
||||
- ProxyServer 提供便捷的 start 与配置访问
|
||||
- PingoraServerManager 封装 Pingora 服务器启动、监听与优雅关闭
|
||||
- 通过 ProxyServiceWrapper 实现 Pingora 的 ProxyHttp trait
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PingoraProxyService {
|
||||
+config : ProxyConfig
|
||||
+backends : HashMap<u16, String>
|
||||
+use_round_robin : bool
|
||||
+metrics : ProxyMetrics
|
||||
+health_map : HashMap<u16, HealthInfo>
|
||||
+create_pingora_proxy() PortProxy
|
||||
+start_health_check_loop(interval, timeout)
|
||||
+health_snapshot() HashMap<u16, HealthInfo>
|
||||
}
|
||||
class PortProxy {
|
||||
+backends : Arc<RwLock<HashMap<u16, String>>>
|
||||
+default_backend_port : u16
|
||||
+backend_host : String
|
||||
+use_round_robin : bool
|
||||
+metrics : Arc<ProxyMetrics>
|
||||
+upstream_peer()
|
||||
+upstream_request_filter()
|
||||
+response_filter()
|
||||
}
|
||||
class ProxyServer {
|
||||
+config : ProxyConfig
|
||||
+service : Arc<PingoraProxyService>
|
||||
+start() Result
|
||||
+service() Arc<PingoraProxyService>
|
||||
}
|
||||
class PingoraServerManager {
|
||||
+config : ProxyConfig
|
||||
+service : Arc<PingoraProxyService>
|
||||
+start() Result
|
||||
+stop() Result
|
||||
+service() Arc<PingoraProxyService>
|
||||
}
|
||||
PingoraProxyService --> PortProxy : "创建"
|
||||
ProxyServer --> PingoraProxyService : "持有"
|
||||
PingoraServerManager --> PingoraProxyService : "持有"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L155)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L106)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L372)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
|
||||
### lib.rs 公共 API 与主应用调用方式
|
||||
- rcoder/src/lib.rs
|
||||
- 重新导出 rcoder 的公共模块与 shared_types 类型
|
||||
- 使主应用与外部模块可直接使用统一的类型与代理模块入口
|
||||
- 主应用调用方式
|
||||
- 在 rcoder/src/main.rs 中通过 use rcoder::* 导入 re-export 的类型
|
||||
- 通过 use pingora_proxy::{PingoraServerManager, ProxyConfig} 使用代理库
|
||||
- 将 PingoraProxyService 的 Arc 引用注入 AppState，供路由层使用
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/lib.rs](file://crates/rcoder/src/lib.rs#L1-L24)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L19-L26)
|
||||
|
||||
### 异步任务通信、错误传播与资源管理
|
||||
- 异步任务通信
|
||||
- 代理服务器以独立 Tokio 任务运行，PingoraServerManager 通过 oneshot 通道接收关闭信号
|
||||
- rcoder 主应用通过广播通道接收 Ctrl+C/SIGTERM，触发优雅关闭
|
||||
- 错误传播
|
||||
- 代理库定义 ProxyError，统一包装配置、网络、后端、端口提取与请求处理错误
|
||||
- rcoder 主应用在代理启动失败时记录错误并终止
|
||||
- 资源管理
|
||||
- 代理服务指标与健康状态采用原子计数与读写锁保护，避免竞争
|
||||
- 优雅关闭阶段清理容器与等待代理任务完成，确保资源释放
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L353-L451)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L67-L91)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L164-L191)
|
||||
|
||||
## 依赖关系分析
|
||||
- 工作区成员
|
||||
- rcoder、agent_runner、shared_types、docker_manager、acp_adapter、claude-code-agent、codex-acp-agent、pingora-proxy
|
||||
- 关键依赖
|
||||
- pingora = { version = "0.6", features = ["lb"] }：启用负载均衡特性
|
||||
- tokio = { version = "1.48", features = ["full"] }：异步运行时
|
||||
- axum = { version = "0.8", features = ["http2", "query", "tracing", "ws"] }：HTTP 服务器
|
||||
- utoipa/utoipa-swagger-ui：OpenAPI 文档
|
||||
- opentelemetry/tracing-opentelemetry：遥测与链路追踪
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cargo["Cargo.toml 工作区"] --> RC["rcoder"]
|
||||
Cargo --> PR["pingora-proxy"]
|
||||
Cargo --> ST["shared_types"]
|
||||
RC --> PR
|
||||
RC --> ST
|
||||
PR --> Pingora["pingora 0.6 + lb"]
|
||||
RC --> Tokio["tokio full"]
|
||||
RC --> Axum["axum 0.8 + features"]
|
||||
RC --> OpenAPI["utoipa + swagger-ui"]
|
||||
RC --> OTel["opentelemetry + tracing-opentelemetry"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 性能考量
|
||||
- 负载均衡与健康检查
|
||||
- 默认使用轮询算法，可切换为一致性哈希（Ketama）；健康检查周期与超时可配置
|
||||
- 指标采集
|
||||
- 统计总请求数、成功率、平均响应时间、按端口聚合指标与活跃连接数
|
||||
- I/O 与并发
|
||||
- Pingora 基于异步 I/O，支持 HTTP/1.1 与 HTTP/2；rcoder 主应用使用 Tokio 全特性
|
||||
- 路由与重定向
|
||||
- /proxy 路由返回 307/308 重定向，避免在主应用中做实际代理转发，降低主应用压力
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L143-L155)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
|
||||
## 故障排查指南
|
||||
- 代理服务未启用
|
||||
- 现象：/proxy/* 接口返回 503
|
||||
- 排查：确认配置中 proxy_config 是否启用；检查 rcoder 启动日志中代理启动信息
|
||||
- 代理启动失败
|
||||
- 现象：启动时报错并终止
|
||||
- 排查：查看 rcoder 启动日志中的错误信息；检查端口占用与网络连通性
|
||||
- 健康检查异常
|
||||
- 现象：后端健康状态不稳定
|
||||
- 排查：调整健康检查间隔与超时；确认后端服务可达；查看健康快照
|
||||
- 优雅关闭问题
|
||||
- 现象：SIGINT/SIGTERM 后资源未完全释放
|
||||
- 排查：确认广播通道信号是否正确接收；检查容器清理逻辑与代理服务等待
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L353-L451)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L91)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
|
||||
## 结论
|
||||
rcoder 通过依赖注入将 pingora-proxy 的 PingoraProxyService 注入到 AppState，实现了代理服务与主应用的解耦。rcoder 主应用负责配置加载、HTTP 服务器与优雅关闭，而代理的实际转发由 Pingora 独立服务器完成。该设计具备良好的扩展性与可观测性，支持动态后端、健康检查与指标统计，满足多服务场景下的统一代理需求。
|
||||
|
||||
## 附录
|
||||
- 系统上下文图（代理服务与 HTTP API、AI 代理管理模块的交互）
|
||||
- rcoder 主应用提供 /chat、/agent/* 等接口，AI 代理管理模块负责会话与任务生命周期
|
||||
- /proxy/* 接口用于代理到任意端口的后端服务，最终由 Pingora 服务器完成转发
|
||||
- 代理状态、统计与配置接口通过 AppState.pingora_service 查询
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 主应用"
|
||||
API["HTTP API (/chat,/agent/*)"]
|
||||
ProxyAPI["代理 API (/proxy/*)"]
|
||||
State["AppState<br/>包含 PingoraProxyService 引用"]
|
||||
end
|
||||
subgraph "AI 代理管理模块"
|
||||
Agents["Agent Runner / Container Manager"]
|
||||
end
|
||||
subgraph "Pingora 代理"
|
||||
PService["PingoraProxyService"]
|
||||
PServer["Pingora 服务器"]
|
||||
end
|
||||
API --> State
|
||||
ProxyAPI --> State
|
||||
State --> PService
|
||||
PService --> PServer
|
||||
Agents -.-> API
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
380
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
Normal file
380
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 反向代理服务
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“反向代理服务”的架构文档，聚焦于基于 Cloudflare Pingora 的高性能反向代理子系统，涵盖其高阶设计、架构模式、系统边界、组件交互、数据流与集成模式。文档解释技术决策、权衡与约束，并给出基础设施要求、可扩展性考虑、部署拓扑、安全与监控、灾难恢复等横切关注点。目标读者既包括工程实践者，也包括对系统架构感兴趣的非技术读者。
|
||||
|
||||
## 项目结构
|
||||
该仓库采用多 Crate 的工作区组织，反向代理能力主要集中在 crates/pingora-proxy 中，而业务服务（如 rcoder、agent_runner）在启动时可按需启用 Pingora 代理服务，并通过统一的路由对外暴露代理状态与统计信息。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "工作区"
|
||||
A["crates/pingora-proxy<br/>反向代理库"]
|
||||
B["crates/rcoder<br/>主服务"]
|
||||
C["crates/agent_runner<br/>代理运行器"]
|
||||
D["crates/shared_types<br/>共享类型"]
|
||||
E["crates/docker_manager<br/>Docker 管理"]
|
||||
F["crates/acp_adapter<br/>ACP 适配"]
|
||||
G["crates/claude-code-agent<br/>Claude 代码代理"]
|
||||
H["crates/codex-acp-agent<br/>Codex ACP 代理"]
|
||||
end
|
||||
subgraph "基础设施"
|
||||
I["docker/Dockerfile<br/>镜像构建"]
|
||||
J["docker/docker-compose.yml<br/>编排"]
|
||||
K["config.yml<br/>服务配置"]
|
||||
end
|
||||
B --> A
|
||||
C --> A
|
||||
A --> D
|
||||
B --> E
|
||||
C --> E
|
||||
B --> F
|
||||
C --> G
|
||||
C --> H
|
||||
I --> J
|
||||
J --> B
|
||||
J --> C
|
||||
K --> B
|
||||
K --> C
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
## 核心组件
|
||||
- Pingora 代理库（crates/pingora-proxy）
|
||||
- 提供基于 Cloudflare Pingora 的高性能反向代理能力，支持路径与查询参数两种端口提取方式、动态后端管理、负载均衡、健康检查与指标统计。
|
||||
- Pingora 服务器管理器（PingoraServerManager）
|
||||
- 负责启动/停止 Pingora 服务器，绑定监听端口，注入代理服务，处理优雅关闭。
|
||||
- 代理服务与代理实现（PingoraProxyService / PortProxy）
|
||||
- 实现 Pingora 的 ProxyHttp trait，负责上游请求过滤、路径重写、端口提取、后端选择、响应过滤与指标统计。
|
||||
- 配置模块（ProxyConfig）
|
||||
- 定义监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与日志开关等。
|
||||
- 业务服务（rcoder / agent_runner）
|
||||
- 在启动时根据配置决定是否启用 Pingora 代理服务；通过统一路由暴露代理状态、统计与配置查询接口；并提供健康检查与优雅关闭。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L372)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)
|
||||
|
||||
## 架构总览
|
||||
反向代理服务采用“库+管理器+业务服务”的分层架构：
|
||||
- 库层：提供代理能力与指标统计，支持动态后端与健康检查。
|
||||
- 管理器层：封装 Pingora 服务器生命周期，负责监听、服务注册与优雅关闭。
|
||||
- 业务层：在 rcoder/agent_runner 中按需启用代理服务，提供统一的代理 API 与健康检查。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "业务服务"
|
||||
RC["rcoder 主服务"]
|
||||
AR["agent_runner 服务"]
|
||||
end
|
||||
subgraph "反向代理子系统"
|
||||
PM["PingoraServerManager<br/>服务器管理器"]
|
||||
PS["PingoraProxyService<br/>代理服务"]
|
||||
PP["PortProxy<br/>代理实现"]
|
||||
PC["ProxyConfig<br/>配置"]
|
||||
end
|
||||
subgraph "外部系统"
|
||||
U["客户端/浏览器"]
|
||||
BE["后端服务<br/>任意端口"]
|
||||
end
|
||||
U --> PM
|
||||
PM --> PS
|
||||
PS --> PP
|
||||
PP --> BE
|
||||
RC --> PM
|
||||
AR --> PM
|
||||
RC --> PC
|
||||
AR --> PC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 组件一：Pingora 服务器管理器（PingoraServerManager）
|
||||
- 职责
|
||||
- 创建并启动 Pingora 服务器，绑定监听端口，注入代理服务。
|
||||
- 提供优雅关闭机制，通过 oneshot 通道接收关闭信号并终止服务器。
|
||||
- 关键行为
|
||||
- 通过 Server::new 与 bootstrap 初始化服务器。
|
||||
- 使用 http_proxy_service 注册代理服务，add_tcp 绑定监听地址。
|
||||
- 通过 ProxyServiceWrapper 实现 Pingora 的 ProxyHttp trait，委托给 PortProxy。
|
||||
- 与业务服务集成
|
||||
- rcoder/agent_runner 在启动时创建 PingoraServerManager 并在后台任务中运行，同时将服务引用注入 AppState，用于读取代理指标。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PingoraServerManager {
|
||||
-config : ProxyConfig
|
||||
-service : Arc<PingoraProxyService>
|
||||
-shutdown_tx : Option<oneshot : : Sender>
|
||||
+new(config) PingoraServerManager
|
||||
+start() Result
|
||||
+stop() Result
|
||||
+service() Arc<PingoraProxyService>
|
||||
}
|
||||
class ProxyServiceWrapper {
|
||||
-inner : Arc<PortProxy>
|
||||
+upstream_peer(...)
|
||||
+upstream_request_filter(...)
|
||||
+response_filter(...)
|
||||
}
|
||||
PingoraServerManager --> ProxyServiceWrapper : "注册代理服务"
|
||||
ProxyServiceWrapper --> PortProxy : "委托实现"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
### 组件二：代理服务与代理实现（PingoraProxyService / PortProxy）
|
||||
- 职责
|
||||
- PingoraProxyService：维护后端映射、负载均衡算法、指标与健康状态缓存；提供后端增删查、健康检查循环与指标快照。
|
||||
- PortProxy：实现 Pingora 的 ProxyHttp trait，完成请求过滤、路径重写、端口提取、后端选择与响应过滤。
|
||||
- 数据流
|
||||
- 请求进入：从请求头提取端口（路径优先，其次查询参数），若端口不在映射中则动态添加默认主机。
|
||||
- 上游请求：重写 Host 与 X-Forwarded-Proto，移除 /proxy/{port} 前缀，保留查询参数。
|
||||
- 上游响应：记录指标（总请求数、成功率、平均响应时间、每端口统计、活跃连接数）。
|
||||
- 指标与健康检查
|
||||
- 指标：原子计数器与每端口快照；健康检查：基于 TCP 连接超时的周期性检查，支持轮询与一致性哈希（Ketama）负载均衡。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Manager as "PingoraServerManager"
|
||||
participant Service as "PingoraProxyService"
|
||||
participant Proxy as "PortProxy"
|
||||
participant Backend as "后端服务"
|
||||
Client->>Manager : "HTTP 请求 /proxy/{port}/..."
|
||||
Manager->>Service : "创建/获取代理服务"
|
||||
Service->>Proxy : "委托处理请求"
|
||||
Proxy->>Proxy : "提取端口/重写路径/设置头部"
|
||||
Proxy->>Service : "记录请求/活跃连接+1"
|
||||
Proxy->>Backend : "转发请求"
|
||||
Backend-->>Proxy : "返回响应"
|
||||
Proxy->>Service : "记录响应/活跃连接-1"
|
||||
Proxy-->>Client : "返回响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L182)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
|
||||
### 组件三：配置与启动（ProxyConfig、业务服务 main）
|
||||
- ProxyConfig
|
||||
- 定义监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与日志开关；提供默认值与校验。
|
||||
- 业务服务启动流程
|
||||
- 解析 CLI 与配置文件，按需创建 PingoraServerManager 并启动后台任务。
|
||||
- 将 Pingora 服务引用注入 AppState，以便路由层读取代理状态与统计。
|
||||
- 提供健康检查端点与优雅关闭信号处理。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动业务服务"]) --> Parse["解析 CLI 与配置"]
|
||||
Parse --> CheckProxy{"是否启用代理?"}
|
||||
CheckProxy --> |否| InitAPI["初始化 API 服务"]
|
||||
CheckProxy --> |是| BuildConfig["构建 ProxyConfig"]
|
||||
BuildConfig --> NewManager["创建 PingoraServerManager"]
|
||||
NewManager --> StartProxy["后台启动代理服务"]
|
||||
StartProxy --> InjectState["注入 AppState含代理服务"]
|
||||
InjectState --> InitAPI
|
||||
InitAPI --> Listen["绑定监听端口并启动服务"]
|
||||
Listen --> End(["运行中"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
### 组件四：路由与代理 API（rcoder/agent_runner 路由）
|
||||
- 路由组织
|
||||
- 系统路由：/health、聊天与代理会话管理等。
|
||||
- 代理 API：/proxy/status、/proxy/stats、/proxy/config、/proxy/{port}、/proxy/{port}/{*path} 等。
|
||||
- 与代理服务的协作
|
||||
- 路由层通过 AppState 获取 PingoraProxyService，读取健康状态、统计快照与配置信息，用于对外展示。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)
|
||||
|
||||
## 依赖关系分析
|
||||
- 语言与运行时
|
||||
- Rust 2024 edition，Tokio 异步运行时，Axum HTTP 服务器，Pingora 负载均衡特性。
|
||||
- 外部依赖
|
||||
- Cloudflare Pingora（lb 特性）、OpenTelemetry（遥测）、Tracing（日志与链路传播）。
|
||||
- 工作区依赖
|
||||
- shared_types 提供共享模型与 gRPC 类型；docker_manager 提供容器管理能力；acp_adapter/claude-code-agent/codex-acp-agent 提供代理生态集成。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
P["pingora-proxy"] --> L["pingora"]
|
||||
P --> T["tokio/async-trait"]
|
||||
P --> O["opentelemetry/tracing"]
|
||||
RC["rcoder"] --> P
|
||||
AR["agent_runner"] --> P
|
||||
RC --> DM["docker_manager"]
|
||||
AR --> DM
|
||||
RC --> ST["shared_types"]
|
||||
AR --> ST
|
||||
RC --> AC["acp_adapter"]
|
||||
AR --> CA["claude-code-agent"]
|
||||
AR --> CO["codex-acp-agent"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 性能考量
|
||||
- 异步 I/O 与事件循环
|
||||
- 基于 Tokio 与 Pingora 的异步事件驱动，避免阻塞，提升吞吐。
|
||||
- 负载均衡与健康检查
|
||||
- 支持轮询与一致性哈希（Ketama）；内置 TCP 健康检查，周期性探测后端可用性。
|
||||
- 指标与可观测性
|
||||
- 原子计数器与每端口快照，支持平均响应时间、成功率、活跃连接数等关键指标。
|
||||
- 路径重写与头部处理
|
||||
- 在上游请求过滤阶段重写 Host 与 X-Forwarded-Proto，减少后端复杂度。
|
||||
- 可扩展性
|
||||
- 动态后端管理：按需添加/删除后端，无需重启；支持多端口并行代理。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动与健康检查
|
||||
- 业务服务提供 /health 健康检查端点；Pingora 代理服务可通过 /proxy/status 与 /proxy/stats 查询状态与统计。
|
||||
- 日志与遥测
|
||||
- 业务服务初始化 Tracing 与 OpenTelemetry，支持 trace_id 传播；日志按天滚动，便于定位问题。
|
||||
- Docker 环境问题
|
||||
- rcoder 在启动时进行宿主机路径解析与 Docker 管理器初始化，若失败会输出详细帮助信息与排障步骤。
|
||||
- 代理端口提取失败
|
||||
- 当请求未携带端口参数或路径不匹配时，将回退到默认后端端口；可在 /proxy/config 查看配置。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)
|
||||
|
||||
## 结论
|
||||
该反向代理服务以 Pingora 为核心，结合动态后端管理、负载均衡与健康检查，提供了高性能、可观测且易于扩展的端口代理能力。业务服务通过统一路由与 AppState 注入，实现了代理状态与统计的可视化与可控性。配合 Docker 编排与日志/遥测体系，满足生产环境的安全、可运维与可扩展需求。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 系统上下文图（概念性）
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "外部系统"
|
||||
Browser["浏览器/客户端"]
|
||||
Agents["AI 代理容器"]
|
||||
end
|
||||
subgraph "RCoder 平台"
|
||||
API["业务 API 服务"]
|
||||
Proxy["Pingora 反向代理"]
|
||||
Stats["指标与健康检查"]
|
||||
end
|
||||
Browser --> API
|
||||
Browser --> Proxy
|
||||
API --> Stats
|
||||
Proxy --> Agents
|
||||
```
|
||||
|
||||
[本图为概念性示意，不对应具体代码文件]
|
||||
|
||||
### 部署拓扑与基础设施要求
|
||||
- 容器化
|
||||
- 使用 docker-compose 编排，挂载 Docker socket 以支持宿主机路径解析与容器管理。
|
||||
- 端口映射：业务服务端口与代理服务端口可分离，默认分别为 8087/8088。
|
||||
- 镜像与健康检查
|
||||
- Dockerfile 提供增强调试镜像，包含性能分析工具与健康检查指令。
|
||||
- 配置
|
||||
- config.yml 定义代理监听端口、默认后端端口、后端主机、端口参数名与健康检查参数。
|
||||
|
||||
章节来源
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L1-L305)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
### 安全性、监控与灾难恢复
|
||||
- 安全性
|
||||
- 代理在上游请求过滤阶段重写 Host 与 X-Forwarded-Proto，便于后端识别真实来源。
|
||||
- 通过健康检查与负载均衡降低单点风险。
|
||||
- 监控
|
||||
- 指标：总请求数、成功/失败数、平均响应时间、每端口统计、活跃连接数。
|
||||
- 健康检查：周期性 TCP 探测，支持阈值配置。
|
||||
- 灾难恢复
|
||||
- 业务服务支持优雅关闭，清理动态容器与资源；代理服务支持优雅停止。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L1-L738)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
321
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/启用与启动.md
Normal file
321
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/启用与启动.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# 启用与启动
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [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/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文面向希望在 rcoder 主应用中启用并启动 Pingora 反向代理服务的开发者，系统讲解如何通过 rcoder 主应用初始化 Pingora 代理服务，覆盖服务启动流程、异步运行时配置、监听端口设置、与主应用的集成方式、服务生命周期管理、错误处理策略以及启动时的健康检查机制。文末提供常见启动失败场景的排查建议，帮助快速定位问题。
|
||||
|
||||
## 项目结构
|
||||
rcoder 采用多 crate 工作区组织，其中与反向代理直接相关的核心模块位于：
|
||||
- crates/pingora-proxy：提供 Pingora 反向代理能力（配置、服务、服务器管理、运行器等）
|
||||
- crates/rcoder：主应用，负责加载配置、启动代理服务、与 API 服务协同
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 主应用"
|
||||
RCMain["crates/rcoder/src/main.rs<br/>入口与集成"]
|
||||
RCHandler["crates/rcoder/src/handler/proxy_handler_api.rs<br/>代理状态/重定向 API"]
|
||||
end
|
||||
subgraph "Pingora 反向代理库"
|
||||
PLib["crates/pingora-proxy/src/lib.rs<br/>导出与便捷函数"]
|
||||
PConfig["crates/pingora-proxy/src/config.rs<br/>配置结构与校验"]
|
||||
PServer["crates/pingora-proxy/src/server.rs<br/>代理服务器/构建器/运行器"]
|
||||
PManager["crates/pingora-proxy/src/pingora_server.rs<br/>PingoraServerManager"]
|
||||
PService["crates/pingora-proxy/src/service.rs<br/>服务/负载均衡/健康检查/指标"]
|
||||
end
|
||||
RCMain --> PManager
|
||||
RCMain --> PService
|
||||
RCHandler --> RCMain
|
||||
PLib --> PConfig
|
||||
PLib --> PServer
|
||||
PLib --> PManager
|
||||
PLib --> PService
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L179-L214)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L70)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L156)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L106)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L411-L596)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L1-L30)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
## 核心组件
|
||||
- 配置（ProxyConfig）：定义监听端口、默认后端端口、后端主机、端口参数名、配置文件路径、详细日志开关等；提供 validate 校验。
|
||||
- 代理服务（PingoraProxyService/PortProxy）：负责端口提取、路径重写、上游 peer 选择、请求/响应过滤、指标统计、健康检查。
|
||||
- 服务器管理（ProxyServer/PingoraServerManager）：提供便捷启动、预检、构建器、运行器；PingoraServerManager 通过 Pingora 库启动 TCP 监听并运行服务器。
|
||||
- 主应用集成：rcoder 主应用在启动时根据配置决定是否启用代理服务，创建 PingoraServerManager 并在后台任务中启动，同时可选地启动健康检查循环。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L596)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L156)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L106)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L179-L214)
|
||||
|
||||
## 架构总览
|
||||
rcoder 主应用在启动阶段根据配置决定是否启用 Pingora 代理服务。若启用，主应用：
|
||||
- 构造 ProxyConfig
|
||||
- 创建 PingoraServerManager
|
||||
- 可选：启动健康检查循环（周期性探测后端连通性）
|
||||
- 在 tokio::spawn 后台任务中启动 Pingora 服务器
|
||||
- 将 Pingora 服务引用注入 AppState，供 API 层使用
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as "rcoder 主应用"
|
||||
participant Cfg as "ProxyConfig"
|
||||
participant Mgr as "PingoraServerManager"
|
||||
participant Svc as "PingoraProxyService"
|
||||
participant Pingora as "Pingora 服务器"
|
||||
participant API as "API 服务(Axum)"
|
||||
App->>Cfg : "构造配置(监听端口/默认后端/主机/参数名)"
|
||||
App->>Mgr : "new(ProxyConfig)"
|
||||
Mgr->>Svc : "service.create_pingora_proxy()"
|
||||
App->>Svc : "可选 : start_health_check_loop(interval, timeout)"
|
||||
App->>Mgr : "spawn(start())"
|
||||
Mgr->>Pingora : "Server : : new + bootstrap + add_tcp + add_service"
|
||||
Pingora-->>Mgr : "run_forever() 运行"
|
||||
App->>API : "绑定主 API 服务端口(config.port)"
|
||||
API-->>App : "优雅关闭信号"
|
||||
App->>Mgr : "stop() 发送关闭信号"
|
||||
Mgr-->>Pingora : "abort 运行线程"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L179-L214)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L91)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 配置与校验（ProxyConfig）
|
||||
- 字段含义与默认值：监听端口、默认后端端口、后端主机、端口参数名、配置文件路径、详细日志开关。
|
||||
- 校验规则：监听端口/默认后端端口必须大于 0；后端主机与端口参数名不能为空。
|
||||
- 便捷方法：with_listen_port、with_backend_host、with_port_param 等。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
### 代理服务与负载均衡（PingoraProxyService/PortProxy）
|
||||
- 端口提取与路径重写：
|
||||
- 优先从路径 /proxy/{port}/... 提取端口；否则使用默认后端端口。
|
||||
- 重写请求 URI，移除 /proxy/{port} 前缀并保留查询参数。
|
||||
- 上游 peer 选择：动态将未显式注册的端口加入后端映射，默认指向 backend_host。
|
||||
- 请求/响应过滤：修改 Host/X-Forwarded-Proto/X-Port-Proxy/X-Load-Balancer 等头部；记录指标（总请求数、成功率、响应时间、每端口统计、活跃连接数）。
|
||||
- 负载均衡：支持轮询与一致性哈希（Ketama）两种算法，可通过 with_load_balancing 切换。
|
||||
- 健康检查：提供 start_health_check_loop 周期性探测，使用 TcpStream 连接测试；支持 timeout 控制；维护每个端口的健康状态快照。
|
||||
- 后端管理：add_backend/remove_backend/list_backends/has_backend/backend_count 等。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["请求进入"]) --> ExtractPort["提取目标端口<br/>优先路径 /proxy/{port}"]
|
||||
ExtractPort --> HasBackend{"后端映射中存在该端口?"}
|
||||
HasBackend --> |否| AddBackend["动态添加到 backend_host"]
|
||||
HasBackend --> |是| UseHost["使用已知主机"]
|
||||
AddBackend --> UseHost
|
||||
UseHost --> RewriteURI["重写 URI<br/>移除 /proxy/{port}<br/>保留查询参数"]
|
||||
RewriteURI --> SelectPeer["选择上游 peer"]
|
||||
SelectPeer --> FilterReq["上游请求过滤<br/>设置 X-* 头部"]
|
||||
FilterReq --> Forward["转发到上游"]
|
||||
Forward --> RecordResp["响应过滤<br/>记录指标/活跃连接-1"]
|
||||
RecordResp --> End(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L246-L354)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L356-L409)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L596)
|
||||
|
||||
### 服务器管理与启动（PingoraServerManager）
|
||||
- 启动流程：
|
||||
- 创建 Opt::default()，构建 Server 并 bootstrap。
|
||||
- 从服务创建 PortProxy，包装为 ProxyHttp 实现，创建 http_proxy_service 并 add_tcp 监听 0.0.0.0:listen_port。
|
||||
- 将服务加入 Server，创建 oneshot 关闭通道。
|
||||
- spawn_blocking 运行 run_forever；tokio::select 等待关闭信号或运行结束。
|
||||
- 停止：向 oneshot 发送关闭信号，主线程 abort 运行线程。
|
||||
- 便捷函数：start_pingora_proxy 快速启动。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Mgr as "PingoraServerManager"
|
||||
participant Srv as "Server"
|
||||
participant Svc as "PortProxy"
|
||||
participant Net as "TCP 监听"
|
||||
Mgr->>Srv : "new(Opt) + bootstrap"
|
||||
Mgr->>Svc : "create_pingora_proxy()"
|
||||
Mgr->>Srv : "http_proxy_service + add_tcp(0.0.0.0 : listen_port)"
|
||||
Mgr->>Srv : "add_service"
|
||||
Mgr->>Net : "监听端口"
|
||||
Mgr->>Srv : "spawn_blocking(run_forever)"
|
||||
Srv-->>Mgr : "运行中"
|
||||
Mgr->>Mgr : "等待关闭信号"
|
||||
Mgr-->>Srv : "abort 运行线程"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L91)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L106)
|
||||
|
||||
### 代理服务器与构建器（ProxyServer/PingoraServerRunner）
|
||||
- ProxyServer.new/with_*：构造服务实例，提供预启动检查、配置访问、负载均衡切换等。
|
||||
- ProxyServerBuilder：链式配置监听端口、默认后端端口、后端主机、端口参数名、配置文件、详细日志、负载均衡算法。
|
||||
- PingoraServerRunner：直接获取 PortProxy 实例，便于更细粒度控制。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L156)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L157-L266)
|
||||
|
||||
### 主应用集成与启动流程（rcoder）
|
||||
- 启动阶段：
|
||||
- 解析 CLI 与配置，决定是否启用代理服务。
|
||||
- 构造 ProxyConfig（来自应用配置），创建 PingoraServerManager。
|
||||
- 可选：根据配置启动健康检查循环（interval_seconds、timeout_seconds）。
|
||||
- spawn 后台任务执行 manager.start()。
|
||||
- 绑定主 API 服务端口（config.port），支持优雅关闭。
|
||||
- 优雅关闭：接收 Ctrl+C/SIGINT/SIGTERM，触发清理任务与代理服务停止。
|
||||
- 代理状态 API：提供 /proxy/status 与重定向到 /proxy/{port}/... 的辅助接口，便于调试与文档展示。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder 主应用(main)"
|
||||
participant PMgr as "PingoraServerManager"
|
||||
participant PAPI as "代理状态 API"
|
||||
participant Axum as "Axum API 服务"
|
||||
RC->>RC : "加载配置/解析 CLI"
|
||||
RC->>PMgr : "new(ProxyConfig) + 可选 : start_health_check_loop"
|
||||
RC->>PMgr : "spawn(start())"
|
||||
RC->>Axum : "bind(config.port) + serve"
|
||||
Axum-->>RC : "优雅关闭信号"
|
||||
RC->>PMgr : "stop() 发送关闭信号"
|
||||
PMgr-->>Axum : "代理服务停止"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L179-L214)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L350)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L179-L214)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/rcoder/src/handler/proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L350)
|
||||
|
||||
## 依赖分析
|
||||
- 工作区依赖统一来源于 workspace.dependencies，主应用与库共享 tokio、axum、tracing、serde 等生态。
|
||||
- pingora-proxy 依赖 pingora 生态（pingora-core/pingora-http/pingora-proxy/pingora-load-balancing），并使用 tokio/async-trait/anyhow/tracing/structopt。
|
||||
- rcoder 依赖 pingora-proxy 作为子模块，同时集成 OpenTelemetry、Swagger 文档、Docker 管理等。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
WS["workspace.dependencies"] --> Tokio["tokio(full)"]
|
||||
WS --> Axum["axum(http2/query/...)"]
|
||||
WS --> Trace["tracing/tracing-subscriber"]
|
||||
WS --> Serde["serde/serde_json"]
|
||||
WS --> OTel["opentelemetry/opentelemetry_sdk"]
|
||||
PkgPP["pingora-proxy"] --> Pingora["pingora(0.6)+lb"]
|
||||
PkgPP --> Tokio
|
||||
PkgPP --> Trace
|
||||
PkgPP --> Axum
|
||||
PkgPP --> Serde
|
||||
PkgRC["rcoder"] --> PkgPP
|
||||
PkgRC --> Tokio
|
||||
PkgRC --> Trace
|
||||
PkgRC --> Axum
|
||||
PkgRC --> OTel
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L35-L205)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L1-L30)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L35-L205)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L1-L30)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
## 性能考虑
|
||||
- 异步运行时：统一使用 tokio::main，启用 full 特性，支持 spawn/spawn_blocking/select 等高并发场景。
|
||||
- 负载均衡：默认轮询算法，可在服务层 with_load_balancing 切换为一致性哈希；Pingora 生态内置健康检查，降低故障上游流量。
|
||||
- 指标与可观测：内置活跃连接、每端口统计、平均响应时间等指标，便于性能分析与告警。
|
||||
- I/O 与阻塞：Pingora 服务器运行在 spawn_blocking 的阻塞线程中，避免阻塞主异步运行时；Tokio select 等待关闭信号，保证优雅退出。
|
||||
|
||||
[本节为通用指导，无需列出具体文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败（端口占用/权限不足）
|
||||
- 现象：Pingora 服务器无法绑定监听端口。
|
||||
- 排查：确认 listen_port 未被占用；检查防火墙/SELinux；确认以足够权限运行。
|
||||
- 参考：PingoraServerManager 在启动时会打印监听地址与路由规则。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L66)
|
||||
|
||||
- 配置校验失败
|
||||
- 现象：启动前预检或启动时报错“监听端口不能为 0”、“默认后端端口不能为 0”、“后端主机地址不能为空”、“端口参数名不能为空”。
|
||||
- 排查：修正 ProxyConfig 字段；使用 with_listen_port/with_backend_host/with_port_param 等便捷方法。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L48-L68)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L94-L108)
|
||||
|
||||
- 代理请求失败（后端不可达）
|
||||
- 现象：请求 /proxy/{port}/... 无法到达后端。
|
||||
- 排查：确认 backend_host 与 port_param 正确；检查健康检查是否开启并生效；查看每端口统计与活跃连接数；必要时手动 add_backend 注册。
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L444-L476)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
|
||||
- 优雅关闭异常
|
||||
- 现象：收到关闭信号后代理服务未及时停止。
|
||||
- 排查：确认主应用已发送广播信号；检查 PingoraServerManager.stop 是否被调用；观察日志中“收到关闭信号/服务器异常结束”的提示。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L77-L91)
|
||||
|
||||
- 健康检查未生效
|
||||
- 现象：健康检查未更新或状态异常。
|
||||
- 排查：确认已调用 start_health_check_loop；检查 interval_seconds 与 timeout_seconds 设置；查看 health_snapshot 快照。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L191-L196)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L581-L596)
|
||||
|
||||
## 结论
|
||||
通过 rcoder 主应用与 pingora-proxy 库的协作，可以在同一进程内启用高性能的 Pingora 反向代理服务。启动流程清晰：先构造配置，再创建管理器，可选启动健康检查，随后在后台任务中启动服务器。主应用负责优雅关闭与 API 服务绑定，代理服务负责端口路由、路径重写、负载均衡与健康检查。遵循本文的配置要点、启动流程与故障排查建议，可稳定启用并维护代理服务。
|
||||
395
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/请求处理与路由.md
Normal file
395
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/请求处理与路由.md
Normal file
@@ -0,0 +1,395 @@
|
||||
# 请求处理与路由
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕基于 Pingora 的反向代理请求处理与路由机制展开，重点解析：
|
||||
- 基于 Axum 的 API 路由与重定向逻辑
|
||||
- `/proxy/{port}/{path}` 路由规则的实现原理
|
||||
- 动态端口映射、请求头传递、超时控制与健康检查
|
||||
- 负载均衡策略（轮询与一致性哈希）
|
||||
- 从 Axum 路由到 Pingora 服务的请求转发链路
|
||||
- 实际请求示例与调试技巧
|
||||
|
||||
## 项目结构
|
||||
该仓库采用多 crate 组织，其中与反向代理直接相关的核心模块如下：
|
||||
- agent_runner：提供 API 层（Axum 路由、状态查询、统计信息），并持有 Pingora 服务引用以读取指标
|
||||
- pingora-proxy：提供 Pingora 代理服务、负载均衡、健康检查与请求过滤
|
||||
- rcoder：应用入口，负责启动 Pingora 服务器管理器、注入 AppState、合并路由
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "应用层"
|
||||
AR["agent_runner<br/>API 路由与状态查询"]
|
||||
CFG["agent_runner/config.rs<br/>应用配置"]
|
||||
MAIN["rcoder/src/main.rs<br/>应用入口与路由合并"]
|
||||
end
|
||||
subgraph "代理层"
|
||||
PINGORA_LIB["pingora-proxy/lib.rs<br/>库入口与特性说明"]
|
||||
PINGORA_SRV["pingora-proxy/server.rs<br/>代理服务器管理器"]
|
||||
PINGORA_SVC["pingora-proxy/service.rs<br/>代理服务与负载均衡"]
|
||||
PINGORA_MGR["pingora-proxy/pingora_server.rs<br/>Pingora 服务器启动"]
|
||||
end
|
||||
MAIN --> AR
|
||||
AR --> CFG
|
||||
MAIN --> PINGORA_MGR
|
||||
PINGORA_MGR --> PINGORA_SRV
|
||||
PINGORA_SRV --> PINGORA_SVC
|
||||
PINGORA_LIB --> PINGORA_SVC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L38-L110)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L120)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L355)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L38-L110)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
|
||||
## 核心组件
|
||||
- Axum 路由与代理 API
|
||||
- 提供 `/proxy/status`、`/proxy/stats`、`/proxy/config` 等状态查询接口
|
||||
- 提供 `/proxy/{port}` 与 `/proxy/{port}/{*path}` 的重定向逻辑，将请求转发至 Pingora 监听端口
|
||||
- Pingora 代理服务
|
||||
- 路径解析：从 `/proxy/{port}` 前缀提取目标端口，剥离前缀得到目标路径
|
||||
- 动态后端：若端口未在映射中，自动添加默认主机映射
|
||||
- 请求过滤：重写 Host、添加 X-Forwarded-Proto、X-Port-Proxy、X-Load-Balancer 等头部
|
||||
- 响应过滤：记录指标、计算平均响应时间、维护活跃连接数
|
||||
- 负载均衡：支持轮询与一致性哈希（Ketama），并内置健康检查
|
||||
- 应用入口与状态注入
|
||||
- 启动 Pingora 服务器管理器，提取服务引用注入 AppState，供 API 查询使用
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs#L1-L195)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L252-L355)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
|
||||
## 架构总览
|
||||
下图展示了从客户端请求到 Pingora 代理再到后端服务的整体链路，以及 API 层对代理状态与统计的读取。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant API as "Axum 路由层<br/>/proxy/*"
|
||||
participant State as "AppState<br/>持有 Pingora 服务引用"
|
||||
participant PingoraMgr as "Pingora 服务器管理器"
|
||||
participant PingoraSvc as "Pingora 代理服务"
|
||||
participant Backend as "后端服务"
|
||||
Client->>API : "GET /proxy/{port}/{path}"
|
||||
API->>API : "校验代理配置是否启用"
|
||||
API->>Client : "307 临时重定向到 127.0.0.1 : {listen_port}/proxy/{port}{path}"
|
||||
Client->>PingoraMgr : "GET /proxy/{port}{/path}"
|
||||
PingoraMgr->>PingoraSvc : "upstream_peer()<br/>提取端口并选择后端"
|
||||
PingoraSvc->>PingoraSvc : "upstream_request_filter()<br/>重写 Host/URI/添加代理头"
|
||||
PingoraSvc->>Backend : "转发请求"
|
||||
Backend-->>PingoraSvc : "响应"
|
||||
PingoraSvc->>PingoraSvc : "response_filter()<br/>记录指标/活跃连接"
|
||||
PingoraSvc-->>Client : "返回响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L252-L355)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Axum 路由与代理 API
|
||||
- 路由注册
|
||||
- API 路由与代理 API 路由分别注册，最终合并到一个 Router
|
||||
- 代理 API 路由包括状态、统计、配置查询，以及 `/proxy/{port}` 与 `/proxy/{port}/{*path}` 的重定向
|
||||
- 重定向逻辑
|
||||
- `/proxy/{port}`：构造 Location 为 `http://127.0.0.1:{listen_port}/proxy/{port}`
|
||||
- `/proxy/{port}/{*path}`：保持路径，构造 Location 为 `http://127.0.0.1:{listen_port}/proxy/{port}{path}`
|
||||
- 状态查询与统计
|
||||
- `/proxy/status`：读取 Pingora 服务配置、后端映射与健康快照
|
||||
- `/proxy/stats`：读取总请求数、成功率、平均响应时间、按端口统计
|
||||
- `/proxy/config`：读取监听端口、默认后端、负载均衡算法与健康检查配置
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入代理 API"]) --> CheckCfg["检查代理配置是否启用"]
|
||||
CheckCfg --> |未启用| Return503["返回 503 错误"]
|
||||
CheckCfg --> |已启用| RouteType{"请求路径类型？"}
|
||||
RouteType --> |/proxy/{port}| BuildLoc1["构造 Location: 127.0.0.1:{listen_port}/proxy/{port}"]
|
||||
RouteType --> |/proxy/{port}/{*path}| BuildLoc2["构造 Location: 127.0.0.1:{listen_port}/proxy/{port}{path}"]
|
||||
BuildLoc1 --> Redirect["307 临时重定向"]
|
||||
BuildLoc2 --> Redirect
|
||||
Redirect --> End(["完成"])
|
||||
Return503 --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs#L1-L195)
|
||||
|
||||
### Pingora 代理服务与负载均衡
|
||||
- 端口提取与路径重写
|
||||
- 从请求 URI 中提取端口：优先解析 `/proxy/{port}` 前缀；若不存在则回退到默认端口
|
||||
- 重写请求 URI：移除 `/proxy/{port}` 前缀，保留查询参数
|
||||
- 重写 Host 为 127.0.0.1，并添加 X-Forwarded-Proto、X-Port-Proxy、X-Load-Balancer 等头部
|
||||
- 动态后端管理
|
||||
- 若目标端口不在映射中，自动添加默认主机映射
|
||||
- 支持添加/移除后端、列出后端、检查后端存在性、统计后端数量
|
||||
- 指标与健康检查
|
||||
- 维护总请求数、成功/失败计数、平均响应时间、每端口统计
|
||||
- 维护活跃连接数，原子递增/递减
|
||||
- 健康检查：基于 TCP 连接超时检测，周期性更新健康状态快照
|
||||
- 负载均衡
|
||||
- 支持轮询与一致性哈希（Ketama），可通过配置切换
|
||||
- 内置健康检查，可配置检查频率、超时与阈值
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PingoraProxyService {
|
||||
+config : ProxyConfig
|
||||
+backends : HashMap<u16, String>
|
||||
+use_round_robin : bool
|
||||
+metrics : ProxyMetrics
|
||||
+health_map : HashMap<u16, HealthInfo>
|
||||
+create_pingora_proxy() PortProxy
|
||||
+add_backend(port, host) void
|
||||
+remove_backend(port) void
|
||||
+list_backends() HashMap<u16, String>
|
||||
+has_backend(port) bool
|
||||
+backend_count() usize
|
||||
+extract_target_port(req) u16
|
||||
+get_target_backend(port) String
|
||||
+create_load_balancer(backend_list) LoadBalancer
|
||||
+start_health_check_loop(interval, timeout) void
|
||||
+health_snapshot() HashMap<u16, HealthInfo>
|
||||
}
|
||||
class PortProxy {
|
||||
+backends : HashMap<u16, String>
|
||||
+default_backend_port : u16
|
||||
+backend_host : String
|
||||
+use_round_robin : bool
|
||||
+metrics : ProxyMetrics
|
||||
+upstream_peer(session, ctx) HttpPeer
|
||||
+upstream_request_filter(session, upstream_request, ctx) void
|
||||
+response_filter(session, upstream_response, ctx) void
|
||||
-extract_target_port(session) u16
|
||||
-extract_target_path(session) String
|
||||
-get_backend_host(port) String
|
||||
}
|
||||
class ProxyMetrics {
|
||||
+total_requests : AtomicU64
|
||||
+successful_responses : AtomicU64
|
||||
+failed_responses : AtomicU64
|
||||
+total_response_time_ns : AtomicU64
|
||||
+active_connections : AtomicU64
|
||||
+record_request() void
|
||||
+record_request_port(port) void
|
||||
+record_response(status_text, duration) void
|
||||
+record_response_port(port, status_text, duration) void
|
||||
+avg_response_time_ms() f64
|
||||
+inc_active() void
|
||||
+dec_active() void
|
||||
+active() u64
|
||||
+port_snapshots() Vec<PortSnapshot>
|
||||
}
|
||||
PingoraProxyService --> PortProxy : "创建代理实例"
|
||||
PortProxy --> ProxyMetrics : "记录指标"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L355)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L509-L596)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L252-L355)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L509-L596)
|
||||
|
||||
### Pingora 服务器启动与运行
|
||||
- 服务器管理器
|
||||
- 创建 Opt、Server、HTTP 代理服务，绑定 TCP 监听端口
|
||||
- 通过 ProxyServiceWrapper 将 PortProxy 实现适配为 Pingora 的 ProxyHttp
|
||||
- 提供启动/停止与服务引用获取能力
|
||||
- 应用入口集成
|
||||
- rcoder 在启动时创建 PingoraServerManager，提取服务引用注入 AppState
|
||||
- 启动健康检查循环（按配置）
|
||||
- 合并 API 路由与 Swagger UI
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as "rcoder/main.rs"
|
||||
participant Manager as "PingoraServerManager"
|
||||
participant Server as "Pingora Server"
|
||||
participant Service as "PingoraProxyService"
|
||||
participant Wrapper as "ProxyServiceWrapper"
|
||||
Main->>Manager : "new(config)"
|
||||
Main->>Manager : "start()"
|
||||
Manager->>Server : "创建 Server/HTTP 代理服务"
|
||||
Manager->>Wrapper : "包装 PortProxy"
|
||||
Wrapper-->>Server : "实现 ProxyHttp"
|
||||
Server-->>Main : "run_forever() 运行"
|
||||
Main->>Service : "service() 获取引用"
|
||||
Main-->>Main : "注入 AppState 并启动 API 服务"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
|
||||
## 依赖关系分析
|
||||
- 组件耦合
|
||||
- agent_runner 的路由层依赖 AppState 中的 Pingora 服务引用，用于读取状态与统计
|
||||
- rcoder 的 main.rs 负责创建 PingoraServerManager 并注入 AppState
|
||||
- pingora-proxy 的 service.rs 与 pingora_server.rs 分别承担服务实现与服务器启动职责
|
||||
- 外部依赖
|
||||
- Pingora 库提供高性能代理、负载均衡与健康检查
|
||||
- Axum 提供路由与 HTTP 处理
|
||||
- Tokio 提供异步运行时与任务管理
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
AR["agent_runner/router.rs"] --> API["agent_runner/handler/proxy_handler_api.rs"]
|
||||
API --> CFG["agent_runner/config.rs"]
|
||||
API --> STATE["AppState<br/>持有 Pingora 服务引用"]
|
||||
STATE --> MAIN["rcoder/main.rs"]
|
||||
MAIN --> MGR["pingora_proxy/pingora_server.rs"]
|
||||
MGR --> SRV["pingora_proxy/server.rs"]
|
||||
SRV --> SVC["pingora_proxy/service.rs"]
|
||||
LIB["pingora_proxy/lib.rs"] --> SVC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L38-L110)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L355)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L38-L110)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L37-L106)
|
||||
- [crates/pingora-proxy/src/server.rs](file://crates/pingora-proxy/src/server.rs#L1-L100)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L223-L355)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L60-L120)
|
||||
|
||||
## 性能考量
|
||||
- 路由与重定向
|
||||
- 代理 API 层采用 307 重定向，避免在 API 服务中直接发起网络请求，降低延迟与资源占用
|
||||
- 负载均衡与健康检查
|
||||
- 轮询与一致性哈希两种策略可按需切换；健康检查周期与超时可配置，平衡准确性与开销
|
||||
- 指标与可观测性
|
||||
- 提供总请求数、成功率、平均响应时间、每端口统计与活跃连接数，便于性能分析与容量规划
|
||||
- 异步与并发
|
||||
- 基于 Tokio 的异步 I/O，Pingora 代理服务在高并发场景下具备良好吞吐能力
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 代理未启用
|
||||
- 现象：调用 `/proxy/status`、`/proxy/stats`、`/proxy/config` 返回 503
|
||||
- 排查：确认应用配置中启用了代理，且 Pingora 服务器已启动
|
||||
- 端口提取失败
|
||||
- 现象：请求未命中预期后端
|
||||
- 排查：检查请求路径是否符合 `/proxy/{port}` 格式；确认端口参数是否有效
|
||||
- 后端未发现
|
||||
- 现象：动态添加后端后仍报“未找到后端”
|
||||
- 排查：确认端口已被加入映射；检查默认主机配置与健康检查状态
|
||||
- 超时与连接问题
|
||||
- 现象：健康检查超时或连接失败
|
||||
- 排查：调整健康检查超时与间隔；检查后端服务监听端口与防火墙策略
|
||||
- 请求头与路径问题
|
||||
- 现象：后端服务无法识别 Host 或路径被错误重写
|
||||
- 排查：确认上游请求过滤已正确重写 Host 与 URI；检查查询参数是否保留
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L31-L174)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L252-L355)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
## 结论
|
||||
该系统通过 Axum 的轻量 API 层与 Pingora 的高性能代理服务实现了灵活、可扩展的反向代理能力。其核心优势包括：
|
||||
- 清晰的路由与重定向机制，简化了 API 层与代理层的职责分离
|
||||
- 动态端口映射与请求头传递，保证了透明代理与可观测性
|
||||
- 可配置的负载均衡与健康检查，满足生产环境的稳定性需求
|
||||
- 丰富的指标与状态查询接口，便于运维与性能优化
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 实际请求示例
|
||||
- 查询代理状态
|
||||
- 请求：GET /proxy/status
|
||||
- 作用：返回代理服务状态、监听端口、默认后端、后端列表与负载均衡配置
|
||||
- 查询代理统计
|
||||
- 请求：GET /proxy/stats
|
||||
- 作用：返回总请求数、成功率、平均响应时间、按端口统计与活跃连接数
|
||||
- 查询代理配置
|
||||
- 请求：GET /proxy/config
|
||||
- 作用：返回监听端口、默认后端、负载均衡算法与健康检查配置
|
||||
- 代理到指定端口（无路径）
|
||||
- 请求：GET /proxy/{port}
|
||||
- 作用：307 重定向到 127.0.0.1:{listen_port}/proxy/{port}
|
||||
- 代理到指定端口与路径
|
||||
- 请求：GET /proxy/{port}/{*path}
|
||||
- 作用：307 重定向到 127.0.0.1:{listen_port}/proxy/{port}{path}
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/handler/proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L230-L332)
|
||||
- [crates/agent_runner/src/handler/proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs#L1-L195)
|
||||
|
||||
### 调试技巧
|
||||
- 启用健康检查
|
||||
- 在配置中开启健康检查，并设置合理的间隔与超时，观察健康状态快照
|
||||
- 观察指标
|
||||
- 通过 `/proxy/stats` 与 `/proxy/status` 持续监控请求量、成功率与平均响应时间
|
||||
- 路径与端口验证
|
||||
- 使用 curl 验证重定向行为与端口提取逻辑，确保路径前缀被正确剥离
|
||||
- 日志与追踪
|
||||
- 关注 Pingora 与应用层日志，定位请求过滤与响应过滤阶段的问题
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L170-L265)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
387
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/配置选项.md
Normal file
387
qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/配置选项.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# 配置选项
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [config.yml](file://config.yml)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构与配置来源](#项目结构与配置来源)
|
||||
3. [核心配置组件](#核心配置组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向反向代理服务的配置系统，聚焦于 PingoraConfig 结构体及其在代理服务中的作用，系统性说明监听地址、超时设置、缓冲区大小、TLS 配置等参数的含义与影响；阐述“命令行 > 环境变量 > 配置文件”的优先级链在代理服务中的具体实现；结合 config.yml 示例解释如何定制化代理行为以适配不同部署环境；并提供性能调优建议与安全配置最佳实践。
|
||||
|
||||
## 项目结构与配置来源
|
||||
- 代理库提供 PingoraConfig 结构体与启动能力，负责解析命令行参数、配置文件与运行时环境变量，形成最终的代理配置。
|
||||
- 应用层（rcoder/agent_runner）在启动时加载配置，若启用代理，则将应用配置中的代理段落转换为 PingoraConfig 并启动 Pingora 服务。
|
||||
- 配置文件 config.yml 作为应用层的默认配置来源，包含代理、Docker 等多类配置项。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "应用层"
|
||||
RC["rcoder 主服务<br/>加载配置并启动代理"]
|
||||
AR["agent_runner 服务<br/>加载配置并启动代理"]
|
||||
end
|
||||
subgraph "代理库"
|
||||
PLib["pingora-proxy 库<br/>提供 ProxyConfig/PingoraServerManager"]
|
||||
end
|
||||
subgraph "配置来源"
|
||||
YML["config.yml<br/>默认配置文件"]
|
||||
ENV["环境变量<br/>RCODER_*"]
|
||||
CLI["命令行参数<br/>--port/--proxy-port 等"]
|
||||
end
|
||||
CLI --> RC
|
||||
CLI --> AR
|
||||
ENV --> RC
|
||||
ENV --> AR
|
||||
YML --> RC
|
||||
YML --> AR
|
||||
RC --> PLib
|
||||
AR --> PLib
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L66-L70)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L66-L70)
|
||||
|
||||
## 核心配置组件
|
||||
本节围绕 PingoraConfig 结构体展开，说明其在代理服务中的关键参数及默认值来源。
|
||||
|
||||
- 监听端口
|
||||
- 字段：listen_port
|
||||
- 作用：代理服务对外监听的 TCP 端口
|
||||
- 默认值：来自代理库默认常量（8080），应用层也可通过命令行或配置文件覆盖
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L11-L12)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L115-L120)
|
||||
|
||||
- 默认后端端口
|
||||
- 字段：default_backend_port
|
||||
- 作用：当请求未携带端口参数时，代理默认转发到的后端端口
|
||||
- 默认值：来自代理库默认常量（3000），应用层可通过命令行或配置文件覆盖
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L15-L16)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L115-L120)
|
||||
|
||||
- 后端主机地址
|
||||
- 字段：backend_host
|
||||
- 作用：代理转发的目标主机地址（通常为 127.0.0.1）
|
||||
- 默认值：来自代理库默认常量（127.0.0.1）
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L19-L20)
|
||||
|
||||
- URL 端口参数名
|
||||
- 字段：port_param
|
||||
- 作用：从查询参数中提取目标端口的参数名，默认为 "port"
|
||||
- 默认值：来自代理库默认常量（"port"）
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L23-L24)
|
||||
|
||||
- 配置文件路径
|
||||
- 字段：config_file
|
||||
- 作用：指向代理库的配置文件路径（如需启用配置文件支持）
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L27-L29)
|
||||
|
||||
- 详细日志开关
|
||||
- 字段：verbose
|
||||
- 作用：启用更详细的日志输出
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L31-L33)
|
||||
|
||||
- 健康检查配置（应用层代理段落）
|
||||
- 字段：health_check.enabled/interval_seconds/timeout_seconds/healthy_threshold/unhealthy_threshold
|
||||
- 作用：控制代理服务对后端健康检查的启用、周期、超时与阈值
|
||||
- 参考路径：
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
|
||||
|
||||
## 架构总览
|
||||
下图展示配置在应用层与代理库之间的流转过程，以及优先级链的执行顺序。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行参数"
|
||||
participant ENV as "环境变量"
|
||||
participant FILE as "配置文件 config.yml"
|
||||
participant APP as "应用层配置加载"
|
||||
participant LIB as "代理库配置(PingoraConfig)"
|
||||
participant SRV as "代理服务(PingoraServer)"
|
||||
CLI->>APP : 解析 --port/--proxy-port 等
|
||||
ENV->>APP : RCODER_PORT/RCODER_PROJECTS_DIR 等
|
||||
FILE->>APP : 读取并解析 config.yml
|
||||
APP->>LIB : 将代理段落转换为 PingoraConfig
|
||||
APP->>SRV : 启动代理服务(可选)
|
||||
SRV-->>APP : 健康检查循环(按配置)
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 组件一：PingoraConfig 结构体与默认值
|
||||
- 结构体定义与默认值来源
|
||||
- 监听端口、默认后端端口、后端主机、端口参数名均来自代理库默认常量
|
||||
- 代理库提供便捷构造方法（如 with_listen_port、with_backend_host、with_port_param）
|
||||
- 校验规则
|
||||
- 监听端口与默认后端端口不可为 0
|
||||
- 后端主机与端口参数名不可为空
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L68)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L99-L126)
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ProxyConfig {
|
||||
+u16 listen_port
|
||||
+u16 default_backend_port
|
||||
+string backend_host
|
||||
+string port_param
|
||||
+Option~string~ config_file
|
||||
+bool verbose
|
||||
+validate() Result
|
||||
+new() ProxyConfig
|
||||
+with_listen_port(u16) ProxyConfig
|
||||
+with_backend_host(string) ProxyConfig
|
||||
+with_port_param(string) ProxyConfig
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L94)
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L94)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L71-L76)
|
||||
|
||||
### 组件二：配置优先级链（命令行 > 环境变量 > 配置文件）
|
||||
- 应用层（rcoder/agent_runner）的优先级链
|
||||
- 命令行参数优先级最高，覆盖配置文件与环境变量
|
||||
- 环境变量次之，覆盖配置文件
|
||||
- 配置文件再次之，作为默认来源
|
||||
- rcoder 的优先级链实现
|
||||
- 若存在配置文件，先加载；否则创建默认配置文件
|
||||
- 命令行参数覆盖配置文件中的端口与项目目录
|
||||
- 环境变量 RCODER_PORT、RCODER_PROJECTS_DIR 覆盖应用层配置
|
||||
- 启用代理时，命令行 --proxy-port、--backend-port 覆盖代理段落
|
||||
- Docker 配置支持环境变量覆盖（RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL）
|
||||
- agent_runner 的优先级链实现
|
||||
- 首先加载默认配置，尝试从配置文件读取，失败则创建默认配置文件
|
||||
- 环境变量 RCODER_PORT 覆盖端口
|
||||
- 启用代理时，命令行参数决定代理监听端口与默认后端端口
|
||||
- 命令行参数优先级最高，覆盖配置文件与环境变量
|
||||
- 参考路径：
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> LoadFile["读取配置文件 config.yml"]
|
||||
LoadFile --> HasFile{"文件存在？"}
|
||||
HasFile --> |否| CreateDefault["创建默认配置文件"]
|
||||
HasFile --> |是| ParseYAML["解析 YAML 为应用配置"]
|
||||
ParseYAML --> ApplyCLI["应用命令行参数覆盖"]
|
||||
ApplyCLI --> ApplyENV["应用环境变量覆盖"]
|
||||
ApplyENV --> ApplyDockerEnv["应用 Docker 环境变量覆盖"]
|
||||
ApplyDockerEnv --> Validate["配置验证"]
|
||||
Validate --> Done(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L347-L403)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
|
||||
### 组件三：代理服务启动与健康检查
|
||||
- 应用层启动代理服务
|
||||
- 若配置中启用代理，将应用层代理段落转换为 PingoraConfig 并启动 PingoraServerManager
|
||||
- 启动健康检查循环（按配置的 interval_seconds 与 timeout_seconds）
|
||||
- 参考路径：
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L104-L108)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant APP as "应用层"
|
||||
participant CFG as "应用配置(AppConfig.ProxyConfig)"
|
||||
participant PCONF as "PingoraConfig"
|
||||
participant MGR as "PingoraServerManager"
|
||||
participant HC as "健康检查循环"
|
||||
APP->>CFG : 读取代理配置
|
||||
APP->>PCONF : 构造 PingoraConfig
|
||||
APP->>MGR : new(PCONF)
|
||||
APP->>HC : start_health_check_loop(interval, timeout_ms)
|
||||
MGR-->>APP : 后台启动服务
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L169-L208)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L192-L196)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L118)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L104-L108)
|
||||
|
||||
### 组件四：配置文件 config.yml 的定制化
|
||||
- 代理段落（proxy_config）
|
||||
- listen_port：代理服务监听端口
|
||||
- default_backend_port：默认后端端口
|
||||
- backend_host：后端主机地址
|
||||
- port_param：URL 中端口参数名
|
||||
- health_check：健康检查开关、间隔、超时、健康/不健康阈值
|
||||
- Docker 配置（docker_config）
|
||||
- multi_image_config：多镜像配置（服务镜像、环境变量、挂载、资源限制、工作目录、网络模式等）
|
||||
- network_mode/work_dir/auto_cleanup/container_ttl_seconds：Docker 运行时通用配置
|
||||
- 参考路径：
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L314-L401)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L360-L401)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
|
||||
|
||||
章节来源
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L314-L401)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L360-L401)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
|
||||
|
||||
## 依赖关系分析
|
||||
- 应用层依赖代理库提供的 PingoraServerManager 与 ProxyConfig
|
||||
- 应用层配置（AppConfig.ProxyConfig）与代理库配置（ProxyConfig）字段一一对应
|
||||
- Docker 配置通过共享类型模块提供多镜像配置与资源限制等能力
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RC["rcoder/src/config.rs"] --> PC["pingora-proxy/src/config.rs"]
|
||||
AR["agent_runner/src/config.rs"] --> PC
|
||||
RC --> SC["shared_types/src/service_config.rs"]
|
||||
AR --> SC
|
||||
SC --> MIC["shared_types/src/multi_image_config.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L37-L81)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L74)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L37-L81)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L74)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L15-L53)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L56)
|
||||
|
||||
## 性能考量
|
||||
- 监听端口与默认后端端口
|
||||
- 将代理监听端口与后端端口设置为不同值，避免端口冲突
|
||||
- 默认后端端口应与主服务端口一致，便于统一路由
|
||||
- 健康检查
|
||||
- 合理设置 interval_seconds 与 timeout_seconds，避免过于频繁导致额外开销
|
||||
- healthy_threshold 与 unhealthy_threshold 用于平滑波动，建议根据后端稳定性调整
|
||||
- 端口参数名
|
||||
- 使用较短且稳定的参数名（默认 "port"），减少路径长度与解析成本
|
||||
- 环境变量覆盖
|
||||
- 在容器编排中通过环境变量快速切换端口与目录，避免频繁修改配置文件
|
||||
- Docker 配置
|
||||
- 合理设置资源限制（内存、CPU、交换），避免容器争抢导致抖动
|
||||
- 启用 auto_cleanup 与合理的 container_ttl_seconds，降低长期运行的资源占用
|
||||
|
||||
[本节为通用指导，无需列出具体文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 常见配置错误
|
||||
- 监听端口或默认后端端口为 0：校验失败，需修正为有效端口
|
||||
- 后端主机或端口参数名为空：校验失败，需提供有效值
|
||||
- 代理无法启动
|
||||
- 检查代理监听端口是否被占用
|
||||
- 确认后端主机可达且端口开放
|
||||
- 健康检查异常
|
||||
- 调整 interval_seconds 与 timeout_seconds，避免过于敏感
|
||||
- 检查后端服务健康状态与响应时间
|
||||
- 环境变量覆盖无效
|
||||
- 确认环境变量命名正确（RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL）
|
||||
- 确认命令行参数未覆盖环境变量（命令行优先级最高）
|
||||
|
||||
章节来源
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L49-L68)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
|
||||
## 结论
|
||||
- PingoraConfig 为代理服务的核心配置载体，提供监听端口、默认后端端口、后端主机、端口参数名、配置文件路径与详细日志等关键参数。
|
||||
- 配置优先级链清晰明确：命令行 > 环境变量 > 配置文件，应用层在启动时严格遵循该顺序，确保部署灵活性与可控性。
|
||||
- 通过 config.yml 可定制代理行为与 Docker 运行参数，满足不同部署环境需求。
|
||||
- 建议在生产环境中合理设置健康检查与资源限制，并通过环境变量实现快速切换与运维。
|
||||
|
||||
[本节为总结性内容，无需列出具体文件来源]
|
||||
|
||||
## 附录
|
||||
- 关键字段对照表
|
||||
- 监听端口：listen_port
|
||||
- 默认后端端口：default_backend_port
|
||||
- 后端主机：backend_host
|
||||
- 端口参数名：port_param
|
||||
- 配置文件路径：config_file
|
||||
- 详细日志：verbose
|
||||
- 健康检查：enabled/interval_seconds/timeout_seconds/healthy_threshold/unhealthy_threshold
|
||||
- 参考路径：
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L8-L33)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L53-L80)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
[本节为参考性内容，无需列出具体文件来源]
|
||||
426
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/可观测性.md
Normal file
426
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/可观测性.md
Normal file
@@ -0,0 +1,426 @@
|
||||
# 可观测性
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs)
|
||||
- [rcoder 路由与状态](file://crates/rcoder/src/router.rs)
|
||||
- [agent_runner 路由与状态](file://crates/agent_runner/src/router.rs)
|
||||
- [rcoder 健康检查处理器](file://crates/rcoder/src/handler/health_handler.rs)
|
||||
- [agent_runner 健康检查处理器](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [服务镜像配置](file://crates/shared_types/src/service_config.rs)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件系统性阐述本仓库的可观测性实现，涵盖日志系统、链路追踪、性能监控与错误处理。内容基于实际代码库，提供面向初学者的易懂说明与面向资深工程师的技术深度，包括配置项、参数与返回值、组件关系、常见问题与解决方案。
|
||||
|
||||
## 项目结构
|
||||
- 两个主要服务：
|
||||
- rcoder：主服务，提供聊天、SSE 实时通知、代理与健康检查等能力
|
||||
- agent_runner：代理运行器，负责代理会话、清理任务与健康检查
|
||||
- 共享模块：
|
||||
- shared_types：共享模型与错误类型
|
||||
- 配置模块：统一的配置加载与环境变量覆盖
|
||||
- 追踪中间件：HTTP 请求级链路追踪与日志注入
|
||||
- 清理任务：闲置资源回收与孤立容器清理
|
||||
- 代理 API：Pingora 代理的状态、统计与配置查询
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 服务"
|
||||
RMain["rcoder 主程序<br/>初始化遥测/路由/代理"]
|
||||
RRouter["路由与状态<br/>/health /chat /agent/* /proxy/*"]
|
||||
RTracing["追踪中间件<br/>HTTP 请求追踪"]
|
||||
RClean["清理任务<br/>闲置容器/会话清理"]
|
||||
RProxyAPI["代理 API 处理器<br/>状态/统计/配置"]
|
||||
end
|
||||
subgraph "agent_runner 服务"
|
||||
AMain["agent_runner 主程序<br/>初始化遥测/路由/代理"]
|
||||
ARouter["路由与状态<br/>/health /chat /agent/* /proxy/*"]
|
||||
ATracing["追踪中间件<br/>HTTP 请求追踪"]
|
||||
AClean["清理任务<br/>闲置会话/SSE消息清理"]
|
||||
AProxyAPI["代理 API 处理器<br/>状态/统计/配置"]
|
||||
end
|
||||
subgraph "共享"
|
||||
SharedErr["共享错误类型<br/>AppError"]
|
||||
SharedCfg["服务镜像配置<br/>ServiceImageConfig"]
|
||||
end
|
||||
RMain --> RRouter --> RTracing
|
||||
RMain --> RClean
|
||||
RMain --> RProxyAPI
|
||||
AMain --> ARouter --> ATracing
|
||||
AMain --> AClean
|
||||
AMain --> AProxyAPI
|
||||
RRouter --> SharedErr
|
||||
ARouter --> SharedErr
|
||||
RMain --> SharedCfg
|
||||
AMain --> SharedCfg
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L1-L120)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L1-L120)
|
||||
- [rcoder 路由与状态](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [agent_runner 路由与状态](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L60)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L60)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L1-L120)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L120)
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [服务镜像配置](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L1-L120)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L1-L120)
|
||||
- [rcoder 路由与状态](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [agent_runner 路由与状态](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- 日志系统
|
||||
- 使用 tracing 与 tracing-subscriber 输出到文件与控制台，按天滚动，JSON 格式便于后续分析
|
||||
- rcoder 与 agent_runner 分别初始化各自的遥测系统，设置 TraceContextPropagator
|
||||
- 链路追踪
|
||||
- HTTP 请求中间件自动生成 trace_id，注入 OpenTelemetry 上下文，记录请求/响应
|
||||
- 中间件将 trace_id 放入请求扩展，便于后续处理器使用
|
||||
- 性能监控
|
||||
- Pingora 代理内置指标：总请求数、成功/失败响应数、平均响应时间等
|
||||
- 代理 API 提供 /proxy/status、/proxy/stats、/proxy/config 查询
|
||||
- 错误处理
|
||||
- 统一的 AppError 类型，实现 IntoResponse，返回标准化错误体
|
||||
- 代理 API 对未启用代理场景返回明确的错误码与消息
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 架构总览
|
||||
可观测性贯穿请求生命周期：从 HTTP 入口经中间件注入 trace_id，进入路由与处理器，期间产生日志与指标；代理服务提供运行时状态与统计；清理任务定期回收闲置资源；错误统一收敛。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum 路由"
|
||||
participant Tracing as "追踪中间件"
|
||||
participant Handler as "业务处理器"
|
||||
participant Proxy as "Pingora 代理"
|
||||
participant Cleaner as "清理任务"
|
||||
Client->>Router : "HTTP 请求"
|
||||
Router->>Tracing : "进入中间件"
|
||||
Tracing->>Tracing : "生成/提取 trace_id<br/>记录请求开始"
|
||||
Tracing->>Handler : "继续处理"
|
||||
Handler->>Proxy : "代理转发/查询"
|
||||
Proxy-->>Handler : "代理响应"
|
||||
Handler-->>Client : "业务响应"
|
||||
Tracing->>Tracing : "记录响应状态"
|
||||
Note over Cleaner : "定时扫描闲置资源并清理"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L220-L271)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L120-L178)
|
||||
- [rcoder 路由与状态](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [agent_runner 路由与状态](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L278-L310)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L294-L310)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 日志系统
|
||||
- 初始化
|
||||
- 创建 logs 目录，按天滚动，最多保留 N 份日志文件
|
||||
- 控制台输出简洁格式，文件输出 JSON 格式，包含目标、线程 ID/名称等
|
||||
- 设置全局 TextMapPropagator，支持 trace_id 传播
|
||||
- 输出位置
|
||||
- rcoder：日志前缀 rcoder
|
||||
- agent_runner：日志前缀 agent-runner
|
||||
- 使用方式
|
||||
- 通过 tracing::info/warn/error/debug 等宏记录结构化日志
|
||||
- 中间件在请求开始与结束处记录关键信息，便于关联 trace_id
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
### 链路追踪中间件
|
||||
- 功能要点
|
||||
- 自动生成 trace_id（UUID v4 简短格式）
|
||||
- 从常见 trace 请求头提取 trace_id（如 x-trace-id、traceparent 等）
|
||||
- 为每次请求创建 info_span，记录 method、URI、trace_id、User-Agent、Content-Type
|
||||
- 将 trace_id 插入请求扩展，供后续处理器使用
|
||||
- 在 span 中执行请求处理，记录响应状态
|
||||
- 适用范围
|
||||
- rcoder 与 agent_runner 各自提供独立的中间件实现，均注册到各自路由
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入中间件"]) --> Extract["尝试从请求头提取 trace_id"]
|
||||
Extract --> HasHeader{"是否包含有效 trace 头？"}
|
||||
HasHeader --> |是| UseHeader["使用请求头中的 trace_id"]
|
||||
HasHeader --> |否| GenNew["生成新的 trace_id"]
|
||||
UseHeader --> CreateSpan["创建请求 span含 trace_id 等字段"]
|
||||
GenNew --> CreateSpan
|
||||
CreateSpan --> LogStart["记录请求开始"]
|
||||
LogStart --> Inject["将 trace_id 注入请求扩展"]
|
||||
Inject --> RunHandler["继续处理下游处理器"]
|
||||
RunHandler --> LogEnd["记录响应状态"]
|
||||
LogEnd --> End(["返回响应"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L44-L130)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L44-L130)
|
||||
|
||||
章节来源
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L44-L130)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L44-L130)
|
||||
|
||||
### 健康检查与代理监控
|
||||
- 健康检查
|
||||
- /health 返回标准结构，包含状态、时间戳与服务名
|
||||
- rcoder 与 agent_runner 均提供独立实现
|
||||
- 代理监控
|
||||
- /proxy/status：返回代理配置、后端列表与健康状态快照
|
||||
- /proxy/stats：返回总请求数、成功/失败响应数、平均响应时间等指标
|
||||
- /proxy/config：返回代理配置与健康检查配置
|
||||
- 代理健康检查
|
||||
- 配置包含启用开关、检查间隔、超时、健康阈值与不健康阈值
|
||||
- 启动时可按配置启动健康检查循环
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant API as "代理 API 处理器"
|
||||
participant ProxySvc as "Pingora 代理服务"
|
||||
participant HC as "健康检查"
|
||||
Client->>API : "GET /proxy/status"
|
||||
API->>ProxySvc : "读取配置/后端/健康快照"
|
||||
ProxySvc-->>API : "聚合状态信息"
|
||||
API-->>Client : "返回状态/后端列表/健康状态"
|
||||
Client->>API : "GET /proxy/stats"
|
||||
API->>ProxySvc : "读取指标总请求数/成功/失败/平均响应时间"
|
||||
ProxySvc-->>API : "返回指标"
|
||||
API-->>Client : "返回统计信息"
|
||||
Client->>API : "GET /proxy/config"
|
||||
API->>ProxySvc : "读取代理配置"
|
||||
API->>HC : "读取健康检查配置"
|
||||
ProxySvc-->>API : "返回代理配置"
|
||||
HC-->>API : "返回健康检查配置"
|
||||
API-->>Client : "返回配置信息"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L206)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L206)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L52-L80)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs#L51-L73)
|
||||
|
||||
章节来源
|
||||
- [rcoder 健康检查处理器](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [agent_runner 健康检查处理器](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L206)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L206)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L52-L80)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs#L51-L73)
|
||||
|
||||
### 清理任务与资源回收
|
||||
- rcoder 清理任务
|
||||
- 基于 RAII 原则：从 project_and_agent_map 移除条目，触发 AgentLifecycleGuard 自动清理
|
||||
- 保护期：新建容器在最小保护时间内不清理，避免误删
|
||||
- 超时判断：考虑最后活动时间与创建时间，加入 1 秒缓冲避免时间误差
|
||||
- 孤立容器清理：扫描 rcoder-agent-* 容器，批量并行清理，限制单次清理数量
|
||||
- 超时保护：清理过程整体超时，防止阻塞
|
||||
- agent_runner 清理任务
|
||||
- 清理孤立的 SSE 会话与消息
|
||||
- 仅清理 Idle 状态且超时的 agent，避免中断 Active/Terminating 状态
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
ScanStart["开始扫描"] --> Collect["收集所有项目ID"]
|
||||
Collect --> Eval["逐个评估agent状态/最后活动/创建时间"]
|
||||
Eval --> Protected{"是否在保护期内？"}
|
||||
Protected --> |是| Skip["跳过清理"]
|
||||
Protected --> |否| Timeout{"是否超时且Idle？"}
|
||||
Timeout --> |否| Skip
|
||||
Timeout --> |是| Remove["从MAP移除触发RAII清理"]
|
||||
Remove --> Orphan["清理孤立SSE会话/消息"]
|
||||
Orphan --> Done["统计并记录清理结果"]
|
||||
Skip --> Done
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L248-L420)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L245)
|
||||
|
||||
章节来源
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L1-L420)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L245)
|
||||
|
||||
### 错误处理与返回值
|
||||
- 统一错误类型
|
||||
- AppError：AnyhowError、IoError、Generic
|
||||
- 实现 IntoResponse，返回 JSON 结构，包含 success=false 与 error.code/message
|
||||
- 代理 API 错误
|
||||
- 未启用代理时返回 SERVICE_UNAVAILABLE，携带错误码与消息
|
||||
- 健康检查
|
||||
- /health 返回标准结构，包含 status、timestamp、service
|
||||
|
||||
章节来源
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [rcoder 健康检查处理器](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [agent_runner 健康检查处理器](file://crates/agent_runner/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
### 配置与参数
|
||||
- rcoder 配置
|
||||
- AppConfig：default_agent、projects_dir、port、proxy_config、docker_config
|
||||
- ProxyConfig：listen_port、default_backend_port、backend_host、port_param、health_check
|
||||
- HealthCheckConfig：enabled、interval_seconds、timeout_seconds、healthy_threshold、unhealthy_threshold
|
||||
- DockerConfig：multi_image_config、network_mode、work_dir、auto_cleanup、container_ttl_seconds
|
||||
- agent_runner 配置
|
||||
- AppConfig：default_agent、projects_dir、port、proxy_config
|
||||
- ProxyConfig：listen_port、default_backend_port、backend_host、port_param、health_check
|
||||
- HealthCheckConfig：enabled、interval_seconds、timeout_seconds、healthy_threshold、unhealthy_threshold
|
||||
- 环境变量覆盖
|
||||
- rcoder：RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL
|
||||
- agent_runner：RCODER_PORT、RCODER_PROJECTS_DIR（部分）
|
||||
|
||||
章节来源
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L37-L110)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L112-L210)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs#L38-L110)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs#L112-L180)
|
||||
- [agent_runner 配置](file://crates/agent_runner/src/config.rs#L252-L315)
|
||||
|
||||
### 与容器与镜像的关系
|
||||
- 服务镜像配置
|
||||
- ServiceImageConfig：image/arm64_image/amd64_image/default_image、environment、mounts、resource_limits、work_dir、network_mode、container_path_template
|
||||
- 支持镜像选择、环境变量合并、挂载点校验与路径模板解析
|
||||
- Docker 配置
|
||||
- rcoder DockerConfig 支持多镜像配置与环境变量覆盖，提供验证与摘要信息
|
||||
- 启动时合并应用配置与多镜像配置，初始化全局 DockerManager
|
||||
|
||||
章节来源
|
||||
- [服务镜像配置](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [服务镜像配置](file://crates/shared_types/src/service_config.rs#L120-L262)
|
||||
- [服务镜像配置](file://crates/shared_types/src/service_config.rs#L314-L401)
|
||||
- [rcoder 配置](file://crates/rcoder/src/config.rs#L148-L211)
|
||||
|
||||
## 依赖关系分析
|
||||
- 日志与追踪
|
||||
- rcoder/agent_runner 主程序分别初始化 tracing-subscriber 与 OpenTelemetry Propagator
|
||||
- 追踪中间件依赖 tracing/tracing-opentelemetry，生成/注入 trace_id
|
||||
- 代理与监控
|
||||
- 代理 API 依赖 Pingora 服务对象，读取配置、后端列表与健康快照
|
||||
- 代理配置包含健康检查参数，启动时可开启健康检查循环
|
||||
- 清理任务
|
||||
- rcoder 清理任务依赖 DockerManager 全局实例，清理孤立容器与会话
|
||||
- agent_runner 清理任务清理 SSE 会话与消息
|
||||
- 错误处理
|
||||
- AppError 实现 IntoResponse，统一错误返回格式
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RCMain["rcoder 主程序"] --> RT["追踪中间件"]
|
||||
RCMain --> RP["代理 API 处理器"]
|
||||
RCMain --> RClean["rcoder 清理任务"]
|
||||
AMain["agent_runner 主程序"] --> AT["追踪中间件"]
|
||||
AMain --> AP["代理 API 处理器"]
|
||||
AMain --> AClean["agent_runner 清理任务"]
|
||||
RT --> TE["OpenTelemetry Propagator"]
|
||||
AT --> TE
|
||||
RP --> P["Pingora 代理服务"]
|
||||
AP --> P
|
||||
RClean --> DM["DockerManager 全局实例"]
|
||||
AClean --> SSE["SSE 会话/消息"]
|
||||
RP --> AE["AppError"]
|
||||
AP --> AE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L602)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L245)
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L602)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L245)
|
||||
- [共享错误类型](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 性能考量
|
||||
- 日志滚动与保留
|
||||
- 按天滚动，限制日志文件数量，降低磁盘占用与 IO 压力
|
||||
- 代理指标
|
||||
- 通过 /proxy/stats 获取平均响应时间等关键指标，辅助容量规划与性能调优
|
||||
- 清理策略
|
||||
- rcoder 清理任务对孤立容器清理加总超时与单次上限，避免阻塞
|
||||
- agent_runner 清理任务仅清理 Idle 且超时的 agent，避免中断活跃任务
|
||||
- 超时与保护
|
||||
- 清理过程整体超时、单容器清理超时、新建容器保护期，提升稳定性
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L602)
|
||||
- [agent_runner 清理任务](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L245)
|
||||
|
||||
## 故障排查指南
|
||||
- Docker 相关
|
||||
- 启动时自动检测宿主机挂载路径，失败时提供详细配置帮助与排错步骤
|
||||
- 建议检查 DOCKER_SOCKET_PATH、Docker socket 权限与挂载路径
|
||||
- 代理未启用
|
||||
- 调用 /proxy/* 接口返回 SERVICE_UNAVAILABLE，需确认代理配置与启动参数
|
||||
- 日志定位
|
||||
- 使用 trace_id 关联请求全链路日志，结合 /proxy/stats 观察异常时段的指标波动
|
||||
- 清理异常
|
||||
- rcoder 清理任务对单次清理与总清理过程设置超时，若出现长时间卡顿，检查 Docker API 可用性与容器状态
|
||||
- 健康检查
|
||||
- /health 返回 healthy 表示服务正常，若异常需结合日志与代理状态进一步排查
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L48-L118)
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L322-L351)
|
||||
- [rcoder 代理 API 处理器](file://crates/rcoder/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [agent_runner 代理 API 处理器](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L1-L120)
|
||||
- [rcoder 清理任务](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L602)
|
||||
|
||||
## 结论
|
||||
本项目通过统一的日志与链路追踪中间件、Pingora 代理指标、定时清理任务与统一错误类型，构建了完善的可观测性体系。rcoder 与 agent_runner 在同一套可观测框架下运行，既保证了跨服务的 trace_id 一致性，又提供了可操作的健康检查与代理监控接口。建议在生产环境中结合日志滚动策略、代理指标与清理任务配置，持续优化性能与稳定性。
|
||||
297
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/日志系统.md
Normal file
297
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/日志系统.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 日志系统
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [诊断脚本](file://docker/scripts/diagnose-blocking.sh)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件系统性阐述基于 tracing 和 tracing-appender 的日志实现，覆盖以下要点：
|
||||
- 控制台与文件双输出配置
|
||||
- JSON 格式化输出
|
||||
- 按天滚动策略与日志保留
|
||||
- 日志级别与过滤
|
||||
- 线程信息包含
|
||||
- 与链路追踪的集成（trace_id 注入）
|
||||
- 常见问题（路径不存在、权限不足）及解决方案
|
||||
- 性能优化建议（异步写入、滚动开销）
|
||||
|
||||
该说明面向初学者与资深开发者，既提供清晰的背景知识，也给出深入的技术细节与可视化图示。
|
||||
|
||||
## 项目结构
|
||||
日志系统在两个二进制服务中分别初始化：
|
||||
- rcoder 服务：负责主业务逻辑与容器管理
|
||||
- agent_runner 服务：负责代理与子进程交互
|
||||
|
||||
两者均通过统一的遥测初始化流程，创建 logs 目录、配置文件 appender、控制台层，并注册 EnvFilter 作为日志级别来源。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 服务"
|
||||
RMain["crates/rcoder/src/main.rs<br/>init_telemetry()"]
|
||||
RMid["crates/rcoder/src/middleware/tracing_middleware.rs<br/>HTTP 追踪中间件"]
|
||||
end
|
||||
subgraph "agent_runner 服务"
|
||||
AMain["crates/agent_runner/src/main.rs<br/>init_telemetry()"]
|
||||
AMid["crates/agent_runner/src/middleware/tracing_middleware.rs<br/>HTTP 追踪中间件"]
|
||||
end
|
||||
RMain --> |"注册 EnvFilter + 文件层 + 控制台层"| RMain
|
||||
AMain --> |"注册 EnvFilter + 文件层 + 控制台层"| AMain
|
||||
RMid --> |"生成/提取 trace_id 并注入 span"| RMain
|
||||
AMid --> |"生成/提取 trace_id 并注入 span"| AMain
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L91-L105)
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
## 核心组件
|
||||
- 日志订阅者与层级
|
||||
- EnvFilter：从环境变量读取日志级别，若未设置则回退到默认级别
|
||||
- 文件层（JSON）：按天滚动，保留最近 N 份日志文件
|
||||
- 控制台层：简洁输出，便于本地调试
|
||||
- 链路追踪集成
|
||||
- 设置全局 TextMapPropagator，支持 trace context 传播
|
||||
- HTTP 中间件为每个请求生成/提取 trace_id，并注入到日志 span
|
||||
- 目录与文件管理
|
||||
- 启动时自动创建 logs 目录
|
||||
- 文件名前缀区分不同服务（rcoder、agent-runner）
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
## 架构总览
|
||||
日志系统由“订阅者注册 + 层级配置 + 过滤 + 追踪中间件”构成，形成“双输出 + 结构化 + 可追踪”的日志体系。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Svc as "服务进程"
|
||||
participant Sub as "tracing_subscriber : : registry"
|
||||
participant Env as "EnvFilter"
|
||||
participant F as "文件层(JSON)"
|
||||
participant C as "控制台层"
|
||||
participant Mid as "HTTP 追踪中间件"
|
||||
participant Log as "日志输出"
|
||||
Svc->>Sub : 初始化订阅者
|
||||
Sub->>Env : 注册 EnvFilter
|
||||
Sub->>F : 注册文件层(JSON)
|
||||
Sub->>C : 注册控制台层
|
||||
Svc->>Mid : 注入 HTTP 中间件
|
||||
Mid->>Mid : 提取/生成 trace_id
|
||||
Mid->>Log : 写入带 trace_id 的结构化日志
|
||||
F-->>Log : 写入 JSON 日志
|
||||
C-->>Log : 写入控制台日志
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 1) 日志订阅者与层级配置
|
||||
- EnvFilter
|
||||
- 从环境变量读取日志级别；若未设置，则 rcoder 回退到 info，agent_runner 回退到更细粒度的调试级别
|
||||
- 文件层（JSON）
|
||||
- 使用 tracing-appender 的按天滚动策略
|
||||
- 通过 filename_prefix 区分服务
|
||||
- max_log_files 限制保留的旧日志数量
|
||||
- 输出 JSON，便于后续结构化分析
|
||||
- 控制台层
|
||||
- 简洁输出，便于本地快速查看
|
||||
- 关闭 ANSI，避免非终端环境污染
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
### 2) 日志目录创建与文件滚动策略
|
||||
- 目录创建
|
||||
- 启动时检查 logs 目录是否存在，不存在则创建
|
||||
- 滚动策略
|
||||
- Rotation::DAILY：按自然日滚动
|
||||
- filename_prefix：rcoder 或 agent-runner 前缀
|
||||
- max_log_files：保留最近 N 个日志文件，超出自动清理
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
### 3) 日志级别与输出格式
|
||||
- 日志级别
|
||||
- EnvFilter 优先级：环境变量 > 默认值
|
||||
- rcoder 默认 info
|
||||
- agent_runner 默认更细粒度，便于调试
|
||||
- 输出格式
|
||||
- 文件层：JSON，包含目标、线程 ID、线程名等字段
|
||||
- 控制台层：简洁，便于人类阅读
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
### 4) 线程信息包含
|
||||
- 文件层开启线程 ID 与线程名，便于定位并发场景下的日志来源
|
||||
- 控制台层关闭线程信息，避免冗余
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
### 5) 链路追踪与 trace_id 注入
|
||||
- 全局传播器
|
||||
- 设置 TraceContextPropagator，支持 trace context 传播
|
||||
- HTTP 中间件
|
||||
- 从请求头提取 trace_id；若无则生成新的 UUID
|
||||
- 为每次请求创建 info_span，携带 trace_id、方法、URI、UA、Content-Type 等
|
||||
- 将 trace_id 注入请求扩展，便于后续处理器使用
|
||||
- 在 span 中记录请求开始与结束，形成完整的调用链日志
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum 路由"
|
||||
participant Mid as "Tracing 中间件"
|
||||
participant Handler as "业务处理器"
|
||||
participant Log as "日志系统(JSON/控制台)"
|
||||
Client->>Router : HTTP 请求
|
||||
Router->>Mid : 进入中间件
|
||||
Mid->>Mid : 提取/生成 trace_id
|
||||
Mid->>Log : 写入请求开始日志(含 trace_id)
|
||||
Mid->>Handler : 调用业务处理器
|
||||
Handler-->>Mid : 返回响应
|
||||
Mid->>Log : 写入请求结束日志(含 trace_id)
|
||||
Mid-->>Router : 返回响应
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
### 6) 类图：日志与追踪相关组件
|
||||
```mermaid
|
||||
classDiagram
|
||||
class InitTelemetry {
|
||||
+init_telemetry() Result
|
||||
}
|
||||
class EnvFilter {
|
||||
+try_from_default_env() Filter
|
||||
}
|
||||
class FileLayer {
|
||||
+json()
|
||||
+with_writer(writer)
|
||||
+with_target(flag)
|
||||
+with_thread_ids(flag)
|
||||
+with_thread_names(flag)
|
||||
}
|
||||
class ConsoleLayer {
|
||||
+with_target(flag)
|
||||
+with_ansi(flag)
|
||||
}
|
||||
class TracingMiddleware {
|
||||
+tracing_middleware_handler(req,next) Response
|
||||
+add_tracing_layer(router) Router
|
||||
}
|
||||
InitTelemetry --> EnvFilter : "注册"
|
||||
InitTelemetry --> FileLayer : "注册"
|
||||
InitTelemetry --> ConsoleLayer : "注册"
|
||||
TracingMiddleware --> InitTelemetry : "配合使用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [rcoder 追踪中间件](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [agent_runner 追踪中间件](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
## 依赖分析
|
||||
- 核心依赖
|
||||
- tracing、tracing-subscriber：日志框架与订阅者
|
||||
- tracing-appender：文件滚动与 writer
|
||||
- opentelemetry、opentelemetry_sdk、tracing-opentelemetry、axum-tracing-opentelemetry：链路追踪与传播
|
||||
- uuid：生成 trace_id
|
||||
- 服务差异
|
||||
- rcoder：EnvFilter 默认 info
|
||||
- agent_runner：EnvFilter 默认更细粒度，便于调试
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L91-L105)
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
## 性能考量
|
||||
- 异步日志写入
|
||||
- tracing-appender 默认异步写入，减少阻塞
|
||||
- 建议保持默认异步配置，避免同步 I/O 导致延迟放大
|
||||
- 滚动开销
|
||||
- 按天滚动在高吞吐下会产生少量文件系统操作
|
||||
- max_log_files 控制保留数量，避免无限增长
|
||||
- JSON 输出
|
||||
- JSON 格式便于结构化分析，但序列化成本略高于文本
|
||||
- 若对性能极度敏感，可在生产环境切换为文本格式或减少字段
|
||||
- 级别过滤
|
||||
- EnvFilter 仅在必要时进行解析，建议通过环境变量集中管理
|
||||
- 并发与线程信息
|
||||
- 启用线程 ID/名称会增加少量开销，建议仅在调试阶段开启
|
||||
|
||||
[本节为通用性能建议，无需特定文件来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 日志文件路径不存在
|
||||
- 现象：启动时报错或无日志文件
|
||||
- 处理：确认 logs 目录存在；若不存在，服务会自动创建
|
||||
- 参考：日志初始化中包含目录创建逻辑
|
||||
- 权限不足
|
||||
- 现象：无法写入日志文件
|
||||
- 处理：确保运行用户对 logs 目录具有写权限
|
||||
- 日志过多占用磁盘
|
||||
- 现象：磁盘空间被占满
|
||||
- 处理：调整 max_log_files，或定期清理旧日志
|
||||
- 无法看到 trace_id
|
||||
- 现象：日志中缺少 trace_id
|
||||
- 处理：确认中间件已注入；检查请求头是否携带 trace_id；或允许自动生成
|
||||
- 诊断脚本辅助
|
||||
- 使用诊断脚本检查今日日志中的 ERROR/WARN
|
||||
- 参考：诊断脚本中对日志文件的读取与错误定位
|
||||
|
||||
章节来源
|
||||
- [rcoder 主程序](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [agent_runner 主程序](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [诊断脚本](file://docker/scripts/diagnose-blocking.sh#L49-L85)
|
||||
|
||||
## 结论
|
||||
该日志系统以 tracing 为核心，结合 tracing-appender 实现了“双输出 + JSON + 按天滚动 + trace_id 注入”的完整方案。通过 EnvFilter 精准控制日志级别，借助 HTTP 中间件将 trace_id 无缝注入到每条日志中，既满足日常运维需求，又为分布式追踪提供了坚实基础。建议在生产环境中保持异步写入与合理的滚动策略，并根据需要调整日志级别与输出格式，以平衡可观测性与性能。
|
||||
188
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/链路追踪.md
Normal file
188
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/链路追踪.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# 链路追踪
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [Cargo.lock](file://Cargo.lock)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [trace_id生成与传播机制](#trace_id生成与传播机制)
|
||||
3. [追踪中间件实现](#追踪中间件实现)
|
||||
4. [OpenTelemetry集成配置](#opentelemetry集成配置)
|
||||
5. [日志系统协同工作](#日志系统协同工作)
|
||||
6. [常见问题与解决方案](#常见问题与解决方案)
|
||||
7. [性能优化建议](#性能优化建议)
|
||||
8. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
|
||||
链路追踪是分布式系统中至关重要的可观测性工具，它能够帮助开发者理解请求在系统中的完整执行路径。本项目基于OpenTelemetry实现了完整的分布式追踪系统，通过`tracing_middleware_handler`中间件为每个HTTP请求生成和传播`trace_id`，并将其与日志系统深度集成。该系统支持跨服务的请求追踪，确保在复杂的微服务架构中能够准确地定位问题和分析性能瓶颈。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
|
||||
## trace_id生成与传播机制
|
||||
|
||||
### trace_id生成策略
|
||||
|
||||
系统采用UUID v4作为`trace_id`的生成策略，确保了全局唯一性和高熵值。在`tracing_middleware.rs`文件中，`generate_trace_id()`函数通过`uuid::Uuid::new_v4().simple().to_string()`生成32位无连字符的UUID字符串。这种格式既保证了唯一性，又便于日志记录和查询。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([请求到达]) --> ExtractHeader["从请求头提取 trace_id"]
|
||||
ExtractHeader --> HasTraceID{存在 trace_id?}
|
||||
HasTraceID --> |是| UseExisting["使用现有 trace_id"]
|
||||
HasTraceID --> |否| GenerateNew["生成新的 UUID v4"]
|
||||
GenerateNew --> Format["转换为 simple 格式 (32位)"]
|
||||
Format --> UseNew["使用新生成的 trace_id"]
|
||||
UseExisting --> CreateSpan
|
||||
UseNew --> CreateSpan
|
||||
CreateSpan["创建包含 trace_id 的 span"]
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L44-L47)
|
||||
|
||||
### 请求头提取逻辑
|
||||
|
||||
系统支持从多种标准请求头中提取`trace_id`，包括`x-trace-id`、`x-request-id`、`traceparent`和`x-correlation-id`。`extract_trace_id_from_headers()`函数遍历这些头字段，优先使用最先找到的有效值。这种多头支持的设计提高了系统的兼容性，能够与不同的追踪系统和代理工具无缝集成。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L49-L69)
|
||||
|
||||
## 追踪中间件实现
|
||||
|
||||
### tracing_middleware_handler完整流程
|
||||
|
||||
`tracing_middleware_handler`是链路追踪的核心处理函数，它在请求处理管道中扮演着关键角色。该函数首先从请求头中提取或生成`trace_id`，然后创建一个包含丰富上下文信息的span。通过`info_span!`宏，系统记录了HTTP方法、URI、用户代理、内容类型等关键信息。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Middleware as "追踪中间件"
|
||||
participant Handler as "业务处理器"
|
||||
Client->>Middleware : HTTP请求 (含trace_id头)
|
||||
Middleware->>Middleware : 提取/生成trace_id
|
||||
Middleware->>Middleware : 创建http_request span
|
||||
Middleware->>Handler : 调用next.run()
|
||||
Handler->>Handler : 业务逻辑处理
|
||||
Handler->>Middleware : 返回响应
|
||||
Middleware->>Middleware : 记录响应信息
|
||||
Middleware->>Client : HTTP响应
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
### info_span!宏的使用
|
||||
|
||||
`info_span!`宏用于创建结构化的日志span，它不仅记录了基本的请求信息，还包含了`trace_id`作为核心标识。在中间件中，span的创建包含了HTTP方法、URI、`trace_id`、用户代理和内容类型等字段，为后续的调试和分析提供了丰富的上下文信息。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Span {
|
||||
+method : String
|
||||
+uri : String
|
||||
+trace_id : String
|
||||
+user_agent : Option<String>
|
||||
+content_type : Option<String>
|
||||
}
|
||||
class TraceContext {
|
||||
+trace_id : String
|
||||
+span_id : String
|
||||
+trace_flags : u8
|
||||
}
|
||||
Span --> TraceContext : "包含"
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L86-L93)
|
||||
|
||||
### .instrument(span)调用
|
||||
|
||||
`.instrument(span)`是tracing框架的关键特性，它将异步代码块与创建的span关联起来。在中间件中，整个请求处理过程被包裹在`.instrument(span)`中，确保了所有在该代码块内生成的日志都会自动关联到同一个`trace_id`下。这种设计实现了零侵入式的追踪集成，业务代码无需关心追踪细节。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L126-L127)
|
||||
|
||||
## OpenTelemetry集成配置
|
||||
|
||||
### 上下文注入配置
|
||||
|
||||
系统通过`opentelemetry::global::set_text_map_propagator()`设置了全局的文本映射传播器，使用`TraceContextPropagator::new()`来处理W3C Trace Context标准。这确保了`traceparent`头能够在服务间正确传播，实现了跨服务的链路追踪。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L302-L305)
|
||||
|
||||
### Jaeger后端集成
|
||||
|
||||
通过Cargo.toml中的依赖配置，系统集成了Jaeger作为追踪后端。`cf-rustracing-jaeger`依赖在Cargo.lock中被明确列出，表明系统支持将追踪数据发送到Jaeger服务器进行可视化和分析。这种集成使得开发者可以通过Jaeger UI直观地查看请求的完整调用链路。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [Cargo.lock](file://Cargo.lock#L969-L983)
|
||||
|
||||
## 日志系统协同工作
|
||||
|
||||
### trace_id一致性保证
|
||||
|
||||
系统通过多种机制确保`trace_id`在所有日志条目中保持一致。首先，在请求开始时生成的`trace_id`被存储在请求扩展中（`req.extensions_mut().insert(trace_id.clone())`），可供后续处理器访问。其次，通过`.instrument(span)`确保了整个请求处理过程中的所有日志都自动关联到同一个span。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[请求到达] --> B[生成/提取trace_id]
|
||||
B --> C[创建span并注入context]
|
||||
C --> D[将trace_id存入请求扩展]
|
||||
D --> E[处理请求]
|
||||
E --> F[所有日志自动包含trace_id]
|
||||
F --> G[响应返回]
|
||||
```
|
||||
|
||||
**图示来源**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L106-L109)
|
||||
|
||||
### JSON日志格式
|
||||
|
||||
系统配置了JSON格式的日志输出，便于后续的集中式日志分析。通过`fmt::layer().json()`设置，所有日志以结构化JSON格式写入文件，包含时间戳、级别、目标、消息和自定义字段（如`trace_id`）。这种格式与ELK或Loki等日志系统完美兼容。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L291-L297)
|
||||
|
||||
## 常见问题与解决方案
|
||||
|
||||
### trace_id丢失问题
|
||||
|
||||
`trace_id`丢失通常发生在异步任务或跨线程调用中。解决方案是确保在任务创建时正确传播OpenTelemetry上下文。对于`!Send`类型的值，可以使用`tokio::task::LocalSet`来确保它们在同一个线程中执行，避免上下文丢失。
|
||||
|
||||
### 跨服务传播失败
|
||||
|
||||
跨服务传播失败可能是由于代理或网关修改了请求头。确保`x-trace-id`、`traceparent`等头字段在服务间传递时未被过滤或修改。在Kubernetes环境中，检查Ingress控制器的配置，确保追踪头被正确转发。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
|
||||
## 性能优化建议
|
||||
|
||||
### 采样策略
|
||||
|
||||
在高流量场景下，建议配置合理的采样策略以减少追踪数据量。可以通过设置`EnvFilter`来控制追踪的详细程度，例如只对错误请求或特定路径进行全量追踪，对正常请求进行低频采样。
|
||||
|
||||
### span开销控制
|
||||
|
||||
避免在热点路径上创建过多细粒度的span，这会增加性能开销。建议只在关键业务逻辑和外部调用处创建span。对于高频调用的简单操作，可以考虑使用计时器而非完整的span。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L309-L311)
|
||||
|
||||
## 结论
|
||||
|
||||
本项目的链路追踪实现基于OpenTelemetry标准，通过精心设计的中间件和配置，实现了高效、可靠的分布式追踪功能。`trace_id`的生成和传播机制确保了请求的完整可追溯性，与日志系统的深度集成提供了强大的调试能力。对于初学者，系统提供了清晰的`trace_id`生命周期；对于专家，提供了丰富的性能优化选项。这种分层的设计既满足了基本的可观测性需求，又为高级用例留下了扩展空间。
|
||||
365
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/错误处理.md
Normal file
365
qiming-rcoder/.qoder/repowiki/zh/content/可观测性/错误处理.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# 错误处理
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心错误类型](#核心错误类型)
|
||||
3. [HTTP中间件错误处理](#http中间件错误处理)
|
||||
4. [应用级错误结构](#应用级错误结构)
|
||||
5. [错误传播与日志记录](#错误传播与日志记录)
|
||||
6. [错误分类与状态码映射](#错误分类与状态码映射)
|
||||
7. [错误信息暴露策略](#错误信息暴露策略)
|
||||
8. [可观测性集成](#可观测性集成)
|
||||
9. [常见问题与解决方案](#常见问题与解决方案)
|
||||
10. [错误处理流程图](#错误处理流程图)
|
||||
11. [监控与告警最佳实践](#监控与告警最佳实践)
|
||||
|
||||
## 简介
|
||||
本文档全面解释系统中的错误处理机制，重点描述在 `tracing_middleware_handler` 中如何捕获和处理HTTP中间件错误，包括 `Result<Response, StatusCode>` 的返回模式。结合 `shared_types` 中的 `AppError` 模型，说明应用级错误的结构设计和序列化方式。文档包括来自实际代码库的具体示例，如中间件中错误的传播和日志记录，以及错误处理与可观测性的集成。
|
||||
|
||||
## 核心错误类型
|
||||
|
||||
系统采用分层错误处理架构，主要包含两种核心错误类型：`AppError` 和 `HttpResult`。`AppError` 作为应用级错误的统一抽象，封装了不同来源的错误，而 `HttpResult` 则是标准化的HTTP响应格式，用于向客户端返回一致的错误信息。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppError {
|
||||
+AnyhowError(anyhow : : Error)
|
||||
+IoError(std : : io : : Error)
|
||||
+Generic(String)
|
||||
+generic(msg : impl Into<String>) AppError
|
||||
+internal_server_error(msg : &str) AppError
|
||||
+validation_error(msg : &str) AppError
|
||||
}
|
||||
class HttpResult~T~ {
|
||||
+code : String
|
||||
+message : String
|
||||
+data : Option~T~
|
||||
+tid : Option~String~
|
||||
+success : bool
|
||||
+success(data : T) HttpResult~T~
|
||||
+error(code : &str, message : &str) HttpResult~T~
|
||||
+internal_error(message : &str) HttpResult~T~
|
||||
}
|
||||
AppError --> "implements" axum : : response : : IntoResponse
|
||||
HttpResult~T~ --> "implements" axum : : response : : IntoResponse
|
||||
HttpResult~T~ --> "serializes to" JSON
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L3-L30)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L58)
|
||||
|
||||
**本节源**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L64)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## HTTP中间件错误处理
|
||||
|
||||
`tracing_middleware_handler` 是系统中的核心HTTP中间件，负责请求追踪和错误处理。该中间件采用 `Result<Response, StatusCode>` 的返回模式，确保所有HTTP请求都能被正确处理或以适当的HTTP状态码返回错误。
|
||||
|
||||
中间件的主要功能包括：
|
||||
1. 为每个HTTP请求自动生成 `trace_id`
|
||||
2. 创建请求span用于日志跟踪
|
||||
3. 记录请求和响应信息
|
||||
4. 自动将 `trace_id` 注入到OpenTelemetry上下文中
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Middleware as "tracing_middleware_handler"
|
||||
participant Next as "下一个处理器"
|
||||
participant Response as "响应"
|
||||
Client->>Middleware : HTTP请求
|
||||
Middleware->>Middleware : 提取或生成trace_id
|
||||
Middleware->>Middleware : 创建追踪span
|
||||
Middleware->>Middleware : 记录请求开始日志
|
||||
Middleware->>Next : 调用next.run()
|
||||
Next-->>Middleware : 返回Response
|
||||
Middleware->>Middleware : 记录响应完成日志
|
||||
Middleware->>Response : 返回Result<Response, StatusCode>
|
||||
Response-->>Client : HTTP响应
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
**本节源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
## 应用级错误结构
|
||||
|
||||
`AppError` 枚举是系统中应用级错误的核心数据结构，定义了三种主要的错误类型：
|
||||
|
||||
1. **AnyhowError**: 包装 `anyhow::Error` 类型，用于处理任意错误
|
||||
2. **IoError**: 包装标准库的 `std::io::Error`，用于处理I/O操作错误
|
||||
3. **Generic**: 通用错误类型，用于表示自定义错误消息
|
||||
|
||||
`AppError` 实现了 `axum::response::IntoResponse` trait，使其可以直接作为HTTP响应返回。当错误发生时，系统会根据错误类型映射到相应的HTTP状态码，并生成结构化的JSON响应。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([错误发生]) --> MatchError["匹配AppError类型"]
|
||||
MatchError --> AnyhowError{"是AnyhowError?"}
|
||||
AnyhowError --> |是| Set500["设置状态码500"]
|
||||
MatchError --> IoError{"是IoError?"}
|
||||
IoError --> |是| Set500
|
||||
MatchError --> Generic{"是Generic?"}
|
||||
Generic --> |是| Set500
|
||||
Set500 --> CreateJSON["创建JSON响应体"]
|
||||
CreateJSON --> ReturnResponse["返回Response"]
|
||||
ReturnResponse --> End([错误响应完成])
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L56)
|
||||
|
||||
**本节源**
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L64)
|
||||
|
||||
## 错误传播与日志记录
|
||||
|
||||
系统中的错误传播遵循Rust的错误处理最佳实践，使用 `?` 操作符进行错误传播，并在适当的位置使用 `map_err` 进行错误转换。这种模式确保了错误信息能够在调用栈中正确传递，同时保持代码的简洁性。
|
||||
|
||||
在日志记录方面，系统使用 `tracing` 库进行结构化日志记录。每个错误都会被记录为包含 `trace_id` 的结构化日志条目，便于后续的错误追踪和分析。
|
||||
|
||||
```rust
|
||||
// 示例：错误传播和日志记录
|
||||
let project_workspace = get_project_workspace(&project_id).await?;
|
||||
```
|
||||
|
||||
```rust
|
||||
// 示例：错误转换
|
||||
.map_err(|e| anyhow::anyhow!(e))?;
|
||||
```
|
||||
|
||||
```rust
|
||||
// 示例：错误日志记录
|
||||
error!(
|
||||
"❌ 收到 agent 执行结果失败: {}",
|
||||
e
|
||||
);
|
||||
```
|
||||
|
||||
**本节源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L261-L261)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L283-L283)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L312-L316)
|
||||
|
||||
## 错误分类与状态码映射
|
||||
|
||||
系统采用统一的错误分类和状态码映射策略，确保错误处理的一致性。错误分类主要基于错误的严重程度和来源：
|
||||
|
||||
1. **客户端错误** (4xx): 由客户端请求引起的错误，如参数验证失败
|
||||
2. **服务器错误** (5xx): 由服务器内部问题引起的错误，如数据库连接失败
|
||||
3. **业务逻辑错误**: 特定于业务场景的错误，使用自定义错误码
|
||||
|
||||
状态码映射遵循HTTP标准，同时使用自定义错误码提供更详细的错误信息。例如，`5000` 表示内部服务器错误，`9010` 表示Agent正在执行任务等。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
ERROR_CATEGORY {
|
||||
string code PK
|
||||
string name
|
||||
string description
|
||||
int http_status
|
||||
string severity
|
||||
}
|
||||
ERROR_CODE {
|
||||
string code PK
|
||||
string category FK
|
||||
string message
|
||||
string solution
|
||||
datetime created_at
|
||||
}
|
||||
ERROR_CATEGORY ||--o{ ERROR_CODE : contains
|
||||
ERROR_CATEGORY {
|
||||
"CLIENT_ERROR" "客户端错误" "请求参数错误等" 400 "HIGH"
|
||||
"SERVER_ERROR" "服务器错误" "内部服务错误" 500 "CRITICAL"
|
||||
"BUSINESS_ERROR" "业务错误" "业务逻辑错误" 400 "MEDIUM"
|
||||
}
|
||||
ERROR_CODE {
|
||||
"0001" "BUSINESS_ERROR" "停止智能体执行失败" "重试或联系管理员" "2024-01-01"
|
||||
"5000" "SERVER_ERROR" "内部服务器错误" "检查服务日志" "2024-01-01"
|
||||
"9010" "BUSINESS_ERROR" "Agent正在执行任务" "等待当前任务完成" "2024-01-01"
|
||||
"PROMPT001" "SERVER_ERROR" "Agent处理失败" "检查Agent状态" "2024-01-01"
|
||||
}
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L56-L57)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L213-L213)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L218-L218)
|
||||
|
||||
**本节源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L46-L58)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L134-L138)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L181-L184)
|
||||
|
||||
## 错误信息暴露策略
|
||||
|
||||
系统采用谨慎的错误信息暴露策略，平衡了调试需求和安全考虑。错误信息暴露遵循以下原则：
|
||||
|
||||
1. **生产环境最小化暴露**: 在生产环境中，只暴露必要的错误信息，避免泄露敏感信息
|
||||
2. **开发环境详细暴露**: 在开发环境中，提供详细的错误信息，便于调试
|
||||
3. **结构化错误响应**: 所有错误都以统一的JSON格式返回，包含错误码、消息和trace_id
|
||||
|
||||
`HttpResult` 结构的设计体现了这一策略，它包含 `code`、`message`、`data`、`tid` 和 `success` 字段，确保客户端能够获得足够的信息来处理错误，同时不会暴露过多的内部细节。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Production
|
||||
[*] --> Development
|
||||
Production --> ErrorHandling : 发生错误
|
||||
Development --> ErrorHandling : 发生错误
|
||||
ErrorHandling --> CheckEnvironment : 检查环境
|
||||
CheckEnvironment --> |生产环境| MinimizeInfo : 最小化错误信息
|
||||
CheckEnvironment --> |开发环境| DetailedInfo : 详细错误信息
|
||||
MinimizeInfo --> FormatResponse : 格式化为标准响应
|
||||
DetailedInfo --> FormatResponse : 格式化为标准响应
|
||||
FormatResponse --> LogError : 记录完整错误日志
|
||||
LogError --> ReturnResponse : 返回响应
|
||||
ReturnResponse --> [*]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L33)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L56)
|
||||
|
||||
**本节源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## 可观测性集成
|
||||
|
||||
错误处理与系统的可观测性深度集成，主要体现在以下几个方面：
|
||||
|
||||
1. **分布式追踪**: 每个请求都分配唯一的 `trace_id`，贯穿整个请求处理链路
|
||||
2. **结构化日志**: 所有错误日志都包含 `trace_id`，便于跨服务追踪
|
||||
3. **指标监控**: 错误发生时记录相应的指标，用于监控和告警
|
||||
|
||||
`trace_id` 的生成和传播机制确保了在复杂的微服务架构中，能够快速定位和诊断问题。系统优先从请求头中提取 `trace_id`，如果不存在则生成新的UUID作为 `trace_id`。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[客户端请求] --> B{包含trace_id?}
|
||||
B --> |是| C[使用请求中的trace_id]
|
||||
B --> |否| D[生成新的trace_id]
|
||||
C --> E[注入到OpenTelemetry上下文]
|
||||
D --> E
|
||||
E --> F[记录带trace_id的日志]
|
||||
F --> G[传播到下游服务]
|
||||
G --> H[集中式日志系统]
|
||||
H --> I[错误分析和根因定位]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L80-L83)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L9-L22)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L51-L51)
|
||||
|
||||
**本节源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## 常见问题与解决方案
|
||||
|
||||
在实际使用中，可能会遇到一些常见的错误处理问题，以下是这些问题及其解决方案：
|
||||
|
||||
### 错误信息泄露
|
||||
**问题**: 生产环境中暴露了过多的内部错误细节，可能导致安全风险。
|
||||
**解决方案**: 实现环境感知的错误响应策略，在生产环境中只返回通用的错误消息，详细的错误信息仅在开发环境中暴露。
|
||||
|
||||
### 错误码不一致
|
||||
**问题**: 不同的处理器使用不同的错误码，导致客户端难以处理。
|
||||
**解决方案**: 建立统一的错误码注册表，所有错误码都从中心化的位置获取，确保一致性。
|
||||
|
||||
### trace_id丢失
|
||||
**问题**: 在某些异步操作中，`trace_id` 可能丢失，导致无法完整追踪请求链路。
|
||||
**解决方案**: 在 `HttpResult` 的 `into_response` 实现中添加 `trace_id` 的补全逻辑，确保即使在中间件之外创建的响应也能包含 `trace_id`。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[问题识别] --> B[错误信息泄露]
|
||||
A --> C[错误码不一致]
|
||||
A --> D[trace_id丢失]
|
||||
B --> E[实施环境感知响应]
|
||||
C --> F[建立错误码注册表]
|
||||
D --> G[实现trace_id补全]
|
||||
E --> H[解决方案]
|
||||
F --> H
|
||||
G --> H
|
||||
H --> I[改进的错误处理]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L82-L84)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L17-L29)
|
||||
|
||||
**本节源**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L78-L85)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L16-L30)
|
||||
|
||||
## 错误处理流程图
|
||||
|
||||
以下是系统错误处理的完整流程图，展示了从错误发生到最终响应的整个过程：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[HTTP请求] --> B[tracing_middleware]
|
||||
B --> C[提取/生成trace_id]
|
||||
C --> D[创建追踪span]
|
||||
D --> E[调用业务处理器]
|
||||
E --> F{发生错误?}
|
||||
F --> |是| G[捕获错误]
|
||||
F --> |否| H[返回成功响应]
|
||||
G --> I[转换为AppError]
|
||||
I --> J[记录错误日志]
|
||||
J --> K[创建HttpResult错误响应]
|
||||
K --> L[序列化为JSON]
|
||||
L --> M[返回HTTP错误响应]
|
||||
H --> N[创建HttpResult成功响应]
|
||||
N --> O[序列化为JSON]
|
||||
O --> P[返回HTTP成功响应]
|
||||
M --> Q[客户端]
|
||||
P --> Q
|
||||
style F fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style G fill:#f96,stroke:#333,stroke-width:2px
|
||||
style H fill:#6f9,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L56)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L77-L102)
|
||||
|
||||
**本节源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L56)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L77-L102)
|
||||
|
||||
## 监控与告警最佳实践
|
||||
|
||||
为了有效监控和告警系统中的错误，建议采用以下最佳实践：
|
||||
|
||||
1. **基于trace_id的根因分析**: 利用 `trace_id` 作为关键字，在日志系统中搜索完整的请求链路，快速定位问题根源。
|
||||
2. **错误率监控**: 监控不同错误码的发生频率，设置告警阈值。
|
||||
3. **P99延迟监控**: 监控错误响应的P99延迟，确保错误处理不会成为性能瓶颈。
|
||||
4. **错误分类仪表板**: 创建按错误类型、服务、时间维度分类的仪表板，便于趋势分析。
|
||||
|
||||
通过这些实践，可以建立一个健壮的错误监控体系，及时发现和解决系统中的问题。
|
||||
|
||||
**本节源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L98-L103)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L115-L122)
|
||||
374
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/Docker集成.md
Normal file
374
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/Docker集成.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Docker集成
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [crates/docker_manager/Cargo.toml](file://crates/docker_manager/Cargo.toml)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [Cargo.lock](file://Cargo.lock)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕 docker_manager crate 与 bollard 库的集成，系统阐述其如何通过 Docker 守护进程通信、客户端初始化、连接配置与 API 调用模式，实现容器的创建、启动与状态查询。文档还结合 rcoder 主应用与 agent_runner 的集成方式，说明会话上下文传递与生命周期协调；并提供权限配置、Docker 套接字访问、网络模式选择等常见问题的解决方案与生产环境安全配置建议。
|
||||
|
||||
## 项目结构
|
||||
docker_manager crate 位于 crates/docker_manager，核心职责是面向 rcoder 的容器生命周期管理与镜像选择。rcoder 主应用通过 proxy_agent 与 service 层协作，驱动 docker_manager 完成容器的动态创建与网络通信。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "docker_manager"
|
||||
DM["DockerManager<br/>容器管理器"]
|
||||
Types["Types<br/>配置/状态模型"]
|
||||
Utils["Utils<br/>工具函数"]
|
||||
ImgSel["ImageSelector<br/>镜像选择器"]
|
||||
Lib["lib.rs<br/>导出与全局管理"]
|
||||
end
|
||||
subgraph "rcoder 应用"
|
||||
CM["ContainerManager<br/>容器服务层"]
|
||||
DCA["DockerContainerAgent<br/>容器代理"]
|
||||
CFG["AppConfig/DockerConfig<br/>配置"]
|
||||
end
|
||||
subgraph "外部依赖"
|
||||
Bollard["bollard<br/>Docker API 客户端"]
|
||||
Docker["Docker 守护进程"]
|
||||
Shared["shared_types<br/>多镜像配置"]
|
||||
end
|
||||
CM --> DCA
|
||||
DCA --> DM
|
||||
DM --> Bollard
|
||||
DM --> Docker
|
||||
DM --> Shared
|
||||
DM --> Types
|
||||
DM --> Utils
|
||||
DM --> ImgSel
|
||||
CFG --> DM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L60)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L220)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L80-L120)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L60)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L220)
|
||||
|
||||
## 核心组件
|
||||
- DockerManager：封装 bollard 客户端，负责容器创建、启动、状态查询、日志获取、网络检测与镜像拉取等。
|
||||
- DockerContainerConfig/DockerContainerInfo：容器配置与运行信息的数据模型。
|
||||
- DockerManagerConfig：管理器配置，包含默认镜像、网络模式、工作目录、平台、自动清理等。
|
||||
- DockerUtils：平台检测、镜像兼容性判断、配置从环境变量加载、容器命名等工具。
|
||||
- ImageSelector：基于多镜像配置选择镜像与服务配置，支持按服务类型与平台选择。
|
||||
- 全局管理：提供全局 DockerManager 单例初始化与获取，简化跨模块使用。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L60)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L143-L211)
|
||||
|
||||
## 架构总览
|
||||
docker_manager 通过 bollard 与 Docker 守护进程交互，采用“配置驱动 + 多镜像选择 + 动态网络”的设计，确保容器在 rcoder 生态中可复用、可扩展且安全可控。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder 应用"
|
||||
participant CM as "ContainerManager"
|
||||
participant DCA as "DockerContainerAgent"
|
||||
participant DM as "DockerManager"
|
||||
participant B as "bollard/Docker"
|
||||
participant SH as "shared_types"
|
||||
RC->>CM : 请求获取或创建容器(project_id, service_type)
|
||||
CM->>DM : 获取动态网络名称
|
||||
DM-->>CM : 返回主网络名称
|
||||
CM->>DCA : 启动容器服务(project_id, network_name)
|
||||
DCA->>DM : 选择镜像/服务配置
|
||||
DM->>SH : 读取多镜像配置
|
||||
DM->>B : 拉取镜像/创建容器/启动容器
|
||||
DM-->>DCA : 返回容器信息
|
||||
DCA->>DM : 等待agent_runner就绪
|
||||
DM-->>CM : 返回容器IP与服务URL
|
||||
CM-->>RC : 返回容器基本信息
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L220)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L100-L220)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L60)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### DockerManager：客户端初始化与连接配置
|
||||
- 客户端初始化
|
||||
- 若配置提供 docker_host，则使用 HTTP 连接；否则使用本地默认连接。
|
||||
- 初始化后执行 ping 校验，确保与 Docker 守护进程连通。
|
||||
- 主网络检测
|
||||
- 通过静态方法检测主网络名称，若失败则中断初始化，保证后续网络连接的可靠性。
|
||||
- 网络与安全
|
||||
- 默认连接到动态检测的主网络，避免硬编码网络名。
|
||||
- 容器安全：移除 NET_RAW/NET_ADMIN 能力，禁用特权模式，降低容器逃逸风险。
|
||||
- 资源限制
|
||||
- 支持内存、swap、CPU（nano_cpus）限制，按配置注入到 HostConfig。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["初始化 DockerManager"]) --> CheckHost["读取配置 docker_host"]
|
||||
CheckHost --> |有| ConnectHTTP["connect_with_http(...)"]
|
||||
CheckHost --> |无| ConnectLocal["connect_with_local_defaults()"]
|
||||
ConnectHTTP --> Ping["ping() 校验连接"]
|
||||
ConnectLocal --> Ping
|
||||
Ping --> DetectNet["检测主网络名称"]
|
||||
DetectNet --> |成功| EnsureNet["ensure_rcoder_network()"]
|
||||
DetectNet --> |失败| Fail["返回错误并终止"]
|
||||
EnsureNet --> Done(["初始化完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L51-L74)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
|
||||
### 容器创建流程：创建、启动与健康检查
|
||||
- 名称与挂载
|
||||
- 使用统一容器命名规则，便于管理与调试。
|
||||
- 绑定宿主机路径到容器路径，支持额外挂载点与只读挂载。
|
||||
- 环境变量与端口映射
|
||||
- 环境变量以“键=值”形式注入；端口映射支持动态分配。
|
||||
- 网络连接
|
||||
- 优先连接到主网络，支持 host 模式；通过 NetworkingConfig 指定网络别名。
|
||||
- 启动与健康检查
|
||||
- 创建后立即启动容器，短暂等待后检查容器状态，确保运行正常。
|
||||
- 资源限制与安全
|
||||
- 注入资源限制；默认移除敏感能力，禁用特权模式。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant DM as "DockerManager"
|
||||
participant B as "bollard/Docker"
|
||||
DM->>DM : 生成容器名称/挂载/环境变量/端口映射
|
||||
DM->>B : create_container(...)
|
||||
B-->>DM : 返回 container_id
|
||||
DM->>B : start_container(...)
|
||||
DM->>B : inspect_container(...) 检查状态
|
||||
DM-->>DM : 更新容器映射与状态
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L81-L294)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L81-L294)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
|
||||
### 镜像选择与配置加载
|
||||
- 多镜像配置
|
||||
- 通过 MultiImageConfig 定义全局默认与服务特定镜像，支持 ARM64/AMD64 平台选择。
|
||||
- 镜像选择器
|
||||
- ImageSelector 强制明确服务类型，按服务配置优先级选择镜像；必要时回退到全局默认。
|
||||
- 配置来源
|
||||
- DockerManagerConfig 可从环境变量与 rcoder 配置加载，支持镜像、网络、工作目录、自动清理等参数。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+global_defaults
|
||||
+services
|
||||
+selection_strategy
|
||||
+cache_config
|
||||
+validate()
|
||||
+get_service_config()
|
||||
}
|
||||
class ImageSelector {
|
||||
-config
|
||||
-platform
|
||||
+select_image()
|
||||
+get_service_config()
|
||||
+is_service_enabled()
|
||||
}
|
||||
class DockerManagerConfig {
|
||||
+docker_host
|
||||
+default_image
|
||||
+default_network_mode
|
||||
+default_work_dir
|
||||
+auto_cleanup
|
||||
+container_ttl_seconds
|
||||
+multi_image_config
|
||||
}
|
||||
ImageSelector --> MultiImageConfig : "读取配置"
|
||||
DockerManager --> ImageSelector : "选择镜像"
|
||||
DockerManager --> DockerManagerConfig : "加载配置"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L232)
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L120)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L172-L244)
|
||||
|
||||
### rcoder 集成：会话上下文与生命周期
|
||||
- 会话上下文传递
|
||||
- ContainerManager 通过 project_id 标识容器，返回包含容器ID、名称、IP、端口、状态与服务URL的基本信息。
|
||||
- 生命周期协调
|
||||
- DockerContainerAgent 在创建容器后等待 agent_runner 就绪，失败时自动销毁容器，避免资源泄漏。
|
||||
- rcoder 侧通过 get_or_create_container 与 create_container_for_request 统一管理容器生命周期。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder 应用"
|
||||
participant CM as "ContainerManager"
|
||||
participant DCA as "DockerContainerAgent"
|
||||
participant DM as "DockerManager"
|
||||
RC->>CM : get_or_create_container(project_id, service_type)
|
||||
alt 容器已存在
|
||||
CM->>DM : get_container_network_info()
|
||||
DM-->>CM : 返回网络IP
|
||||
CM-->>RC : 返回容器基本信息
|
||||
else 容器不存在
|
||||
CM->>DCA : start_docker_container_agent_service(...)
|
||||
DCA->>DM : create_container(...)
|
||||
DM-->>DCA : 返回容器信息
|
||||
DCA->>DM : wait_for_agent_server_ready()
|
||||
DCA-->>CM : 返回容器信息与服务URL
|
||||
CM-->>RC : 返回容器基本信息
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L220)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L296-L372)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L220)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
|
||||
## 依赖关系分析
|
||||
- 外部依赖
|
||||
- bollard：Docker API 客户端，版本在 Cargo.lock 中记录。
|
||||
- tokio/futures-serde/tracing/dashmap/chrono/uuid 等：异步运行时、序列化、日志、并发容器与时序。
|
||||
- 内部依赖
|
||||
- shared_types：提供多镜像配置与服务类型定义，支撑镜像选择与挂载配置。
|
||||
- rcoder 应用：通过 proxy_agent 与 service 层调用 docker_manager。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
DM["docker_manager"] --> Bollard["bollard"]
|
||||
DM --> Tokio["tokio"]
|
||||
DM --> Serde["serde/serde_json"]
|
||||
DM --> Tracing["tracing"]
|
||||
DM --> Dashmap["dashmap"]
|
||||
DM --> Chrono["chrono"]
|
||||
DM --> Shared["shared_types"]
|
||||
RC["rcoder 应用"] --> DM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/Cargo.toml](file://crates/docker_manager/Cargo.toml#L1-L40)
|
||||
- [Cargo.lock](file://Cargo.lock#L805-L869)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/Cargo.toml](file://crates/docker_manager/Cargo.toml#L1-L40)
|
||||
- [Cargo.lock](file://Cargo.lock#L805-L869)
|
||||
|
||||
## 性能考量
|
||||
- 并发与映射
|
||||
- 使用 DashMap 存储容器映射，支持高并发读写，减少锁竞争。
|
||||
- 网络与I/O
|
||||
- 通过动态网络检测与容器内部DNS解析，避免宿主机端口映射带来的额外开销。
|
||||
- 镜像拉取
|
||||
- 拉取镜像采用流式处理，边拉取边记录进度，避免阻塞主线程。
|
||||
- 资源限制
|
||||
- 合理设置 CPU/内存/swap，避免容器争抢导致的抖动。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L167-L175)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
|
||||
## 故障排查指南
|
||||
- Docker 连接失败
|
||||
- 现象：初始化时 ping 失败或网络检测失败。
|
||||
- 排查：确认 DOCKER_HOST 环境变量、Docker 守护进程状态、socket 权限。
|
||||
- 参考路径：[DockerManager::new](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- 镜像拉取失败
|
||||
- 现象：create_container 中拉取镜像报错。
|
||||
- 排查：检查网络、镜像地址、认证信息；查看拉取进度日志。
|
||||
- 参考路径：[ensure_image_exists](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- 容器启动后立即退出
|
||||
- 现象：check_container_health 报错，退出码非零。
|
||||
- 排查：查看容器日志、环境变量、挂载路径权限、资源限制。
|
||||
- 参考路径：[check_container_health](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
- 端口冲突或不可用
|
||||
- 现象：宿主机端口映射失败。
|
||||
- 排查：使用端口管理器分配端口或改为内部网络通信。
|
||||
- 参考路径：[PortManager](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
- 网络连接异常
|
||||
- 现象：容器未连接到期望网络。
|
||||
- 排查：确认主网络名称检测结果、容器网络别名、Docker Compose 项目名称。
|
||||
- 参考路径：[get_dynamic_network_name](file://crates/rcoder/src/service/container_manager.rs#L142-L151)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L142-L151)
|
||||
|
||||
## 结论
|
||||
docker_manager 通过 bollard 与 Docker 守护进程紧密集成，提供稳定可靠的容器生命周期管理能力。配合 rcoder 的容器服务层与代理层，实现了以 project_id 为中心的会话上下文传递与生命周期协调。多镜像配置与动态网络检测进一步提升了灵活性与安全性。建议在生产环境中严格控制权限、合理设置资源限制，并通过日志与健康检查保障稳定性。
|
||||
|
||||
## 附录
|
||||
|
||||
### Docker 连接配置与示例路径
|
||||
- 客户端初始化与连接校验
|
||||
- [DockerManager::new](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- 环境变量配置（Docker）
|
||||
- [DockerUtils::config_from_env](file://crates/docker_manager/src/utils.rs#L172-L209)
|
||||
- rcoder 配置加载与镜像选择
|
||||
- [DockerConfig::apply_env_overrides](file://crates/rcoder/src/config.rs#L212-L239)
|
||||
- [DockerManagerConfig::default](file://crates/docker_manager/src/types.rs#L218-L232)
|
||||
- [ImageSelector::select_image](file://crates/docker_manager/src/image_selector.rs#L32-L63)
|
||||
|
||||
### 常见问题与解决方案
|
||||
- 权限配置与 Docker 套接字访问
|
||||
- 将运行用户加入 docker 用户组；确保 /var/run/docker.sock 权限正确。
|
||||
- 参考路径：[DockerManager::new](file://crates/docker_manager/src/manager.rs#L35-L74)
|
||||
- 网络模式选择
|
||||
- bridge 模式适合容器间互通；host 模式适合低延迟场景但牺牲隔离性。
|
||||
- 参考路径：[DockerContainerConfig::default](file://crates/docker_manager/src/types.rs#L62-L82)
|
||||
- 生产环境安全配置建议
|
||||
- 移除敏感能力（NET_RAW/NET_ADMIN）、禁用特权模式、限制资源、最小化镜像与只读根文件系统。
|
||||
- 参考路径：[HostConfig 安全配置](file://crates/docker_manager/src/manager.rs#L147-L166)
|
||||
422
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/容器化管理.md
Normal file
422
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/容器化管理.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# 容器化管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [crates/shared_types/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件系统性阐述本项目的容器化管理能力，涵盖 Docker 集成、容器生命周期、资源隔离与镜像管理的实现细节。文档基于实际代码库，提供面向初学者的循序讲解与面向资深工程师的技术深度，包括配置选项、参数与返回值说明、组件间关系、常见问题与解决方案，并辅以可视化图示帮助理解。
|
||||
|
||||
## 项目结构
|
||||
围绕容器化管理的关键模块分布如下：
|
||||
- docker_manager：Docker 客户端封装、容器生命周期管理、镜像选择、网络与资源限制、容器自检测与停止策略
|
||||
- rcoder 服务层：容器编排入口、容器信息查询与服务 URL 生成、与 docker_manager 的交互
|
||||
- shared_types：多镜像配置模型、服务镜像配置、服务类型枚举等
|
||||
- docker 目录：Dockerfile 与 docker-compose.yml，定义运行时镜像与编排网络
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 服务层"
|
||||
RC["rcoder 服务<br/>容器管理器"]
|
||||
DCA["Docker 容器 Agent"]
|
||||
end
|
||||
subgraph "docker_manager"
|
||||
DM["DockerManager"]
|
||||
IS["镜像选择器"]
|
||||
UT["工具集"]
|
||||
CSI["容器自检测"]
|
||||
CS["停止策略"]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
MIC["多镜像配置"]
|
||||
SIC["服务镜像配置"]
|
||||
end
|
||||
subgraph "运行时"
|
||||
DC["Docker 守护进程"]
|
||||
NET["Docker 网络"]
|
||||
end
|
||||
RC --> DM
|
||||
DCA --> DM
|
||||
DM --> DC
|
||||
DM --> NET
|
||||
DM --> IS
|
||||
DM --> UT
|
||||
DM --> CSI
|
||||
DM --> CS
|
||||
IS --> MIC
|
||||
IS --> SIC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L200)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L80)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
## 核心组件
|
||||
- DockerManager：统一的 Docker 客户端封装，负责容器创建、启动、停止、删除、状态查询、日志获取、网络信息查询、镜像存在性检查与拉取等
|
||||
- 镜像选择器：基于服务类型与多镜像配置选择镜像，支持架构特定镜像与全局默认镜像
|
||||
- 工具集：平台检测、镜像兼容性判断、容器命名、配置加载（环境变量/配置文件）、路径规范化
|
||||
- 容器自检测：在容器内部通过 Docker API 获取自身挂载信息，解析容器内路径到宿主机路径
|
||||
- 停止策略：提供启动时清理与运行时清理两种策略，支持并发停止、超时控制与错误过滤
|
||||
- rcoder 服务层：容器编排入口，负责按项目维度创建/复用容器，生成服务 URL，查询网络信息
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L120)
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L120)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
|
||||
## 架构总览
|
||||
容器化管理采用“服务层 + docker_manager + Docker 守护进程”的分层设计。rcoder 服务层通过 DockerManager 与 Docker 守护进程交互，镜像选择器根据服务类型与多镜像配置决定镜像，工具集负责平台检测与配置加载，容器自检测与停止策略分别用于容器内部路径解析与资源回收。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant RC as "rcoder 服务层"
|
||||
participant DCA as "Docker 容器 Agent"
|
||||
participant DM as "DockerManager"
|
||||
participant DC as "Docker 守护进程"
|
||||
Client->>RC : 请求项目容器
|
||||
RC->>DM : 获取/创建容器
|
||||
DM->>DC : 列出/检查镜像
|
||||
DC-->>DM : 镜像存在/不存在
|
||||
DM->>DC : 创建容器(挂载/网络/资源限制)
|
||||
DC-->>DM : 返回容器ID
|
||||
DM->>DC : 启动容器
|
||||
DC-->>DM : 容器状态
|
||||
DM-->>RC : 返回容器信息
|
||||
RC->>DCA : 启动容器内 agent_runner
|
||||
DCA-->>RC : 返回服务URL
|
||||
RC-->>Client : 返回服务URL
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L320)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L180)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L80-L180)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### DockerManager：容器生命周期与资源隔离
|
||||
- 连接与初始化：支持通过环境变量或本地默认连接 Docker 守护进程；初始化时检测主网络名称并确保 RCoder 网络存在
|
||||
- 容器创建：生成容器名称、检查同项目容器、拉取镜像、绑定挂载点、设置环境变量与端口映射、应用资源限制（内存、CPU、交换）、连接到动态检测的网络
|
||||
- 容器停止：提供按项目与按容器 ID 的停止接口，支持超时与强制删除；并发清理提升效率
|
||||
- 状态与日志：查询容器状态、健康状态、获取容器日志
|
||||
- 网络信息：通过 Docker API 获取容器网络 IP，支持基于网络名称的通信
|
||||
- 错误处理：统一的 DockerError 错误类型，区分连接、创建、启动、停止、删除、拉取、配置、IO、序列化、Bollard 错误
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DockerManager {
|
||||
+new(config) DockerManager
|
||||
+create_container(config) DockerContainerInfo
|
||||
+stop_container(project_id) void
|
||||
+stop_container_by_id(id, timeout) void
|
||||
+get_container_info(project_id) DockerContainerInfo
|
||||
+list_containers() Vec~DockerContainerInfo~
|
||||
+update_container_status(project_id) ContainerStatus
|
||||
+get_container_logs(project_id, lines) String
|
||||
+restart_container(project_id) void
|
||||
+get_container_network_info(id) HashMap~String,String~
|
||||
+get_docker_client() Docker
|
||||
+get_service_config(type) ServiceImageConfig
|
||||
+select_image(type, overrides) String
|
||||
}
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
|
||||
### 镜像选择器：多镜像配置与架构适配
|
||||
- 多镜像配置：支持全局默认镜像、服务特定镜像（通用/ARM64/AMD64/默认回退）、镜像选择策略（当前为 ServiceOnly）、缓存配置
|
||||
- 服务镜像配置：包含服务类型、镜像、环境变量、挂载点、命令、入口点、资源限制、工作目录、网络模式、容器路径模板等
|
||||
- 选择逻辑：优先使用服务通用镜像，否则按平台选择架构特定镜像，最后回退到默认镜像；支持项目级镜像覆盖与环境变量合并
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckService["检查服务是否启用"]
|
||||
CheckService --> |否| Err["返回配置错误"]
|
||||
CheckService --> |是| Priority["优先使用服务通用镜像"]
|
||||
Priority --> |存在| UseGeneric["使用通用镜像"]
|
||||
Priority --> |不存在| Platform["按平台选择架构镜像"]
|
||||
Platform --> UseArm64["使用 ARM64 镜像"]
|
||||
Platform --> UseAmd64["使用 AMD64 镜像"]
|
||||
UseArm64 --> Fallback["使用默认镜像"]
|
||||
UseAmd64 --> Fallback
|
||||
Fallback --> Done(["结束"])
|
||||
UseGeneric --> Done
|
||||
Err --> Done
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L120)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L200)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L200)
|
||||
|
||||
### 工具集：平台检测、镜像兼容性与配置加载
|
||||
- 平台检测：自动检测系统架构并返回 Docker 平台字符串，支持环境变量覆盖
|
||||
- 镜像兼容性：根据镜像标签判断与当前平台的兼容性
|
||||
- 配置加载：从环境变量与 rcoder 配置加载 DockerManagerConfig，支持网络模式、工作目录、自动清理、容器 TTL、默认镜像等
|
||||
- 容器命名：使用 project_id 生成稳定容器名称，便于管理与调试
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["获取环境变量"] --> B["检测平台"]
|
||||
B --> C{"平台是否来自环境变量?"}
|
||||
C --> |是| D["使用环境变量平台"]
|
||||
C --> |否| E["自动检测平台"]
|
||||
D --> F["加载 DockerManagerConfig"]
|
||||
E --> F
|
||||
F --> G["应用 rcoder 配置覆盖"]
|
||||
G --> H["生成默认镜像(按架构)"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L120-L220)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs#L1-L200)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L120-L220)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
|
||||
### 容器自检测：容器内路径解析
|
||||
- 在容器内部通过 Docker API 获取自身挂载信息，解析容器内路径到宿主机路径
|
||||
- 提供容器路径到宿主机路径的解析器，支持已知路径的硬编码映射与通用路径解析
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant INS as "容器自检测器"
|
||||
participant DC as "Docker 守护进程"
|
||||
INS->>DC : inspect 当前容器
|
||||
DC-->>INS : 返回挂载信息
|
||||
INS->>INS : 解析目标容器路径
|
||||
INS-->>INS : 返回宿主机绝对路径
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L200)
|
||||
|
||||
### 停止策略：启动时清理与运行时清理
|
||||
- 启动时清理：并发停止匹配模式的容器，使用较短超时，过滤 409 冲突错误，快速清理遗留容器
|
||||
- 运行时清理：单个或批量容器停止，使用较短超时，超时后强制停止，快速释放资源
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Mode{"清理模式"}
|
||||
Mode --> |启动时| Startup["并发停止匹配容器"]
|
||||
Mode --> |运行时| Runtime["单个/批量停止"]
|
||||
Startup --> Timeout["短超时(5s)"]
|
||||
Runtime --> ShortTimeout["短超时(3s)"]
|
||||
Timeout --> Force["超时后强制停止"]
|
||||
ShortTimeout --> Force
|
||||
Force --> Stats["统计成功/失败/耗时"]
|
||||
Stats --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L180)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L200)
|
||||
|
||||
### rcoder 服务层：容器编排与服务 URL 生成
|
||||
- 容器编排：按项目维度检查/创建容器，动态获取网络名称，生成服务 URL
|
||||
- 服务 URL：通过 Docker API 获取容器在动态网络中的 IP，拼接服务端口生成 URL
|
||||
- 与 docker_manager 的交互：调用 DockerManager 的容器创建、网络信息查询、服务配置获取等
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "ContainerManager"
|
||||
participant DM as "DockerManager"
|
||||
participant DC as "Docker 守护进程"
|
||||
RC->>DM : 获取动态网络名称
|
||||
DM-->>RC : 返回网络名称
|
||||
RC->>DM : 获取容器网络信息
|
||||
DM->>DC : inspect 容器
|
||||
DC-->>DM : 返回网络IP
|
||||
DM-->>RC : 返回网络IP映射
|
||||
RC-->>RC : 生成服务URL
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L120-L220)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L220)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L200)
|
||||
|
||||
## 依赖关系分析
|
||||
- docker_manager 依赖 bollard 与 DashMap，提供 Docker 客户端、并发容器映射与错误类型
|
||||
- rcoder 服务层依赖 docker_manager 的全局实例与容器信息结构
|
||||
- shared_types 提供多镜像配置与服务镜像配置模型，被 docker_manager 与 rcoder 共同使用
|
||||
- docker 目录提供运行时镜像与编排网络，与 rcoder 服务层配合实现容器化部署
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RC["rcoder 服务层"] --> DM["docker_manager"]
|
||||
DM --> ST["shared_types"]
|
||||
DM --> BOL["bollard"]
|
||||
DM --> DMAP["DashMap"]
|
||||
RC --> DM
|
||||
ST --> MIC["MultiImageConfig"]
|
||||
ST --> SIC["ServiceImageConfig"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L60)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L60)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
|
||||
## 性能考虑
|
||||
- 并发停止：启动时清理与运行时批量清理均采用并发任务，显著缩短清理时间
|
||||
- 超时控制：启动时使用较短超时（5s），运行时使用更短超时（3s），在保证稳定性的同时快速回收资源
|
||||
- 网络连接：容器创建时直接连接到动态检测的网络，避免跨网络通信开销
|
||||
- 资源限制：通过 HostConfig 的内存、CPU、交换限制实现资源隔离，避免资源争用
|
||||
- 镜像拉取：仅在本地不存在时拉取镜像，减少重复下载
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L120)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L140-L220)
|
||||
|
||||
## 故障排查指南
|
||||
- Docker 连接失败
|
||||
- 现象：初始化 DockerManager 报错
|
||||
- 排查：确认 DOCKER_HOST 环境变量、Docker 守护进程状态、socket 权限
|
||||
- 参考：DockerError::ConnectionError
|
||||
- 容器创建失败
|
||||
- 现象：创建容器报错
|
||||
- 排查：检查镜像是否存在、挂载路径、网络名称、资源限制参数
|
||||
- 参考：DockerError::ContainerCreationError
|
||||
- 容器启动失败
|
||||
- 现象：容器创建后立即退出
|
||||
- 排查：查看容器日志、健康检查状态、入口点与命令、环境变量
|
||||
- 参考：DockerError::ContainerStartError、get_container_logs
|
||||
- 容器停止失败
|
||||
- 现象：删除容器报错
|
||||
- 排查：忽略 409 冲突错误（已在启动清理中处理）；检查容器是否已删除或正在删除
|
||||
- 参考：DockerError::ContainerStopError、DockerError::ContainerRemoveError
|
||||
- 镜像拉取失败
|
||||
- 现象：ensure_image_exists 失败
|
||||
- 排查：检查镜像仓库可达性、认证配置、网络策略
|
||||
- 参考：DockerError::ImagePullError
|
||||
- 网络不存在
|
||||
- 现象：ensure_rcoder_network 失败
|
||||
- 排查：确认 docker-compose 网络已创建、主容器处于预期网络
|
||||
- 参考：DockerError::ConnectionError
|
||||
- 容器自检测失败
|
||||
- 现象：无法解析容器内路径到宿主机路径
|
||||
- 排查：确认 Docker socket 挂载与权限、/proc 文件系统可读
|
||||
- 参考：ContainerSelfInspector::detect_host_path_for_container_dir
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L60)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L540-L760)
|
||||
- [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
|
||||
## 结论
|
||||
本项目通过 docker_manager 提供了完善的容器化管理能力：统一的 Docker 客户端封装、灵活的多镜像配置与架构适配、稳定的容器生命周期管理、资源隔离与网络连接、以及容器内部路径解析与高效停止策略。rcoder 服务层在此基础上实现了按项目维度的容器编排与服务 URL 生成，整体架构清晰、扩展性强，既满足初学者快速上手，也为高级用户提供深入定制的空间。
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置选项与参数说明
|
||||
- DockerManagerConfig
|
||||
- docker_host：Docker 守护进程地址（可选）
|
||||
- default_image：默认镜像
|
||||
- default_platform：默认平台（如 linux/amd64）
|
||||
- default_network_mode：默认网络模式（如 bridge）
|
||||
- default_work_dir：默认工作目录
|
||||
- auto_cleanup：是否启用自动清理
|
||||
- container_ttl_seconds：容器存活时间（秒）
|
||||
- multi_image_config：多镜像配置（来自 rcoder 配置）
|
||||
- DockerContainerConfig
|
||||
- project_id：项目标识
|
||||
- image：镜像名称
|
||||
- name_prefix：容器名称前缀
|
||||
- host_path：宿主机路径
|
||||
- container_path：容器内路径
|
||||
- work_dir：工作目录
|
||||
- env_vars：环境变量
|
||||
- port_bindings：端口映射
|
||||
- network_mode：网络模式
|
||||
- auto_remove：容器停止后自动删除
|
||||
- resource_limits：资源限制（内存、CPU、交换）
|
||||
- extra_mounts：额外挂载点
|
||||
- command：启动命令
|
||||
- entrypoint：入口点
|
||||
- network_name：网络名称（可选）
|
||||
- DockerConfig（rcoder 配置）
|
||||
- multi_image_config：多镜像配置
|
||||
- network_mode：网络模式
|
||||
- work_dir：工作目录
|
||||
- auto_cleanup：自动清理
|
||||
- container_ttl_seconds：容器存活时间（秒）
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L200)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L80-L220)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
|
||||
### 运行时镜像与编排
|
||||
- Dockerfile：包含调试工具与健康检查，暴露端口，设置环境变量
|
||||
- docker-compose.yml：定义 rcoder 服务、端口映射、环境变量、卷挂载、健康检查、网络
|
||||
|
||||
章节来源
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L1-L120)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
407
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/容器生命周期管理.md
Normal file
407
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/容器生命周期管理.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# 容器生命周期管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件围绕容器的完整生命周期管理展开，涵盖创建、启动、运行时监控、优雅停止与清理。重点基于 docker_manager 中的 create_container/start_container 流程，解析容器配置参数（资源限制、挂载卷、环境变量、网络与端口等）的设置逻辑；结合 container_stop 中的终止策略（超时与强制清理）、container_self_inspector 的容器内自检能力，以及 rcoder 层面的会话与容器映射关系，给出从 API 请求到容器终止的完整调用链路，并讨论异常终止场景下的恢复与资源泄漏防范策略。
|
||||
|
||||
## 项目结构
|
||||
该仓库采用多 crate 的模块化组织，其中与容器生命周期直接相关的关键模块如下：
|
||||
- docker_manager：容器生命周期与资源编排的核心实现
|
||||
- rcoder：业务层容器管理与会话映射
|
||||
- shared_types：跨模块共享的数据模型与生命周期抽象
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "容器管理核心"
|
||||
DM["DockerManager<br/>manager.rs"]
|
||||
CS["容器停止策略<br/>container_stop.rs"]
|
||||
CSI["容器自检器<br/>container_self_inspector.rs"]
|
||||
DT["类型与配置<br/>types.rs"]
|
||||
DL["错误与导出<br/>lib.rs"]
|
||||
end
|
||||
subgraph "业务集成"
|
||||
RCA["容器代理服务<br/>docker_container_agent.rs"]
|
||||
CM["容器服务封装<br/>container_manager.rs"]
|
||||
CT["清理任务<br/>cleanup_task.rs"]
|
||||
AM["Agent生命周期模型<br/>agent_model.rs"]
|
||||
end
|
||||
DM --> CS
|
||||
DM --> CSI
|
||||
DM --> DT
|
||||
DM --> DL
|
||||
RCA --> DM
|
||||
CM --> DM
|
||||
CT --> DM
|
||||
CT --> CS
|
||||
CT --> AM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L60)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L40)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L60)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L40)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L40)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L40)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L400-L480)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L40)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L40)
|
||||
|
||||
## 核心组件
|
||||
- DockerManager：负责容器创建、启动、状态更新、日志获取、重启与网络信息查询；提供统一的容器停止接口（支持超时与强制清理）。
|
||||
- 容器停止策略：提供启动时清理与运行时清理两类策略，分别针对遗留容器与即时回收资源。
|
||||
- 容器自检器：在容器内部通过 Docker API 检测挂载信息，解析容器内路径到宿主机路径。
|
||||
- 类型与配置：集中定义容器配置、状态、清理结果等数据结构。
|
||||
- 业务容器代理：将服务类型映射为镜像与配置，构造 DockerContainerConfig 并驱动 DockerManager 创建容器。
|
||||
- 容器服务封装：对外暴露容器信息查询与服务 URL 生成，屏蔽底层网络细节。
|
||||
- 清理任务：周期性扫描孤立容器并统一清理，结合运行时停止策略与 RAII 资源回收。
|
||||
- Agent 生命周期模型：提供优雅停止与强制清理的 RAII 抽象，确保资源释放。
|
||||
|
||||
章节来源
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L60)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L60)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L60)
|
||||
|
||||
## 架构总览
|
||||
下图展示从 API 请求到容器终止的完整调用链路，强调会话 ID 与容器的映射关系。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "rcoder处理器"
|
||||
participant CM as "容器服务封装<br/>container_manager.rs"
|
||||
participant RCA as "容器代理服务<br/>docker_container_agent.rs"
|
||||
participant DM as "DockerManager<br/>manager.rs"
|
||||
participant CS as "停止策略<br/>container_stop.rs"
|
||||
participant CT as "清理任务<br/>cleanup_task.rs"
|
||||
Client->>Handler : "发起请求"
|
||||
Handler->>CM : "get_or_create_container(project_id, service_type)"
|
||||
CM->>DM : "get_container_info / create_container"
|
||||
DM-->>CM : "返回容器信息"
|
||||
CM-->>Handler : "返回服务URL"
|
||||
Handler-->>Client : "响应服务URL"
|
||||
Note over Handler,CT : "异常或闲置清理时"
|
||||
Handler->>CT : "触发清理任务"
|
||||
CT->>DM : "find_container_by_identifier / list_containers_with_pattern"
|
||||
DM-->>CT : "容器信息"
|
||||
CT->>CS : "runtime_cleanup_container / startup_cleanup_containers"
|
||||
CS->>DM : "stop_container_by_id_with_timeout(force=true)"
|
||||
DM-->>CS : "清理完成"
|
||||
CS-->>CT : "清理结果"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L120)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L226-L390)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### DockerManager：创建与启动流程
|
||||
- 容器创建与启动
|
||||
- 生成容器名称并检查是否已有同项目容器，若存在则先停止并删除。
|
||||
- 拉取镜像（本地不存在时）。
|
||||
- 构造挂载点（绑定宿主机路径到容器路径，支持只读与额外挂载）。
|
||||
- 设置环境变量、端口映射、资源限制（内存、CPU、Swap）。
|
||||
- 主动连接到动态检测的主网络，或使用 host 网络模式。
|
||||
- 设置容器主机名、域名为便于识别。
|
||||
- 设置启动命令与入口点。
|
||||
- 调用 create_container 并立即 start_container。
|
||||
- 等待短暂时间后检查容器健康状态，再写入容器映射。
|
||||
- 停止与清理
|
||||
- 提供 stop_container_by_id_with_timeout（支持超时与强制清理）。
|
||||
- 提供 stop_container（按 project_id 停止并移除映射）。
|
||||
- 提供 find_container_by_identifier（支持 project_id、容器名称与 Docker API 查询）。
|
||||
- 提供 update_container_status、get_container_network_info、get_container_logs 等辅助能力。
|
||||
- 资源限制与网络
|
||||
- 资源限制通过 HostConfig 的 memory、memory_swap、nano_cpus 设置。
|
||||
- 网络通过 NetworkingConfig 连接到动态主网络，支持 aliases 与 host 模式。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始创建容器"]) --> GenName["生成容器名称"]
|
||||
GenName --> CheckExisting{"是否已存在同项目容器？"}
|
||||
CheckExisting --> |是| StopOld["停止并删除旧容器"]
|
||||
CheckExisting --> |否| PullImage["拉取镜像"]
|
||||
StopOld --> PullImage
|
||||
PullImage --> BuildMounts["构建挂载点"]
|
||||
BuildMounts --> BuildEnv["构建环境变量"]
|
||||
BuildEnv --> BuildPorts["构建端口映射"]
|
||||
BuildPorts --> ApplyLimits["应用资源限制"]
|
||||
ApplyLimits --> NetMode{"网络模式 host？"}
|
||||
NetMode --> |否| ConnectNet["连接到动态主网络"]
|
||||
NetMode --> |是| UseHost["使用 host 网络"]
|
||||
ConnectNet --> BuildCfg["组装 ContainerCreateBody"]
|
||||
UseHost --> BuildCfg
|
||||
BuildCfg --> Create["create_container"]
|
||||
Create --> Start["start_container"]
|
||||
Start --> Health["检查容器健康状态"]
|
||||
Health --> SaveMap["写入容器映射"]
|
||||
SaveMap --> End(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
|
||||
### 容器停止策略：优雅停止与强制清理
|
||||
- 启动时清理（startup_cleanup）
|
||||
- 使用 5 秒超时，支持并发停止多个容器。
|
||||
- 过滤 409 冲突错误（容器已在删除中），避免阻塞服务启动。
|
||||
- 运行时清理（runtime_cleanup）
|
||||
- 使用 3 秒优雅停止超时，超时后强制停止，快速释放资源。
|
||||
- 支持单个与批量清理，返回详细清理统计。
|
||||
- 统一停止接口
|
||||
- stop_container_by_id_with_timeout 内部使用 force=true 的 remove_container，避免“removal already in progress”竞态。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as "调用方"
|
||||
participant CS as "container_stop.rs"
|
||||
participant DM as "DockerManager"
|
||||
Caller->>CS : "runtime_cleanup_container(container_id)"
|
||||
CS->>DM : "stop_container_by_id_with_timeout(container_id, 3s)"
|
||||
DM->>DM : "remove_container(..., force=true)"
|
||||
DM-->>CS : "清理完成"
|
||||
CS-->>Caller : "OK"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L226-L390)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L296-L372)
|
||||
|
||||
章节来源
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L180)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L226-L390)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L296-L372)
|
||||
|
||||
### 容器自检器：容器内状态探测与路径解析
|
||||
- 在容器内部通过 Docker API 检测自身挂载信息，解析容器内路径到宿主机路径。
|
||||
- 支持列出所有挂载点、验证 Docker socket 连接、从 /proc/self/cgroup 解析容器 ID 等能力。
|
||||
- 为容器内路径解析提供同步与异步两种接口，便于不同上下文使用。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Enter(["进入容器内自检"]) --> Ping["连接 Docker socket 并 ping"]
|
||||
Ping --> GetCID["解析容器ID/proc/self/cgroup"]
|
||||
GetCID --> Inspect["inspect_container 获取挂载信息"]
|
||||
Inspect --> MatchPath{"目标路径匹配？"}
|
||||
MatchPath --> |是| ReturnHost["返回宿主机路径"]
|
||||
MatchPath --> |否| ListMounts["列出所有挂载点并告警"]
|
||||
ListMounts --> Error["返回错误"]
|
||||
ReturnHost --> Exit(["完成"])
|
||||
Error --> Exit
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L140)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L140-L220)
|
||||
|
||||
章节来源
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L140)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L140-L220)
|
||||
|
||||
### 业务集成：从 API 到容器终止的调用链
|
||||
- 会话与容器映射
|
||||
- rcoder 层通过 ProjectAndContainerInfo 维护 project_id 与 session_id 的映射关系。
|
||||
- 容器服务封装 ContainerManager 提供 get_or_create_container/get_container_info，内部通过 DockerManager 获取网络信息并生成服务 URL。
|
||||
- 容器代理服务
|
||||
- docker_container_agent 根据服务类型选择镜像与配置，构造 DockerContainerConfig 并调用 DockerManager.create_container。
|
||||
- 等待容器内 agent_runner 就绪后返回服务 URL。
|
||||
- 清理与异常恢复
|
||||
- cleanup_task 周期性扫描孤立容器，使用 runtime_cleanup_container 统一清理。
|
||||
- 采用 RAII 的 AgentLifecycleGuard，当容器或 Agent 被移除时自动清理子进程与任务，避免资源泄漏。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as "API请求"
|
||||
participant CM as "ContainerManager"
|
||||
participant RCA as "docker_container_agent"
|
||||
participant DM as "DockerManager"
|
||||
participant CT as "cleanup_task"
|
||||
participant AG as "AgentLifecycleGuard"
|
||||
API->>CM : "get_or_create_container(project_id, service_type)"
|
||||
CM->>RCA : "start_docker_container_agent_service"
|
||||
RCA->>DM : "create_container(config)"
|
||||
DM-->>RCA : "返回容器信息"
|
||||
RCA-->>CM : "返回服务URL"
|
||||
CM-->>API : "返回服务URL"
|
||||
Note over CT,AG : "异常或闲置清理"
|
||||
CT->>DM : "find_container_by_identifier / list_containers_with_pattern"
|
||||
DM-->>CT : "容器信息"
|
||||
CT->>DM : "runtime_cleanup_container"
|
||||
DM-->>CT : "清理完成"
|
||||
AG-->>CT : "Drop时清理资源"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L100-L200)
|
||||
|
||||
章节来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L100-L200)
|
||||
|
||||
### 容器配置参数设置逻辑（资源限制、挂载卷、环境变量）
|
||||
- 资源限制
|
||||
- 通过 HostConfig.nano_cpus 设置 CPU 限制（1 CPU = 1e9 nano CPUs）。
|
||||
- 通过 memory/memory_swap 设置内存与 Swap 限制。
|
||||
- 挂载卷
|
||||
- 默认绑定项目工作目录到容器内路径，支持只读。
|
||||
- 支持额外挂载点，逐项转换为 Mount。
|
||||
- 环境变量
|
||||
- 将 HashMap 转换为 "KEY=VALUE" 形式的字符串列表注入。
|
||||
- 端口映射
|
||||
- 通过端口绑定映射，host_ip 固定为 0.0.0.0，host_port 由映射提供。
|
||||
- 网络与主机名
|
||||
- 通过 NetworkingConfig 连接到动态主网络，设置 aliases。
|
||||
- 设置 hostname/domainname 便于识别。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L108-L206)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
|
||||
### 终止策略：信号发送、超时处理与强制杀灭
|
||||
- 优雅停止
|
||||
- 运行时清理使用 3 秒超时，超时后强制停止。
|
||||
- 启动时清理使用 5 秒超时，过滤 409 冲突错误。
|
||||
- 强制杀灭
|
||||
- stop_container_by_id_with_timeout 内部使用 force=true 的 remove_container，避免“removal already in progress”竞态。
|
||||
- 统一清理统计
|
||||
- 返回 total_found、successfully_removed、failed_removals、removed_container_ids、failed_removals_details、duration_ms 等指标。
|
||||
|
||||
章节来源
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L180)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L226-L390)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L234-L284)
|
||||
|
||||
### 容器内状态探测与自检流程
|
||||
- 通过 Docker API 获取容器挂载信息，匹配目标容器内路径并返回宿主机绝对路径。
|
||||
- 支持列出所有挂载点用于调试，支持从 /proc/self/cgroup 解析容器 ID。
|
||||
- 提供 verify_docker_connection 与 get_all_mounts 辅助诊断。
|
||||
|
||||
章节来源
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L140-L220)
|
||||
|
||||
## 依赖分析
|
||||
- 组件耦合
|
||||
- DockerManager 与 container_stop：停止策略依赖 DockerManager 的 remove_container 接口。
|
||||
- docker_container_agent 与 DockerManager：代理服务通过 DockerManager 创建容器。
|
||||
- cleanup_task 与 DockerManager/container_stop：清理任务统一调用停止策略。
|
||||
- rcoder 的会话与容器映射：ProjectAndContainerInfo 与 cleanup_task 的映射关系。
|
||||
- 外部依赖
|
||||
- bollard：Docker API 客户端。
|
||||
- tokio/dashmap/tracing：异步运行时、并发容器与日志。
|
||||
- 循环依赖
|
||||
- 未见循环导入；各模块职责清晰，通过公共类型与接口解耦。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RCA["docker_container_agent.rs"] --> DM["manager.rs"]
|
||||
CM["container_manager.rs"] --> DM
|
||||
CT["cleanup_task.rs"] --> DM
|
||||
CT --> CS["container_stop.rs"]
|
||||
DM --> CS
|
||||
DM --> DT["types.rs"]
|
||||
DM --> DL["lib.rs"]
|
||||
CT --> AM["agent_model.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L60)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L40)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L60)
|
||||
|
||||
章节来源
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L60)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L40)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L60)
|
||||
|
||||
## 性能考虑
|
||||
- 并发清理：container_stop 支持并发停止多个容器，显著提升启动时遗留容器清理效率。
|
||||
- 超时控制：运行时清理使用短超时（3 秒），避免阻塞；启动时清理使用更短超时（5 秒），保证服务启动不被拖慢。
|
||||
- 端口映射优化：业务侧采用内部网络通信，避免端口分配与释放带来的开销。
|
||||
- 资源限制：合理设置 CPU 与内存限制，避免容器争抢影响整体稳定性。
|
||||
- 日志与健康检查：通过 get_container_logs 与健康检查减少无效重试与等待。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 容器启动后立即退出
|
||||
- 检查 DockerManager.check_container_health 的错误输出，定位退出码与错误信息。
|
||||
- 容器不存在或已在删除中
|
||||
- stop_container_by_id_with_timeout 对 No such container 与 removal already in progress 做了特殊处理，可忽略相关警告。
|
||||
- 网络连接问题
|
||||
- 使用 get_container_network_info 获取容器网络信息，确认容器已连接到动态主网络。
|
||||
- 清理统计异常
|
||||
- 通过 CleanupResult 的字段（如 failed_removals_details）定位失败容器与错误原因。
|
||||
- 会话与容器映射丢失
|
||||
- 使用 cleanup_task 的孤立容器检查与清理，结合 RAII 的 AgentLifecycleGuard 自动清理资源。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L200-L320)
|
||||
|
||||
## 结论
|
||||
本系统通过 DockerManager 提供统一的容器生命周期管理能力，配合 container_stop 的优雅停止与强制清理策略、container_self_inspector 的容器内自检能力，以及 rcoder 层的会话与容器映射、清理任务与 RAII 资源回收，实现了从 API 请求到容器终止的闭环管理。在异常终止场景下，通过统一的停止接口与清理统计，能够快速定位问题并防止资源泄漏。建议在生产环境中合理设置资源限制与网络策略，并持续监控清理任务的执行效果。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 关键流程路径参考
|
||||
- 创建与启动：[manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
- 停止与清理：[manager.rs](file://crates/docker_manager/src/manager.rs#L296-L372)、[container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L226-L390)
|
||||
- 自检与路径解析：[container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
- 业务集成与映射：[container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L270)、[cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L520)
|
||||
- Agent 生命周期：[agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L100-L200)
|
||||
329
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/资源隔离与安全.md
Normal file
329
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/资源隔离与安全.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 资源隔离与安全
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件聚焦容器化环境中的资源隔离与安全实践，围绕命名空间、cgroups、文件系统隔离展开，并结合代码实现说明如何在 manager.rs 中配置容器的资源限制（CPU、内存），如何通过只读挂载与安全选项（如能力集降级、禁用特权模式）提升安全性；同时基于 types.rs 中的 DockerContainerConfig 与 ResourceLimits 结构体解释各隔离参数的作用与默认值；并阐述 host_path_resolver.rs 如何与 docker_manager 协作，安全地解析宿主机路径，防止路径遍历攻击。最后给出实际配置示例，讨论容器逃逸风险缓解与最小权限原则的应用。
|
||||
|
||||
## 项目结构
|
||||
本项目采用多 crate 的模块化组织，其中与容器资源隔离和安全直接相关的关键模块如下：
|
||||
- docker_manager：负责容器生命周期管理、资源限制与网络配置
|
||||
- rcoder/utils：提供宿主机路径解析工具，保障挂载路径的安全性
|
||||
- rcoder/service：容器管理服务，协调容器创建与网络信息获取
|
||||
- rcoder/proxy_agent：代理层，负责挂载路径解析与容器间通信
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 服务层"
|
||||
CM["容器管理服务<br/>container_manager.rs"]
|
||||
DCA["代理容器代理<br/>docker_container_agent.rs"]
|
||||
HPR["宿主机路径解析器<br/>host_path_resolver.rs"]
|
||||
end
|
||||
subgraph "docker 管理层"
|
||||
DM["Docker 管理器<br/>manager.rs"]
|
||||
T["类型定义<br/>types.rs"]
|
||||
DU["工具函数<br/>utils.rs"]
|
||||
CSI["容器自检测器<br/>container_self_inspector.rs"]
|
||||
end
|
||||
CM --> DM
|
||||
DCA --> DM
|
||||
DCA --> HPR
|
||||
HPR --> CSI
|
||||
DM --> T
|
||||
DM --> DU
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
|
||||
## 核心组件
|
||||
- DockerManager：负责容器创建、启动、网络连接、资源限制与清理；在创建阶段应用能力集降级、禁用特权模式等安全策略，并按配置设置 CPU/内存限制。
|
||||
- DockerContainerConfig/ResourceLimits：定义容器配置与资源限制的结构体，包含默认值与可选字段。
|
||||
- HostPathResolver：在容器内自动检测挂载映射，将容器内路径解析为宿主机绝对路径，避免路径遍历与越权访问。
|
||||
- ContainerManager：服务层容器管理器，负责网络名称动态获取、容器信息查询与服务 URL 构造。
|
||||
- DockerContainerAgent：代理层，负责挂载路径解析、容器健康检查等待与网络 IP 获取。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
|
||||
## 架构总览
|
||||
容器资源隔离与安全的关键流程如下：
|
||||
- 配置阶段：通过 DockerContainerConfig/ResourceLimits 设置 CPU、内存、交换等限制，并决定挂载点与只读属性。
|
||||
- 创建阶段：DockerManager 构建 HostConfig，应用能力集降级与禁用特权模式，设置网络连接与端口映射。
|
||||
- 安全挂载：docker_container_agent 使用 HostPathResolver 将容器内路径标准化并解析为宿主机绝对路径，避免路径穿越。
|
||||
- 运行阶段：容器网络信息通过 Docker API 获取，服务 URL 基于容器网络 IP 构造，避免不必要的宿主机端口暴露。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Svc as "容器管理服务<br/>container_manager.rs"
|
||||
participant Agent as "代理容器代理<br/>docker_container_agent.rs"
|
||||
participant Resolver as "路径解析器<br/>host_path_resolver.rs"
|
||||
participant CSI as "容器自检测器<br/>container_self_inspector.rs"
|
||||
participant DM as "Docker 管理器<br/>manager.rs"
|
||||
Svc->>Agent : 请求创建容器
|
||||
Agent->>Resolver : 解析挂载宿主机路径
|
||||
Resolver->>CSI : 自检容器挂载映射
|
||||
CSI-->>Resolver : 返回宿主机路径
|
||||
Resolver-->>Agent : 返回标准化后的宿主机路径
|
||||
Agent->>DM : 创建容器传入 HostConfig/挂载配置
|
||||
DM-->>Agent : 返回容器信息
|
||||
Agent->>DM : 获取容器网络信息
|
||||
DM-->>Agent : 返回网络IP
|
||||
Agent-->>Svc : 返回服务URL
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L180-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L80-L170)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 资源限制与安全选项（manager.rs）
|
||||
- 资源限制
|
||||
- 内存限制：通过 HostConfig.memory 与 HostConfig.memory_swap 设置内存与交换上限。
|
||||
- CPU 限制：通过 HostConfig.nano_cpus 设置 CPU 配额（1 CPU = 1e9 nano CPUs）。
|
||||
- 交换限制：memory_swap 与 memory_limit 配合控制内存+交换总量。
|
||||
- 安全选项
|
||||
- 能力集降级：cap_drop 显式移除 NET_RAW、NET_ADMIN 等高危能力，降低网络层面的攻击面。
|
||||
- 禁用特权模式：privileged=false，避免容器获得宿主机同等权限。
|
||||
- 网络连接：通过 NetworkingConfig 将容器连接到动态检测的主网络，而非 host 网络模式，减少直接暴露风险。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["创建容器"]) --> BuildHost["构建 HostConfig"]
|
||||
BuildHost --> Limits{"是否配置资源限制?"}
|
||||
Limits --> |是| ApplyMem["设置 memory/memory_swap"]
|
||||
ApplyMem --> ApplyCPU["设置 nano_cpus"]
|
||||
Limits --> |否| SkipLimits["跳过资源限制"]
|
||||
BuildHost --> CapDrop["cap_drop: 移除高危能力"]
|
||||
BuildHost --> Privileged["privileged=false"]
|
||||
ApplyCPU --> Net["连接到动态网络"]
|
||||
SkipLimits --> Net
|
||||
CapDrop --> Net
|
||||
Privileged --> Net
|
||||
Net --> Create["创建并启动容器"]
|
||||
Create --> End(["完成"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
|
||||
### 配置结构体与默认值（types.rs）
|
||||
- DockerContainerConfig
|
||||
- 关键字段：project_id、image、name_prefix、host_path、container_path、work_dir、env_vars、port_bindings、network_mode、auto_remove、resource_limits、extra_mounts、command、entrypoint、network_name。
|
||||
- 默认值：默认镜像、默认网络模式、默认工作目录、默认 auto_remove=false、默认 resource_limits=None。
|
||||
- ResourceLimits
|
||||
- 字段：memory_limit（字节）、cpu_limit（核心数）、swap_limit（字节）。
|
||||
- 默认值：均为 None，表示不强制限制。
|
||||
- MountPoint
|
||||
- 字段：host_path、container_path、read_only。
|
||||
- 作用：用于 extra_mounts 的扩展挂载，支持只读挂载。
|
||||
|
||||
章节来源
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L120-L220)
|
||||
|
||||
### 宿主机路径解析与安全挂载（host_path_resolver.rs 与 docker_container_agent.rs）
|
||||
- HostPathResolver
|
||||
- 自动检测容器内 /app/project_workspace 对应的宿主机路径，记录容器内与宿主机的基础路径。
|
||||
- 提供 resolve_to_host_path：将容器内路径标准化为绝对路径，优先通过 ContainerSelfInspector 解析挂载映射，其次基于项目工作目录拼接，最后回退到绝对路径解析。
|
||||
- 提供诊断接口 get_diagnostics 与连接验证 check_docker_connection。
|
||||
- docker_container_agent
|
||||
- 在挂载解析阶段，先将 host_path 标准化为绝对路径，再判断是否为容器内路径（以 /app 开头），若是则通过 HostPathResolver 转换为宿主机路径；否则直接使用该路径。
|
||||
- 输出调试日志，记录每个挂载的容器路径、宿主机路径与只读标记。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["输入容器内路径"] --> B["标准化为绝对路径"]
|
||||
B --> C{"是否以 /app 开头?"}
|
||||
C --> |是| D["通过 ContainerSelfInspector 解析挂载映射"]
|
||||
D --> E["得到宿主机绝对路径"]
|
||||
C --> |否| F["尝试 canonicalize 绝对化"]
|
||||
F --> G{"能否成功?"}
|
||||
G --> |是| H["使用绝对路径"]
|
||||
G --> |否| I["回退为原始路径"]
|
||||
E --> J["输出宿主机路径"]
|
||||
H --> J
|
||||
I --> J
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L80-L170)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L297-L346)
|
||||
|
||||
章节来源
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L170)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L140)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L346)
|
||||
|
||||
### 网络与容器管理（container_manager.rs 与 manager.rs）
|
||||
- ContainerManager
|
||||
- 动态获取 Docker Compose 项目名称（优先环境变量，其次容器 labels，再次容器名称推断）。
|
||||
- 通过 DockerManager 检测主网络名称并连接容器到该网络，避免 host 网络模式带来的风险。
|
||||
- 获取容器网络信息，构造服务 URL（基于容器网络 IP 与固定端口）。
|
||||
- DockerManager
|
||||
- 在创建容器时，通过 NetworkingConfig 连接容器到主网络，而非使用 network_mode 字符串。
|
||||
- 通过 Docker API 获取容器网络信息，用于服务 URL 构造。
|
||||
|
||||
章节来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L180-L270)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L170-L210)
|
||||
|
||||
### 错误处理与全局管理（lib.rs 与 utils.rs）
|
||||
- DockerError：统一的错误类型，涵盖连接失败、容器创建/启动/停止/删除失败、镜像拉取失败、配置错误、IO/序列化/Bollard 错误等。
|
||||
- DockerUtils：提供平台检测、镜像兼容性判断、从 rcoder 配置加载 DockerManagerConfig、规范化项目路径等工具函数。
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
|
||||
## 依赖关系分析
|
||||
- docker_container_agent 依赖 host_path_resolver 与 container_self_inspector，实现挂载路径解析与诊断。
|
||||
- container_manager 依赖 docker_manager 获取容器网络信息与动态网络名称。
|
||||
- docker_manager 依赖 bollard API 与 types.rs 中的配置结构体，构建 HostConfig 并执行容器生命周期操作。
|
||||
- utils.rs 与 lib.rs 为公共工具与错误类型，被多个模块复用。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
DCA["docker_container_agent.rs"] --> HPR["host_path_resolver.rs"]
|
||||
HPR --> CSI["container_self_inspector.rs"]
|
||||
CM["container_manager.rs"] --> DM["manager.rs"]
|
||||
DM --> T["types.rs"]
|
||||
DM --> DU["utils.rs"]
|
||||
DM --> LIB["lib.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L280-L360)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
|
||||
## 性能考量
|
||||
- 资源限制
|
||||
- 合理设置 memory_limit 与 swap_limit，避免 OOM 导致频繁回收；CPU 限制通过 nano_cpus 控制配额，避免“饿死”其他容器。
|
||||
- 使用 HostConfig.memory_swap 与 memory_limit 的组合，确保内存+交换总量可控。
|
||||
- 网络连接
|
||||
- 通过动态网络连接而非 host 网络模式，减少不必要的端口暴露与网络冲突。
|
||||
- I/O 与挂载
|
||||
- 优先使用只读挂载（read_only=true），降低写入风险；对大文件或频繁读写场景，评估磁盘 IO 与缓存策略。
|
||||
- 日志与诊断
|
||||
- 在开发阶段开启调试日志，生产环境适度降低日志级别，避免 I/O 影响。
|
||||
|
||||
## 故障排查指南
|
||||
- 容器创建失败
|
||||
- 检查 Docker 连接状态与权限；确认镜像存在或可拉取；核对 HostConfig 的 cap_drop、privileged、mounts 等配置。
|
||||
- 容器启动后立即退出
|
||||
- 通过 DockerManager 的健康检查与状态查询定位退出原因；查看容器日志与错误信息。
|
||||
- 网络连接异常
|
||||
- 使用 ContainerManager 的 get_container_network_info 获取容器网络信息；确认容器已连接到动态检测的主网络。
|
||||
- 路径解析失败
|
||||
- 使用 HostPathResolver 的 get_diagnostics 获取挂载信息；确认容器内路径以 /app 开头且存在相应挂载映射；必要时回退到绝对路径解析。
|
||||
- 权限不足
|
||||
- 确认 Docker socket 权限与容器内 /proc 访问权限；检查 cap_drop 是否移除了必要的能力集。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L580-L790)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L200-L270)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L160-L210)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L250-L309)
|
||||
|
||||
## 结论
|
||||
本项目通过在 manager.rs 中应用能力集降级、禁用特权模式与资源限制，结合 types.rs 的配置结构体，实现了对容器 CPU、内存与交换的可控约束；通过 host_path_resolver.rs 与 docker_container_agent.rs 的协作，有效防止路径遍历与越权挂载，提升了挂载阶段的安全性；配合 container_manager.rs 的动态网络连接与服务 URL 构造，进一步降低了容器间与宿主机的暴露面。整体遵循最小权限原则，兼顾开发便利性与运行时安全。
|
||||
|
||||
## 附录
|
||||
|
||||
### 实际配置示例（平衡开发便利性与安全）
|
||||
- 资源限制
|
||||
- 在 DockerContainerConfig 中设置 resource_limits：memory_limit、cpu_limit、swap_limit，按项目需求设定上限。
|
||||
- 对开发环境可适当放宽限制，生产环境严格限制并开启 swap 保护。
|
||||
- 只读挂载
|
||||
- 对不需要写入的挂载点设置 read_only=true，减少数据破坏风险。
|
||||
- 安全选项
|
||||
- 保持 privileged=false，cap_drop 包含 NET_RAW、NET_ADMIN 等高危能力。
|
||||
- 避免使用 host 网络模式，通过动态网络连接实现容器间通信。
|
||||
- 路径解析
|
||||
- 使用 docker_container_agent 的挂载解析流程，确保容器内路径统一标准化并解析为宿主机绝对路径，防止 ../ 等路径穿越。
|
||||
|
||||
章节来源
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L297-L346)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L80-L170)
|
||||
|
||||
### 容器逃逸风险缓解与最小权限原则
|
||||
- 风险缓解
|
||||
- 禁用特权模式与能力集降级，限制容器对宿主机内核与网络的访问。
|
||||
- 使用只读挂载与最小权限文件系统，避免容器写入关键目录。
|
||||
- 通过动态网络连接与端口映射策略，减少不必要的网络暴露。
|
||||
- 最小权限原则
|
||||
- 仅授予容器完成任务所需的最小能力与权限；对挂载路径进行白名单校验与标准化处理。
|
||||
- 在开发与测试环境中适度放宽限制，生产环境严格执行安全策略。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L210)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L297-L346)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L80-L170)
|
||||
409
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/镜像管理与选择.md
Normal file
409
qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/镜像管理与选择.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# 镜像管理与选择
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕多Docker镜像管理策略展开，重点解析 image_selector.rs 中的镜像选择逻辑，说明如何根据 AI 代理类型（如 Claude、Codex 对应的服务类型）动态选择最优基础镜像；解释镜像标签策略、本地缓存检查与自动拉取机制；结合 multi-docker-image-design.md 设计文档阐述支持多镜像配置的架构考量；描述 manager.rs 如何将选定镜像应用于容器创建流程；并提供配置示例，涵盖自定义镜像源、私有仓库认证、开发/生产镜像切换等场景，以及镜像拉取超时、校验失败等常见问题的解决方案。
|
||||
|
||||
## 项目结构
|
||||
本项目采用按功能域划分的模块化组织方式，镜像管理相关的核心位于 crates/docker_manager 与 crates/shared_types：
|
||||
- crates/docker_manager：容器生命周期与镜像管理（镜像拉取、容器创建、网络等）
|
||||
- crates/shared_types：跨模块共享的数据结构与配置模型（多镜像配置、服务类型、服务镜像配置等）
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "镜像管理模块"
|
||||
IS["ImageSelector<br/>镜像选择器"]
|
||||
DM["DockerManager<br/>容器管理器"]
|
||||
DU["DockerUtils<br/>工具集"]
|
||||
DT["DockerTypes<br/>类型定义"]
|
||||
end
|
||||
subgraph "共享类型模块"
|
||||
MIC["MultiImageConfig<br/>多镜像配置"]
|
||||
SIC["ServiceImageConfig<br/>服务镜像配置"]
|
||||
ST["ServiceType<br/>服务类型"]
|
||||
end
|
||||
IS --> MIC
|
||||
IS --> ST
|
||||
IS --> DU
|
||||
DM --> IS
|
||||
DM --> DT
|
||||
MIC --> SIC
|
||||
MIC --> ST
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L73)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L175-L216)
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L120)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L73)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L175-L216)
|
||||
|
||||
## 核心组件
|
||||
- 镜像选择器（ImageSelector）：基于服务类型与平台，从多镜像配置中选择具体镜像；支持服务级覆盖与全局默认回退。
|
||||
- DockerManager：负责容器创建、网络连接、镜像拉取与健康检查；在创建容器前调用镜像选择器确定镜像。
|
||||
- 多镜像配置（MultiImageConfig）：集中管理全局默认镜像、各服务类型镜像配置、选择策略与缓存配置。
|
||||
- 服务镜像配置（ServiceImageConfig）：定义每种服务类型的镜像、环境变量、挂载点、资源限制等。
|
||||
- 服务类型（ServiceType）：枚举 RCoder 与 AgentRunner，强制明确指定服务类型，避免默认值带来的歧义。
|
||||
- 工具集（DockerUtils）：平台检测、镜像兼容性判断、容器命名等辅助能力。
|
||||
- 类型定义（DockerTypes）：容器配置、状态、管理器配置等数据结构。
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L73)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L175-L216)
|
||||
|
||||
## 架构总览
|
||||
镜像管理的整体流程如下：
|
||||
- 输入：服务类型（如 RCoder、AgentRunner）、可选的项目级镜像覆盖、全局多镜像配置。
|
||||
- 处理：镜像选择器根据“服务类型优先”策略与平台选择镜像；若服务配置缺失或禁用，则回退到全局默认镜像。
|
||||
- 输出：返回具体镜像名称。
|
||||
- 应用：DockerManager 在创建容器前检查镜像是否存在，不存在则自动拉取，随后创建并启动容器。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as "调用方"
|
||||
participant DM as "DockerManager"
|
||||
participant IS as "ImageSelector"
|
||||
participant DU as "DockerUtils"
|
||||
participant Docker as "Docker守护进程"
|
||||
Caller->>DM : 请求创建容器(含服务类型)
|
||||
DM->>IS : select_image(服务类型, 项目覆盖)
|
||||
IS->>DU : get_optimal_platform()
|
||||
DU-->>IS : 返回平台(linux/arm64 或 linux/amd64)
|
||||
IS->>IS : 选择服务镜像(通用/架构特定/全局默认)
|
||||
IS-->>DM : 返回镜像名称
|
||||
DM->>Docker : inspect_image(镜像)
|
||||
alt 本地不存在
|
||||
DM->>Docker : create_image(拉取镜像)
|
||||
Docker-->>DM : 拉取进度/完成
|
||||
end
|
||||
DM->>Docker : create_container/start_container
|
||||
Docker-->>DM : 容器ID/状态
|
||||
DM-->>Caller : 返回容器信息
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L32-L159)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L32-L159)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 镜像选择器（ImageSelector）
|
||||
- 作用：根据服务类型与平台选择镜像，支持服务级覆盖与全局默认回退。
|
||||
- 关键行为：
|
||||
- 强制验证服务类型已启用且存在配置。
|
||||
- 优先使用服务通用镜像；若未配置，则按平台选择架构特定镜像；若仍不可用，则回退到全局默认镜像。
|
||||
- 当前实现为简化版本，未内置缓存；设计文档中提供了带缓存的完整实现思路。
|
||||
- 与平台的关系：通过 DockerUtils 获取最佳平台（优先环境变量，其次自动检测），并据此选择镜像。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckService["检查服务类型是否启用且存在配置"]
|
||||
CheckService --> |否| ErrCfg["返回配置错误"]
|
||||
CheckService --> |是| TryGeneric["尝试服务通用镜像"]
|
||||
TryGeneric --> FoundGeneric{"找到通用镜像?"}
|
||||
FoundGeneric --> |是| ReturnGeneric["返回通用镜像"]
|
||||
FoundGeneric --> |否| PlatformSelect["根据平台选择架构镜像"]
|
||||
PlatformSelect --> FoundArch{"找到架构镜像?"}
|
||||
FoundArch --> |是| ReturnArch["返回架构镜像"]
|
||||
FoundArch --> |否| TryGlobal["尝试全局默认镜像"]
|
||||
TryGlobal --> FoundGlobal{"找到全局默认镜像?"}
|
||||
FoundGlobal --> |是| ReturnGlobal["返回全局默认镜像"]
|
||||
FoundGlobal --> |否| ErrNoImage["返回配置错误(无可用镜像)"]
|
||||
ReturnGeneric --> End(["结束"])
|
||||
ReturnArch --> End
|
||||
ReturnGlobal --> End
|
||||
ErrCfg --> End
|
||||
ErrNoImage --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L92-L159)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L32-L159)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
### DockerManager 与容器创建流程
|
||||
- 容器创建前的镜像检查与拉取：
|
||||
- 若镜像不存在，调用 create_image 拉取；拉取过程通过流式事件输出进度，遇到错误时返回镜像拉取失败。
|
||||
- 容器创建：
|
||||
- 构建 HostConfig、NetworkingConfig、EnvVars、Mounts、端口映射等。
|
||||
- 使用配置中的 default_platform 作为创建容器的平台参数。
|
||||
- 创建完成后进行健康检查与状态确认。
|
||||
- 与镜像选择器的集成：
|
||||
- DockerManager.select_image 调用 ImageSelector，将最终镜像注入到 DockerContainerConfig 中，再交由 create_container 流程使用。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant DM as "DockerManager"
|
||||
participant Docker as "Docker守护进程"
|
||||
DM->>Docker : inspect_image(镜像)
|
||||
alt 镜像存在
|
||||
Docker-->>DM : OK
|
||||
else 镜像不存在
|
||||
DM->>Docker : create_image(拉取)
|
||||
loop 拉取进度
|
||||
Docker-->>DM : 进度事件
|
||||
end
|
||||
Docker-->>DM : 完成/错误
|
||||
end
|
||||
DM->>Docker : create_container(start_container)
|
||||
Docker-->>DM : 容器ID/状态
|
||||
DM->>Docker : inspect_container(check_container_health)
|
||||
Docker-->>DM : 健康状态
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L294)
|
||||
|
||||
### 多镜像配置与服务类型
|
||||
- MultiImageConfig：集中管理全局默认镜像、各服务类型镜像配置、选择策略与缓存配置。
|
||||
- ServiceImageConfig：定义每种服务的镜像（通用/架构特定/默认）、环境变量、挂载点、资源限制、工作目录、网络模式等。
|
||||
- ServiceType：枚举 RCoder 与 AgentRunner，强制明确指定服务类型，避免默认值导致的歧义。
|
||||
- 设计文档中的完整实现包含镜像缓存与更丰富的策略，当前简化实现聚焦于“服务类型优先”。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+GlobalImageDefaults global_defaults
|
||||
+HashMap~String, ServiceImageConfig~ services
|
||||
+ImageSelectionStrategy selection_strategy
|
||||
+ImageCacheConfig cache_config
|
||||
}
|
||||
class ServiceImageConfig {
|
||||
+ServiceType service_type
|
||||
+Option~String~ image
|
||||
+Option~String~ arm64_image
|
||||
+Option~String~ amd64_image
|
||||
+Option~String~ default_image
|
||||
+Option~String~ image_tag_prefix
|
||||
+bool enabled
|
||||
+HashMap~String, String~ environment
|
||||
+Vec~ServiceMountConfig~ mounts
|
||||
+Vec~String~ command
|
||||
+Option~Vec~String~~ entrypoint
|
||||
+ServiceResourceLimits resource_limits
|
||||
+String work_dir
|
||||
+String network_mode
|
||||
+String container_path_template
|
||||
}
|
||||
class ServiceType {
|
||||
+as_str() String
|
||||
+from_str(s) ServiceType
|
||||
+description() String
|
||||
+is_enabled(config) bool
|
||||
}
|
||||
MultiImageConfig --> ServiceImageConfig : "包含"
|
||||
MultiImageConfig --> ServiceType : "键名与枚举一致"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
|
||||
### 镜像标签策略与平台检测
|
||||
- 平台检测：优先使用环境变量 DOCKER_DEFAULT_PLATFORM，否则自动检测当前系统架构，返回 linux/arm64 或 linux/amd64。
|
||||
- 镜像标签策略：镜像名称中包含架构后缀（如 -arm64/-amd64/-latest）时，选择器按平台优先选择对应镜像；若未包含架构后缀，则按默认镜像回退。
|
||||
- 工具函数还提供镜像与当前架构兼容性判断，便于提前发现潜在问题。
|
||||
|
||||
章节来源
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L133-L159)
|
||||
|
||||
### 本地缓存检查与自动拉取机制
|
||||
- 本地缓存：当前简化实现未内置缓存；设计文档提供了带缓存的实现思路（缓存键包含服务类型、平台与项目覆盖哈希）。
|
||||
- 自动拉取：DockerManager.ensure_image_exists 在镜像不存在时触发拉取，拉取过程持续输出进度事件，遇到错误返回镜像拉取失败。
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L30)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
|
||||
### 结合设计文档的架构考量
|
||||
- 服务类型定义：明确 RCoder 与 AgentRunner，避免默认值；提供 from_str 与描述信息。
|
||||
- 服务镜像配置：支持通用镜像、架构特定镜像与默认回退镜像；支持服务特定环境变量与挂载点。
|
||||
- 多镜像配置：支持全局默认镜像、服务类型特定配置、选择策略（当前为 ServiceOnly）与缓存配置。
|
||||
- 项目级覆盖：支持在项目层面对镜像与环境变量进行覆盖，并生成哈希键用于缓存区分。
|
||||
- 容器创建集成：在创建容器前选择镜像，合并服务特定环境变量与挂载点，再执行创建与启动。
|
||||
|
||||
章节来源
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L41-L120)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L122-L172)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L251-L448)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L450-L575)
|
||||
|
||||
### manager.rs 中镜像选择的应用
|
||||
- DockerManager.select_image 直接委托给 ImageSelector，返回镜像名称。
|
||||
- DockerManager.create_container 在创建容器前调用 ensure_image_exists，确保镜像存在后再创建与启动。
|
||||
- 通过 DockerContainerConfig.image 字段将选定镜像注入到容器创建流程。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L702-L727)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L120)
|
||||
|
||||
## 依赖关系分析
|
||||
- ImageSelector 依赖：
|
||||
- MultiImageConfig：读取全局默认与服务配置
|
||||
- ServiceType：键名与配置映射
|
||||
- DockerUtils：平台检测
|
||||
- DockerManager 依赖：
|
||||
- ImageSelector：镜像选择
|
||||
- Docker 客户端：镜像检查与拉取、容器创建与启动
|
||||
- DockerTypes：容器配置、状态、管理器配置
|
||||
- 共享类型：
|
||||
- MultiImageConfig、ServiceImageConfig、ServiceType：跨模块共享
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
ST["ServiceType"] --> IS["ImageSelector"]
|
||||
MIC["MultiImageConfig"] --> IS
|
||||
DU["DockerUtils"] --> IS
|
||||
IS --> DM["DockerManager"]
|
||||
DT["DockerTypes"] --> DM
|
||||
SIC["ServiceImageConfig"] --> MIC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L30)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L702-L727)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L73)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L175-L216)
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L30)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L702-L727)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L120)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs#L1-L65)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L73)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L175-L216)
|
||||
|
||||
## 性能考量
|
||||
- 镜像拉取：拉取过程为流式事件，建议在高并发场景下控制拉取频率与并发度，避免网络拥塞。
|
||||
- 平台检测：平台检测为 O(1)，成本极低；建议通过环境变量固定平台以减少检测开销。
|
||||
- 缓存策略：当前简化实现未内置缓存；设计文档提供了缓存键与 TTL 机制，可在双服务场景下显著降低重复计算与网络请求。
|
||||
- 资源限制：容器资源限制在 DockerManager 中设置，合理配置可避免资源争用。
|
||||
|
||||
[本节为通用指导，不涉及具体文件分析]
|
||||
|
||||
## 故障排查指南
|
||||
- 镜像拉取超时
|
||||
- 现象：ensure_image_exists 拉取过程中长时间无响应或报错。
|
||||
- 排查要点：检查网络连通性、镜像仓库可达性、代理/防火墙设置；确认镜像名称与标签正确。
|
||||
- 参考实现位置：[manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- 镜像校验失败
|
||||
- 现象：inspect_image 报错或容器启动后立即退出。
|
||||
- 排查要点：确认镜像架构与当前平台匹配；检查镜像标签是否包含架构后缀；查看容器健康状态与日志。
|
||||
- 参考实现位置：[manager.rs](file://crates/docker_manager/src/manager.rs#L759-L800)
|
||||
- 服务类型未启用或配置缺失
|
||||
- 现象：select_image 返回配置错误。
|
||||
- 排查要点：检查 MultiImageConfig.services 中对应服务是否 enabled；确认服务键名与 ServiceType.as_str() 一致。
|
||||
- 参考实现位置：[image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L92-L114)
|
||||
- 平台不匹配
|
||||
- 现象：镜像与当前平台不兼容导致运行异常。
|
||||
- 排查要点：通过 DockerUtils.get_optimal_platform 检查平台；必要时设置 DOCKER_DEFAULT_PLATFORM；确认镜像标签包含正确架构后缀。
|
||||
- 参考实现位置：[utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L759-L800)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L92-L114)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
## 结论
|
||||
本系统通过“服务类型优先”的镜像选择策略与平台感知，实现了对多镜像配置的灵活管理。当前简化实现聚焦于核心流程与可维护性，设计文档提供了完善的缓存与策略扩展方案。在实际部署中，建议：
|
||||
- 明确服务类型并启用所需服务；
|
||||
- 为不同架构提供架构特定镜像标签；
|
||||
- 通过环境变量固定平台以提升稳定性；
|
||||
- 在高并发场景下优化镜像拉取与缓存策略；
|
||||
- 遇到镜像拉取与校验问题时，结合日志与平台检测进行定位。
|
||||
|
||||
[本节为总结性内容，不涉及具体文件分析]
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置示例与最佳实践
|
||||
- 自定义镜像源与镜像标签
|
||||
- 在 rcoder_default.yml 的 multi_image_config.services.{rcoder|agent-runner} 下配置 arm64_image、amd64_image、default_image，或使用 image 指定通用镜像。
|
||||
- 参考路径：[rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L46-L153)
|
||||
- 私有仓库认证
|
||||
- DockerManager 未内置私有仓库认证逻辑；建议通过 Docker 守护进程侧的认证配置或在镜像名称中携带凭据（不推荐）。
|
||||
- 参考实现位置：[manager.rs](file://crates/docker_manager/src/manager.rs#L545-L585)
|
||||
- 开发/生产镜像切换
|
||||
- 通过 MultiImageConfig.services.{rcoder|agent-runner}.enabled 控制服务启用状态；在 rcoder_default.yml 中调整 enabled 与镜像标签。
|
||||
- 参考实现位置：[multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L198-L210)
|
||||
- 参考配置位置：[rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L46-L153)
|
||||
- 项目级镜像覆盖
|
||||
- 使用 ProjectImageOverrides 在项目层面对镜像与环境变量进行覆盖，并通过 hash_key 区分缓存。
|
||||
- 参考实现位置：[multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L308-L390)
|
||||
- 平台固定与镜像标签
|
||||
- 设置环境变量 DOCKER_DEFAULT_PLATFORM 以固定平台；确保镜像标签包含架构后缀（如 -arm64/-amd64/-latest）。
|
||||
- 参考实现位置：[utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
|
||||
章节来源
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L46-L153)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L308-L390)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
446
qiming-rcoder/.qoder/repowiki/zh/content/开发指南.md
Normal file
446
qiming-rcoder/.qoder/repowiki/zh/content/开发指南.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# 开发指南
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [README.md](file://README.md)
|
||||
- [config.yml](file://config.yml)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||||
- [mod.rs](file://crates/rcoder/src/proxy_agent/mod.rs)
|
||||
- [shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP (Agent Client Protocol) 协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，让开发者能够轻松集成和管理 AI 辅助开发功能。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L1-L652)
|
||||
|
||||
## 项目结构
|
||||
项目采用 Rust workspace 结构，包含多个 crates，每个 crate 负责特定功能：
|
||||
|
||||
```
|
||||
.
|
||||
├── crates/
|
||||
│ ├── acp_adapter/ # ACP 协议适配器
|
||||
│ ├── agent_runner/ # 代理运行器核心
|
||||
│ ├── claude-code-agent/ # Claude Code 代理实现
|
||||
│ ├── codex-acp-agent/ # Codex ACP 代理实现
|
||||
│ ├── docker_manager/ # Docker 管理器
|
||||
│ ├── pingora-proxy/ # Pingora 反向代理封装
|
||||
│ ├── rcoder/ # 主应用（Axum 路由、业务、配置）
|
||||
│ └── shared_types/ # 共享类型定义
|
||||
├── docker/ # Docker 相关脚本和配置
|
||||
├── specs/ # 设计文档
|
||||
├── .dockerignore
|
||||
├── .gitignore
|
||||
├── CLAUDE.md
|
||||
├── Cargo.lock
|
||||
├── Cargo.toml # Workspace 配置
|
||||
├── Makefile
|
||||
├── README.md
|
||||
├── config.yml # 默认配置文件
|
||||
├── http_test.rest
|
||||
├── install.md
|
||||
└── test_auto_arch_detection.sh
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L269-L377)
|
||||
|
||||
## 核心组件
|
||||
系统由多个核心组件构成，包括主应用、代理运行器、Docker 管理器、Pingora 反向代理和共享类型。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [README.md](file://README.md#L380-L382)
|
||||
|
||||
## 架构概述
|
||||
系统采用微服务架构，主要组件包括主服务、代理运行器和反向代理。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Client] --> B[Axum HTTP Server]
|
||||
A --> C[Pingora Proxy]
|
||||
B --> D[API Routes]
|
||||
B --> E[Agent Worker (LocalSet)]
|
||||
C --> F[Backends: 127.0.0.1:{port}]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [README.md](file://README.md#L18-L25)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 配置系统分析
|
||||
配置系统支持多层优先级配置，从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。
|
||||
|
||||
#### 配置结构
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppConfig {
|
||||
+default_agent : AgentType
|
||||
+projects_dir : PathBuf
|
||||
+port : u16
|
||||
+proxy_config : Option<ProxyConfig>
|
||||
+docker_config : Option<DockerConfig>
|
||||
}
|
||||
class ProxyConfig {
|
||||
+listen_port : u16
|
||||
+default_backend_port : u16
|
||||
+backend_host : String
|
||||
+port_param : String
|
||||
+health_check : HealthCheckConfig
|
||||
}
|
||||
class DockerConfig {
|
||||
+multi_image_config : Option<MultiImageConfig>
|
||||
+network_mode : Option<String>
|
||||
+work_dir : Option<String>
|
||||
+auto_cleanup : Option<bool>
|
||||
+container_ttl_seconds : Option<u64>
|
||||
}
|
||||
class HealthCheckConfig {
|
||||
+enabled : bool
|
||||
+interval_seconds : u64
|
||||
+timeout_seconds : u64
|
||||
+healthy_threshold : u32
|
||||
+unhealthy_threshold : u32
|
||||
}
|
||||
AppConfig --> ProxyConfig : "包含"
|
||||
AppConfig --> DockerConfig : "包含"
|
||||
ProxyConfig --> HealthCheckConfig : "包含"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L38-L96)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L39-L73)
|
||||
|
||||
#### 配置加载流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始加载配置]) --> CheckFile["检查配置文件是否存在"]
|
||||
CheckFile --> |存在| LoadFromFile["从文件加载配置"]
|
||||
CheckFile --> |不存在| CreateDefault["创建默认配置文件"]
|
||||
LoadFromFile --> ApplyEnv["应用环境变量覆盖"]
|
||||
CreateDefault --> ApplyEnv
|
||||
ApplyEnv --> ApplyCli["应用命令行参数覆盖"]
|
||||
ApplyCli --> Validate["验证配置"]
|
||||
Validate --> End([返回最终配置])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L254-L331)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L111-L191)
|
||||
|
||||
### 主应用分析
|
||||
主应用负责处理 HTTP 请求、管理会话状态和协调其他组件。
|
||||
|
||||
#### 主应用启动流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as main()
|
||||
participant Config as load_config_with_args()
|
||||
participant PathResolver as HostPathResolver
|
||||
participant DockerManager as DockerManager
|
||||
participant Cleanup as startup_cleanup_containers()
|
||||
participant Proxy as PingoraServerManager
|
||||
participant Server as Axum Server
|
||||
Main->>Config : 解析命令行参数并加载配置
|
||||
Config-->>Main : 返回配置对象
|
||||
Main->>PathResolver : 初始化宿主机路径解析器
|
||||
PathResolver-->>Main : 返回路径解析器
|
||||
Main->>DockerManager : 初始化全局 DockerManager
|
||||
DockerManager-->>Main : 返回 DockerManager 实例
|
||||
Main->>Cleanup : 启动时清理遗留容器
|
||||
Cleanup-->>Main : 清理结果
|
||||
Main->>Proxy : 启动 Pingora 反向代理如果启用
|
||||
Proxy-->>Main : 代理服务句柄
|
||||
Main->>Server : 创建路由并启动 HTTP 服务器
|
||||
Server-->>Main : 服务器句柄
|
||||
Main->>Main : 等待关闭信号
|
||||
Main->>Main : 执行优雅关闭
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L32-L451)
|
||||
|
||||
### 路由系统分析
|
||||
路由系统使用 Axum 框架，提供 REST API 和 SSE 流接口。
|
||||
|
||||
#### 路由结构
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppState {
|
||||
+config : AppConfig
|
||||
+sessions : DashMap<String, Arc<ProjectAndContainerInfo>>
|
||||
+project_and_agent_map : DashMap<String, Arc<ProjectAndContainerInfo>>
|
||||
+pingora_service : Option<Arc<PingoraProxyService>>
|
||||
}
|
||||
class Router {
|
||||
+create_router(state : Arc<AppState>) Router
|
||||
+create_swagger_ui() SwaggerUi
|
||||
}
|
||||
class SessionInfo {
|
||||
+session_id : String
|
||||
+user_id : String
|
||||
+project_id : Option<String>
|
||||
+created_at : DateTime<Utc>
|
||||
+last_activity : DateTime<Utc>
|
||||
}
|
||||
Router --> AppState : "使用"
|
||||
AppState --> SessionInfo : "包含"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L26-L38)
|
||||
|
||||
#### API 路由流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([HTTP 请求]) --> MatchRoute["匹配路由"]
|
||||
MatchRoute --> |/health| HealthCheck["健康检查处理器"]
|
||||
MatchRoute --> |/chat| ChatHandler["聊天处理器"]
|
||||
MatchRoute --> |/agent/progress/{session_id}| SSEHandler["SSE 通知处理器"]
|
||||
MatchRoute --> |/agent/session/cancel| CancelHandler["会话取消处理器"]
|
||||
MatchRoute --> |/agent/stop| StopHandler["代理停止处理器"]
|
||||
MatchRoute --> |/agent/status/{project_id}| StatusHandler["状态查询处理器"]
|
||||
MatchRoute --> |/proxy/*| ProxyHandler["代理处理器"]
|
||||
HealthCheck --> Response["返回健康状态"]
|
||||
ChatHandler --> Response
|
||||
SSEHandler --> Response
|
||||
CancelHandler --> Response
|
||||
StopHandler --> Response
|
||||
StatusHandler --> Response
|
||||
ProxyHandler --> Response
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L53-L83)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L41-L69)
|
||||
|
||||
### 聊天处理器分析
|
||||
聊天处理器负责处理用户聊天请求，转发到容器化代理服务。
|
||||
|
||||
#### 聊天请求处理流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as 客户端
|
||||
participant Handler as handle_chat
|
||||
participant Container as ContainerManager
|
||||
participant Forward as forward_request_to_container_service
|
||||
participant Agent as agent_runner
|
||||
Client->>Handler : 发送聊天请求
|
||||
Handler->>Container : 获取或创建容器
|
||||
Container-->>Handler : 返回容器信息
|
||||
Handler->>Handler : 更新项目状态映射
|
||||
Handler->>Forward : 转发请求到容器服务
|
||||
Forward->>Agent : 发送 HTTP 请求到 agent_runner
|
||||
Agent-->>Forward : 返回处理结果
|
||||
Forward-->>Handler : 返回解析结果
|
||||
Handler->>Handler : 更新会话状态
|
||||
Handler-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L321)
|
||||
|
||||
### SSE 通知处理器分析
|
||||
SSE 通知处理器负责建立服务器发送事件连接，实时推送代理执行进度。
|
||||
|
||||
#### SSE 代理流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([SSE 连接请求]) --> FindContainer["查找对应容器"]
|
||||
FindContainer --> |找到| GetSSEURL["获取容器 SSE 端点 URL"]
|
||||
FindContainer --> |未找到| ReturnError["返回 404 错误"]
|
||||
GetSSEURL --> |成功| CreateStream["创建 SSE 代理流"]
|
||||
GetSSEURL --> |失败| ReturnError
|
||||
CreateStream --> ConnectContainer["连接到容器 SSE 端点"]
|
||||
ConnectContainer --> |成功| ForwardEvents["转发 SSE 事件"]
|
||||
ConnectContainer --> |失败| SendErrorEvent["发送错误事件"]
|
||||
ForwardEvents --> Client["客户端接收事件"]
|
||||
SendErrorEvent --> Client
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L97-L153)
|
||||
|
||||
### Docker 管理器分析
|
||||
Docker 管理器负责容器的创建、启动、停止和删除操作。
|
||||
|
||||
#### 多镜像配置结构
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+global_defaults : GlobalImageDefaults
|
||||
+services : HashMap<String, ServiceImageConfig>
|
||||
+selection_strategy : ImageSelectionStrategy
|
||||
+cache_config : ImageCacheConfig
|
||||
}
|
||||
class GlobalImageDefaults {
|
||||
+image : Option<String>
|
||||
+arm64_image : Option<String>
|
||||
+amd64_image : Option<String>
|
||||
+default_image : Option<String>
|
||||
+registry_prefix : Option<String>
|
||||
}
|
||||
class ServiceImageConfig {
|
||||
+service_type : ServiceType
|
||||
+image : Option<String>
|
||||
+arm64_image : Option<String>
|
||||
+amd64_image : Option<String>
|
||||
+default_image : Option<String>
|
||||
+image_tag_prefix : String
|
||||
+enabled : bool
|
||||
+environment : HashMap<String, String>
|
||||
+command : Vec<String>
|
||||
+entrypoint : Option<Vec<String>>
|
||||
+resource_limits : ResourceLimits
|
||||
+work_dir : String
|
||||
+network_mode : String
|
||||
+mounts : Vec<ServiceMountConfig>
|
||||
}
|
||||
class ImageSelectionStrategy {
|
||||
+ServiceOnly
|
||||
}
|
||||
class ImageCacheConfig {
|
||||
+enabled : bool
|
||||
+ttl_seconds : u64
|
||||
+max_entries : usize
|
||||
}
|
||||
MultiImageConfig --> GlobalImageDefaults : "包含"
|
||||
MultiImageConfig --> ServiceImageConfig : "包含多个"
|
||||
MultiImageConfig --> ImageSelectionStrategy : "包含"
|
||||
MultiImageConfig --> ImageCacheConfig : "包含"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L17-L26)
|
||||
|
||||
#### 全局 DockerManager 结构
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DockerManager {
|
||||
+config : DockerManagerConfig
|
||||
+docker : Docker
|
||||
+image_selector : ImageSelector
|
||||
}
|
||||
class DockerManagerConfig {
|
||||
+multi_image_config : MultiImageConfig
|
||||
+auto_cleanup : bool
|
||||
+container_ttl_seconds : Option<u64>
|
||||
}
|
||||
class ImageSelector {
|
||||
+select_image(service_type : ServiceType) String
|
||||
}
|
||||
class global {
|
||||
+init_global_docker_manager() DockerResult<()>
|
||||
+init_global_docker_manager_with_config(config : DockerManagerConfig) DockerResult<()>
|
||||
+get_global_docker_manager() DockerResult<Arc<DockerManager>>
|
||||
+with_global_docker_manager(f : FnOnce(&Arc<DockerManager>) -> R) DockerResult<R>
|
||||
}
|
||||
DockerManager --> DockerManagerConfig : "使用"
|
||||
DockerManager --> ImageSelector : "使用"
|
||||
global --> DockerManager : "管理单例"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L144-L210)
|
||||
|
||||
## 依赖分析
|
||||
项目依赖关系复杂，主要依赖包括：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "主应用"
|
||||
Rcoder[rcoder]
|
||||
AgentRunner[agent_runner]
|
||||
end
|
||||
subgraph "基础设施"
|
||||
Pingora[pingora-proxy]
|
||||
DockerManager[docker_manager]
|
||||
SharedTypes[shared_types]
|
||||
end
|
||||
subgraph "协议适配"
|
||||
AcpAdapter[acp_adapter]
|
||||
ClaudeAgent[claude-code-agent]
|
||||
CodexAgent[codex-acp-agent]
|
||||
end
|
||||
Rcoder --> AgentRunner
|
||||
Rcoder --> Pingora
|
||||
Rcoder --> DockerManager
|
||||
Rcoder --> SharedTypes
|
||||
AgentRunner --> Pingora
|
||||
AgentRunner --> DockerManager
|
||||
AgentRunner --> SharedTypes
|
||||
AcpAdapter --> SharedTypes
|
||||
ClaudeAgent --> AcpAdapter
|
||||
CodexAgent --> AcpAdapter
|
||||
style Rcoder fill:#f9f,stroke:#333
|
||||
style AgentRunner fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 性能考虑
|
||||
系统在设计时考虑了多项性能优化：
|
||||
|
||||
1. **异步架构**：使用 Tokio 异步运行时，支持高并发处理
|
||||
2. **状态管理**：使用 DashMap 实现高效的并发状态管理
|
||||
3. **连接复用**：使用 reqwest 客户端复用 HTTP 连接
|
||||
4. **日志优化**：使用 tracing 和 JSON 格式日志，便于后续分析
|
||||
5. **资源清理**：定期清理闲置容器，释放系统资源
|
||||
|
||||
**Section sources**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L164)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L158-L164)
|
||||
|
||||
## 故障排除指南
|
||||
常见问题及解决方案：
|
||||
|
||||
### 容器自检测失败
|
||||
当容器自检测失败时，检查以下配置：
|
||||
- Docker socket 路径是否正确
|
||||
- Docker socket 是否已挂载到容器
|
||||
- 容器是否有权限访问 Docker API
|
||||
- 项目工作目录是否正确挂载
|
||||
|
||||
### 端口被占用
|
||||
使用 `--port` 参数指定其他端口：
|
||||
```bash
|
||||
cargo run --bin rcoder -- --port 8087
|
||||
```
|
||||
|
||||
### AI 代理连接失败
|
||||
检查 API 密钥和网络连接，确保相关服务已正确配置。
|
||||
|
||||
### 配置文件错误
|
||||
检查 YAML 格式和字段名称，确保配置文件语法正确。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L620-L626)
|
||||
|
||||
## 结论
|
||||
RCoder 是一个功能强大的 AI 驱动开发平台，通过模块化设计和现代化技术栈实现了高效的 AI 代理集成。系统具有良好的可扩展性和维护性，适合进一步开发和定制。
|
||||
380
qiming-rcoder/.qoder/repowiki/zh/content/快速开始.md
Normal file
380
qiming-rcoder/.qoder/repowiki/zh/content/快速开始.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 快速开始
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [install.md](file://install.md)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [config.yml](file://config.yml)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能与可用性](#性能与可用性)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP（Agent Client Protocol）协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，支持聊天、SSE 实时进度流、代理服务与容器化工作流，适用于本地开发与生产部署。
|
||||
|
||||
- 核心能力：反向代理（Cloudflare Pingora）、HTTP API（Axum）、多代理支持（Codex、Claude Code）、异步架构（Tokio）、可观测性（Tracing + OpenTelemetry）、Swagger UI 文档。
|
||||
- 快速开始：克隆仓库、构建、运行主服务、可选启用 Pingora 反向代理、使用 curl 或 Swagger UI 调用 API。
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L1-L60
|
||||
|
||||
## 项目结构
|
||||
RCoder 采用多 crate Workspace 组织，核心模块包括：
|
||||
- 主应用（rcoder）：Axum 路由、业务处理、配置加载、代理启动
|
||||
- 代理运行器（agent_runner）：独立运行 AI 代理工作流，支持本地任务通道与 Pingora 代理
|
||||
- Pingora 代理封装（pingora-proxy）：代理配置、服务管理
|
||||
- 共享类型（shared_types）：模型、错误、协议类型
|
||||
- Claude Code 代理（claude-code-agent）
|
||||
- Codex ACP 代理（codex-acp-agent）
|
||||
- Docker 管理（docker_manager）
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "主应用 rcoder"
|
||||
A["crates/rcoder/src/main.rs"]
|
||||
B["crates/rcoder/src/router.rs"]
|
||||
C["crates/rcoder/src/config.rs"]
|
||||
D["crates/rcoder/src/handler/chat_handler.rs"]
|
||||
end
|
||||
subgraph "代理运行器 agent_runner"
|
||||
E["crates/agent_runner/src/main.rs"]
|
||||
F["crates/agent_runner/src/config.rs"]
|
||||
end
|
||||
subgraph "代理封装 pingora-proxy"
|
||||
G["crates/pingora-proxy/src/config.rs"]
|
||||
end
|
||||
subgraph "共享类型 shared_types"
|
||||
H["crates/shared_types/src/lib.rs"]
|
||||
end
|
||||
A --> B
|
||||
A --> C
|
||||
A --> D
|
||||
E --> F
|
||||
A --> G
|
||||
B --> H
|
||||
D --> H
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L120)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L120)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L1-L120)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L1-L120)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L60)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L50)
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L269-L383
|
||||
|
||||
## 核心组件
|
||||
- 命令行参数与配置优先级：命令行 > 环境变量 > 配置文件 > 默认配置
|
||||
- 主服务（rcoder）：启动 Axum HTTP 服务器、加载配置、可选启动 Pingora 代理、注册路由、SSE 进度流、健康检查
|
||||
- 代理运行器（agent_runner）：独立运行 AI 代理工作流，支持本地任务通道、Pingora 代理
|
||||
- Pingora 代理：高性能反向代理，路径前缀 /proxy/{port}/{path} 转发到指定后端
|
||||
- Docker 管理：自动检测宿主机路径、容器清理、镜像多配置与资源限制
|
||||
|
||||
**章节来源**
|
||||
- file://crates/rcoder/src/config.rs#L1-L120
|
||||
- file://crates/agent_runner/src/config.rs#L1-L120
|
||||
- file://crates/pingora-proxy/src/config.rs#L1-L60
|
||||
- file://crates/rcoder/src/main.rs#L1-L120
|
||||
|
||||
## 架构总览
|
||||
RCoder 采用双服务架构：
|
||||
- Axum 主服务：提供业务 API、SSE 进度流、代理状态文档路由
|
||||
- Pingora 代理：独立监听端口，按路径前缀转发到任意后端端口
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Client["客户端"] --> Axum["Axum 主服务"]
|
||||
Client --> Proxy["Pingora 代理"]
|
||||
Axum --> Routes["API 路由"]
|
||||
Axum --> SSE["SSE 进度流"]
|
||||
Proxy --> Backend["后端服务: 127.0.0.1:{port}"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [README.md](file://README.md#L16-L31)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L210)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L16-L31
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 环境要求与安装
|
||||
- 环境要求：Rust 1.75+（2024 Edition），可选 Claude Code CLI、OpenAI Codex
|
||||
- 安装步骤：克隆仓库、构建工作区、运行主服务、可选启用 Pingora 代理
|
||||
- 命令行参数：端口、项目目录、启用代理、代理端口、默认后端端口
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Clone["克隆仓库"]
|
||||
Clone --> Build["构建工作区"]
|
||||
Build --> RunMain["运行主服务"]
|
||||
RunMain --> EnableProxy{"是否启用代理?"}
|
||||
EnableProxy --> |是| RunProxy["启动 Pingora 代理"]
|
||||
EnableProxy --> |否| Done(["完成"])
|
||||
RunProxy --> Done
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [README.md](file://README.md#L44-L105)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L44-L105
|
||||
|
||||
### 配置系统与优先级
|
||||
- 配置优先级：命令行参数 > 环境变量 > 配置文件 > 默认配置
|
||||
- 配置文件：首次启动自动生成默认配置文件；支持默认代理类型、项目目录、主服务端口、Pingora 代理配置、Docker 多镜像配置
|
||||
- 环境变量：RCODER_PORT、DATABASE_URL、CLAUDE_CODE_PATH、RUST_LOG 等
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["默认配置"] --> B["读取配置文件"]
|
||||
B --> C{"文件存在?"}
|
||||
C --> |是| D["加载配置文件"]
|
||||
C --> |否| E["创建默认配置文件"]
|
||||
D --> F["应用环境变量覆盖"]
|
||||
E --> F
|
||||
F --> G["应用命令行参数覆盖"]
|
||||
G --> H["最终配置生效"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.yml](file://config.yml#L1-L60)
|
||||
|
||||
**章节来源**
|
||||
- file://crates/rcoder/src/config.rs#L253-L332
|
||||
- file://crates/agent_runner/src/config.rs#L110-L192
|
||||
- file://README.md#L384-L450
|
||||
|
||||
### 命令行参数与运行方式
|
||||
- rcoder 主服务常用参数：
|
||||
- --port/-p：设置主服务端口
|
||||
- --projects-dir/-d：设置项目工作目录
|
||||
- --enable-proxy：启用 Pingora 反向代理
|
||||
- --proxy-port：设置代理监听端口
|
||||
- --default-backend-port：未指定端口时的默认后端端口
|
||||
- agent_runner 服务参数与 rcoder 类似，支持独立运行
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant CLI as "命令行参数"
|
||||
participant CFG as "配置加载"
|
||||
participant MAIN as "主服务启动"
|
||||
participant AXUM as "Axum 服务器"
|
||||
participant PING as "Pingora 代理"
|
||||
U->>CLI : 传入参数
|
||||
CLI->>CFG : 解析并合并配置
|
||||
CFG->>MAIN : 返回最终配置
|
||||
MAIN->>AXUM : 绑定端口并启动
|
||||
MAIN->>PING : 可选启动代理
|
||||
AXUM-->>U : 提供 API 文档与路由
|
||||
PING-->>U : 提供 /proxy/{port}/{path} 代理
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L11-L36)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L11-L36)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L178)
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L88-L105
|
||||
- file://crates/rcoder/src/config.rs#L11-L36
|
||||
- file://crates/agent_runner/src/config.rs#L11-L36
|
||||
|
||||
### API 与代理使用
|
||||
- 核心端点：
|
||||
- GET /health：健康检查
|
||||
- POST /chat：发送聊天消息给 AI 代理
|
||||
- GET /agent/progress/{session_id}：SSE 实时进度流
|
||||
- POST /agent/session/cancel：取消会话任务
|
||||
- POST /agent/stop：停止当前 Agent
|
||||
- GET /agent/status/{project_id}：查询 Agent 状态
|
||||
- GET /api/docs：Swagger UI API 文档
|
||||
- Pingora 代理：
|
||||
- 路由规则：/proxy/{port}/{path}
|
||||
- 状态查询：/proxy/status、/proxy/config、/proxy/stats
|
||||
- 真实代理请求需直接发送到 Pingora 监听端口
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant AX as "Axum 主服务"
|
||||
participant PR as "Pingora 代理"
|
||||
participant BE as "后端服务"
|
||||
C->>PR : GET /proxy/{port}/{path}
|
||||
PR->>BE : 转发到 127.0.0.1 : {port}
|
||||
BE-->>PR : 响应
|
||||
PR-->>C : 代理响应
|
||||
note over AX,PR : 状态查询接口仅用于文档与状态，真实代理请求请直接到 Pingora
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [README.md](file://README.md#L209-L242)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L209-L242
|
||||
- file://crates/rcoder/src/router.rs#L52-L84
|
||||
|
||||
### 聊天与容器化工作流
|
||||
- /chat 接口：将请求转发到容器内的 agent_runner 服务，由后者处理会话、项目隔离与 AI 代理
|
||||
- 容器管理：根据 project_id 动态创建或复用容器，支持 ServiceType::RCoder
|
||||
- SSE 进度流：统一通过 /agent/progress/{session_id} 推送执行进度
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as "用户"
|
||||
participant RC as "rcoder 主服务"
|
||||
participant CM as "容器管理"
|
||||
participant AR as "agent_runner 容器"
|
||||
participant SSE as "SSE 进度流"
|
||||
U->>RC : POST /chat
|
||||
RC->>CM : 获取/创建容器
|
||||
CM-->>RC : 返回容器信息
|
||||
RC->>AR : 转发原始请求
|
||||
AR-->>RC : 返回处理结果
|
||||
RC-->>U : 返回最终响应
|
||||
RC->>SSE : 建立 /agent/progress/{session_id} 连接
|
||||
AR-->>SSE : 推送进度事件
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
**章节来源**
|
||||
- file://crates/rcoder/src/handler/chat_handler.rs#L108-L170
|
||||
- file://crates/rcoder/src/router.rs#L52-L84
|
||||
|
||||
### Docker 与部署
|
||||
- Dockerfile：多阶段构建，包含调试工具与健康检查
|
||||
- docker-compose：挂载 Docker socket、项目工作目录、日志目录与启动脚本，设置环境变量与健康检查
|
||||
- 建议：生产环境使用 systemd 管理服务，或结合 Nginx 反向代理
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["构建镜像"] --> B["运行容器"]
|
||||
B --> C["挂载 Docker socket"]
|
||||
B --> D["挂载项目工作目录"]
|
||||
B --> E["挂载日志目录"]
|
||||
B --> F["设置环境变量"]
|
||||
F --> G["RCODER_PORT/RUST_LOG 等"]
|
||||
B --> H["健康检查 /health"]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L1-L120)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
**章节来源**
|
||||
- file://docker/Dockerfile#L1-L120
|
||||
- file://docker/docker-compose.yml#L1-L37
|
||||
- file://README.md#L490-L584
|
||||
|
||||
## 依赖关系分析
|
||||
- 工作区依赖：clap、tokio、axum、tower、sqlx、serde、tracing、opentelemetry、utoipa、pingora、bollard 等
|
||||
- 代理相关：agent-client-protocol、codex-acp（可选）、codex-core、codex-common、codex-arg0
|
||||
- 代理运行器：与 rcoder 共享配置与类型，独立运行
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
W["Workspace 依赖"] --> C1["clap"]
|
||||
W --> T1["tokio"]
|
||||
W --> A1["axum"]
|
||||
W --> O1["opentelemetry"]
|
||||
W --> U1["utoipa"]
|
||||
W --> P1["pingora"]
|
||||
W --> B1["bollard"]
|
||||
subgraph "代理依赖"
|
||||
AC["agent-client-protocol"]
|
||||
CA["codex-acp"]
|
||||
CC["codex-core"]
|
||||
CO["codex-common"]
|
||||
CG["codex-arg0"]
|
||||
end
|
||||
A1 --> AC
|
||||
CA --> CC
|
||||
CA --> CO
|
||||
CA --> CG
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://Cargo.toml#L35-L205)
|
||||
|
||||
**章节来源**
|
||||
- file://Cargo.toml#L35-L205
|
||||
|
||||
## 性能与可用性
|
||||
- 异步运行时：Tokio 全功能特性，支持高并发
|
||||
- 观测性：Tracing + OpenTelemetry，日志按天滚动，支持 trace_id 传播
|
||||
- 代理性能：Pingora 基于 Rust 异步 I/O 的高性能代理，支持健康检查与动态后端发现
|
||||
- 容器管理：自动清理遗留容器、资源限制与 TTL 控制，提升稳定性
|
||||
|
||||
[本节为通用性能讨论，无需特定文件引用]
|
||||
|
||||
## 故障排查指南
|
||||
- 端口冲突：使用 --port 指定不同端口
|
||||
- 代理连接失败：检查 API 密钥与网络连通性
|
||||
- 配置文件错误：检查 YAML 格式与字段名称
|
||||
- Docker socket 权限：确保挂载 /var/run/docker.sock 并具备访问权限
|
||||
- Pingora 代理请求：确认直接请求代理监听端口，避免误发到主服务端口
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L611-L652
|
||||
- file://crates/rcoder/src/main.rs#L322-L351
|
||||
|
||||
## 结论
|
||||
RCoder 提供了从本地开发到生产部署的一体化方案：清晰的命令行参数与配置系统、高性能的 Axum + Pingora 架构、完善的可观测性与容器化能力。按照本文的快速开始步骤，您可以迅速搭建并使用 RCoder 平台。
|
||||
|
||||
[本节为总结性内容，无需特定文件引用]
|
||||
|
||||
## 附录
|
||||
|
||||
### 常用命令与示例
|
||||
- 构建与运行主服务：cargo build --workspace；cargo run --bin rcoder
|
||||
- 启用代理：cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
|
||||
- 健康检查：curl -X GET http://localhost:3000/health
|
||||
- 聊天接口：POST /chat，SSE 进度流：GET /agent/progress/{session_id}
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L44-L105
|
||||
- file://README.md#L229-L268
|
||||
|
||||
### AI 代理配置要点
|
||||
- Claude Code：安装 CLI 并设置 API Key 与模型
|
||||
- OpenAI Codex：参考官方文档进行配置
|
||||
|
||||
**章节来源**
|
||||
- file://README.md#L107-L131
|
||||
- file://install.md#L1-L9
|
||||
598
qiming-rcoder/.qoder/repowiki/zh/content/技术栈与依赖.md
Normal file
598
qiming-rcoder/.qoder/repowiki/zh/content/技术栈与依赖.md
Normal file
@@ -0,0 +1,598 @@
|
||||
# 技术栈与依赖
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [crates/shared_types/Cargo.toml](file://crates/shared_types/Cargo.toml)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [技术栈概览](#技术栈概览)
|
||||
2. [核心依赖选型](#核心依赖选型)
|
||||
3. [Rust语言特性](#rust语言特性)
|
||||
4. [Axum框架集成](#axum框架集成)
|
||||
5. [Tokio异步运行时](#tokio异步运行时)
|
||||
6. [Pingora反向代理](#pingora反向代理)
|
||||
7. [依赖管理策略](#依赖管理策略)
|
||||
8. [配置与初始化](#配置与初始化)
|
||||
9. [代码架构与模块化](#代码架构与模块化)
|
||||
10. [实际使用示例](#实际使用示例)
|
||||
|
||||
## 技术栈概览
|
||||
|
||||
RCoder项目是一个基于Rust语言的AI代理框架，采用了现代化的异步技术栈。项目主要由多个Crate组成，包括核心服务、代理运行器、共享类型、Docker管理器和Pingora代理等组件。技术栈以Rust为核心，结合Axum作为Web框架，Tokio作为异步运行时，Pingora作为高性能反向代理，形成了一个高效、可扩展的系统架构。
|
||||
|
||||
项目采用工作区（workspace）模式管理多个Crate，通过`Cargo.toml`文件中的`[workspace]`配置来统一管理依赖和版本。这种架构设计使得各个组件可以独立开发和测试，同时又能共享公共依赖和配置。
|
||||
|
||||
**技术栈核心组件**
|
||||
- **Rust**: 系统编程语言，提供内存安全和高性能
|
||||
- **Axum**: Web框架，用于构建HTTP服务
|
||||
- **Tokio**: 异步运行时，处理并发和I/O操作
|
||||
- **Pingora**: 高性能反向代理，基于Cloudflare的技术
|
||||
- **Tonic**: gRPC框架，用于服务间通信
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
## 核心依赖选型
|
||||
|
||||
### Rust语言版本
|
||||
项目采用Rust 2024 edition，这是最新的Rust语言版本，包含了最新的语言特性和性能优化。在`Cargo.toml`文件中通过`edition = "2024"`进行指定，确保所有组件都使用统一的语言版本。
|
||||
|
||||
```toml
|
||||
[workspace.package]
|
||||
version = "0.1.0"
|
||||
edition = "2024"
|
||||
authors = ["Your Name <your.email@example.com>"]
|
||||
license = "MIT OR Apache-2.0"
|
||||
description = "Rust-based AI agent framework"
|
||||
publish = false
|
||||
```
|
||||
|
||||
### Axum Web框架
|
||||
Axum是Tokio团队开发的现代Web框架，以其高性能和类型安全著称。项目在`Cargo.toml`中配置了Axum的多个功能特性：
|
||||
|
||||
```toml
|
||||
axum = { version = "0.8", features = [
|
||||
"http2",
|
||||
"query",
|
||||
"tracing",
|
||||
"ws",
|
||||
"multipart",
|
||||
"macros",
|
||||
] }
|
||||
```
|
||||
|
||||
这些特性包括HTTP/2支持、查询参数解析、分布式追踪、WebSocket、多部分表单数据和宏支持，为构建复杂的Web服务提供了全面的功能。
|
||||
|
||||
### Tokio异步运行时
|
||||
Tokio是Rust生态系统中最流行的异步运行时，项目使用1.48版本并启用了全功能集：
|
||||
|
||||
```toml
|
||||
tokio = { version = "1.48", features = ["full"] }
|
||||
```
|
||||
|
||||
`full`特性包含了网络、文件系统、定时器等所有功能模块，为项目提供了完整的异步编程能力。
|
||||
|
||||
### Pingora反向代理
|
||||
Pingora是Cloudflare开发的高性能代理服务器，项目使用0.6版本并启用了负载均衡功能：
|
||||
|
||||
```toml
|
||||
pingora = { version = "0.6", features = ["lb"] }
|
||||
```
|
||||
|
||||
Pingora作为反向代理层，负责请求路由、负载均衡和健康检查，为前端应用提供统一的访问入口。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L27-L205)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L1-L30)
|
||||
|
||||
## Rust语言特性
|
||||
|
||||
RCoder项目充分利用了Rust语言的现代特性，确保代码的安全性、性能和可维护性。
|
||||
|
||||
### 异步编程
|
||||
项目广泛使用Rust的异步编程模型，通过`async`/`await`语法简化异步代码的编写。在主函数中使用`#[tokio::main]`宏来启动Tokio运行时：
|
||||
|
||||
```rust
|
||||
#[tokio::main]
|
||||
async fn main() -> anyhow::Result<()> {
|
||||
// 异步代码
|
||||
}
|
||||
```
|
||||
|
||||
这种模式使得异步代码看起来像同步代码一样直观，同时保持了异步执行的性能优势。
|
||||
|
||||
### 错误处理
|
||||
项目采用`anyhow`和`thiserror`库进行错误处理，提供了丰富的错误信息和上下文：
|
||||
|
||||
```toml
|
||||
anyhow = "1.0"
|
||||
thiserror = "2.0"
|
||||
```
|
||||
|
||||
`anyhow`用于应用程序代码中的错误传播，而`thiserror`用于定义自定义错误类型，两者结合提供了灵活且强大的错误处理机制。
|
||||
|
||||
### 序列化与反序列化
|
||||
使用`serde`库进行数据的序列化和反序列化，支持JSON、YAML等多种格式：
|
||||
|
||||
```toml
|
||||
serde = { version = "1.0", features = ["derive"] }
|
||||
serde_json = "1.0"
|
||||
serde_yaml = "0.9"
|
||||
```
|
||||
|
||||
`derive`特性允许通过宏自动生成序列化代码，大大减少了样板代码的编写。
|
||||
|
||||
### 日志与追踪
|
||||
项目集成了完整的日志和分布式追踪系统：
|
||||
|
||||
```toml
|
||||
tracing = "0.1"
|
||||
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
|
||||
opentelemetry = "0.30"
|
||||
opentelemetry_sdk = { version = "0.30", features = ["rt-tokio"] }
|
||||
tracing-opentelemetry = "0.31"
|
||||
```
|
||||
|
||||
这套系统提供了结构化日志、环境过滤、OpenTelemetry集成和分布式追踪功能，便于系统监控和问题排查。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L72-L104)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||||
|
||||
## Axum框架集成
|
||||
|
||||
Axum作为项目的Web框架，负责处理HTTP请求和路由。项目在多个Crate中集成了Axum，包括`rcoder`和`agent_runner`。
|
||||
|
||||
### 路由配置
|
||||
项目使用Axum的路由系统来定义API端点。在`router.rs`文件中创建路由：
|
||||
|
||||
```rust
|
||||
pub fn create_router(state: Arc<AppState>) -> Router {
|
||||
let api_routes = Router::new()
|
||||
.route("/health", get(handler::health_check))
|
||||
.route("/chat", post(handler::handle_chat))
|
||||
.route("/agent/progress/{session_id}", get(handler::agent_session_notification))
|
||||
.route("/agent/session/cancel", post(handler::agent_session_cancel))
|
||||
.route("/agent/stop", post(handler::agent_stop))
|
||||
.route("/agent/status/{project_id}", get(handler::agent_status))
|
||||
.with_state(state.clone());
|
||||
|
||||
Router::new().merge(api_routes)
|
||||
}
|
||||
```
|
||||
|
||||
这种模块化的路由设计使得API端点易于管理和扩展。
|
||||
|
||||
### 中间件
|
||||
项目实现了自定义的追踪中间件，用于请求的监控和日志记录：
|
||||
|
||||
```rust
|
||||
pub struct TracingMiddleware;
|
||||
|
||||
impl TracingMiddleware {
|
||||
pub fn new() -> Self {
|
||||
Self
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
中间件在请求处理过程中插入，可以记录请求的trace_id、处理时间和性能指标。
|
||||
|
||||
### 状态管理
|
||||
使用`Arc<AppState>`来共享应用状态，确保多线程环境下的数据安全：
|
||||
|
||||
```rust
|
||||
#[derive(Clone)]
|
||||
pub struct AppState {
|
||||
pub config: AppConfig,
|
||||
pub sessions: DashMap<String, Arc<ProjectAndContainerInfo>>,
|
||||
pub project_and_agent_map: DashMap<String, Arc<ProjectAndContainerInfo>>,
|
||||
pub pingora_service: Option<Arc<pingora_proxy::PingoraProxyService>>,
|
||||
}
|
||||
```
|
||||
|
||||
`DashMap`提供了高性能的并发哈希映射，适合高并发场景下的状态管理。
|
||||
|
||||
**Section sources**
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L1-L217)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L178)
|
||||
|
||||
## Tokio异步运行时
|
||||
|
||||
Tokio作为项目的异步运行时，提供了高效的并发处理能力。
|
||||
|
||||
### 多线程运行时
|
||||
项目使用Tokio的多线程运行时来充分利用多核CPU：
|
||||
|
||||
```rust
|
||||
#[tokio::main]
|
||||
async fn main() -> anyhow::Result<()> {
|
||||
// 使用多线程运行时
|
||||
}
|
||||
```
|
||||
|
||||
这种配置适合CPU密集型和I/O密集型混合的工作负载。
|
||||
|
||||
### 任务调度
|
||||
项目使用Tokio的任务调度功能来管理后台任务：
|
||||
|
||||
```rust
|
||||
let _cleanup_handle = start_cleanup_task(cleanup_config.clone(), state.clone());
|
||||
```
|
||||
|
||||
通过`tokio::spawn`创建异步任务，可以在后台执行清理、监控等周期性操作。
|
||||
|
||||
### 通道通信
|
||||
使用Tokio的通道进行任务间的通信：
|
||||
|
||||
```rust
|
||||
let (local_task_sender, local_task_receiver) = tokio::sync::mpsc::unbounded_channel();
|
||||
```
|
||||
|
||||
无界通道（unbounded_channel）适合高吞吐量的消息传递场景。
|
||||
|
||||
### 信号处理
|
||||
项目实现了优雅的信号处理机制，支持Ctrl+C和SIGTERM信号：
|
||||
|
||||
```rust
|
||||
fn setup_signal_handlers() -> tokio::sync::broadcast::Sender<()> {
|
||||
// 信号处理逻辑
|
||||
}
|
||||
```
|
||||
|
||||
这确保了服务可以安全地关闭，完成正在进行的操作。
|
||||
|
||||
**Section sources**
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L29-L232)
|
||||
- [Cargo.toml](file://Cargo.toml#L53-L57)
|
||||
|
||||
## Pingora反向代理
|
||||
|
||||
Pingora作为高性能反向代理，为项目提供了请求路由和负载均衡功能。
|
||||
|
||||
### 代理配置
|
||||
在`pingora-proxy` Crate中定义了代理配置：
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, StructOpt)]
|
||||
pub struct ProxyConfig {
|
||||
pub listen_port: u16,
|
||||
pub default_backend_port: u16,
|
||||
pub backend_host: String,
|
||||
pub port_param: String,
|
||||
pub config_file: Option<String>,
|
||||
pub verbose: bool,
|
||||
}
|
||||
```
|
||||
|
||||
这些配置允许灵活地调整代理行为，如监听端口、后端主机和端口参数名称。
|
||||
|
||||
### 服务启动
|
||||
代理服务的启动流程如下：
|
||||
|
||||
```rust
|
||||
let mut server_manager = PingoraServerManager::new(pingora_config);
|
||||
let pingora_service = server_manager.service();
|
||||
let handle = tokio::spawn(async move {
|
||||
if let Err(e) = server_manager.start().await {
|
||||
error!("Pingora 代理服务器启动失败: {}", e);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
通过异步任务启动代理服务器，确保不会阻塞主服务的启动。
|
||||
|
||||
### 健康检查
|
||||
项目实现了健康检查功能，确保后端服务的可用性：
|
||||
|
||||
```rust
|
||||
if config.proxy_config.as_ref().unwrap().health_check.enabled {
|
||||
let hc = &config.proxy_config.as_ref().unwrap().health_check;
|
||||
pingora_service
|
||||
.start_health_check_loop(hc.interval_seconds, (hc.timeout_seconds * 1000) as u64);
|
||||
}
|
||||
```
|
||||
|
||||
定期检查后端服务的健康状态，自动剔除不可用的实例。
|
||||
|
||||
**Section sources**
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
## 依赖管理策略
|
||||
|
||||
项目采用工作区（workspace）模式进行依赖管理，确保依赖的一致性和可维护性。
|
||||
|
||||
### 工作区配置
|
||||
在根目录的`Cargo.toml`中定义工作区：
|
||||
|
||||
```toml
|
||||
[workspace]
|
||||
members = ["crates/*"]
|
||||
exclude = ["tmp/*", "crates/ai-agents"]
|
||||
resolver = "2"
|
||||
|
||||
[workspace.dependencies]
|
||||
# 共享依赖
|
||||
tokio = { version = "1.48", features = ["full"] }
|
||||
axum = { version = "0.8", features = [...] }
|
||||
pingora = { version = "0.6", features = ["lb"] }
|
||||
```
|
||||
|
||||
这种配置使得所有Crate可以共享相同的依赖版本，避免版本冲突。
|
||||
|
||||
### 可选依赖
|
||||
项目使用可选依赖来支持不同的功能特性：
|
||||
|
||||
```toml
|
||||
[features]
|
||||
default = []
|
||||
codex = ["shared_types/codex", "dep:codex-acp-agent"]
|
||||
```
|
||||
|
||||
通过特性（features）机制，用户可以根据需要启用或禁用特定功能。
|
||||
|
||||
### 内部依赖
|
||||
Crate之间通过路径依赖进行引用：
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
shared_types = { path = "../shared_types" }
|
||||
acp-adapter = { path = "../acp_adapter" }
|
||||
codex-acp-agent = { path = "../codex-acp-agent", optional = true }
|
||||
```
|
||||
|
||||
这种本地路径依赖使得开发和测试更加方便。
|
||||
|
||||
### 版本锁定
|
||||
使用`Cargo.lock`文件锁定依赖版本，确保构建的可重现性：
|
||||
|
||||
```toml
|
||||
[[package]]
|
||||
name = "tokio"
|
||||
version = "1.48.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff360e02eab121e0bc37a2d3b4d4dc622e6eda3a8e5253d5435ecf5bd4c68408"
|
||||
```
|
||||
|
||||
这保证了在不同环境中构建的结果一致。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [Cargo.lock](file://Cargo.lock#L6979-L6993)
|
||||
|
||||
## 配置与初始化
|
||||
|
||||
项目提供了灵活的配置系统，支持命令行参数、配置文件和环境变量。
|
||||
|
||||
### 配置结构
|
||||
定义了层次化的配置结构：
|
||||
|
||||
```rust
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct AppConfig {
|
||||
pub default_agent: AgentType,
|
||||
pub projects_dir: PathBuf,
|
||||
pub port: u16,
|
||||
pub proxy_config: Option<ProxyConfig>,
|
||||
pub docker_config: Option<DockerConfig>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct ProxyConfig {
|
||||
pub listen_port: u16,
|
||||
pub default_backend_port: u16,
|
||||
pub backend_host: String,
|
||||
pub port_param: String,
|
||||
pub health_check: HealthCheckConfig,
|
||||
}
|
||||
```
|
||||
|
||||
这种嵌套结构使得配置更加组织化和可读。
|
||||
|
||||
### 配置加载
|
||||
实现多层级的配置加载优先级：
|
||||
|
||||
```rust
|
||||
pub fn load_config_with_args(cli_args: CliArgs) -> anyhow::Result<AppConfig> {
|
||||
let mut config = if std::path::Path::new(CONFIG_FILE).exists() {
|
||||
match load_config_from_file() {
|
||||
Ok(file_config) => file_config,
|
||||
Err(e) => {
|
||||
warn!("加载配置文件失败，使用默认配置: {}", e);
|
||||
AppConfig::default()
|
||||
}
|
||||
}
|
||||
} else {
|
||||
info!("配置文件不存在，创建默认配置文件");
|
||||
let default_config = AppConfig::default();
|
||||
create_default_config_file(&default_config)?;
|
||||
default_config
|
||||
};
|
||||
|
||||
// 命令行参数覆盖配置文件
|
||||
if let Some(port) = cli_args.port {
|
||||
config.port = port;
|
||||
}
|
||||
|
||||
// 环境变量覆盖所有配置
|
||||
if let Ok(port) = std::env::var("RCODER_PORT") {
|
||||
if let Ok(port) = port.parse::<u16>() {
|
||||
config.port = port;
|
||||
}
|
||||
}
|
||||
|
||||
Ok(config)
|
||||
}
|
||||
```
|
||||
|
||||
配置优先级为：环境变量 > 命令行参数 > 配置文件 > 默认值。
|
||||
|
||||
### 默认配置
|
||||
提供合理的默认配置值：
|
||||
|
||||
```rust
|
||||
impl Default for AppConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
default_agent: AgentType::Claude,
|
||||
projects_dir: PathBuf::from("./project_workspace"),
|
||||
port: 8087,
|
||||
proxy_config: Some(ProxyConfig::default()),
|
||||
docker_config: Some(DockerConfig::default()),
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这使得项目可以开箱即用，无需复杂配置。
|
||||
|
||||
**Section sources**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L38-L451)
|
||||
|
||||
## 代码架构与模块化
|
||||
|
||||
项目采用模块化的架构设计，将功能分解为独立的Crate。
|
||||
|
||||
### 核心Crate
|
||||
项目包含多个核心Crate：
|
||||
|
||||
- **rcoder**: 主服务，负责API网关和容器管理
|
||||
- **agent_runner**: 代理运行器，处理AI代理的执行
|
||||
- **shared_types**: 共享类型，定义跨Crate的数据结构
|
||||
- **pingora-proxy**: 反向代理，提供高性能的请求路由
|
||||
- **docker_manager**: Docker管理器，负责容器的生命周期管理
|
||||
|
||||
### 模块组织
|
||||
每个Crate内部采用清晰的模块组织：
|
||||
|
||||
```rust
|
||||
mod config;
|
||||
mod handler;
|
||||
mod model;
|
||||
mod proxy_agent;
|
||||
mod middleware;
|
||||
mod router;
|
||||
mod service;
|
||||
mod utils;
|
||||
```
|
||||
|
||||
这种组织方式使得代码结构清晰，易于维护。
|
||||
|
||||
### 依赖关系
|
||||
Crate之间的依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
rcoder --> agent_runner
|
||||
rcoder --> shared_types
|
||||
rcoder --> pingora-proxy
|
||||
rcoder --> docker_manager
|
||||
agent_runner --> shared_types
|
||||
agent_runner --> pingora-proxy
|
||||
shared_types --> tonic
|
||||
shared_types --> prost
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
### 接口设计
|
||||
项目定义了清晰的接口和抽象：
|
||||
|
||||
```rust
|
||||
pub trait AgentLifecycle {
|
||||
fn graceful_stop(&self) -> Pin<Box<dyn Future<Output = Result<()>> + Send + '_>>;
|
||||
fn cancel(&self);
|
||||
fn is_stopped(&self) -> bool;
|
||||
fn cancellation_token(&self) -> &CancellationToken;
|
||||
fn agent_type(&self) -> AgentType;
|
||||
}
|
||||
```
|
||||
|
||||
这种接口设计使得系统具有良好的扩展性和可测试性。
|
||||
|
||||
**Section sources**
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
## 实际使用示例
|
||||
|
||||
### 启动服务
|
||||
启动RCoder服务的基本命令：
|
||||
|
||||
```bash
|
||||
cargo run --bin rcoder -- -p 8087 --projects-dir ./workspace --enable-proxy --proxy-port 8088
|
||||
```
|
||||
|
||||
这将启动主服务，监听8087端口，并启用反向代理服务在8088端口。
|
||||
|
||||
### API调用
|
||||
发送聊天请求的示例：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8087/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "帮我写一个Rust程序",
|
||||
"project_id": "my_project",
|
||||
"model_provider": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4",
|
||||
"api_key": "sk-..."
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 代理使用
|
||||
通过Pingora代理访问后端服务：
|
||||
|
||||
```bash
|
||||
# 访问端口3000的服务
|
||||
curl "http://localhost:8088/proxy/3000/api/users"
|
||||
|
||||
# 使用查询参数指定端口
|
||||
curl "http://localhost:8088?port=3000"
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
创建自定义配置文件`config.yml`：
|
||||
|
||||
```yaml
|
||||
default_agent: claude
|
||||
projects_dir: "./custom_workspace"
|
||||
port: 9000
|
||||
proxy_config:
|
||||
listen_port: 9001
|
||||
default_backend_port: 9002
|
||||
backend_host: "127.0.0.1"
|
||||
port_param: "port"
|
||||
health_check:
|
||||
enabled: true
|
||||
interval_seconds: 5
|
||||
timeout_seconds: 1
|
||||
healthy_threshold: 2
|
||||
unhealthy_threshold: 3
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||||
329
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/安全考虑.md
Normal file
329
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/安全考虑.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 安全考虑
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构与安全边界](#项目结构与安全边界)
|
||||
3. [核心安全组件](#核心安全组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件安全分析](#详细组件安全分析)
|
||||
6. [依赖关系与耦合分析](#依赖关系与耦合分析)
|
||||
7. [性能与安全权衡](#性能与安全权衡)
|
||||
8. [故障排查与安全审计](#故障排查与安全审计)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本章节系统阐述 RCoder 在部署与运行中的安全实践，围绕容器隔离、挂载权限控制、镜像来源验证、API 访问控制、输入验证与防滥用、敏感信息管理、网络隔离脚本、日志与审计、漏洞扫描与最小权限原则等方面展开。文档旨在帮助运维与开发人员在保障功能完备的同时，提升系统的安全性与可审计性。
|
||||
|
||||
## 项目结构与安全边界
|
||||
- 容器运行时：通过 Docker Compose 启动主服务与代理服务，主服务暴露端口并可选启用反向代理；Agent Runner 作为容器内服务参与聊天处理。
|
||||
- 网络隔离：提供宿主机侧网络隔离脚本，基于 iptables 限制容器对内网地址段的访问。
|
||||
- 配置管理：支持命令行参数、环境变量与配置文件的多级覆盖；敏感信息建议通过环境变量注入，避免明文写入配置文件。
|
||||
- 日志与可观测性：内置 OpenTelemetry 与结构化日志，支持按天滚动与 trace_id 传播，便于审计与定位问题。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "宿主机"
|
||||
DC["Docker Compose<br/>rcoder 服务"]
|
||||
NI["网络隔离脚本<br/>iptables 规则"]
|
||||
LOG["日志目录<br/>logs/"]
|
||||
end
|
||||
subgraph "容器内"
|
||||
RC["rcoder 主服务"]
|
||||
AR["agent_runner 服务"]
|
||||
PM["Pingora 反向代理"]
|
||||
DM["Docker 管理器"]
|
||||
end
|
||||
DC --> RC
|
||||
RC --> PM
|
||||
RC --> DM
|
||||
RC --> AR
|
||||
NI -.-> DC
|
||||
LOG -.-> RC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
章节来源
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
|
||||
|
||||
## 核心安全组件
|
||||
- 容器隔离与能力控制：容器启动时丢弃网络相关能力，禁用特权模式，降低逃逸风险。
|
||||
- 网络隔离脚本：在宿主机 iptables 上为 rcoder- 前缀网络添加规则，阻止访问常见内网地址段。
|
||||
- 配置与环境变量：支持环境变量覆盖端口、工作目录、网络模式、自动清理、容器 TTL 等，敏感信息建议通过环境变量注入。
|
||||
- 日志与追踪：结构化 JSON 日志按天滚动，trace_id 传播，便于审计与关联分析。
|
||||
- 反向代理与健康检查：Pingora 代理提供后端健康检查与统计接口，便于监控与故障定位。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L212-L239)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L134-L171)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L232)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
## 架构总览
|
||||
下图展示 RCoder 主服务、Agent Runner、Pingora 代理与 Docker 管理器之间的交互，以及网络隔离脚本对宿主机网络的影响。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant RC as "rcoder 主服务"
|
||||
participant PM as "Pingora 代理"
|
||||
participant AR as "agent_runner 服务"
|
||||
participant DM as "Docker 管理器"
|
||||
participant NI as "网络隔离脚本"
|
||||
Client->>RC : "POST /chat"
|
||||
RC->>DM : "获取/创建容器"
|
||||
DM-->>RC : "返回容器信息"
|
||||
RC->>AR : "转发请求到容器内 /chat"
|
||||
AR-->>RC : "返回处理结果"
|
||||
RC-->>Client : "返回响应"
|
||||
Note over NI,PM : "宿主机 iptables 限制容器访问内网"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L321)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L105-L165)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L70-L95)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
|
||||
## 详细组件安全分析
|
||||
|
||||
### 容器隔离与挂载权限控制
|
||||
- 能力与特权控制
|
||||
- 容器启动时丢弃网络原始与管理能力，禁用特权模式，降低容器逃逸与网络嗅探风险。
|
||||
- 挂载策略
|
||||
- 默认挂载类型为 bind，部分服务挂载路径允许只读或额外绑定，需谨慎评估挂载路径与权限。
|
||||
- 网络隔离脚本
|
||||
- 通过查找 rcoder- 前缀网络，为每个网络子网添加 DROP 规则，阻止访问常见内网地址段；规则在系统重启后会丢失，需持久化或开机重载。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["容器启动"]) --> DropCaps["丢弃网络相关能力<br/>禁用特权模式"]
|
||||
DropCaps --> Mounts["绑定挂载配置<br/>只读/额外挂载"]
|
||||
Mounts --> NetIsolate["宿主机 iptables 规则<br/>阻止访问内网地址段"]
|
||||
NetIsolate --> Run(["容器运行"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L70-L95)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L105-L165)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
|
||||
|
||||
### 镜像来源验证与多镜像配置
|
||||
- 多镜像配置
|
||||
- 支持按服务类型选择镜像，包含全局默认与架构特定镜像，策略为仅使用服务特定配置。
|
||||
- 缓存与选择
|
||||
- 提供镜像缓存配置，支持 TTL 与最大条目数；镜像选择策略为 ServiceOnly。
|
||||
- 建议
|
||||
- 通过 registry 前缀与服务特定镜像保证来源可控；结合镜像签名与拉取策略，进一步强化来源可信度。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+services
|
||||
+global_defaults
|
||||
+selection_strategy
|
||||
+cache_config
|
||||
+validate()
|
||||
+hash_key()
|
||||
}
|
||||
class ServiceConfig {
|
||||
+service_type
|
||||
+image/arm64/amd64
|
||||
+mounts
|
||||
+environment
|
||||
+resource_limits
|
||||
+get_image_for_platform(platform)
|
||||
+validate()
|
||||
}
|
||||
MultiImageConfig --> ServiceConfig : "包含"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L110)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L361-L406)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L153-L188)
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L110)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L361-L406)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L153-L188)
|
||||
|
||||
### API 端点访问控制、输入验证与防滥用
|
||||
- 访问控制
|
||||
- 当前未实现显式的鉴权/授权中间件；建议在反向代理层或网关处增加认证与授权策略。
|
||||
- 输入验证
|
||||
- 主服务与 Agent Runner 均对请求进行基本校验（如 prompt 非空），并在业务层进行并发控制与会话清理。
|
||||
- 防滥用
|
||||
- 通过并发请求限制与会话缓存清理，避免同一项目下的并发冲突；建议引入速率限制中间件或上游限流策略。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant RC as "rcoder 主服务"
|
||||
participant AR as "agent_runner 服务"
|
||||
Client->>RC : "POST /chat"
|
||||
RC->>RC : "校验请求参数"
|
||||
RC->>AR : "转发请求"
|
||||
AR->>AR : "并发检查/会话清理"
|
||||
AR-->>RC : "返回结果"
|
||||
RC-->>Client : "返回响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L238)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
|
||||
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L238)
|
||||
|
||||
### 配置文件与敏感信息管理
|
||||
- 配置优先级
|
||||
- 命令行参数 > 环境变量 > 配置文件 > 默认配置；Docker 配置支持环境变量覆盖。
|
||||
- 敏感信息建议
|
||||
- 将密钥、令牌等敏感信息通过环境变量注入，避免写入 config.yml；必要时使用密钥管理服务或容器编排平台的机密存储。
|
||||
- 配置文件生成
|
||||
- 首次启动会生成默认配置文件，建议在部署时以只读方式挂载或通过环境变量覆盖。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
### 网络隔离脚本实施与影响
|
||||
- 规则生效范围
|
||||
- 为 rcoder- 前缀网络添加 DROP 规则，阻止访问常见内网地址段；规则在系统重启后会丢失，需持久化。
|
||||
- 实施建议
|
||||
- 将脚本加入系统启动项或 systemd 服务；定期检查规则有效性；结合防火墙策略与网络命名空间进一步加固。
|
||||
|
||||
章节来源
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
|
||||
|
||||
### 日志与追踪、健康检查与可观测性
|
||||
- 日志
|
||||
- 结构化 JSON 日志按天滚动，支持 trace_id 传播，便于审计与跨服务关联。
|
||||
- 追踪
|
||||
- 中间件生成并传播 trace_id，便于端到端链路追踪。
|
||||
- 健康检查
|
||||
- Pingora 代理提供健康检查循环与统计接口，便于监控后端健康状态。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder 主服务"
|
||||
participant PM as "Pingora 代理"
|
||||
participant HC as "健康检查循环"
|
||||
RC->>PM : "启动代理服务"
|
||||
PM->>HC : "启动健康检查循环"
|
||||
HC->>HC : "周期性检查后端连通性"
|
||||
PM-->>RC : "健康状态快照/统计"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L121)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L232)
|
||||
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
|
||||
|
||||
### 最小权限原则与系统提示词约束
|
||||
- 最小权限
|
||||
- 容器禁用特权模式并丢弃网络相关能力，减少潜在攻击面。
|
||||
- 系统提示词约束
|
||||
- Agent Runner 的系统提示词包含多项安全禁令，禁止内网探测、反向 Shell、框架转换等行为，有助于降低风险。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L96-L115)
|
||||
|
||||
## 依赖关系与耦合分析
|
||||
- 组件耦合
|
||||
- rcoder 主服务依赖 Docker 管理器进行容器生命周期管理；与 Pingora 代理耦合用于后端发现与健康检查；与 Agent Runner 通过容器内通信协作。
|
||||
- 外部依赖
|
||||
- Docker API、iptables、Pingora 代理、OpenTelemetry/Tracing。
|
||||
- 潜在风险
|
||||
- Docker socket 挂载与权限配置不当可能导致容器逃逸；网络隔离规则缺失可能使容器访问内网。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RC["rcoder 主服务"] --> DM["Docker 管理器"]
|
||||
RC --> PM["Pingora 代理"]
|
||||
RC --> AR["agent_runner 服务"]
|
||||
NI["网络隔离脚本"] -.-> RC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L111-L158)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L52-L95)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L111-L158)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
|
||||
|
||||
## 性能与安全权衡
|
||||
- 性能
|
||||
- 容器能力限制与网络隔离会带来一定开销，但显著降低逃逸与横向移动风险。
|
||||
- 安全
|
||||
- 建议在生产环境启用严格的镜像来源验证、最小权限与网络隔离；结合速率限制与上游防护，平衡吞吐与安全。
|
||||
|
||||
[本节为通用指导，无需引用具体文件]
|
||||
|
||||
## 故障排查与安全审计
|
||||
- 日志审计
|
||||
- 检查 logs 目录下的 JSON 日志，结合 trace_id 进行关联分析；关注健康检查失败与代理统计异常。
|
||||
- 网络隔离验证
|
||||
- 使用脚本列出当前规则，确认 rcoder- 网络的 DROP 规则已生效；必要时重新加载规则。
|
||||
- 配置核验
|
||||
- 确认环境变量覆盖生效，敏感信息未出现在配置文件中；检查 Docker 配置与挂载路径。
|
||||
- 漏洞扫描
|
||||
- 建议对镜像进行静态扫描，识别高危漏洞；对运行时容器进行定期扫描与基线核查。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
|
||||
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L97-L112)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
|
||||
## 结论
|
||||
RCoder 在容器隔离、网络隔离、日志与追踪方面具备良好基础。建议在生产环境中补充鉴权/授权、速率限制、镜像来源验证与漏洞扫描机制，严格使用环境变量管理敏感信息，并完善网络隔离规则的持久化与监控，以实现更全面的安全保障与可审计性。
|
||||
189
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/常见问题.md
Normal file
189
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/常见问题.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 常见问题
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [config.yml](file://config.yml)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [CLAUDE.md](file://CLAUDE.md)
|
||||
- [install.md](file://install.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [代理启动失败](#代理启动失败)
|
||||
2. [端口冲突问题](#端口冲突问题)
|
||||
3. [Docker权限错误](#docker权限错误)
|
||||
4. [SSE流中断](#sse流中断)
|
||||
5. [Claude Code代理集成限制](#claude-code代理集成限制)
|
||||
|
||||
## 代理启动失败
|
||||
|
||||
代理启动失败通常由配置错误或依赖服务未就绪导致。根据`crates/pingora-proxy/src/server.rs`中的实现，代理服务在启动时会进行配置验证。
|
||||
|
||||
**根本原因分析**：
|
||||
- 配置文件`config.yml`中`proxy_config.listen_port`设置为0或无效值
|
||||
- 环境变量`RCODER_PORT`与代理端口冲突
|
||||
- Docker socket未正确挂载，导致容器无法通信
|
||||
|
||||
**调试步骤**：
|
||||
1. 检查日志中是否出现"配置验证失败"错误
|
||||
2. 验证`config.yml`中`proxy_config.listen_port`是否为有效端口
|
||||
3. 确认Docker socket路径是否正确挂载
|
||||
|
||||
**解决方案**：
|
||||
```yaml
|
||||
# config.yml
|
||||
proxy_config:
|
||||
listen_port: 8088 # 确保端口大于0
|
||||
default_backend_port: 8087 # 与主服务端口一致
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L27-L54)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L50-L68)
|
||||
- [config.yml](file://config.yml#L16)
|
||||
|
||||
## 端口冲突问题
|
||||
|
||||
端口冲突主要发生在多个服务尝试绑定同一端口时。系统通过`port_manager.rs`管理端口分配。
|
||||
|
||||
**根本原因分析**：
|
||||
- 多个RCoder实例同时运行
|
||||
- 端口范围(8000-9999)内所有端口已被占用
|
||||
- 容器未正确清理，遗留端口映射
|
||||
|
||||
**调试步骤**：
|
||||
1. 检查`netstat -an | grep <port>`确认端口占用情况
|
||||
2. 查看日志中"端口范围内无可用端口"错误
|
||||
3. 使用`docker ps`检查是否有遗留容器
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 修改端口范围
|
||||
cargo run --bin rcoder -- --port 9000 --proxy-port 9001
|
||||
```
|
||||
|
||||
或在代码中调整端口管理器范围：
|
||||
```rust
|
||||
// port_manager.rs
|
||||
impl PortManager {
|
||||
pub fn new() -> Self {
|
||||
Self::with_range(10000, 11999) // 扩大端口范围
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L32-L49)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L223-L225)
|
||||
|
||||
## Docker权限错误
|
||||
|
||||
Docker权限错误通常与socket访问权限或挂载配置有关。
|
||||
|
||||
**根本原因分析**：
|
||||
- Docker socket未挂载到容器
|
||||
- 用户不在docker组中
|
||||
- 路径解析器初始化失败
|
||||
|
||||
**调试步骤**：
|
||||
1. 检查`docker-compose.yml`中socket挂载配置
|
||||
2. 验证用户权限：`groups $USER | grep docker`
|
||||
3. 测试Docker API连通性：`curl --unix-socket /var/run/docker.sock http://localhost/info`
|
||||
|
||||
**解决方案**：
|
||||
确保`docker-compose.yml`包含正确配置：
|
||||
```yaml
|
||||
services:
|
||||
rcoder:
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- ./project_workspace:/app/project_workspace
|
||||
```
|
||||
|
||||
并添加用户到docker组：
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L49-L82)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L11-L15)
|
||||
|
||||
## SSE流中断
|
||||
|
||||
SSE（Server-Sent Events）流中断会影响实时进度更新功能。
|
||||
|
||||
**根本原因分析**：
|
||||
- 客户端连接超时设置过短
|
||||
- 代理配置未正确转发SSE连接
|
||||
- 服务器资源不足导致连接被重置
|
||||
|
||||
**调试步骤**：
|
||||
1. 检查客户端是否设置`Connection: keep-alive`
|
||||
2. 验证Nginx等反向代理的超时配置
|
||||
3. 监控服务器资源使用情况
|
||||
|
||||
**解决方案**：
|
||||
在客户端增加重连机制：
|
||||
```javascript
|
||||
const eventSource = new EventSource('/agent/progress/session123');
|
||||
eventSource.onmessage = (event) => {
|
||||
console.log(event.data);
|
||||
};
|
||||
eventSource.onerror = () => {
|
||||
setTimeout(() => {
|
||||
// 重新连接
|
||||
eventSource.close();
|
||||
}, 5000);
|
||||
};
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L254-L266)
|
||||
|
||||
## Claude Code代理集成限制
|
||||
|
||||
Claude Code代理集成存在特定限制和配置要求。
|
||||
|
||||
**根本原因分析**：
|
||||
- CLI工具未正确安装
|
||||
- API密钥未配置
|
||||
- 环境变量未正确传递
|
||||
|
||||
**调试步骤**：
|
||||
1. 验证Claude CLI安装：`claude --version`
|
||||
2. 检查环境变量：`echo $ANTHROPIC_API_KEY`
|
||||
3. 查看日志中代理初始化错误
|
||||
|
||||
**解决方案**：
|
||||
1. 安装CLI工具：
|
||||
```bash
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
```
|
||||
|
||||
2. 配置环境变量：
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
|
||||
```
|
||||
|
||||
3. 在`config.yml`中确保代理配置正确：
|
||||
```yaml
|
||||
default_agent: "Claude"
|
||||
```
|
||||
|
||||
**规避方法**：
|
||||
- 使用环境变量而非配置文件存储API密钥
|
||||
- 实现密钥轮换机制
|
||||
- 添加代理健康检查
|
||||
|
||||
**Section sources**
|
||||
- [CLAUDE.md](file://CLAUDE.md#L109-L132)
|
||||
- [install.md](file://install.md#L5-L8)
|
||||
- [config.yml](file://config.yml#L5)
|
||||
335
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/性能优化.md
Normal file
335
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/性能优化.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 性能优化
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件聚焦RCoder系统在高并发、低延迟场景下的性能优化策略，围绕以下主题展开：
|
||||
- Pingora反向代理的性能优势与配置参数对吞吐量的影响
|
||||
- 代理会话的资源清理机制（cleanup_task.rs）如何避免内存泄漏和连接堆积
|
||||
- 系统提示词（system_prompt.rs）优化建议以降低AI推理开销
|
||||
- Tokio运行时调优、连接池配置、缓存策略与SSE流压缩等实践
|
||||
- 基于实际压测数据与火焰图（generate-flamegraph.sh）的优化效果验证
|
||||
|
||||
## 项目结构
|
||||
RCoder系统由“代理层”和“业务层”组成：
|
||||
- 代理层：基于Cloudflare Pingora的高性能反向代理，支持HTTP/1.1与HTTP/2、健康检查、连接池与负载均衡
|
||||
- 业务层：Agent Runner提供统一SSE流、会话缓存、清理任务与代理会话管理；RCoder侧提供SSE代理与后端健康状态查询
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "代理层"
|
||||
PLib["pingora-proxy 库<br/>lib.rs"]
|
||||
PConf["配置<br/>config.rs"]
|
||||
PServer["服务器管理<br/>pingora_server.rs"]
|
||||
PRun["服务器运行器<br/>server.rs"]
|
||||
PMetrics["指标记录<br/>service.rs"]
|
||||
end
|
||||
subgraph "业务层"
|
||||
ARMain["Agent Runner 入口<br/>main.rs"]
|
||||
Clean["清理任务<br/>cleanup_task.rs"]
|
||||
Sess["会话缓存<br/>session_cache.rs"]
|
||||
SSE["SSE处理器<br/>agent_session_notification.rs"]
|
||||
ProxyAPI["代理API<br/>proxy_handler_api.rs"]
|
||||
end
|
||||
PLib --> PServer
|
||||
PLib --> PRun
|
||||
PConf --> PServer
|
||||
PServer --> PMetrics
|
||||
ARMain --> PServer
|
||||
ARMain --> Clean
|
||||
ARMain --> Sess
|
||||
Sess --> SSE
|
||||
ProxyAPI --> PServer
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L120)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L1-L120)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L90-L140)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L120)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L100-L170)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L1-L120)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L120)
|
||||
|
||||
## 核心组件
|
||||
- Pingora反向代理库：提供高性能、异步I/O、HTTP/1.1与HTTP/2支持、健康检查与连接池
|
||||
- 代理服务器管理器：封装Pingora Server启动、监听与关闭信号处理
|
||||
- 代理服务器运行器：提供便捷的代理实例创建与负载均衡算法选择
|
||||
- 会话缓存与SSE：基于环形缓冲区与mpsc通道的极简设计，支持心跳与取消令牌
|
||||
- 清理任务：基于RAII的闲置Agent清理，定期扫描并移除超时闲置Agent，避免资源泄漏
|
||||
- 系统提示词：通过结构化提示词配置降低AI推理冗余，提升稳定性与一致性
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L1-L120)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L1-L120)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L120)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L120)
|
||||
|
||||
## 架构总览
|
||||
RCoder在高并发场景下的关键路径：
|
||||
- 客户端请求经Pingora代理到达业务层路由
|
||||
- 业务层根据会话ID将SSE流推送至客户端
|
||||
- 代理层维护后端健康状态与连接池，保障低延迟转发
|
||||
- 清理任务周期性回收闲置Agent，避免内存与连接堆积
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant P as "Pingora代理"
|
||||
participant R as "Agent Runner"
|
||||
participant S as "会话缓存/Worker"
|
||||
participant T as "清理任务"
|
||||
C->>P : "HTTP 请求"
|
||||
P->>R : "转发到业务路由"
|
||||
R->>S : "推送SSE消息"
|
||||
S-->>R : "实时消息/心跳"
|
||||
R-->>C : "SSE流"
|
||||
T->>R : "周期清理闲置Agent"
|
||||
R-->>T : "清理完成"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L38-L120)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L390-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L278-L310)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Pingora反向代理性能与配置
|
||||
- 性能优势
|
||||
- 基于Pingora的高性能异步I/O与HTTP/1.1、HTTP/2支持，适合高并发与低延迟场景
|
||||
- 内置健康检查与连接池，减少后端抖动带来的延迟
|
||||
- 负载均衡算法可选轮询或一致性哈希，满足不同流量特征
|
||||
- 关键配置参数
|
||||
- 监听端口、默认后端端口、后端主机、端口参数名、详细日志开关
|
||||
- 负载均衡算法（轮询/一致性哈希）影响后端命中与抖动
|
||||
- 吞吐量影响
|
||||
- 合理设置监听端口与后端端口，避免端口冲突与回退路径
|
||||
- 启用健康检查与连接池可显著降低后端异常导致的失败率与重试成本
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["代理启动"]) --> LoadCfg["加载配置<br/>监听端口/后端端口/主机/参数名"]
|
||||
LoadCfg --> LB["选择负载均衡算法<br/>轮询/一致性哈希"]
|
||||
LB --> HC["健康检查与连接池"]
|
||||
HC --> Run["运行服务器"]
|
||||
Run --> Metrics["记录指标<br/>成功率/平均响应时间"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L120-L155)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L90-L140)
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs#L120-L155)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L90-L140)
|
||||
|
||||
### 代理会话资源清理机制（cleanup_task.rs）
|
||||
- 设计要点
|
||||
- 基于RAII的清理：从全局映射移除Agent即触发资源自动释放
|
||||
- 定时扫描：按闲置超时与清理间隔执行
|
||||
- 清理范围：闲置Agent、孤立SSE会话与消息
|
||||
- 关键流程
|
||||
- 先清理孤立SSE会话与消息，再扫描Idle状态Agent
|
||||
- 通过全局映射与上下文映射同步清理，避免悬挂引用
|
||||
- 统计清理数量与剩余状态，便于监控
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Tick["定时Tick"] --> Scan["扫描闲置Agent"]
|
||||
Scan --> |Idle且超时| Remove["从映射移除<br/>触发RAII清理"]
|
||||
Scan --> |非Idle| Skip["跳过"]
|
||||
Remove --> Stats["更新统计"]
|
||||
Skip --> Stats
|
||||
Stats --> Done["完成一轮清理"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L241)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L243-L310)
|
||||
|
||||
章节来源
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L310)
|
||||
|
||||
### 系统提示词优化建议（system_prompt.rs）
|
||||
- 目标：降低AI推理开销，提升一致性与安全性
|
||||
- 建议
|
||||
- 明确框架识别优先级与路由模式（hash模式），避免重复检索与转换
|
||||
- 严格约束安全与框架转换禁令，减少无效推理分支
|
||||
- 限定允许的操作范围，减少无关工具调用
|
||||
- 将MCP工具使用规则前置，减少上下文膨胀
|
||||
- 效果：通过结构化提示词减少模型输出冗余，缩短推理时间，提高稳定性
|
||||
|
||||
章节来源
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L1-L260)
|
||||
- [system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L260-L407)
|
||||
|
||||
### Tokio运行时调优与连接池配置
|
||||
- 运行时布局
|
||||
- 主异步运行时：启动清理任务、代理服务器与HTTP服务
|
||||
- 单线程LocalSet运行时：承载非Send的Agent Worker，避免跨线程迁移成本
|
||||
- 连接池与健康检查
|
||||
- 代理层内置连接池与健康检查，按配置启动健康检查循环
|
||||
- 通过后端健康快照与后端列表接口暴露状态，便于运维观测
|
||||
- 建议
|
||||
- 根据CPU核数与I/O密集度调整主运行时线程数
|
||||
- 为I/O密集型任务分配更多线程，为CPU密集型任务使用LocalSet隔离
|
||||
- 合理设置健康检查间隔与超时，避免过度探测
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant M as "主运行时"
|
||||
participant L as "LocalSet运行时"
|
||||
participant P as "Pingora服务器"
|
||||
participant HC as "健康检查循环"
|
||||
M->>M : "启动清理任务"
|
||||
M->>P : "启动代理服务器"
|
||||
M->>HC : "启动健康检查循环"
|
||||
L->>L : "运行Agent Worker!Send"
|
||||
HC-->>M : "后端健康状态快照"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L29-L120)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L60-L120)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
章节来源
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L29-L120)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L60-L120)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
### 缓存策略与SSE流压缩
|
||||
- 会话缓存（session_cache.rs）
|
||||
- 基于环形缓冲区（ringbuf）与mpsc通道，支持心跳过滤与实时推送
|
||||
- 通过共享状态直接设置当前连接，避免命令传递开销
|
||||
- 主动关闭SSE连接时使用取消令牌与显式关闭发送端，确保客户端及时断开
|
||||
- SSE流（agent_session_notification.rs）
|
||||
- SSE代理直连容器SSE端点，按双换行符分割事件，透传原始SSE数据
|
||||
- 心跳定时器与取消令牌结合，保证连接生命周期可控
|
||||
- 压缩建议
|
||||
- SSE事件透传原始数据，建议在上游服务端启用Gzip/Deflate压缩
|
||||
- 对于大消息，可考虑分片与增量推送，减少单事件体积
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Push["推送消息到SessionData"] --> Buffer["环形缓冲区"]
|
||||
Buffer --> Realtime["实时推送到当前连接"]
|
||||
Realtime --> |失败| Drop["清空当前连接状态"]
|
||||
Close["主动关闭SSE连接"] --> Cancel["触发取消令牌"]
|
||||
Close --> Drop2["显式关闭发送端"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L390-L483)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L222)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L100-L170)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L390-L483)
|
||||
|
||||
## 依赖分析
|
||||
- 组件耦合
|
||||
- 代理层与业务层通过Pingora服务接口解耦，业务层仅依赖会话缓存与SSE处理器
|
||||
- 清理任务与会话缓存相互配合，避免资源泄漏
|
||||
- 外部依赖
|
||||
- Pingora提供高性能代理能力
|
||||
- Tokio运行时与OpenTelemetry用于可观测性
|
||||
- 潜在风险
|
||||
- 若清理任务配置不当，可能导致连接堆积或频繁重建
|
||||
- SSE代理需关注上游SSE端点可用性与事件格式一致性
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
P["Pingora 服务器"] --> R["Agent Runner"]
|
||||
R --> S["会话缓存"]
|
||||
R --> C["清理任务"]
|
||||
R --> SSE["SSE处理器"]
|
||||
P --> API["代理API"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L38-L120)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L120-L179)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
章节来源
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs#L38-L120)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L120-L179)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
## 性能考量
|
||||
- 高并发与低延迟
|
||||
- 使用Pingora的HTTP/2与连接池，减少握手与队头阻塞
|
||||
- 会话缓存采用环形缓冲区与共享状态，降低锁竞争与拷贝
|
||||
- 资源管理
|
||||
- RAII清理避免悬挂Agent与会话，降低内存与文件描述符占用
|
||||
- SSE连接主动关闭与心跳维持，避免连接堆积
|
||||
- 可观测性
|
||||
- 指标记录与健康检查快照，便于定位瓶颈
|
||||
- 火焰图脚本用于CPU热点分析，指导进一步优化
|
||||
|
||||
## 故障排查指南
|
||||
- 火焰图分析
|
||||
- 使用脚本采集进程采样并生成SVG火焰图，定位热点函数与阻塞调用
|
||||
- 关注cleanup_task、docker_manager相关调用与tokio运行时相关函数
|
||||
- 常见问题
|
||||
- SSE连接长时间不释放：检查取消令牌与发送端关闭逻辑
|
||||
- 代理后端不稳定：查看健康检查快照与后端列表
|
||||
- 清理任务未生效：确认清理间隔与闲置超时配置
|
||||
|
||||
章节来源
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh#L1-L59)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L390-L483)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs#L40-L80)
|
||||
|
||||
## 结论
|
||||
RCoder通过Pingora代理的高性能转发、会话缓存与SSE流的极简设计、以及基于RAII的清理机制，在高并发与低延迟场景下实现了稳定的吞吐表现。结合Tokio运行时调优、连接池与健康检查、提示词优化与火焰图分析，可进一步降低AI推理开销与系统延迟，持续提升整体性能与可靠性。
|
||||
|
||||
## 附录
|
||||
- 实践建议
|
||||
- 启用HTTP/2与连接池，合理设置健康检查间隔
|
||||
- 优化提示词结构，减少模型冗余输出
|
||||
- 使用火焰图定位热点，针对性优化关键路径
|
||||
- 通过指标与日志持续监控系统状态
|
||||
617
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/故障排除.md
Normal file
617
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/故障排除.md
Normal file
@@ -0,0 +1,617 @@
|
||||
# 故障排除
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [常见问题及解决方案](#常见问题及解决方案)
|
||||
2. [日志分析](#日志分析)
|
||||
3. [性能优化](#性能优化)
|
||||
4. [安全考虑](#安全考虑)
|
||||
5. [配置选项与参数](#配置选项与参数)
|
||||
6. [组件关系](#组件关系)
|
||||
|
||||
## 常见问题及解决方案
|
||||
|
||||
### Docker连接问题
|
||||
当服务无法连接到Docker守护进程时，系统会提供详细的错误信息和解决建议。主要问题包括：
|
||||
|
||||
- **Docker socket路径错误**：检查环境变量`DOCKER_SOCKET_PATH`是否正确设置
|
||||
- **权限不足**：确保容器有权限访问Docker API
|
||||
- **Docker服务未运行**：验证Docker是否正在运行
|
||||
|
||||
**解决方案**：
|
||||
1. 检查`docker-compose.yml`中的配置，确保正确挂载Docker socket
|
||||
2. 验证Docker socket文件是否存在
|
||||
3. 检查用户是否在docker组中
|
||||
4. 测试Docker API连通性
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([启动服务]) --> CheckDockerSocket["检查DOCKER_SOCKET_PATH环境变量"]
|
||||
CheckDockerSocket --> ValidateSocket["验证Docker socket文件存在"]
|
||||
ValidateSocket --> TestAPI["测试Docker API连通性"]
|
||||
TestAPI --> CheckPermissions["检查用户权限"]
|
||||
CheckPermissions --> Success["服务启动成功"]
|
||||
CheckDockerSocket --> |路径未设置| UseDefault["使用默认路径: /var/run/docker.sock"]
|
||||
UseDefault --> ValidateSocket
|
||||
TestAPI --> |连接失败| ShowHelp["显示详细的配置帮助信息"]
|
||||
ShowHelp --> Stop["停止服务启动"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L48-L81)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L322-L351)
|
||||
|
||||
### 容器清理失败
|
||||
在服务启动和关闭时，系统会尝试清理遗留的容器。可能会遇到以下问题：
|
||||
|
||||
- **409冲突错误**：容器已在删除过程中，这是正常情况
|
||||
- **容器不存在**：容器已被其他进程清理
|
||||
- **权限不足**：无法访问或删除容器
|
||||
|
||||
系统采用智能清理策略，忽略409冲突错误和容器不存在的情况，只记录真正的清理失败。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([启动清理]) --> FindContainers["查找匹配模式的容器"]
|
||||
FindContainers --> CheckExist["检查容器是否存在"]
|
||||
CheckExist --> |存在| StopContainer["停止并删除容器"]
|
||||
CheckExist --> |不存在| Skip["跳过，记录为已清理"]
|
||||
StopContainer --> CheckError["检查错误类型"]
|
||||
CheckError --> |409冲突| Skip["跳过，记录为已清理"]
|
||||
CheckError --> |其他错误| LogError["记录失败，计入失败统计"]
|
||||
CheckError --> |成功| LogSuccess["记录成功"]
|
||||
LogSuccess --> NextContainer["处理下一个容器"]
|
||||
LogError --> NextContainer
|
||||
Skip --> NextContainer
|
||||
NextContainer --> |还有容器| CheckExist
|
||||
NextContainer --> |无容器| Complete["清理完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L82-L182)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L131-L157)
|
||||
|
||||
### 服务启动失败
|
||||
服务启动时可能遇到多种问题，系统提供了详细的错误处理和恢复机制。
|
||||
|
||||
**常见问题**：
|
||||
- 配置文件加载失败
|
||||
- Docker管理器初始化失败
|
||||
- 端口绑定失败
|
||||
- 依赖服务未就绪
|
||||
|
||||
**解决方案**：
|
||||
1. 检查配置文件是否存在且格式正确
|
||||
2. 验证Docker服务是否正常运行
|
||||
3. 确认端口未被其他进程占用
|
||||
4. 检查依赖服务的状态
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([服务启动]) --> LoadConfig["加载配置文件"]
|
||||
LoadConfig --> |成功| InitDocker["初始化Docker管理器"]
|
||||
LoadConfig --> |失败| UseDefault["使用默认配置"]
|
||||
UseDefault --> InitDocker
|
||||
InitDocker --> |成功| CheckContainers["检查并清理遗留容器"]
|
||||
InitDocker --> |失败| Stop["停止服务启动"]
|
||||
CheckContainers --> |成功| StartProxy["启动代理服务"]
|
||||
CheckContainers --> |失败| LogWarn["记录警告，继续启动"]
|
||||
StartProxy --> |成功| StartServer["启动HTTP服务器"]
|
||||
StartProxy --> |失败| LogError["记录错误"]
|
||||
StartServer --> Complete["服务启动完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L31-L271)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
|
||||
## 日志分析
|
||||
|
||||
### 日志配置
|
||||
系统使用`tracing`库进行日志记录，支持多种输出格式和级别。
|
||||
|
||||
**日志配置特点**：
|
||||
- 按天滚动保存日志文件
|
||||
- 保留最近5天的日志
|
||||
- 同时输出到控制台和文件
|
||||
- 文件日志采用JSON格式，便于后续分析
|
||||
- 控制台日志采用简洁格式
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([日志初始化]) --> CreateDir["创建logs目录"]
|
||||
CreateDir --> SetupRolling["设置按天滚动的文件appender"]
|
||||
SetupRolling --> CreateFileLayer["创建文件日志层"]
|
||||
CreateFileLayer --> CreateConsoleLayer["创建控制台日志层"]
|
||||
CreateConsoleLayer --> SetPropagator["设置全局文本传播器"]
|
||||
SetPropagator --> InitSubscriber["初始化tracing subscriber"]
|
||||
InitSubscriber --> Complete["日志系统初始化成功"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L274-L318)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L182-L229)
|
||||
|
||||
### 日志级别
|
||||
系统支持多种日志级别，便于不同场景下的调试和监控。
|
||||
|
||||
**日志级别**：
|
||||
- `error`：记录错误信息，需要立即关注
|
||||
- `warn`：记录警告信息，可能影响系统稳定性
|
||||
- `info`：记录重要事件和状态变化
|
||||
- `debug`：记录调试信息，用于问题排查
|
||||
- `trace`：记录详细跟踪信息，用于深度分析
|
||||
|
||||
**日志级别配置**：
|
||||
- 通过环境变量`RUST_LOG`设置
|
||||
- 支持按模块设置不同级别
|
||||
- 默认级别为`info`
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([日志级别]) --> Error["error: 记录错误信息"]
|
||||
Error --> Warn["warn: 记录警告信息"]
|
||||
Warn --> Info["info: 记录重要事件"]
|
||||
Info --> Debug["debug: 记录调试信息"]
|
||||
Debug --> Trace["trace: 记录详细跟踪信息"]
|
||||
Trace --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L308-L314)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L217-L225)
|
||||
|
||||
### 日志内容
|
||||
日志记录了系统运行过程中的关键信息，便于问题排查和性能分析。
|
||||
|
||||
**日志内容包括**：
|
||||
- 服务启动和关闭信息
|
||||
- 配置加载和应用信息
|
||||
- 容器创建和销毁信息
|
||||
- 请求处理信息
|
||||
- 错误和异常信息
|
||||
|
||||
**日志字段**：
|
||||
- `timestamp`：时间戳
|
||||
- `level`：日志级别
|
||||
- `target`：日志来源
|
||||
- `message`：日志消息
|
||||
- `trace_id`：请求跟踪ID
|
||||
- `method`：HTTP方法
|
||||
- `uri`：请求URI
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([日志内容]) --> ServiceInfo["服务信息: 启动、关闭、状态"]
|
||||
ServiceInfo --> ConfigInfo["配置信息: 加载、应用、验证"]
|
||||
ConfigInfo --> ContainerInfo["容器信息: 创建、启动、停止、销毁"]
|
||||
ContainerInfo --> RequestInfo["请求信息: 处理、响应、错误"]
|
||||
RequestInfo --> ErrorInfo["错误信息: 异常、堆栈跟踪"]
|
||||
ErrorInfo --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L36-L271)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L75-L128)
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 容器清理优化
|
||||
系统实现了高效的容器清理机制，避免资源泄漏和性能下降。
|
||||
|
||||
**清理策略**：
|
||||
- 定时清理闲置容器
|
||||
- 启动时清理遗留容器
|
||||
- 关闭时清理所有容器
|
||||
- 并发清理多个容器
|
||||
|
||||
**优化措施**：
|
||||
- 使用`force remove`避免竞态条件
|
||||
- 过滤409冲突错误
|
||||
- 并发处理多个容器
|
||||
- 添加超时机制
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([容器清理]) --> CheckIdle["检查容器是否闲置"]
|
||||
CheckIdle --> |是| StopContainer["停止并删除容器"]
|
||||
CheckIdle --> |否| Skip["跳过"]
|
||||
StopContainer --> CheckError["检查错误类型"]
|
||||
CheckError --> |409冲突| Skip["跳过"]
|
||||
CheckError --> |其他错误| LogError["记录错误"]
|
||||
CheckError --> |成功| LogSuccess["记录成功"]
|
||||
LogSuccess --> NextContainer["处理下一个容器"]
|
||||
LogError --> NextContainer
|
||||
Skip --> NextContainer
|
||||
NextContainer --> |还有容器| CheckIdle
|
||||
NextContainer --> |无容器| Complete["清理完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L248-L429)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L82-L182)
|
||||
|
||||
### 请求处理优化
|
||||
系统使用`axum`框架处理HTTP请求，具有高性能和低延迟的特点。
|
||||
|
||||
**优化措施**：
|
||||
- 使用异步处理
|
||||
- 连接复用
|
||||
- 批量处理
|
||||
- 缓存机制
|
||||
|
||||
**性能指标**：
|
||||
- 请求处理时间
|
||||
- 并发连接数
|
||||
- 内存使用
|
||||
- CPU使用
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([请求处理]) --> ReceiveRequest["接收HTTP请求"]
|
||||
ReceiveRequest --> ParseRequest["解析请求"]
|
||||
ParseRequest --> ProcessRequest["处理请求"]
|
||||
ProcessRequest --> GenerateResponse["生成响应"]
|
||||
GenerateResponse --> SendResponse["发送响应"]
|
||||
SendResponse --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L222-L264)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L132-L171)
|
||||
|
||||
### 资源管理优化
|
||||
系统实现了高效的资源管理机制，避免资源泄漏和性能下降。
|
||||
|
||||
**资源管理**：
|
||||
- 内存管理
|
||||
- CPU管理
|
||||
- 网络管理
|
||||
- 存储管理
|
||||
|
||||
**优化措施**：
|
||||
- 资源限制
|
||||
- 资源回收
|
||||
- 资源监控
|
||||
- 资源优化
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([资源管理]) --> Memory["内存管理: 分配、释放、监控"]
|
||||
Memory --> CPU["CPU管理: 调度、限制、监控"]
|
||||
CPU --> Network["网络管理: 连接、带宽、监控"]
|
||||
Network --> Storage["存储管理: 读写、缓存、监控"]
|
||||
Storage --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L147-L175)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L51-L60)
|
||||
|
||||
## 安全考虑
|
||||
|
||||
### 容器安全
|
||||
系统在容器创建和运行时实施了多种安全措施。
|
||||
|
||||
**安全措施**：
|
||||
- 禁用`NET_RAW`和`NET_ADMIN`能力
|
||||
- 禁用特权模式
|
||||
- 使用非root用户运行
|
||||
- 限制资源使用
|
||||
- 网络隔离
|
||||
|
||||
**安全配置**：
|
||||
- `cap_drop`：移除危险能力
|
||||
- `privileged`：禁用特权模式
|
||||
- `user`：指定运行用户
|
||||
- `memory`：限制内存使用
|
||||
- `nano_cpus`：限制CPU使用
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([容器安全]) --> DropCapabilities["移除NET_RAW和NET_ADMIN能力"]
|
||||
DropCapabilities --> DisablePrivileged["禁用特权模式"]
|
||||
DisablePrivileged --> LimitResources["限制资源使用"]
|
||||
LimitResources --> NetworkIsolation["网络隔离"]
|
||||
NetworkIsolation --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L153-L165)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L51-L60)
|
||||
|
||||
### 网络安全
|
||||
系统在网络安全方面实施了多种措施，防止未授权访问和攻击。
|
||||
|
||||
**安全措施**：
|
||||
- 使用安全的网络配置
|
||||
- 限制端口暴露
|
||||
- 使用防火墙规则
|
||||
- 监控网络流量
|
||||
- 防止DDoS攻击
|
||||
|
||||
**网络配置**：
|
||||
- `network_mode`：设置网络模式
|
||||
- `port_bindings`：限制端口映射
|
||||
- `host_config`：配置主机安全
|
||||
- `networking_config`：配置网络安全
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([网络安全]) --> SecureNetwork["使用安全的网络配置"]
|
||||
SecureNetwork --> LimitPorts["限制端口暴露"]
|
||||
LimitPorts --> Firewall["使用防火墙规则"]
|
||||
Firewall --> MonitorTraffic["监控网络流量"]
|
||||
MonitorTraffic --> PreventDDoS["防止DDoS攻击"]
|
||||
PreventDDoS --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L178-L206)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L24-L26)
|
||||
|
||||
### 数据安全
|
||||
系统在数据安全方面实施了多种措施，保护用户数据和系统数据。
|
||||
|
||||
**安全措施**：
|
||||
- 数据加密
|
||||
- 访问控制
|
||||
- 数据备份
|
||||
- 数据审计
|
||||
- 数据隔离
|
||||
|
||||
**数据保护**：
|
||||
- `encryption`：数据加密
|
||||
- `authentication`：身份验证
|
||||
- `authorization`：授权
|
||||
- `backup`：数据备份
|
||||
- `audit`：数据审计
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([数据安全]) --> EncryptData["数据加密"]
|
||||
EncryptData --> AccessControl["访问控制"]
|
||||
AccessControl --> BackupData["数据备份"]
|
||||
BackupData --> AuditData["数据审计"]
|
||||
AuditData --> IsolateData["数据隔离"]
|
||||
IsolateData --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L43-L44)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L15-L16)
|
||||
|
||||
## 配置选项与参数
|
||||
|
||||
### 主要配置选项
|
||||
系统提供了多种配置选项，便于用户根据需求进行定制。
|
||||
|
||||
**配置文件**：`config.yml`
|
||||
|
||||
**主要配置项**：
|
||||
- `default_agent`：默认使用的AI代理类型
|
||||
- `projects_dir`：项目工作目录
|
||||
- `port`：主服务端口
|
||||
- `proxy_config`：反向代理配置
|
||||
- `docker_config`：Docker配置
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([配置选项]) --> DefaultAgent["default_agent: 默认AI代理类型"]
|
||||
DefaultAgent --> ProjectsDir["projects_dir: 项目工作目录"]
|
||||
ProjectsDir --> Port["port: 主服务端口"]
|
||||
Port --> ProxyConfig["proxy_config: 反向代理配置"]
|
||||
ProxyConfig --> DockerConfig["docker_config: Docker配置"]
|
||||
DockerConfig --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L38-L50)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L39-L49)
|
||||
|
||||
### 反向代理配置
|
||||
反向代理配置允许用户自定义代理服务的行为。
|
||||
|
||||
**配置项**：
|
||||
- `listen_port`：代理服务监听端口
|
||||
- `default_backend_port`：默认后端服务端口
|
||||
- `backend_host`：后端服务主机地址
|
||||
- `port_param`：端口参数名称
|
||||
- `health_check`：健康检查配置
|
||||
|
||||
**健康检查配置**：
|
||||
- `enabled`：是否启用健康检查
|
||||
- `interval_seconds`：检查间隔（秒）
|
||||
- `timeout_seconds`：超时时间（秒）
|
||||
- `healthy_threshold`：健康阈值
|
||||
- `unhealthy_threshold`：不健康阈值
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([代理配置]) --> ListenPort["listen_port: 监听端口"]
|
||||
ListenPort --> DefaultBackend["default_backend_port: 默认后端端口"]
|
||||
DefaultBackend --> BackendHost["backend_host: 后端主机"]
|
||||
BackendHost --> PortParam["port_param: 端口参数"]
|
||||
PortParam --> HealthCheck["health_check: 健康检查"]
|
||||
HealthCheck --> Enabled["enabled: 是否启用"]
|
||||
HealthCheck --> Interval["interval_seconds: 间隔"]
|
||||
HealthCheck --> Timeout["timeout_seconds: 超时"]
|
||||
HealthCheck --> Healthy["healthy_threshold: 健康阈值"]
|
||||
HealthCheck --> Unhealthy["unhealthy_threshold: 不健康阈值"]
|
||||
Unhealthy --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L68-L80)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L61-L73)
|
||||
|
||||
### Docker配置
|
||||
Docker配置允许用户自定义容器的行为。
|
||||
|
||||
**配置项**：
|
||||
- `multi_image_config`：多镜像配置
|
||||
- `network_mode`：网络模式
|
||||
- `work_dir`：工作目录
|
||||
- `auto_cleanup`：自动清理
|
||||
- `container_ttl_seconds`：容器存活时间（秒）
|
||||
|
||||
**多镜像配置**：
|
||||
- `services`：服务配置
|
||||
- `global_defaults`：全局默认配置
|
||||
- `selection_strategy`：选择策略
|
||||
- `cache_config`：缓存配置
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([Docker配置]) --> MultiImage["multi_image_config: 多镜像配置"]
|
||||
MultiImage --> NetworkMode["network_mode: 网络模式"]
|
||||
NetworkMode --> WorkDir["work_dir: 工作目录"]
|
||||
WorkDir --> AutoCleanup["auto_cleanup: 自动清理"]
|
||||
AutoCleanup --> ContainerTTL["container_ttl_seconds: 容器存活时间"]
|
||||
ContainerTTL --> Complete["完成"]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L82-L96)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L176-L195)
|
||||
|
||||
## 组件关系
|
||||
|
||||
### 核心组件关系
|
||||
系统由多个核心组件组成，它们之间有明确的关系和依赖。
|
||||
|
||||
**主要组件**：
|
||||
- `rcoder`：主服务
|
||||
- `agent_runner`：代理运行器
|
||||
- `docker_manager`：Docker管理器
|
||||
- `pingora-proxy`：反向代理
|
||||
- `shared_types`：共享类型
|
||||
|
||||
**组件关系**：
|
||||
- `rcoder`依赖`docker_manager`和`pingora-proxy`
|
||||
- `agent_runner`依赖`docker_manager`
|
||||
- `rcoder`和`agent_runner`共享`shared_types`
|
||||
- `pingora-proxy`提供反向代理功能
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Rcoder {
|
||||
+start()
|
||||
+load_config()
|
||||
+init_docker_manager()
|
||||
+start_proxy()
|
||||
}
|
||||
class AgentRunner {
|
||||
+start()
|
||||
+load_config()
|
||||
+run_agent()
|
||||
}
|
||||
class DockerManager {
|
||||
+create_container()
|
||||
+stop_container()
|
||||
+get_container_info()
|
||||
}
|
||||
class PingoraProxy {
|
||||
+start()
|
||||
+add_backend()
|
||||
+health_check()
|
||||
}
|
||||
class SharedTypes {
|
||||
+AgentType
|
||||
+ContainerInfo
|
||||
+AppError
|
||||
}
|
||||
Rcoder --> DockerManager : "使用"
|
||||
Rcoder --> PingoraProxy : "使用"
|
||||
AgentRunner --> DockerManager : "使用"
|
||||
Rcoder --> SharedTypes : "共享"
|
||||
AgentRunner --> SharedTypes : "共享"
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L271)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L179)
|
||||
|
||||
### 服务启动流程
|
||||
服务启动时，各个组件按照特定顺序初始化和启动。
|
||||
|
||||
**启动流程**：
|
||||
1. 初始化遥测系统
|
||||
2. 解析命令行参数
|
||||
3. 加载配置文件
|
||||
4. 创建项目工作目录
|
||||
5. 初始化Docker管理器
|
||||
6. 启动代理服务
|
||||
7. 启动HTTP服务器
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as "main函数"
|
||||
participant Telemetry as "遥测系统"
|
||||
participant Config as "配置系统"
|
||||
participant Docker as "Docker管理器"
|
||||
participant Proxy as "代理服务"
|
||||
participant Server as "HTTP服务器"
|
||||
Main->>Telemetry : init_telemetry()
|
||||
Telemetry-->>Main : 初始化成功
|
||||
Main->>Config : load_config_with_args()
|
||||
Config-->>Main : 返回配置
|
||||
Main->>Main : create_dir_all(projects_dir)
|
||||
Main->>Docker : init_global_docker_manager()
|
||||
Docker-->>Main : 初始化成功
|
||||
Main->>Proxy : start()
|
||||
Proxy-->>Main : 启动成功
|
||||
Main->>Server : serve()
|
||||
Server-->>Main : 服务器运行
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L31-L271)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L30-L179)
|
||||
|
||||
### 请求处理流程
|
||||
HTTP请求的处理流程涉及多个组件的协作。
|
||||
|
||||
**处理流程**：
|
||||
1. 接收HTTP请求
|
||||
2. 通过追踪中间件处理
|
||||
3. 路由到相应处理器
|
||||
4. 处理请求
|
||||
5. 生成响应
|
||||
6. 返回响应
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Server as "HTTP服务器"
|
||||
participant Middleware as "追踪中间件"
|
||||
participant Router as "路由"
|
||||
participant Handler as "处理器"
|
||||
Client->>Server : HTTP请求
|
||||
Server->>Middleware : 调用中间件
|
||||
Middleware->>Middleware : 生成trace_id
|
||||
Middleware->>Middleware : 创建span
|
||||
Middleware->>Router : 调用下一个处理器
|
||||
Router->>Handler : 路由到处理器
|
||||
Handler->>Handler : 处理请求
|
||||
Handler-->>Router : 返回响应
|
||||
Router-->>Middleware : 返回响应
|
||||
Middleware-->>Server : 返回响应
|
||||
Server-->>Client : HTTP响应
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L72-L128)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L220-L221)
|
||||
284
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/日志分析.md
Normal file
284
qiming-rcoder/.qoder/repowiki/zh/content/故障排除/日志分析.md
Normal file
@@ -0,0 +1,284 @@
|
||||
# 日志分析
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [日志结构与关键日志点](#日志结构与关键日志点)
|
||||
2. [Tracing与OpenTelemetry集成](#tracing与opentelemetry集成)
|
||||
3. [关键操作日志记录模式](#关键操作日志记录模式)
|
||||
4. [性能瓶颈与错误识别](#性能瓶颈与错误识别)
|
||||
5. [日志级别配置与过滤](#日志级别配置与过滤)
|
||||
6. [Docker容器日志集成](#docker容器日志集成)
|
||||
7. [端到端问题定位](#端到端问题定位)
|
||||
|
||||
## 日志结构与关键日志点
|
||||
|
||||
RCoder系统采用结构化日志记录，结合`tracing`和`OpenTelemetry`实现分布式追踪。日志系统在`main.rs`中初始化，配置了文件和控制台双输出。文件日志采用JSON格式，便于后续分析和监控系统集成。
|
||||
|
||||
日志文件按天滚动保存，保留最近5天的日志文件，文件名前缀分别为`agent-runner`和`rcoder`，分别对应不同的服务组件。日志目录自动创建于项目根目录下的`logs`文件夹中。
|
||||
|
||||
关键日志点包括：
|
||||
- HTTP请求的开始和结束
|
||||
- 容器创建、启动和停止
|
||||
- 代理服务的状态转换
|
||||
- 会话管理操作
|
||||
- 错误和异常处理
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L182-L231)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L275-L320)
|
||||
|
||||
## Tracing与OpenTelemetry集成
|
||||
|
||||
系统通过`tracing_middleware.rs`实现了HTTP请求追踪中间件，为每个请求生成唯一的`trace_id`，并创建相应的span用于日志跟踪。中间件自动从请求头中提取`trace_id`，支持`x-trace-id`、`x-request-id`、`traceparent`等常见追踪头。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Rcoder as "RCoder服务"
|
||||
participant Agent as "AgentRunner服务"
|
||||
Client->>Rcoder : POST /chat (带trace_id)
|
||||
Rcoder->>Rcoder : 生成/提取trace_id
|
||||
Rcoder->>Rcoder : 记录请求开始
|
||||
Rcoder->>Agent : 转发请求 (传递trace_id)
|
||||
Agent->>Agent : 记录代理处理
|
||||
Agent-->>Rcoder : 返回响应
|
||||
Rcoder->>Rcoder : 记录请求完成
|
||||
Rcoder-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
**Section sources**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L179)
|
||||
|
||||
## 关键操作日志记录模式
|
||||
|
||||
### HTTP入口日志记录
|
||||
|
||||
在`chat_handler.rs`中，HTTP请求的处理过程有详细的日志记录。当处理聊天请求时，系统会记录请求的开始、项目ID的生成、会话状态的检查等关键信息。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始处理聊天请求]) --> Validate["验证请求参数"]
|
||||
Validate --> CheckStatus["检查Agent状态"]
|
||||
CheckStatus --> RemoveSession["移除旧会话"]
|
||||
RemoveSession --> CreateWorkspace["创建项目工作目录"]
|
||||
CreateWorkspace --> SelectAgent["选择Agent类型"]
|
||||
SelectAgent --> SendTask["发送本地任务"]
|
||||
SendTask --> AwaitResponse["等待代理响应"]
|
||||
AwaitResponse --> HandleResult["处理响应结果"]
|
||||
HandleResult --> End([返回响应])
|
||||
style Start fill:#4CAF50,stroke:#388E3C
|
||||
style End fill:#4CAF50,stroke:#388E3C
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
|
||||
**Section sources**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
|
||||
### 代理服务日志记录
|
||||
|
||||
在`agent_service.rs`中，代理服务的启动和管理有明确的日志记录。系统通过`AcpAgentService` trait定义了统一的接口，不同类型的代理（如Claude、Codex）实现该接口。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt, model_provider) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class AgentType {
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
AcpAgentService <|-- AgentType : "实现"
|
||||
AgentType --> "ClaudeCodeAgent" : "调用"
|
||||
AgentType --> "CodexAgent" : "调用"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||||
|
||||
**Section sources**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||||
|
||||
## 性能瓶颈与错误识别
|
||||
|
||||
### 性能瓶颈识别
|
||||
|
||||
通过分析日志中的时间戳和处理时长，可以识别系统性能瓶颈。关键的性能指标包括：
|
||||
|
||||
- HTTP请求处理时间
|
||||
- 容器创建和启动时间
|
||||
- 代理服务响应时间
|
||||
- 网络通信延迟
|
||||
|
||||
日志中的emoji标记有助于快速识别不同类型的日志：
|
||||
- 🚀 表示开始处理
|
||||
- ✅ 表示成功完成
|
||||
- ❌ 表示错误或失败
|
||||
- ⚠️ 表示警告或需要注意的情况
|
||||
|
||||
### 错误堆栈分析
|
||||
|
||||
系统在关键错误点记录详细的错误信息，包括错误代码、消息和堆栈跟踪。例如，在`chat_handler.rs`中，当代理处理失败时，系统会记录错误详情：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[收到代理执行结果] --> B{结果是否成功?}
|
||||
B --> |是| C[检查响应错误]
|
||||
C --> D{有错误?}
|
||||
D --> |是| E[记录错误日志]
|
||||
D --> |否| F[记录成功日志]
|
||||
B --> |否| G[记录接收失败日志]
|
||||
style E fill:#f44336,stroke:#d32f2f
|
||||
style G fill:#f44336,stroke:#d32f2f
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L289-L318)
|
||||
|
||||
**Section sources**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L289-L318)
|
||||
|
||||
## 日志级别配置与过滤
|
||||
|
||||
### 日志级别配置
|
||||
|
||||
系统通过`tracing_subscriber::EnvFilter`配置日志级别，支持环境变量配置。默认配置如下：
|
||||
|
||||
- `rcoder=debug`：RCoder组件的调试级别
|
||||
- `tower_http=debug`：HTTP中间件的调试级别
|
||||
- `axum_tracing_opentelemetry=info`：OpenTelemetry追踪的普通级别
|
||||
|
||||
### 日志过滤技巧
|
||||
|
||||
可以通过环境变量`RUST_LOG`来动态调整日志级别，例如：
|
||||
|
||||
```bash
|
||||
# 只显示错误日志
|
||||
export RUST_LOG=error
|
||||
|
||||
# 显示RCoder组件的调试日志
|
||||
export RUST_LOG=rcoder=debug
|
||||
|
||||
# 显示所有组件的详细日志
|
||||
export RUST_LOG=debug
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L219-L221)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L310-L311)
|
||||
|
||||
## Docker容器日志集成
|
||||
|
||||
### 容器管理日志
|
||||
|
||||
`docker_manager`模块提供了完整的容器管理功能，包括创建、启动、停止和清理容器。每个操作都有相应的日志记录：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Rcoder as "RCoder服务"
|
||||
participant Docker as "Docker守护进程"
|
||||
Rcoder->>Docker : 创建容器
|
||||
Docker-->>Rcoder : 返回容器ID
|
||||
Rcoder->>Rcoder : 记录容器创建
|
||||
Rcoder->>Docker : 启动容器
|
||||
Docker-->>Rcoder : 启动成功
|
||||
Rcoder->>Rcoder : 记录容器启动
|
||||
Rcoder->>Docker : 检查容器健康
|
||||
Docker-->>Rcoder : 健康状态
|
||||
Rcoder->>Rcoder : 记录健康检查
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L81-L352)
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L81-L352)
|
||||
|
||||
### 容器日志获取
|
||||
|
||||
系统提供了获取容器日志的功能，可以通过`get_container_logs`方法获取指定容器的日志：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[获取容器日志] --> B{容器是否存在?}
|
||||
B --> |是| C[调用Docker API]
|
||||
C --> D[获取日志流]
|
||||
D --> E[合并日志内容]
|
||||
E --> F[返回日志字符串]
|
||||
B --> |否| G[返回错误]
|
||||
style G fill:#f44336,stroke:#d32f2f
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L588-L623)
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L588-L623)
|
||||
|
||||
## 端到端问题定位
|
||||
|
||||
### 请求生命周期追踪
|
||||
|
||||
通过`trace_id`可以追踪请求从HTTP入口到代理执行的完整生命周期。系统在`chat_handler.rs`中实现了请求转发，保持了`trace_id`的传递：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Rcoder as "RCoder服务"
|
||||
participant Container as "Agent容器"
|
||||
Client->>Rcoder : 发送请求 (带trace_id)
|
||||
Rcoder->>Rcoder : 记录请求开始
|
||||
Rcoder->>Container : 转发请求 (传递trace_id)
|
||||
Container->>Container : 处理请求
|
||||
Container-->>Rcoder : 返回响应
|
||||
Rcoder->>Rcoder : 记录请求完成
|
||||
Rcoder-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L110-L320)
|
||||
|
||||
**Section sources**
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L110-L320)
|
||||
|
||||
### 状态转换异常检测
|
||||
|
||||
系统通过日志记录关键状态的转换，可以检测异常状态。例如，在容器管理中，系统会检查容器的健康状态：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Creating : "创建容器"
|
||||
Creating --> Running : "启动成功"
|
||||
Creating --> Error : "启动失败"
|
||||
Running --> Stopped : "停止容器"
|
||||
Running --> Error : "健康检查失败"
|
||||
Stopped --> Idle : "清理完成"
|
||||
Error --> Idle : "错误处理"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L758-L800)
|
||||
299
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/HTTP结果模型.md
Normal file
299
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/HTTP结果模型.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# HTTP结果模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [router.rs（agent_runner）](file://crates/agent_runner/src/router.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕HTTP结果模型展开，重点说明统一响应格式的设计理念、成功与失败路径的处理逻辑，并结合Axum处理器的返回类型使用，系统性地介绍HttpResult<T>泛型结果类型与AppError错误体系。文档同时梳理错误码与触发条件、错误上下文信息收集机制、序列化输出示例以及客户端错误处理建议，帮助开发者在不同服务中一致地构建标准化API响应。
|
||||
|
||||
## 项目结构
|
||||
- 共享类型位于 crates/shared_types，其中定义了HttpResult<T>与AppError等跨服务通用模型。
|
||||
- rcoder与agent_runner两个服务各自实现了Axum路由与处理器，广泛采用HttpResult<T>作为成功响应，AppError作为错误响应。
|
||||
- 通过lib.rs统一导出共享类型，便于服务间复用。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "共享类型"
|
||||
SR["shared_types/lib.rs<br/>统一导出"]
|
||||
HR["model/http_result.rs<br/>HttpResult<T>"]
|
||||
AE["model/app_error.rs<br/>AppError 错误体系"]
|
||||
end
|
||||
subgraph "rcoder 服务"
|
||||
RR["rcoder/router.rs<br/>路由注册"]
|
||||
RH["rcoder/handler/agent_status_handler.rs<br/>处理器示例"]
|
||||
end
|
||||
subgraph "agent_runner 服务"
|
||||
AR["agent_runner/router.rs<br/>路由注册"]
|
||||
AH["agent_runner/handler/agent_status_handler.rs<br/>处理器示例"]
|
||||
end
|
||||
SR --> HR
|
||||
SR --> AE
|
||||
RR --> RH
|
||||
AR --> AH
|
||||
RH --> HR
|
||||
AH --> HR
|
||||
RH --> AE
|
||||
AH --> AE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L15-L53)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [router.rs（agent_runner）](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L15-L53)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [router.rs（agent_runner）](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- HttpResult<T>：统一的成功/失败响应载体，包含业务字段code、message、data、tid以及运行时计算的success布尔值。成功路径通过success(data)构造，失败路径通过error(code, message)或internal_error(message)构造。序列化时自动注入success字段，Axum IntoResponse实现负责HTTP状态码与Content-Type设置。
|
||||
- AppError：统一的错误类型，封装anyhow、IO与通用错误，提供generic、internal_server_error、validation_error等便捷构造方法。其IntoResponse实现将错误标准化为包含error.code与error.message的对象，状态码固定为500。
|
||||
|
||||
章节来源
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 架构总览
|
||||
下图展示了Axum处理器与统一响应模型之间的交互关系，以及错误路径与成功路径的分流。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant R as "Axum 路由"
|
||||
participant H as "处理器"
|
||||
participant S as "业务逻辑"
|
||||
participant OK as "HttpResult<T>"
|
||||
participant ERR as "AppError"
|
||||
C->>R : "HTTP 请求"
|
||||
R->>H : "调用处理器"
|
||||
H->>S : "执行业务逻辑"
|
||||
alt "成功"
|
||||
S-->>H : "返回数据"
|
||||
H->>OK : "构造 HttpResult : : success(data)"
|
||||
OK-->>R : "IntoResponse"
|
||||
R-->>C : "200 OK + JSON"
|
||||
else "失败"
|
||||
S-->>H : "返回错误"
|
||||
H->>ERR : "构造 AppError 或返回错误"
|
||||
ERR-->>R : "IntoResponse"
|
||||
R-->>C : "500 Internal Server Error + JSON"
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L77-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L57)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### HttpResult<T> 泛型结果类型
|
||||
- 设计理念
|
||||
- 统一响应格式：所有API响应均包含code、message、data、tid与success字段，便于前端统一解析与展示。
|
||||
- 成功路径：success(data)构造，code默认“0000”，success=true。
|
||||
- 失败路径：error(code, message)构造，success=false；internal_error(message)为内部错误的快捷方式。
|
||||
- 上下文追踪：自动从OpenTelemetry上下文提取trace_id，若无则置空，便于日志与链路追踪。
|
||||
- 序列化策略：自定义Serialize实现，显式写出5个字段，其中success根据code是否为“0000”动态计算。
|
||||
- 响应适配：实现IntoResponse，优先返回JSON，序列化失败时降级为500与纯文本。
|
||||
|
||||
- 关键行为与复杂度
|
||||
- 构造函数O(1)，序列化O(n)（n为data序列化开销），IntoResponse序列化O(1)+序列化开销。
|
||||
- trace_id提取依赖当前span上下文，若无效则返回None，不影响响应正确性。
|
||||
|
||||
- 使用建议
|
||||
- 成功场景：优先使用success(data)返回结构化数据。
|
||||
- 失败场景：明确错误码与message，避免使用internal_error除非无法确定具体原因。
|
||||
- 数据为空：data字段可为None，但需保证业务语义清晰。
|
||||
|
||||
章节来源
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
### AppError 错误体系
|
||||
- 设计理念
|
||||
- 统一错误抽象：通过枚举封装常见错误来源，便于集中处理与上报。
|
||||
- 易于扩展：支持From实现，如tokio mpsc SendError的转换，便于在异步通道中传播错误。
|
||||
- 标准化输出：IntoResponse固定返回500状态码与包含error.code与error.message的对象，便于前端统一处理。
|
||||
|
||||
- 错误分类与构造
|
||||
- AnyhowError：包装底层异常，便于上抛。
|
||||
- IoError：包装IO错误。
|
||||
- Generic：通用错误，支持validation_error与internal_server_error等便捷方法。
|
||||
|
||||
- 使用建议
|
||||
- 业务层尽量将错误转换为明确的错误码与message，必要时使用AppError::Generic承载。
|
||||
- 对于可恢复的业务错误，优先返回HttpResult::error(...)而非抛出AppError，以便客户端区分业务错误与系统错误。
|
||||
|
||||
章节来源
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
### Axum处理器中的返回类型使用
|
||||
- 返回类型约定
|
||||
- 成功：Result<HttpResult<T>, AppError>，处理器返回Ok(HttpResult::success(...))或Ok(HttpResult::error(...))。
|
||||
- 失败：Result<HttpResult<T>, AppError>，处理器返回Err(AppError::...)或Ok(HttpResult::error(...))。
|
||||
- 示例：rcoder与agent_runner的agent_status处理器均采用该模式，先做参数校验，再构造AgentStatusResponse并返回HttpResult.success(...)，或在参数非法时返回HttpResult.error(...)。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入处理器"]) --> Validate["校验输入参数"]
|
||||
Validate --> Valid{"参数有效?"}
|
||||
Valid --> |否| BuildErr["构造 HttpResult::error(code, message)"]
|
||||
BuildErr --> ReturnErr["返回 Ok(HttpResult::error)"]
|
||||
Valid --> |是| DoBiz["执行业务逻辑"]
|
||||
DoBiz --> BizOK{"业务成功?"}
|
||||
BizOK --> |否| BuildBizErr["构造 HttpResult::error(code, message)"]
|
||||
BuildBizErr --> ReturnBizErr["返回 Ok(HttpResult::error)"]
|
||||
BizOK --> |是| BuildData["构造响应数据"]
|
||||
BuildData --> ReturnOk["返回 Ok(HttpResult::success(data))"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
|
||||
### 错误码与触发条件
|
||||
- 内置错误码
|
||||
- “0000”：成功。
|
||||
- “5000”：内部错误（internal_error(message)构造）。
|
||||
- 业务错误码示例
|
||||
- “INVALID_PARAMS”：参数校验失败（例如agent_status处理器对project_id为空的处理）。
|
||||
- “INVALID_SESSION”：会话无效（OpenAPI示例中出现）。
|
||||
- “SESSION_NOT_FOUND”：会话不存在（OpenAPI示例中出现）。
|
||||
- 触发条件
|
||||
- 参数校验失败：处理器在进入业务逻辑前进行参数校验，不符合要求时返回HttpResult::error(...)。
|
||||
- 业务状态异常：如Agent不存在、会话不存在等，返回相应错误码与message。
|
||||
- 系统异常：无法预期的错误，使用AppError或HttpResult::internal_error(...)。
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L36-L58)
|
||||
|
||||
### 错误上下文信息收集机制
|
||||
- trace_id采集
|
||||
- HttpResult<T>在构造时与IntoResponse阶段均可从OpenTelemetry上下文提取trace_id，若当前span无效则置空。
|
||||
- 该机制确保每个响应具备可追踪的链路标识，便于日志聚合与问题定位。
|
||||
- 请求ID（request_id）
|
||||
- 在聊天响应等结构中提供request_id字段，用于标识与追踪请求，便于跨服务关联。
|
||||
- 会话消息中的错误字段
|
||||
- 会话通知结构中包含错误信息字段，便于在SSE流中传递错误详情。
|
||||
|
||||
章节来源
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L8-L22)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L71-L97)
|
||||
|
||||
### 序列化输出示例
|
||||
- 成功响应（示例结构）
|
||||
- 字段：code、message、data、tid、success
|
||||
- data为对象或数组时，success为true；data为null时，success仍为true
|
||||
- 失败响应（示例结构）
|
||||
- 字段：code、message、data为null、tid、success为false
|
||||
- 或AppError的标准化错误对象（error.code与error.message）
|
||||
|
||||
章节来源
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L61-L74)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L33-L57)
|
||||
|
||||
### 客户端错误处理建议
|
||||
- 成功与失败路径区分
|
||||
- 优先依据success字段判断整体成功与否；若为false，读取error.code与error.message进行分支处理。
|
||||
- 错误码映射
|
||||
- 将“0000”视为成功；“5000”视为内部错误，提示用户稍后重试或上报工单。
|
||||
- “INVALID_PARAMS”、“INVALID_SESSION”、“SESSION_NOT_FOUND”等业务错误码用于提示用户修正输入或重新发起请求。
|
||||
- 上下文追踪
|
||||
- 记录并回传tid，便于服务端定位问题；在客户端日志中附带request_id，便于跨服务关联。
|
||||
- 降级与重试
|
||||
- 对瞬时性错误（如网络抖动）建议客户端进行指数退避重试；对参数类错误直接提示用户修正。
|
||||
|
||||
## 依赖关系分析
|
||||
- 组件耦合
|
||||
- HttpResult<T>与AppError均为共享类型，rcoder与agent_runner通过lib.rs统一导出使用，降低重复实现与耦合。
|
||||
- 处理器依赖共享类型，路由层仅负责注册与文档生成，职责清晰。
|
||||
- 外部依赖
|
||||
- OpenTelemetry与tracing用于trace_id采集与日志追踪。
|
||||
- serde、utoipa用于序列化与OpenAPI文档生成。
|
||||
- axum用于HTTP响应适配与IntoResponse实现。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
HR["HttpResult<T>"] --> AX["axum::response::IntoResponse"]
|
||||
HR --> OT["opentelemetry/tracing"]
|
||||
HR --> SD["serde"]
|
||||
AE["AppError"] --> AX
|
||||
AE --> TH["thiserror"]
|
||||
RC["rcoder/handler/*"] --> HR
|
||||
RC --> AE
|
||||
AR["agent_runner/handler/*"] --> HR
|
||||
AR --> AE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L15-L53)
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L15-L53)
|
||||
|
||||
## 性能考量
|
||||
- 序列化成本
|
||||
- HttpResult<T>的序列化为结构体序列化，主要开销取决于data的大小；建议在成功路径仅返回必要字段，避免冗余数据。
|
||||
- IntoResponse路径
|
||||
- 成功路径返回200+JSON，失败路径返回500+JSON；序列化失败时降级为500+纯文本，避免中间件异常。
|
||||
- trace_id采集
|
||||
- trace_id提取依赖当前span上下文，若无上下文则跳过，不会引入额外开销。
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题
|
||||
- 响应未携带success字段：确认使用HttpResult<T>而非自定义结构体。
|
||||
- 错误响应格式不一致：统一使用AppError或HttpResult::error(...)，避免混合返回。
|
||||
- trace_id缺失：检查OpenTelemetry中间件是否正确注入span上下文。
|
||||
- 定位步骤
|
||||
- 根据tid在日志系统中检索对应链路。
|
||||
- 结合request_id在聊天/会话相关接口中定位具体请求。
|
||||
- 对业务错误码进行聚合统计，识别高频错误与潜在输入问题。
|
||||
|
||||
## 结论
|
||||
通过HttpResult<T>与AppError的组合，系统实现了统一、可观测、易维护的API响应模型。成功与失败路径清晰分离，错误码与上下文信息完整，配合Axum的IntoResponse实现，能够稳定地输出标准化响应。建议在所有新接口中遵循该模式，以提升客户端体验与运维效率。
|
||||
|
||||
## 附录
|
||||
- 统一导出入口
|
||||
- shared_types::lib.rs统一导出HttpResult与AppError，便于服务间复用。
|
||||
- OpenAPI示例
|
||||
- rcoder与agent_runner的OpenAPI文档中对HttpResult<T>进行了标注与示例展示，便于客户端理解响应结构。
|
||||
|
||||
章节来源
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L15-L53)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L86-L151)
|
||||
- [router.rs（agent_runner）](file://crates/agent_runner/src/router.rs#L72-L128)
|
||||
393
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/gRPC数据模型.md
Normal file
393
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/gRPC数据模型.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# gRPC数据模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [build.rs](file://crates/shared_types/build.rs)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件围绕 agent.proto 协议生成的 Rust gRPC 数据模型，系统性阐述 Protobuf 消息类型（如 AgentRequest、AgentResponse）的字段定义与语义；解释 gRPC 服务接口与 ACP 协议的映射关系，重点覆盖流式调用 SubscribeProgress 的实现细节；提供序列化性能分析、版本兼容性策略与协议扩展指南；并结合 agent_runner 的实际调用场景，展示客户端与服务端之间的数据交换模式。
|
||||
|
||||
## 项目结构
|
||||
- 协议定义位于 shared_types/proto/agent.proto，描述 gRPC 服务与消息类型。
|
||||
- 生成的 Rust gRPC 客户端与服务端代码位于 shared_types/src/grpc/agent.rs。
|
||||
- 构建脚本 build.rs 使用 tonic-prost-build 将 .proto 编译为 Rust。
|
||||
- agent_runner 通过 HTTP 路由与 ACP 代理协作，间接消费 gRPC 数据模型。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "shared_types"
|
||||
P["proto/agent.proto"]
|
||||
G["src/grpc/agent.rs"]
|
||||
L["src/lib.rs"]
|
||||
B["build.rs"]
|
||||
end
|
||||
subgraph "agent_runner"
|
||||
H["handler/chat_handler.rs"]
|
||||
R["router.rs"]
|
||||
A["proxy_agent/acp_agent.rs"]
|
||||
S["proxy_agent/agent_service.rs"]
|
||||
end
|
||||
P --> B --> G
|
||||
L --> G
|
||||
H --> A
|
||||
A --> S
|
||||
R --> H
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
|
||||
## 核心组件
|
||||
- gRPC 服务与消息
|
||||
- 服务：AgentService，包含 Chat、SubscribeProgress（Server Streaming）、CancelSession、GetStatus 四个 RPC。
|
||||
- 消息：ChatRequest、ChatResponse、ProgressRequest、ProgressEvent、CancelRequest、CancelResponse、GetStatusRequest、GetStatusResponse、ModelProviderConfig、Attachment。
|
||||
- 生成代码
|
||||
- 通过 build.rs 调用 tonic-prost-build，生成客户端与服务端桩代码，位于 shared_types/src/grpc/agent.rs。
|
||||
- ACP 协议映射
|
||||
- agent_runner 通过 HTTP 路由与 ACP 代理协作，将 ChatRequest/Response 与 ACP 的 PromptRequest/PromptResponse 对接，实现会话进度的 SSE 通知与取消控制。
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
|
||||
## 架构总览
|
||||
下图展示了 gRPC 数据模型在系统中的位置与交互关系，以及与 ACP 的对接路径。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "客户端"
|
||||
C1["HTTP 客户端"]
|
||||
end
|
||||
subgraph "agent_runner"
|
||||
R1["Axum 路由 /chat"]
|
||||
H1["聊天处理器 handle_chat"]
|
||||
A1["ACP 代理调度 agent_worker"]
|
||||
S1["AcpAgentService trait"]
|
||||
end
|
||||
subgraph "gRPC 层"
|
||||
G1["AgentServiceClient<br/>Chat/SubscribeProgress/CancelSession/GetStatus"]
|
||||
G2["AgentServiceServer<br/>实现 Chat/SubscribeProgress/CancelSession/GetStatus"]
|
||||
end
|
||||
subgraph "ACP 代理"
|
||||
P1["PromptRequest/PromptResponse"]
|
||||
N1["会话进度通知 SSE"]
|
||||
end
|
||||
C1 --> R1 --> H1 --> A1 --> S1
|
||||
H1 --> G1
|
||||
G1 --> G2
|
||||
G2 --> A1
|
||||
A1 --> P1
|
||||
A1 --> N1
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L122-L650)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Protobuf 消息类型与字段语义
|
||||
- AgentService
|
||||
- Chat：一元 RPC，请求 ChatRequest，返回 ChatResponse。
|
||||
- SubscribeProgress：服务端流式 RPC，请求 ProgressRequest，返回 ProgressEvent 流。
|
||||
- CancelSession：一元 RPC，请求 CancelRequest，返回 CancelResponse。
|
||||
- GetStatus：一元 RPC，请求 GetStatusRequest，返回 GetStatusResponse。
|
||||
- ChatRequest
|
||||
- project_id：项目标识。
|
||||
- session_id：会话标识。
|
||||
- prompt：用户提示词。
|
||||
- model_config：可选的模型提供商配置。
|
||||
- attachments：可选的附件列表。
|
||||
- request_id：可选的请求标识。
|
||||
- ChatResponse
|
||||
- request_id：请求标识。
|
||||
- success：是否成功。
|
||||
- error：可选的错误信息。
|
||||
- ProgressRequest
|
||||
- session_id：订阅进度的会话标识。
|
||||
- ProgressEvent
|
||||
- event：oneof，包含 log、thought、chunk、done、error 等事件类型。
|
||||
- json_payload：保留的原始 JSON，用于兼容过渡。
|
||||
- timestamp：Unix 时间戳。
|
||||
- CancelRequest
|
||||
- session_id：要取消的会话标识。
|
||||
- reason：取消原因。
|
||||
- CancelResponse
|
||||
- success：是否取消成功。
|
||||
- GetStatusRequest
|
||||
- project_id：项目标识。
|
||||
- GetStatusResponse
|
||||
- status：状态字符串，如 "idle"、"busy"、"error"。
|
||||
- ModelProviderConfig
|
||||
- provider：提供商名称。
|
||||
- model：模型名称。
|
||||
- api_key：可选的 API 密钥。
|
||||
- api_base：可选的 API 基地址。
|
||||
- Attachment
|
||||
- name：附件名称。
|
||||
- kind：附件类型（如 text、image、file）。
|
||||
- content：内容（文本、base64 或 URL）。
|
||||
- source：来源（如 local、upload、paste）。
|
||||
- language：可选的语言（仅文本）。
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
|
||||
### 生成的 gRPC 客户端与服务端
|
||||
- 客户端
|
||||
- AgentServiceClient 提供 chat、subscribe_progress、cancel_session、get_status 方法，均基于 tonic+prost 编解码。
|
||||
- 支持压缩、最大消息大小、拦截器等配置。
|
||||
- 服务端
|
||||
- AgentServiceServer 实现 trait AgentService 的四个方法，并在内部将 HTTP 路径映射到具体 RPC。
|
||||
- 支持压缩、最大消息大小等配置。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentServiceClient {
|
||||
+connect(dst) Result
|
||||
+send_compressed(encoding) Self
|
||||
+accept_compressed(encoding) Self
|
||||
+max_decoding_message_size(limit) Self
|
||||
+max_encoding_message_size(limit) Self
|
||||
+chat(request) -> Response~ChatResponse~
|
||||
+subscribe_progress(request) -> Response~Streaming~ProgressEvent~
|
||||
+cancel_session(request) -> Response~CancelResponse~
|
||||
+get_status(request) -> Response~GetStatusResponse~
|
||||
}
|
||||
class AgentServiceServer {
|
||||
+new(inner) Self
|
||||
+from_arc(inner) Self
|
||||
+with_interceptor(interceptor) Self
|
||||
+accept_compressed(encoding) Self
|
||||
+send_compressed(encoding) Self
|
||||
+max_decoding_message_size(limit) Self
|
||||
+max_encoding_message_size(limit) Self
|
||||
}
|
||||
class AgentService {
|
||||
<<trait>>
|
||||
+chat(request) -> Response~ChatResponse~
|
||||
+subscribe_progress(request) -> Stream~ProgressEvent~
|
||||
+cancel_session(request) -> Response~CancelResponse~
|
||||
+get_status(request) -> Response~GetStatusResponse~
|
||||
}
|
||||
AgentServiceServer --> AgentService : "实现"
|
||||
AgentServiceClient --> AgentServiceServer : "调用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L122-L650)
|
||||
|
||||
章节来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L122-L650)
|
||||
|
||||
### 与 ACP 协议的映射关系
|
||||
- ChatRequest/Response 与 ACP 的 PromptRequest/PromptResponse 对接
|
||||
- agent_runner 的聊天处理器将 HTTP 请求转换为 ChatPrompt，并通过 ACP 代理发送 PromptRequest，接收 PromptResponse。
|
||||
- 会话进度通过 SSE 推送，与 gRPC 的 SubscribeProgress 语义一致（替代 /agent/progress/{session_id}）。
|
||||
- 取消与状态
|
||||
- CancelSession 对应 ACP 的取消通知；GetStatus 对应查询代理状态。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "HTTP 客户端"
|
||||
participant Handler as "handle_chat"
|
||||
participant Worker as "agent_worker"
|
||||
participant ACP as "AcpAgentService"
|
||||
participant Server as "AgentServiceServer"
|
||||
participant ClientG as "AgentServiceClient"
|
||||
Client->>Handler : POST /chat
|
||||
Handler->>Worker : LocalSetAgentRequest
|
||||
Worker->>ACP : start_agent_service(...)
|
||||
ACP-->>Worker : AcpConnectionInfo
|
||||
Worker->>ACP : 发送 PromptRequest
|
||||
ACP-->>Worker : PromptResponse
|
||||
Worker-->>Handler : ChatPromptResponse
|
||||
Handler-->>Client : ChatResponse
|
||||
Note over Client,Server : SubscribeProgress 通过 gRPC 客户端订阅 ProgressEvent 流
|
||||
Client->>ClientG : subscribe_progress(ProgressRequest)
|
||||
ClientG->>Server : /agent.AgentService/SubscribeProgress
|
||||
Server-->>ClientG : ProgressEvent stream
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L232-L257)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L232-L257)
|
||||
|
||||
### 流式调用 SubscribeProgress 的实现细节
|
||||
- 客户端侧
|
||||
- AgentServiceClient.subscribe_progress 返回 Streaming<ProgressEvent>。
|
||||
- 可配置压缩与最大消息大小。
|
||||
- 服务端侧
|
||||
- AgentServiceServer 将 /agent.AgentService/SubscribeProgress 映射到 subscribe_progress 方法，返回实现者提供的流。
|
||||
- 实际使用
|
||||
- agent_runner 通过 HTTP SSE 提供 /agent/progress/{session_id}，与 gRPC 流式接口语义一致，便于替换与统一。
|
||||
|
||||
章节来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L232-L257)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
### 序列化性能分析
|
||||
- 编解码器
|
||||
- 使用 prost+tonic 编解码，二进制序列化，开销低、吞吐高。
|
||||
- 压缩
|
||||
- 支持 send_compressed/accept_compressed，可在高延迟网络中降低带宽占用。
|
||||
- 消息大小限制
|
||||
- 提供 max_decoding_message_size/max_encoding_message_size，默认解码上限通常为 4MB，可根据业务调整。
|
||||
- oneof 与可选字段
|
||||
- ProgressEvent.event 使用 oneof，减少冗余字段存储；可选字段（如 ChatRequest.request_id、ModelProviderConfig.api_key）按需传输，降低体积。
|
||||
- 附件与 JSON 兼容
|
||||
- Attachment.content 支持多种格式；ProgressEvent.json_payload 保留原始 JSON，便于过渡期兼容。
|
||||
|
||||
章节来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L182-L212)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L397-L412)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
|
||||
### 版本兼容性策略与协议扩展指南
|
||||
- 向后兼容
|
||||
- 新增字段使用 optional，避免破坏已有客户端解析。
|
||||
- 保留 json_payload 等兼容字段，逐步迁移至强类型字段。
|
||||
- 扩展建议
|
||||
- 新增 RPC：在 AgentService 中添加新方法，同时在客户端/服务端生成代码中补充实现。
|
||||
- 新增消息：在 proto 中新增 message，并在 shared_types/src/grpc/agent.rs 中自动生成。
|
||||
- 迁移路径：先提供新接口，再逐步引导客户端切换，最后清理旧接口。
|
||||
- 构建与发布
|
||||
- 修改 proto 后，通过 build.rs 重新生成 agent.rs，确保客户端/服务端一致性。
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
|
||||
### 客户端与服务端数据交换模式（结合 agent_runner 场景）
|
||||
- HTTP 到 gRPC 的桥接
|
||||
- HTTP 路由 /chat 由 handle_chat 处理，内部通过 ACP 代理发送 PromptRequest，接收 PromptResponse。
|
||||
- gRPC 的 Chat/SubscribeProgress/CancelSession/GetStatus 由 AgentServiceClient/Server 提供，可用于直接的 gRPC 客户端接入。
|
||||
- 会话与进度
|
||||
- 会话 ID 与项目 ID 在 ChatRequest/Response 中传递，服务端据此维护会话状态与进度推送。
|
||||
- 取消与状态
|
||||
- CancelSession 与 GetStatus 与 ACP 的取消与状态查询对齐，保证一致性。
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L122-L650)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 依赖分析
|
||||
- 构建链路
|
||||
- build.rs 调用 tonic_prost_build::configure().build_server(true).build_client(true)，输出到 src/grpc/agent.rs。
|
||||
- shared_types/src/lib.rs include!("grpc/agent.rs")，统一导出 gRPC 模块。
|
||||
- 运行时依赖
|
||||
- workspace.dependencies 中包含 agent-client-protocol（ACP 协议），用于与 ACP 代理交互。
|
||||
- tokio、tonic、prost 等异步与序列化依赖。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Build["build.rs"] --> Proto["agent.proto"]
|
||||
Proto --> Gen["src/grpc/agent.rs"]
|
||||
Lib["src/lib.rs"] --> Gen
|
||||
Cargo["Cargo.toml"] --> ACP["agent-client-protocol"]
|
||||
Runner["agent_runner"] --> ACP
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
章节来源
|
||||
- [build.rs](file://crates/shared_types/build.rs#L1-L14)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 性能考虑
|
||||
- 序列化
|
||||
- prost 二进制编码，相比 JSON 更小更快；oneof 与可选字段减少冗余。
|
||||
- 压缩
|
||||
- 在高延迟网络中启用压缩，降低带宽；注意服务端需支持对应编码。
|
||||
- 消息大小
|
||||
- 合理设置 max_decoding_message_size/max_encoding_message_size，避免过大消息导致内存压力。
|
||||
- 流式传输
|
||||
- SubscribeProgress 使用服务端流，分片推送进度，降低一次性传输成本。
|
||||
- 并发与连接
|
||||
- gRPC 客户端连接池与重连策略需结合业务并发量评估；在 agent_runner 中可通过 ACP 代理连接管理策略优化。
|
||||
|
||||
## 故障排查指南
|
||||
- 常见问题
|
||||
- 服务未就绪：客户端 ready() 失败，检查服务端启动与网络可达性。
|
||||
- 消息过大：触发 max_decoding_message_size 限制，适当增大或拆分消息。
|
||||
- 压缩不匹配：客户端启用压缩但服务端不支持，需协商一致的压缩算法。
|
||||
- 会话状态异常：确认 project_id/session_id 传递正确，避免跨会话混淆。
|
||||
- 排查步骤
|
||||
- 检查 gRPC 客户端/服务端生成代码是否与 proto 一致。
|
||||
- 核对 ACP 代理连接与生命周期管理，确保连接可用且未超时。
|
||||
- 结合 agent_runner 的日志，定位 HTTP 到 ACP 的转换与进度推送环节。
|
||||
|
||||
章节来源
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L182-L212)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L397-L412)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L321)
|
||||
|
||||
## 结论
|
||||
本文基于 agent.proto 生成的 Rust gRPC 数据模型，系统梳理了消息类型、服务接口与 ACP 协议的映射关系，给出了流式调用的实现要点、序列化性能分析、版本兼容与扩展策略，并结合 agent_runner 的实际调用场景展示了客户端与服务端的数据交换模式。遵循本文建议可确保在演进过程中保持协议稳定与性能最优。
|
||||
|
||||
## 附录
|
||||
- 相关文件清单
|
||||
- 协议与生成：agent.proto、agent.rs、build.rs、lib.rs
|
||||
- 业务集成：chat_handler.rs、acp_agent.rs、agent_service.rs、router.rs
|
||||
- 依赖声明：Cargo.toml
|
||||
391
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/代理状态模型.md
Normal file
391
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/代理状态模型.md
Normal file
@@ -0,0 +1,391 @@
|
||||
# 代理状态模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件系统化梳理代理状态模型，聚焦以下目标：
|
||||
- 解释 AgentStatusResponse、AgentType 等关键类型
|
||||
- 对比不同 AI 代理（Codex、Claude Code）的状态表示与统一抽象机制
|
||||
- 说明状态查询接口的数据输出格式、字段含义与扩展点
|
||||
- 结合 agent_status_handler 的实现，展示状态聚合逻辑与错误传播路径
|
||||
- 提供 gRPC 协议映射细节（来自 agent.proto）与 JSON 序列化示例
|
||||
|
||||
## 项目结构
|
||||
围绕“代理状态模型”的相关模块分布如下：
|
||||
- 协议与序列化：shared_types/proto/agent.proto 与生成的 gRPC 客户端/服务端代码
|
||||
- 数据模型：shared_types/src/model 下的 agent_model.rs、agent_type.rs、model_provider.rs、http_result.rs、app_error.rs
|
||||
- HTTP 状态查询处理器：agent_runner 与 rcoder 两处实现
|
||||
- 代理抽象与生命周期：agent_runner/proxy_agent 下的抽象层与生命周期管理
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "共享类型与协议"
|
||||
P["agent.proto<br/>gRPC 定义"]
|
||||
G["agent.rs<br/>生成的gRPC客户端/服务端"]
|
||||
M["agent_model.rs<br/>AgentStatusResponse/AgentStatus"]
|
||||
T["agent_type.rs<br/>AgentType/Claude/Codex"]
|
||||
MP["model_provider.rs<br/>ModelProviderConfig/SafeInfo"]
|
||||
HR["http_result.rs<br/>统一HTTP响应结构"]
|
||||
AE["app_error.rs<br/>应用错误类型"]
|
||||
end
|
||||
subgraph "HTTP状态查询"
|
||||
AR["agent_status_handler.rsagent_runner"]
|
||||
RC["agent_status_handler.rsrcoder"]
|
||||
end
|
||||
subgraph "代理抽象与生命周期"
|
||||
PA["proxy_agent/mod.rs<br/>PROJECT_AND_AGENT_INFO_MAP"]
|
||||
AS["agent_service.rs<br/>AcpAgentService"]
|
||||
end
|
||||
P --> G
|
||||
M --> AR
|
||||
M --> RC
|
||||
T --> AR
|
||||
T --> RC
|
||||
MP --> AR
|
||||
MP --> RC
|
||||
HR --> AR
|
||||
HR --> RC
|
||||
AE --> AR
|
||||
AE --> RC
|
||||
PA --> AR
|
||||
AS --> AR
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L120)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L43-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L1-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L1-L132)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L120)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L43-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L1-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L1-L132)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
|
||||
## 核心组件
|
||||
- AgentStatusResponse：HTTP 状态查询的统一响应载体，包含项目标识、存活标记、会话ID、代理状态、时间戳与模型提供商安全信息。
|
||||
- AgentStatus：共享的代理服务状态枚举，抽象了 Active、Idle、Terminating 等状态。
|
||||
- AgentType：代理类型枚举，区分 Claude 与 Codex，并提供从模型提供商配置推断类型的能力。
|
||||
- ModelProviderConfig/SafeInfo：模型提供商配置与脱敏后的安全信息，用于在状态响应中安全暴露必要元数据。
|
||||
- gRPC GetStatus：agent.proto 中定义的 GetStatusRequest/GetStatusResponse，字段为字符串形式的状态码。
|
||||
- HTTP 层：agent_status_handler.rs（两套实现）负责参数校验、状态聚合与错误传播。
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L43-L132)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L69-L76)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L82-L91)
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
|
||||
## 架构总览
|
||||
状态查询的端到端流程如下：
|
||||
- HTTP 层：接收 /agent/status/{project_id} 请求，进行参数校验与错误传播
|
||||
- 聚合层：从全局映射中读取项目对应的代理信息（含 AgentStatus、会话ID、时间戳、模型提供商）
|
||||
- 输出层：构造 AgentStatusResponse，按 is_alive 控制可选字段的序列化
|
||||
- gRPC 层：GetStatus 以字符串状态码返回，与 HTTP 层的 AgentStatus 枚举形成互补
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant H as "HTTP处理器<br/>agent_status_handler.rs"
|
||||
participant M as "状态映射<br/>PROJECT_AND_AGENT_INFO_MAP"
|
||||
participant R as "响应构造<br/>AgentStatusResponse"
|
||||
C->>H : GET /agent/status/{project_id}
|
||||
H->>H : 校验project_id
|
||||
alt 有效
|
||||
H->>M : 读取项目代理信息
|
||||
M-->>H : 返回Agent信息(含AgentStatus/时间戳/模型提供商)
|
||||
H->>R : 构造AgentStatusResponse(is_alive=true)
|
||||
R-->>C : JSON响应(success=true,data=完整状态)
|
||||
else 无效
|
||||
H-->>C : JSON响应(success=false,error=INVALID_PARAMS)
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### AgentStatusResponse 与 AgentStatus
|
||||
- 字段与语义
|
||||
- project_id：项目唯一标识
|
||||
- is_alive：代理是否存活（true 表示存在且健康）
|
||||
- session_id：仅在 is_alive=true 时存在
|
||||
- status：仅在 is_alive=true 时存在，枚举值为 Active/Idle/Terminating
|
||||
- last_activity/created_at：仅在 is_alive=true 时存在
|
||||
- model_provider：仅在 is_alive=true 时存在，使用脱敏后的安全信息
|
||||
- 序列化策略
|
||||
- 使用 serde 的 skip_serializing_if 控制可选字段的输出
|
||||
- 通过 http_result.rs 的统一结构体包装 success、code、message、tid 与 data
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentStatusResponse {
|
||||
+string project_id
|
||||
+bool is_alive
|
||||
+string session_id?
|
||||
+AgentStatus status?
|
||||
+datetime last_activity?
|
||||
+datetime created_at?
|
||||
+ModelProviderSafeInfo model_provider?
|
||||
}
|
||||
class AgentStatus {
|
||||
<<enum>>
|
||||
+Active
|
||||
+Idle
|
||||
+Terminating
|
||||
}
|
||||
class ModelProviderSafeInfo {
|
||||
+string id
|
||||
+string name
|
||||
+string api_protocol
|
||||
+string default_model
|
||||
}
|
||||
AgentStatusResponse --> AgentStatus : "包含"
|
||||
AgentStatusResponse --> ModelProviderSafeInfo : "包含"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L117)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L117-L132)
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L70-L117)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
### AgentType 抽象与多代理支持
|
||||
- AgentType 枚举：Claude 与 Codex（条件编译 feature）
|
||||
- 类型推断：根据 ModelProviderConfig 的 name 推断代理类型，默认 Claude
|
||||
- 环境注入：提供从环境变量构建 Claude/Codex 模型提供商配置的方法
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentType {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+Codex?
|
||||
}
|
||||
class ModelProviderConfig {
|
||||
+string id
|
||||
+string name
|
||||
+string base_url
|
||||
+string api_key
|
||||
+bool requires_openai_auth
|
||||
+string default_model
|
||||
+string api_protocol?
|
||||
+to_safe_info()
|
||||
}
|
||||
AgentType --> ModelProviderConfig : "推断/配置"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L43-L132)
|
||||
|
||||
章节来源
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L43-L132)
|
||||
|
||||
### gRPC GetStatus 协议映射
|
||||
- 定义位置：agent.proto 中的 GetStatusRequest/GetStatusResponse
|
||||
- 字段：GetStatusResponse.status 为字符串，取值为 "idle"、"busy"、"error"
|
||||
- 生成代码：agent.rs 中包含 GetStatus 的客户端与服务端方法签名
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["gRPC调用 GetStatus"]) --> Req["构造GetStatusRequest(project_id)"]
|
||||
Req --> Call["调用AgentService.get_status"]
|
||||
Call --> Resp["返回GetStatusResponse(status)"]
|
||||
Resp --> Map["映射到HTTP层AgentStatus枚举"]
|
||||
Map --> Out["HTTP层AgentStatusResponse输出"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L69-L76)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L82-L91)
|
||||
|
||||
章节来源
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L69-L76)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L82-L91)
|
||||
|
||||
### HTTP 状态查询接口与聚合逻辑
|
||||
- 参数校验：project_id 必填且非空，否则返回 INVALID_PARAMS
|
||||
- 存在性判断：从 PROJECT_AND_AGENT_INFO_MAP 获取项目代理信息
|
||||
- 聚合策略：
|
||||
- 存在：填充完整 AgentStatusResponse（包含 session_id、status、时间戳、model_provider.safe）
|
||||
- 不存在：仅返回 project_id 与 is_alive=false
|
||||
- 错误传播：AppError 统一转为 HTTP 响应结构体，包含 success、code、message、tid
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["收到GET /agent/status/{project_id}"] --> B["trim并校验project_id"]
|
||||
B --> C{"project_id为空?"}
|
||||
C -- 是 --> E["返回HttpResult.error(INVALID_PARAMS)"]
|
||||
C -- 否 --> D["从PROJECT_AND_AGENT_INFO_MAP读取"]
|
||||
D --> F{"是否存在代理?"}
|
||||
F -- 是 --> G["构造完整AgentStatusResponse(is_alive=true)"]
|
||||
F -- 否 --> H["构造简化AgentStatusResponse(is_alive=false)"]
|
||||
G --> I["返回HttpResult.success"]
|
||||
H --> I
|
||||
E --> J["返回HttpResult.error"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
### 不同代理（Codex、Claude Code）的状态表示与统一抽象
|
||||
- HTTP 层：AgentStatusResponse 的 status 字段为 Active/Idle/Terminating 枚举，统一表达代理的运行态
|
||||
- gRPC 层：GetStatusResponse.status 为字符串，取值为 "idle"、"busy"、"error"，与 HTTP 枚举形成互补
|
||||
- 类型抽象：AgentType 统一区分 Claude 与 Codex，便于在上层进行差异化配置与行为控制
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L61)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L69-L76)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L82-L91)
|
||||
|
||||
### JSON 序列化示例与字段含义
|
||||
- 成功响应（代理存活）
|
||||
- success: true
|
||||
- data: 包含 project_id、is_alive(true)、session_id、status、last_activity、created_at、model_provider.safe
|
||||
- 成功响应（代理不存活）
|
||||
- success: true
|
||||
- data: 包含 project_id、is_alive(false)
|
||||
- 失败响应（参数错误）
|
||||
- success: false
|
||||
- error: 包含 code、message
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L12-L69)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L12-L67)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
## 依赖关系分析
|
||||
- 低耦合与高内聚
|
||||
- HTTP 层仅依赖共享模型（AgentStatusResponse、AgentStatus、ModelProviderSafeInfo），不直接依赖具体代理实现
|
||||
- gRPC 层独立于 HTTP 层，二者通过共享的模型与协议文件解耦
|
||||
- 关键依赖链
|
||||
- HTTP 处理器依赖：PROJECT_AND_AGENT_INFO_MAP、AgentStatusResponse、HttpResult、AppError
|
||||
- 代理抽象依赖：AgentType、AcpAgentService、生命周期管理（AgentLifecycle）
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
AR["agent_status_handler.rsagent_runner"] --> MAP["PROJECT_AND_AGENT_INFO_MAP"]
|
||||
AR --> RESP["AgentStatusResponse"]
|
||||
AR --> HTTP["HttpResult"]
|
||||
AR --> ERR["AppError"]
|
||||
RC["agent_status_handler.rsrcoder"] --> MAP
|
||||
RC --> RESP
|
||||
RC --> HTTP
|
||||
RC --> ERR
|
||||
RESP --> STAT["AgentStatus"]
|
||||
RESP --> MP["ModelProviderSafeInfo"]
|
||||
AS["agent_service.rs"] --> AT["AgentType"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L1-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L1-L132)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L1-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L1-L132)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L117)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L63)
|
||||
- [mod.rs（proxy_agent）](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
## 性能考量
|
||||
- 读取开销：状态查询仅访问内存映射表（DashMap），读操作为 O(1) 量级
|
||||
- 序列化成本：AgentStatusResponse 采用 serde，skip_serializing_if 减少冗余字段输出
|
||||
- 错误路径短路：参数校验失败立即返回，避免不必要的映射查找
|
||||
- 并发安全：代理信息结构体通过 Arc/Mutex 等并发原语保护（生命周期管理），状态查询不持有写锁
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 参数错误
|
||||
- 现象：返回 INVALID_PARAMS
|
||||
- 排查：确认 project_id 非空且去除前后空白
|
||||
- 代理不存在
|
||||
- 现象：is_alive=false，其余字段省略
|
||||
- 排查：确认项目是否已创建代理服务；检查生命周期管理与清理逻辑
|
||||
- 错误传播
|
||||
- AppError 统一转为 HTTP 响应结构体，包含 success、code、message、tid
|
||||
- gRPC 层的 GetStatus 返回字符串状态码，注意与 HTTP 枚举的映射关系
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_status_handler.rs（rcoder）](file://crates/rcoder/src/handler/agent_status_handler.rs#L72-L132)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L24-L103)
|
||||
|
||||
## 结论
|
||||
- AgentStatusResponse 与 AgentStatus 提供了跨代理的一致状态视图，满足 HTTP 与 gRPC 双栈需求
|
||||
- AgentType 抽象确保 Claude 与 Codex 在配置与行为层面的统一入口
|
||||
- 状态查询接口通过最小化参数校验与内存映射读取，实现高效稳定的可观测性
|
||||
- 扩展建议
|
||||
- 在 gRPC 层引入更丰富的状态枚举（如 error 详情），并与 HTTP 层对齐
|
||||
- 在 AgentStatusResponse 中增加健康检查指标（如最近一次错误时间、重启次数）以增强可观测性
|
||||
- 在生命周期管理中补充 Termination 阶段的细化状态，以便更精确地反映代理终止过程
|
||||
334
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/容器模型.md
Normal file
334
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/容器模型.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 容器模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于 RCoder 项目中的“容器模型”，系统性梳理容器相关数据结构（尤其是 ContainerBasicInfo）、状态转换与生命周期管理、以及与 docker_manager 的交互关系。文档还涵盖序列化/反序列化行为、验证约束、性能优化策略，并说明该模型在代理运行时与容器管理中的作用。
|
||||
|
||||
## 项目结构
|
||||
围绕容器模型的关键文件分布如下：
|
||||
- rcoder 侧：
|
||||
- 容器生命周期编排与服务 URL 构建：[crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- 容器创建与健康检查：[crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- 端口管理（历史/兼容）：[crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
|
||||
- docker_manager 侧：
|
||||
- 容器配置与信息、状态枚举、清理工具等：[crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- 默认镜像、网络常量、全局管理器等：[crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- shared_types 侧：
|
||||
- 容器基本信息结构体定义与导出：[crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs)
|
||||
- 类型导出入口：[crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder"
|
||||
CM["容器管理服务<br/>container_manager.rs"]
|
||||
DCA["Docker容器代理<br/>docker_container_agent.rs"]
|
||||
PM["端口管理器<br/>port_manager.rs"]
|
||||
end
|
||||
subgraph "docker_manager"
|
||||
DMTypes["类型定义<br/>types.rs"]
|
||||
DMLib["默认常量/全局管理器<br/>lib.rs"]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
SModel["容器模型定义<br/>agent_project_runner_model.rs"]
|
||||
SExport["类型导出入口<br/>lib.rs"]
|
||||
end
|
||||
CM --> DCA
|
||||
CM --> DMTypes
|
||||
CM --> SModel
|
||||
DCA --> DMTypes
|
||||
DCA --> DMLib
|
||||
PM -.-> CM
|
||||
SExport --> SModel
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L200)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
- [crates/shared_types/src/lib.rs](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
|
||||
## 核心组件
|
||||
- ContainerBasicInfo：跨模块共享的容器基本信息，包含容器 ID、名称、IP、内外端口、项目 ID、状态、创建时间、服务 URL 等字段，用于对外暴露与持久化。
|
||||
- DockerContainerConfig/DockerContainerInfo：docker_manager 提供的容器配置与运行期信息，前者用于创建容器，后者用于描述已存在容器。
|
||||
- ContainerStatus：容器状态枚举，支持从字符串转换与序列化。
|
||||
- 全局 DockerManager：提供容器生命周期操作、网络信息查询、镜像选择、清理等能力。
|
||||
- 容器管理服务 ContainerManager：在 rcoder 侧协调容器创建、复用、网络检测与服务 URL 构建。
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L85-L174)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L130-L211)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
|
||||
## 架构总览
|
||||
容器模型在 RCoder 中的职责链路：
|
||||
- rcoder 的容器管理服务负责按需创建/复用容器，并基于动态网络名称与容器 IP 构建服务 URL。
|
||||
- docker_container_agent 负责具体创建容器、注入环境变量与挂载、等待 agent_runner 就绪。
|
||||
- docker_manager 提供底层 Docker 操作、镜像选择、资源限制、网络与清理工具。
|
||||
- shared_types 统一导出容器模型，保证跨模块一致性。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as "调用方"
|
||||
participant CM as "ContainerManager"
|
||||
participant DCA as "DockerContainerAgent"
|
||||
participant DM as "DockerManager"
|
||||
participant Agent as "agent_runner(容器内)"
|
||||
Caller->>CM : 请求容器(project_id, service_type)
|
||||
CM->>DM : 查询容器是否存在
|
||||
alt 已存在
|
||||
CM->>DM : 获取网络信息(IP)
|
||||
CM-->>Caller : 返回ContainerBasicInfo(service_url)
|
||||
else 不存在
|
||||
CM->>DCA : start_docker_container_agent_service(...)
|
||||
DCA->>DM : select_image()/get_service_config()
|
||||
DCA->>DM : create_container(DockerContainerConfig)
|
||||
DM-->>DCA : DockerContainerInfo
|
||||
DCA->>DCA : 等待Agent就绪(get_container_ip/wait_for_agent_server_ready)
|
||||
DCA-->>CM : (DockerContainerInfo, server_url)
|
||||
CM->>DM : 获取网络信息(IP)
|
||||
CM-->>Caller : 返回ContainerBasicInfo(service_url)
|
||||
end
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L153-L274)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L19-L130)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据结构：ContainerBasicInfo
|
||||
- 字段定义与业务含义
|
||||
- container_id：容器唯一标识，用于定位与日志追踪。
|
||||
- container_name：容器名称，便于可视化与调试。
|
||||
- container_ip：容器在动态网络中的 IP，用于内部通信。
|
||||
- internal_port：容器内服务监听端口（固定为代理容器默认端口）。
|
||||
- external_port：外部映射端口（当前实现为 0，表示无宿主机端口映射）。
|
||||
- project_id：项目标识，用于多租户隔离与容器复用。
|
||||
- status：容器状态字符串，便于对外展示与持久化。
|
||||
- created_at：容器创建时间，UTC 时间戳。
|
||||
- service_url：服务访问 URL，由容器 IP 与固定端口拼接而成。
|
||||
- 序列化/反序列化
|
||||
- 采用标准的 serde Serialize/Deserialize，支持 JSON 序列化，便于 API 返回与日志输出。
|
||||
- 验证约束
|
||||
- 字段均为简单标量或时间类型，无复杂校验；业务层通过 DockerManager 返回的网络信息与端口常量保证 service_url 有效性。
|
||||
- 性能优化
|
||||
- 作为轻量结构体，拷贝成本低；对外仅暴露必要字段，减少冗余数据传输。
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L242-L269)
|
||||
|
||||
### 数据结构：DockerContainerConfig 与 DockerContainerInfo
|
||||
- DockerContainerConfig
|
||||
- 用途：创建容器时的配置载体，包含镜像、名称前缀、宿主机/容器路径、工作目录、环境变量、端口映射、网络模式、资源限制、额外挂载、命令/入口点、网络名称等。
|
||||
- 关键点：当前实现中端口映射为空，网络模式与工作目录来自服务配置；资源限制来自配置；容器路径通过变量替换与宿主机路径解析。
|
||||
- DockerContainerInfo
|
||||
- 用途：描述已存在容器的运行期信息，包含 ID、名称、项目 ID、镜像、状态、创建/启动时间、主机/容器路径、端口映射、分配端口、健康状态、内部服务端口、网络名称等。
|
||||
- 序列化/反序列化
|
||||
- 均实现 serde Serialize/Deserialize，便于与 Docker API 返回结构互通。
|
||||
- 验证约束
|
||||
- 通过服务配置与镜像选择策略保证镜像与网络模式的有效性；端口映射为空时，内部通信不依赖宿主机端口映射。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L85-L174)
|
||||
|
||||
### 状态转换与生命周期管理
|
||||
- 状态来源
|
||||
- ContainerStatus 枚举支持从字符串转换与序列化，覆盖常见容器状态（创建中、运行中、已停止、已暂停、重启中、移除中、已退出、已死亡、未知）。
|
||||
- 生命周期流程
|
||||
- 容器创建：由 docker_container_agent 基于服务配置与镜像选择策略创建容器。
|
||||
- 就绪等待：等待容器内 agent_runner 健康检查通过，超时则清理失败容器。
|
||||
- 复用与查询：ContainerManager 在后续请求中复用已存在容器，动态获取网络 IP 并构建服务 URL。
|
||||
- 清理：docker_manager 提供清理工具与过滤条件，支持按状态/标签/名称模式筛选并批量删除。
|
||||
- 端口策略
|
||||
- 当前实现采用内部网络通信，无需宿主机端口映射；external_port 字段为 0，端口管理器主要用于历史/兼容场景。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 创建中
|
||||
创建中 --> 运行中 : "启动成功"
|
||||
创建中 --> 已停止 : "启动失败/清理"
|
||||
运行中 --> 已停止 : "停止/异常"
|
||||
已停止 --> 运行中 : "重启"
|
||||
运行中 --> 移除中 : "清理"
|
||||
移除中 --> [*]
|
||||
运行中 --> 已退出 : "优雅退出"
|
||||
已退出 --> [*]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L120-L174)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L120-L174)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L111-L130)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L277-L472)
|
||||
|
||||
### 与 docker_manager 的交互关系
|
||||
- 配置与镜像选择
|
||||
- docker_container_agent 通过 docker_manager 的镜像选择与服务配置接口获取镜像与运行参数。
|
||||
- 容器创建与查询
|
||||
- docker_container_agent 调用 create_container 获取 DockerContainerInfo；ContainerManager 通过 get_container_info 与 get_container_network_info 获取网络 IP 与状态。
|
||||
- 网络与端口
|
||||
- 使用动态网络名称（由 docker_manager 检测），容器内部服务端口固定为代理容器默认端口；当前实现不进行宿主机端口映射。
|
||||
- 默认常量与全局管理器
|
||||
- docker_manager 提供默认工作目录、网络模式、镜像选择策略与全局 DockerManager 单例，rcoder 侧通过全局实例获取管理器并执行操作。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L58-L130)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L142-L274)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L130-L211)
|
||||
|
||||
### 实际使用模式与示例路径
|
||||
- 容器创建与就绪等待
|
||||
- 示例路径：[start_docker_container_agent_service](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L19-L130)
|
||||
- 该函数负责检查已有容器、选择镜像与服务配置、创建容器、等待 agent_runner 就绪并返回容器信息与服务 URL。
|
||||
- 容器复用与服务 URL 构建
|
||||
- 示例路径：[get_or_create_container](file://crates/rcoder/src/service/container_manager.rs#L153-L208)、[ensure_container_exists](file://crates/rcoder/src/service/container_manager.rs#L277-L360)、[create_container_for_request](file://crates/rcoder/src/service/container_manager.rs#L361-L472)
|
||||
- 该流程在容器存在时直接复用，不存在时创建并获取网络 IP，最终构造服务 URL。
|
||||
- 网络 IP 获取与健康检查
|
||||
- 示例路径：[get_container_ip](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L375-L417)、[wait_for_agent_server_ready](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L348-L374)
|
||||
- 通过 docker_manager 的网络信息查询与健康检查端点轮询确认容器内服务可用。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L19-L130)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L153-L208)
|
||||
|
||||
### 序列化/反序列化行为与验证约束
|
||||
- 序列化
|
||||
- ContainerBasicInfo、DockerContainerConfig、DockerContainerInfo、ContainerStatus 均实现 serde Serialize/Deserialize，支持 JSON 输出与 API 交互。
|
||||
- 反序列化
|
||||
- ContainerStatus 支持从字符串转换，便于从 Docker API 返回的状态字符串映射到枚举。
|
||||
- 验证约束
|
||||
- 服务配置与镜像选择在 docker_manager 层保证有效；rcoder 侧通过固定端口与动态网络名称确保 service_url 有效性；容器状态字符串映射为枚举，避免非法状态传播。
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L120-L174)
|
||||
|
||||
### 性能优化策略
|
||||
- 端口映射优化
|
||||
- 采用内部网络通信，避免端口分配与释放开销，external_port 设为 0，简化网络管理。
|
||||
- 路径解析与挂载
|
||||
- 通过容器路径解析器将容器内路径转换为宿主机绝对路径，减少挂载错误与重复 IO。
|
||||
- 写时复制与共享
|
||||
- shared_types 中的 ProjectState 使用 Arc 实现高效共享与写时复制，降低频繁更新带来的内存复制成本。
|
||||
- 超时与重试
|
||||
- 健康检查采用 1 秒间隔与 30 次上限，避免长时间阻塞；失败时快速清理失败容器，降低资源占用。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L111-L130)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L474-L521)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L106-L160)
|
||||
|
||||
## 依赖关系分析
|
||||
- 模块耦合
|
||||
- rcoder 的容器管理服务依赖 docker_manager 的容器信息与网络查询能力；docker_container_agent 依赖 docker_manager 的镜像选择与容器创建能力。
|
||||
- shared_types 统一导出 ContainerBasicInfo，避免跨模块重复定义。
|
||||
- 外部依赖
|
||||
- Docker API（bollard）用于容器查询与网络信息获取。
|
||||
- serde 用于结构体序列化/反序列化。
|
||||
- 循环依赖
|
||||
- 通过 shared_types 导出类型，避免 rcoder 与 docker_manager 之间的循环导入。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CM["rcoder/service/container_manager.rs"] --> DMT["docker_manager/types.rs"]
|
||||
DCA["rcoder/proxy_agent/docker_container_agent.rs"] --> DMT
|
||||
DCA --> DML["docker_manager/lib.rs"]
|
||||
CM --> SModel["shared_types/model/agent_project_runner_model.rs"]
|
||||
DMT --> SModel
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L120)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L1-L120)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [crates/shared_types/src/model/agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
|
||||
## 性能考量
|
||||
- 端口管理
|
||||
- 当前实现不使用宿主机端口映射，external_port 为 0；端口管理器仍可用于历史/兼容场景，避免不必要的端口占用。
|
||||
- 路径解析
|
||||
- 宿主机路径解析与容器内路径标准化减少挂载错误与 IO 重试，提升稳定性。
|
||||
- 状态与网络查询
|
||||
- 通过 docker_manager 的网络信息查询与固定端口，避免多次网络探测与端口冲突。
|
||||
- 资源限制
|
||||
- 服务配置提供资源限制，结合 docker_manager 的资源限制结构，控制容器资源占用，避免资源争用。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L192-L242)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L51-L61)
|
||||
|
||||
## 故障排查指南
|
||||
- 容器创建失败
|
||||
- 检查镜像选择与服务配置是否正确；查看 docker_manager 的错误日志与镜像拉取状态。
|
||||
- 参考路径：[start_docker_container_agent_service](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L88-L130)
|
||||
- 容器内服务未就绪
|
||||
- 观察健康检查轮询与超时设置；确认容器内 agent_runner 启动日志与端口监听情况。
|
||||
- 参考路径：[wait_for_agent_server_ready](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L348-L374)
|
||||
- 网络连接问题
|
||||
- 确认动态网络名称与容器网络映射；检查容器是否连接到预期网络。
|
||||
- 参考路径：[get_container_ip](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L375-L417)、[get_dynamic_network_name](file://crates/rcoder/src/service/container_manager.rs#L142-L151)
|
||||
- 端口冲突（历史/兼容）
|
||||
- 若使用宿主机端口映射，检查端口管理器分配与释放逻辑。
|
||||
- 参考路径：[PortManager](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L88-L130)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L348-L417)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L142-L151)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L96)
|
||||
|
||||
## 结论
|
||||
RCoder 的容器模型以 ContainerBasicInfo 为核心，结合 docker_manager 的配置与生命周期能力，在 rcoder 侧实现了按需创建、复用与健康检查的容器管理流程。通过内部网络通信与固定端口策略，显著降低了端口管理复杂度与资源占用；shared_types 的统一导出保证了跨模块一致性。整体设计在可维护性、性能与可扩展性之间取得良好平衡。
|
||||
|
||||
## 附录
|
||||
- 关键实现路径参考
|
||||
- 容器创建与就绪等待：[start_docker_container_agent_service](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L19-L130)
|
||||
- 容器复用与服务 URL 构建：[get_or_create_container](file://crates/rcoder/src/service/container_manager.rs#L153-L208)
|
||||
- 网络 IP 获取与健康检查：[get_container_ip](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L375-L417)、[wait_for_agent_server_ready](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L348-L374)
|
||||
- 容器状态与序列化：[ContainerStatus](file://crates/docker_manager/src/types.rs#L120-L174)
|
||||
- 容器模型定义：[ContainerBasicInfo](file://crates/shared_types/src/model/agent_project_runner_model.rs#L1-L60)
|
||||
524
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/数据模型与类型.md
Normal file
524
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/数据模型与类型.md
Normal file
@@ -0,0 +1,524 @@
|
||||
# 数据模型与类型
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [config.yml](file://config.yml)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [核心实体与关系](#核心实体与关系)
|
||||
3. [字段定义与数据类型](#字段定义与数据类型)
|
||||
4. [主键/外键、索引与约束](#主键外键索引与约束)
|
||||
5. [数据验证规则与业务规则](#数据验证规则与业务规则)
|
||||
6. [数据库模式图](#数据库模式图)
|
||||
7. [示例数据](#示例数据)
|
||||
8. [数据访问模式、缓存策略与性能考虑](#数据访问模式缓存策略与性能考虑)
|
||||
9. [数据生命周期、保留策略与归档规则](#数据生命周期保留策略与归档规则)
|
||||
10. [数据迁移路径与版本管理](#数据迁移路径与版本管理)
|
||||
|
||||
## 引言
|
||||
RCoder项目是一个基于AI代理的开发辅助系统，其数据模型设计围绕AI代理服务、会话管理、项目状态和用户交互等核心功能构建。本数据模型文档旨在全面介绍RCoder项目的数据结构、类型定义、实体关系以及相关的业务规则和性能策略。通过分析`shared_types` crate中的Rust结构体和`proto`文件中的gRPC消息定义，我们能够理解系统中数据的组织方式和流转过程。该模型支持多代理类型（如Claude和Codex）、灵活的模型提供商配置、丰富的附件类型，并通过gRPC协议实现服务间的通信。此外，系统的配置文件（YAML）定义了服务部署和运行时的参数，这些参数也构成了系统数据模型的一部分。
|
||||
|
||||
## 核心实体与关系
|
||||
RCoder项目的数据模型围绕几个核心实体构建，这些实体通过明确的关系相互连接，形成了一个支持AI代理服务生命周期管理的系统。主要实体包括`Agent`（代理）、`Project`（项目）、`Session`（会话）、`ModelProvider`（模型提供商）和`Attachment`（附件）。
|
||||
|
||||
`Project`（项目）是用户工作的核心单元，每个项目由唯一的`project_id`标识。一个项目可以关联一个正在运行的`Agent`实例。这种关系通过`ProjectAndAgentInfo`结构体体现，其中`project_id`作为关键字段将项目与代理实例绑定。`Agent`实例的生命周期由`AgentLifecycleGuard`管理，当代理被创建时，它会与一个`Session`（会话）相关联，会话ID（`session_id`）是代理与用户交互过程中的唯一标识。
|
||||
|
||||
`ModelProvider`（模型提供商）为`Agent`提供AI模型能力。`Agent`通过`model_provider`字段引用一个`ModelProviderConfig`对象，该对象包含了访问AI模型API所需的所有信息，如API密钥、基础URL和默认模型名称。一个`ModelProvider`可以被多个`Agent`实例共享，但一个`Agent`在同一时间只能使用一个`ModelProvider`。
|
||||
|
||||
`Attachment`（附件）是用户在与AI代理交互时可以附加到提示（prompt）中的数据。一个`ChatPrompt`请求可以包含多个`Attachment`，形成一对多的关系。`Attachment`是一个枚举类型，支持多种媒体类型，如文本、图像、音频和文档，这使得用户可以提供丰富的上下文信息给AI代理。
|
||||
|
||||
最后，`Session`（会话）不仅是代理运行的上下文，也是状态更新和消息通知的载体。`AgentSessionUpdate`、`SessionPromptStart`和`SessionPromptEnd`等结构体都包含`session_id`，用于将状态更新与特定的会话关联起来。这些更新通过`SessionNotify`枚举被统一处理，并最终转换为`UnifiedSessionMessage`发送给前端，实现服务端到客户端的实时通信。
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
PROJECT {
|
||||
string project_id PK
|
||||
datetime created_at
|
||||
datetime last_activity
|
||||
}
|
||||
SESSION {
|
||||
string session_id PK
|
||||
string project_id FK
|
||||
string request_id
|
||||
datetime created_at
|
||||
datetime last_activity
|
||||
string status
|
||||
}
|
||||
AGENT {
|
||||
string agent_type
|
||||
string status
|
||||
string session_id FK
|
||||
string model_provider_id FK
|
||||
}
|
||||
MODEL_PROVIDER {
|
||||
string id PK
|
||||
string name
|
||||
string base_url
|
||||
string api_key
|
||||
string default_model
|
||||
string api_protocol
|
||||
}
|
||||
ATTACHMENT {
|
||||
string id PK
|
||||
string session_id FK
|
||||
string source_type
|
||||
string mime_type
|
||||
string filename
|
||||
text description
|
||||
}
|
||||
CHAT_PROMPT {
|
||||
string project_id FK
|
||||
string session_id FK
|
||||
string prompt
|
||||
string request_id
|
||||
string agent_type
|
||||
string service_type
|
||||
}
|
||||
CHAT_RESPONSE {
|
||||
string project_id FK
|
||||
string session_id FK
|
||||
string request_id
|
||||
string error
|
||||
}
|
||||
PROJECT ||--o{ SESSION : "1 to many"
|
||||
SESSION ||--|| AGENT : "1 to 1"
|
||||
SESSION ||--o{ ATTACHMENT : "1 to many"
|
||||
AGENT }|--|| MODEL_PROVIDER : "uses"
|
||||
CHAT_PROMPT }|--|| SESSION : "references"
|
||||
CHAT_RESPONSE }|--|| SESSION : "references"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L8-L29)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L5-L17)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L93-L104)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L45-L67)
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
|
||||
## 字段定义与数据类型
|
||||
本节详细定义RCoder数据模型中各核心实体的字段及其数据类型。所有类型均基于Rust语言定义，并通过`serde`和`utoipa`等库支持序列化、反序列化和API文档生成。
|
||||
|
||||
### ProjectAndAgentInfo (项目与代理信息)
|
||||
该结构体是`rcoder`和`agent_runner`共用的核心结构，代表一个项目与其实例化代理的关联。
|
||||
- `project_id` (`String`): 项目的唯一标识符。
|
||||
- `session_id` (`SessionId`): 代理服务的会话ID，由代理启动时创建。
|
||||
- `prompt_tx` (`mpsc::UnboundedSender<PromptRequest>`): 用于向代理发送提示请求的异步通道。
|
||||
- `cancel_tx` (`mpsc::UnboundedSender<CancelNotificationRequest>`): 用于向代理发送取消通知的异步通道。
|
||||
- `model_provider` (`Option<ModelProviderConfig>`): 可选的模型提供商配置，为代理提供AI模型能力。
|
||||
- `request_id` (`Option<String>`): 当前活跃的用户请求ID，用于追踪单个请求。
|
||||
- `status` (`AgentStatus`): 代理的当前服务状态（`Active`, `Idle`, `Terminating`）。
|
||||
- `last_activity` (`DateTime<Utc>`): 代理最后一次活动的时间戳。
|
||||
- `created_at` (`DateTime<Utc>`): 代理实例的创建时间戳。
|
||||
- `stop_handle` (`Option<Arc<dyn AgentLifecycle>>`): 代理生命周期管理的句柄，用于优雅停止代理。
|
||||
|
||||
### ChatPrompt (聊天提示)
|
||||
该结构体定义了用户向AI代理发送的请求。
|
||||
- `project_id` (`String`): 关联的项目ID。
|
||||
- `project_path` (`PathBuf`): 项目在文件系统中的路径。
|
||||
- `session_id` (`Option<String>`): 可选的会话ID。如果未提供，代理将自动创建一个新会话。
|
||||
- `prompt` (`String`): 用户输入的提示内容。
|
||||
- `attachments` (`Vec<Attachment>`): 可选的附件列表，`Builder`模式下默认为空。
|
||||
- `data_source_attachments` (`Vec<String>`): 用于AI开发的外部数据源信息，以JSON字符串数组形式传递。
|
||||
- `agent_type` (`AgentType`): 指定使用的代理类型（`Claude`或`Codex`），`Builder`模式下默认值。
|
||||
- `service_type` (`ServiceType`): 必填字段，指定使用的服务类型（`rcoder`或`agent-runner`）。
|
||||
- `request_id` (`Option<String>`): 可选的请求ID，用于标识和追踪。
|
||||
- `model_provider` (`Option<ModelProviderConfig>`): 可选的模型提供商配置，用于覆盖默认配置。
|
||||
|
||||
### ChatResponse (聊天响应)
|
||||
该结构体定义了AI代理对用户请求的响应。
|
||||
- `project_id` (`String`): 关联的项目ID。
|
||||
- `session_id` (`String`): 代理的会话ID。
|
||||
- `error` (`Option<String>`): 可选的错误信息，如果请求失败则填充。
|
||||
- `request_id` (`Option<String>`): 请求ID，用于标识和追踪。
|
||||
- `service_type` (`ServiceType`): 使用的服务类型。
|
||||
|
||||
### Attachment (附件)
|
||||
`Attachment`是一个枚举类型，支持多种媒体格式。
|
||||
- **通用字段**:
|
||||
- `id` (`String`): 附件的唯一标识符，使用UUID生成。
|
||||
- `source` (`AttachmentSource`): 附件数据源，枚举类型，包含`FilePath`、`Base64`和`Url`。
|
||||
- `filename` (`Option<String>`): 可选的文件名。
|
||||
- `description` (`Option<String>`): 可选的描述。
|
||||
- **TextAttachment (文本附件)**: 无额外字段。
|
||||
- **ImageAttachment (图像附件)**:
|
||||
- `mime_type` (`String`): MIME类型（如`image/jpeg`）。
|
||||
- `dimensions` (`Option<ImageDimensions>`): 可选的图像尺寸信息。
|
||||
- **AudioAttachment (音频附件)**:
|
||||
- `mime_type` (`String`): MIME类型（如`audio/mp3`）。
|
||||
- `duration` (`Option<f64>`): 可选的音频时长（秒）。
|
||||
- **DocumentAttachment (文档附件)**:
|
||||
- `mime_type` (`String`): MIME类型（如`application/pdf`）。
|
||||
- `size` (`Option<u64>`): 可选的文件大小（字节）。
|
||||
|
||||
### ModelProviderConfig (模型提供商配置)
|
||||
该结构体封装了访问AI模型API所需的所有凭证和配置。
|
||||
- `id` (`String`): 模型提供商的唯一ID。
|
||||
- `name` (`String`): 提供商名称（如`openai`, `anthropic`）。
|
||||
- `base_url` (`String`): API的基础URL。
|
||||
- `api_key` (`String`): 访问API的密钥。
|
||||
- `requires_openai_auth` (`bool`): 是否需要OpenAI兼容的认证头。
|
||||
- `default_model` (`String`): 默认使用的模型名称。
|
||||
- `api_protocol` (`Option<String>`): 模型接口协议类型（`anthropic`或`openai`），可选。
|
||||
|
||||
### AgentSessionUpdate (代理会话更新)
|
||||
该结构体封装了代理在执行任务过程中产生的各种更新事件。
|
||||
- `session_id` (`String`): 关联的会话ID。
|
||||
- `session_update` (`SessionUpdate`): 具体的更新内容，为枚举类型，包含`UserMessageChunk`、`AgentMessageChunk`、`ToolCall`等。
|
||||
- `request_id` (`Option<String>`): 可选的请求ID。
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L8-L29)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L5-L17)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L23-L90)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L45-L67)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L61-L65)
|
||||
|
||||
## 主键外键索引与约束
|
||||
RCoder的数据模型主要在内存和进程间通信层面运作，其“主键”和“外键”概念更多地体现在数据结构的逻辑关联和唯一性保证上，而非传统的关系型数据库约束。
|
||||
|
||||
### 主键 (Primary Keys)
|
||||
- **`project_id`**: 在`ProjectAndAgentInfo`和`ChatPrompt`等结构体中，`project_id`是项目实体的逻辑主键。它确保了每个项目在系统中的唯一性，并作为查找和管理项目相关资源（如代理、会话）的主要依据。
|
||||
- **`session_id`**: 在`ProjectAndAgentInfo`和`AgentSessionUpdate`等结构体中，`session_id`是会话实体的逻辑主键。它唯一标识一个代理的运行实例，所有与该代理的交互（如发送提示、接收更新、取消任务）都通过此ID进行。
|
||||
- **`id`**: 在`Attachment`结构体中，`id`字段（由`Uuid::new_v4()`生成）是每个附件的唯一标识符，作为附件的主键。
|
||||
|
||||
### 外键 (Foreign Keys)
|
||||
- **`project_id` in `ProjectAndAgentInfo`**: 该字段作为外键，将`ProjectAndAgentInfo`记录与一个具体的`Project`实体关联起来。它确保了代理实例的归属。
|
||||
- **`session_id` in `ProjectAndAgentInfo`**: 该字段作为外键，将`ProjectAndAgentInfo`记录与一个具体的`Session`实体关联起来。它建立了项目、代理和会话三者之间的联系。
|
||||
- **`session_id` in `AgentSessionUpdate`**: 该字段作为外键，将状态更新事件与一个具体的会话关联，确保前端能够正确地将更新渲染到对应的会话流中。
|
||||
- **`request_id` in `ChatPrompt` and `ChatResponse`**: 虽然`request_id`不是严格的外键，但它起到了关联请求和响应的作用，是实现请求-响应追踪的关键。
|
||||
|
||||
### 索引与约束
|
||||
由于数据主要存储在内存数据结构（如`DashMap`）中，索引是隐式存在的。
|
||||
- **内存索引**: `ProjectAndAgentInfo`通常被存储在以`project_id`为键的`DashMap<String, ProjectAndAgentInfo>`中。这使得通过`project_id`查找代理信息的操作具有接近O(1)的时间复杂度，相当于在`project_id`上创建了一个哈希索引。
|
||||
- **业务约束**:
|
||||
1. **唯一性约束**: 系统设计上保证一个`project_id`在同一时间只能关联一个活跃的`Agent`实例。当为一个已有代理的项目创建新会话时，旧的代理实例会被终止。
|
||||
2. **非空约束**: `ChatPrompt`中的`project_id`、`prompt`和`service_type`字段是必填的，由`Builder`模式和业务逻辑保证。
|
||||
3. **枚举约束**: `AgentType`和`AgentStatus`等字段的值被限制在预定义的枚举范围内，由Rust的类型系统强制执行。
|
||||
4. **格式约束**: `model_provider.api_key`等敏感字段在日志中会被脱敏（如显示为`sk-***abc`），通过`Display` trait的实现来保证。
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L10-L29)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L61-L65)
|
||||
|
||||
## 数据验证规则与业务规则
|
||||
RCoder项目通过Rust的强类型系统、`derive_builder`宏和自定义验证逻辑来实施数据验证和业务规则。
|
||||
|
||||
### 数据验证规则
|
||||
- **类型安全**: Rust的编译时类型检查确保了字段的数据类型正确，例如`last_activity`必须是`DateTime<Utc>`，`status`必须是`AgentStatus`枚举的成员。
|
||||
- **必填字段验证**: `ChatPrompt`结构体使用`derive_builder`宏。`project_id`、`prompt`和`service_type`没有`#[builder(default)]`属性，因此在构建时必须显式提供，否则编译失败。
|
||||
- **枚举值验证**: `AgentType`实现了`FromStr` trait，当从字符串解析时，会检查输入是否为有效的类型（`"claude"`或`"codex"`），否则返回错误。
|
||||
- **附件处理验证**: `Attachment`模块定义了`AttachmentError`枚举，用于处理文件读取、Base64解码、URL访问等操作中可能出现的错误，确保附件数据的完整性和可用性。
|
||||
|
||||
### 业务规则
|
||||
- **代理生命周期管理**: 代理的创建、运行和销毁遵循严格的业务流程。`AgentLifecycleGuard`实现了RAII（资源获取即初始化）原则，当其被`drop`时会自动触发资源清理。`graceful_stop`方法首先发送取消信号，等待任务自然退出，最后强制清理资源，确保了代理的优雅关闭。
|
||||
- **会话与项目绑定**: 一个`project_id`在同一时间只能有一个活跃的代理会话。当收到新的`ChatPrompt`请求时，如果该项目已有代理在运行，系统会先取消旧的会话，再启动新的会话，避免资源冲突。
|
||||
- **模型提供商推断**: `AgentType::from_model_provider`方法根据`ModelProviderConfig`的`name`字段自动推断应使用的代理类型（`anthropic` -> `Claude`），简化了用户配置。
|
||||
- **环境变量注入**: `AgentType`提供了`claude_from_env`和`codex_from_env`等方法，能够从进程环境变量中读取配置，并自动注入必要的启动参数（如`--dangerously-skip-permissions`），确保代理能够正确启动。
|
||||
- **状态更新的统一处理**: 所有的会话状态更新（开始、结束、错误、进度）都通过`SessionNotify`枚举被转换为统一的`UnifiedSessionMessage`格式。这保证了前端接收到的消息格式一致，简化了前端的处理逻辑。
|
||||
- **配置优先级**: 当`ChatPrompt`中提供了`model_provider`时，它会覆盖系统默认的模型提供商配置，实现了按请求级别的配置覆盖。
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L339-L403)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L6-L29)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L115-L124)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L77-L162)
|
||||
|
||||
## 数据库模式图
|
||||
RCoder项目并未使用传统的关系型数据库，其数据主要存储在内存中，并通过gRPC进行服务间通信。因此，其“数据库”模式更准确地描述为**数据结构与通信协议模式**。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ProjectAndAgentInfo {
|
||||
+project_id : String
|
||||
+session_id : SessionId
|
||||
+prompt_tx : mpsc : : UnboundedSender<PromptRequest>
|
||||
+cancel_tx : mpsc : : UnboundedSender<CancelNotificationRequest>
|
||||
+model_provider : Option<ModelProviderConfig>
|
||||
+request_id : Option<String>
|
||||
+status : AgentStatus
|
||||
+last_activity : DateTime<Utc>
|
||||
+created_at : DateTime<Utc>
|
||||
+stop_handle : Option<Arc<dyn AgentLifecycle>>
|
||||
}
|
||||
class ChatPrompt {
|
||||
+project_id : String
|
||||
+project_path : PathBuf
|
||||
+session_id : Option<String>
|
||||
+prompt : String
|
||||
+attachments : Vec<Attachment>
|
||||
+data_source_attachments : Vec<String>
|
||||
+agent_type : AgentType
|
||||
+service_type : ServiceType
|
||||
+request_id : Option<String>
|
||||
+model_provider : Option<ModelProviderConfig>
|
||||
}
|
||||
class ChatResponse {
|
||||
+project_id : String
|
||||
+session_id : String
|
||||
+error : Option<String>
|
||||
+request_id : Option<String>
|
||||
+service_type : ServiceType
|
||||
}
|
||||
class Attachment {
|
||||
+id : String
|
||||
+source : AttachmentSource
|
||||
+filename : Option<String>
|
||||
+description : Option<String>
|
||||
}
|
||||
class AttachmentSource {
|
||||
<<enumeration>>
|
||||
+FilePath{ path : String }
|
||||
+Base64{ data : String, mime_type : String }
|
||||
+Url{ url : String }
|
||||
}
|
||||
class ModelProviderConfig {
|
||||
+id : String
|
||||
+name : String
|
||||
+base_url : String
|
||||
+api_key : String
|
||||
+requires_openai_auth : bool
|
||||
+default_model : String
|
||||
+api_protocol : Option<String>
|
||||
}
|
||||
class AgentSessionUpdate {
|
||||
+session_id : String
|
||||
+session_update : SessionUpdate
|
||||
+request_id : Option<String>
|
||||
}
|
||||
class SessionUpdate {
|
||||
<<enumeration>>
|
||||
+UserMessageChunk
|
||||
+AgentMessageChunk
|
||||
+ToolCall
|
||||
+Plan
|
||||
+AvailableCommandsUpdate
|
||||
+CurrentModeUpdate
|
||||
}
|
||||
class UnifiedSessionMessage {
|
||||
+session_id : String
|
||||
+message_type : SessionMessageType
|
||||
+sub_type : String
|
||||
+data : serde_json : : Value
|
||||
+timestamp : DateTime<Utc>
|
||||
}
|
||||
class HttpResult~T~ {
|
||||
+code : String
|
||||
+message : String
|
||||
+data : Option~T~
|
||||
+tid : Option<String>
|
||||
+success : bool
|
||||
}
|
||||
ProjectAndAgentInfo --> ModelProviderConfig : "uses"
|
||||
ChatPrompt --> Attachment : "has many"
|
||||
ChatPrompt --> ModelProviderConfig : "can override"
|
||||
AgentSessionUpdate --> SessionUpdate : "contains"
|
||||
AgentSessionUpdate --> UnifiedSessionMessage : "converts to"
|
||||
HttpResult --> ChatResponse : "wraps"
|
||||
HttpResult --> AgentStatusResponse : "wraps"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
|
||||
## 示例数据
|
||||
以下是根据数据模型生成的JSON格式示例数据，展示了API请求和响应的典型结构。
|
||||
|
||||
### ChatPrompt 请求示例
|
||||
```json
|
||||
{
|
||||
"project_id": "my-web-app",
|
||||
"project_path": "/home/user/project_workspace/my-web-app",
|
||||
"session_id": null,
|
||||
"prompt": "请帮我创建一个React组件，实现一个带有搜索功能的用户列表。",
|
||||
"attachments": [
|
||||
{
|
||||
"type": "text",
|
||||
"content": {
|
||||
"id": "att-123",
|
||||
"source": {
|
||||
"source_type": "FilePath",
|
||||
"data": {
|
||||
"path": "src/components/UserList.js"
|
||||
}
|
||||
},
|
||||
"filename": "UserList.js",
|
||||
"description": "现有用户列表组件"
|
||||
}
|
||||
}
|
||||
],
|
||||
"data_source_attachments": [],
|
||||
"agent_type": "Claude",
|
||||
"service_type": "rcoder",
|
||||
"request_id": "req-abc123",
|
||||
"model_provider": {
|
||||
"id": "openai-gpt4",
|
||||
"name": "openai",
|
||||
"base_url": "https://api.openai.com/v1",
|
||||
"api_key": "sk-very-long-secret-key",
|
||||
"requires_openai_auth": true,
|
||||
"default_model": "gpt-4-turbo",
|
||||
"api_protocol": "openai"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ChatResponse 响应示例
|
||||
```json
|
||||
{
|
||||
"project_id": "my-web-app",
|
||||
"session_id": "sess-456def",
|
||||
"error": null,
|
||||
"request_id": "req-abc123",
|
||||
"service_type": "rcoder"
|
||||
}
|
||||
```
|
||||
|
||||
### AgentStatusResponse 响应示例
|
||||
```json
|
||||
{
|
||||
"project_id": "my-web-app",
|
||||
"is_alive": true,
|
||||
"session_id": "sess-456def",
|
||||
"status": "Active",
|
||||
"last_activity": "2024-01-01T12:05:30Z",
|
||||
"created_at": "2024-01-01T12:00:00Z",
|
||||
"model_provider": {
|
||||
"id": "openai-gpt4",
|
||||
"name": "openai",
|
||||
"api_protocol": "openai",
|
||||
"default_model": "gpt-4-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### UnifiedSessionMessage (SSE流) 示例
|
||||
```json
|
||||
{
|
||||
"session_id": "sess-456def",
|
||||
"message_type": "AgentSessionUpdate",
|
||||
"sub_type": "agent_message_chunk",
|
||||
"data": {
|
||||
"content": {
|
||||
"text": "好的，我将为您创建一个React组件...",
|
||||
"type": "text"
|
||||
},
|
||||
"request_id": "req-abc123"
|
||||
},
|
||||
"timestamp": "2024-01-01T12:05:35Z"
|
||||
}
|
||||
```
|
||||
|
||||
**本节来源**
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L71-L97)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L17-L30)
|
||||
|
||||
## 数据访问模式缓存策略与性能考虑
|
||||
RCoder项目的数据访问模式、缓存策略和性能优化紧密围绕其高并发、低延迟的实时交互需求设计。
|
||||
|
||||
### 数据访问模式
|
||||
- **内存优先**: 核心状态（如`ProjectAndAgentInfo`）存储在全局的`DashMap`或`RwLock<HashMap>`中，提供极快的读写速度。通过`project_id`作为键进行哈希查找，实现O(1)的平均时间复杂度。
|
||||
- **异步通道通信**: `rcoder`主服务与`agent_runner`代理服务之间通过`tokio`的`mpsc`（多生产者单消费者）无界通道进行通信。`prompt_tx`用于发送提示，`cancel_tx`用于发送取消指令。这种模式避免了直接的函数调用开销，实现了服务间的解耦和非阻塞通信。
|
||||
- **gRPC流式传输**: 代理的执行进度通过gRPC的服务器流式RPC（`SubscribeProgress`）或SSE（Server-Sent Events）实时推送给前端。`UnifiedSessionMessage`被序列化为JSON并通过流发送，确保了低延迟的用户体验。
|
||||
- **原子操作与锁优化**: `ProjectState`结构体使用`Arc<ProjectCoreState>`和`Arc<ProjectExtendedState>`，结合`Arc::make_mut`实现写时复制（Copy-on-Write），在读多写少的场景下极大减少了锁竞争。`AtomicBool`用于`AgentLifecycleGuard`的状态标记，避免了对整个结构体的加锁。
|
||||
|
||||
### 缓存策略
|
||||
- **配置缓存**: `MultiImageConfig`中的`cache_config`允许缓存Docker镜像选择的结果，避免重复的镜像解析和选择计算，提高容器启动速度。
|
||||
- **内存缓存**: 整个`ProjectAndAgentInfo`映射本身就是一种内存缓存，避免了每次请求都重新创建或查询代理实例。
|
||||
- **无持久化缓存**: 项目未使用Redis等外部缓存系统，所有缓存均为进程内内存缓存，简化了架构，但依赖于单个进程的可用性。
|
||||
|
||||
### 性能考虑
|
||||
- **零拷贝与高效克隆**: 广泛使用`Arc`（原子引用计数）来共享数据，避免了不必要的数据复制。`ProjectState`的设计确保了核心状态的高效克隆。
|
||||
- **异步非阻塞I/O**: 整个系统基于`tokio`异步运行时构建，所有I/O操作（文件读写、网络通信、进程管理）都是非阻塞的，能够高效处理大量并发连接。
|
||||
- **资源限制**: 通过`docker_config`中的`resource_limits`（如`memory_limit`, `cpu_limit`）对Docker容器施加资源限制，防止单个代理消耗过多系统资源，影响整体稳定性。
|
||||
- **连接池与复用**: 虽然未明确提及，但`reqwest`客户端等HTTP库通常会内部维护连接池，复用TCP连接，减少握手开销。
|
||||
- **批处理与合并**: `ProjectAndContainerInfo`的`update_extended_from_request`方法允许一次性批量更新多个字段，减少状态更新的次数。
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs)
|
||||
- [config.yml](file://config.yml#L144-L147)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L9-L11)
|
||||
|
||||
## 数据生命周期保留策略与归档规则
|
||||
RCoder项目的数据生命周期管理主要通过自动化和配置驱动的策略来实现，侧重于临时性和运行时数据的管理。
|
||||
|
||||
### 数据生命周期
|
||||
1. **创建 (Creation)**:
|
||||
- 当用户发起`ChatPrompt`请求时，系统检查`project_id`。
|
||||
- 如果该项目没有活跃的代理，则创建一个新的`ProjectAndAgentInfo`实例，启动`agent_runner`进程，并生成新的`session_id`。
|
||||
- 代理的生命周期由`AgentLifecycleGuard`管理，其创建标志着代理生命周期的开始。
|
||||
|
||||
2. **活跃 (Active)**:
|
||||
- 代理处于`Active`状态，通过`prompt_tx`接收用户提示，并通过`SessionNotify`发送状态更新。
|
||||
- `last_activity`字段在每次交互时被更新，用于判断代理的活跃度。
|
||||
|
||||
3. **终止 (Termination)**:
|
||||
- **正常终止**: 当代理完成任务或用户主动取消时，调用`AgentLifecycleGuard::graceful_stop`。该方法发送取消信号，等待任务退出，然后清理资源（终止子进程、关闭通道）。
|
||||
- **超时终止**: 配置文件中的`container_ttl_seconds`（默认3600秒）定义了容器的存活时间。后台任务会定期检查超过TTL的代理并自动终止。
|
||||
- **错误终止**: 如果代理进程崩溃或发生严重错误，`Drop`实现会确保资源被清理。
|
||||
|
||||
4. **销毁 (Destruction)**:
|
||||
- `AgentLifecycleGuard`被`drop`时，其`Drop`实现会执行最终的清理工作，确保子进程被杀死，通道被关闭。
|
||||
- `ProjectAndAgentInfo`记录从`DashMap`中被移除，相关内存被回收。
|
||||
|
||||
### 保留策略与归档规则
|
||||
- **临时性数据**: 会话（`Session`）和代理（`Agent`）实例被视为临时工作负载。它们的生命周期与用户的开发会话绑定，一旦任务完成或超时，就会被销毁。
|
||||
- **无长期归档**: 项目当前的设计中，没有明确的机制将聊天记录、生成的代码或会话日志归档到持久化存储（如数据库或文件系统）。所有数据在代理终止后即丢失。
|
||||
- **配置驱动的保留**: `container_ttl_seconds`是主要的保留策略配置，它强制性地保留了代理实例的最长时间。
|
||||
- **自动清理**: `docker_config.auto_cleanup`设置为`true`，表明系统会在代理终止后自动清理Docker容器，释放系统资源。
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L218-L249)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L348-L403)
|
||||
- [config.yml](file://config.yml#L160-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L173-L174)
|
||||
|
||||
## 数据迁移路径与版本管理
|
||||
RCoder项目的数据迁移和版本管理主要体现在配置文件和gRPC协议的演进上。
|
||||
|
||||
### 数据迁移路径
|
||||
- **配置文件迁移**: 从`config.yml`到`rcoder_default.yml`的演变，以及`multi_image_config`的引入，代表了系统配置的演进。迁移路径通常由代码中的默认值和向后兼容逻辑处理。例如，`create_legacy_multi_image_config`函数可以将旧的简单配置转换为新的多镜像配置格式。
|
||||
- **gRPC协议迁移**: `agent.proto`文件定义了服务间的通信协议。当需要添加新功能（如新的`ProgressEvent`类型）时，会通过添加新的字段或消息来实现，遵循gRPC的向后兼容原则（如使用`optional`关键字）。
|
||||
- **数据结构演进**: Rust结构体通过添加新字段（通常为`Option<T>`类型）来实现向后兼容。例如，`ChatPrompt`中的`data_source_attachments`是一个后来添加的字段，旧的客户端可以忽略它，而新的服务器可以安全地处理缺失的字段。
|
||||
|
||||
### 版本管理
|
||||
- **语义化版本控制**: 项目使用`Cargo.toml`进行依赖管理，遵循语义化版本控制（SemVer）。`crates/shared_types`等内部crate的版本号变化反映了API的稳定性。
|
||||
- **配置版本**: 配置文件本身没有明确的`version`字段，但其结构的变化（如`docker_config`的复杂化）隐式地代表了版本迭代。代码通过检查字段是否存在来处理不同版本的配置。
|
||||
- **gRPC服务版本**: `agent.proto`中的`package agent;`和`service AgentService`定义了服务的命名空间。未来可以通过创建新的`AgentServiceV2`服务来实现不兼容的API变更。
|
||||
- **环境变量映射**: `agent-abstraction-layer-design.md`中的JSON配置展示了如何通过模板（如`{MODEL_PROVIDER_API_KEY}`）将不同模型提供商的环境变量映射到代理的启动参数中，这是一种灵活的配置版本管理方式。
|
||||
|
||||
**本节来源**
|
||||
- [config.yml](file://config.yml)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L545-L610)
|
||||
336
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/聊天数据模型.md
Normal file
336
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/聊天数据模型.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 聊天数据模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [http_test.rest](file://http_test.rest)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件聚焦于聊天数据模型，系统性阐述 ChatPrompt 与 ChatResponse 的结构定义、提示词构造规则、上下文管理机制与附件处理方式；同时结合 chat_handler 的实现逻辑，完整描述从请求到响应的数据转换流程，并给出流式响应（SSE）的数据分块格式、进度更新机制与终止条件。最后提供 HTTP 请求/响应示例与边界情况、错误处理模式，帮助开发者快速理解并正确使用该系统。
|
||||
|
||||
## 项目结构
|
||||
围绕聊天数据模型的关键文件分布如下：
|
||||
- 共享类型层：定义 ChatPrompt、ChatResponse、附件与模型提供商配置等核心数据结构
|
||||
- 业务处理器层：chat_handler 负责接收请求、构建 ChatPrompt、调度代理并返回统一响应
|
||||
- 实时通知层：SSE 通道 agent_session_notification 将会话消息以事件形式推送给客户端
|
||||
- 会话缓存层：session_cache 提供会话级消息缓冲与推送，支持心跳、取消与清理
|
||||
- 代理服务层：根据模型提供商选择具体代理类型并启动 ACP 代理服务
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "共享类型层"
|
||||
A["ChatPrompt<br/>ChatResponse<br/>Attachment<br/>ModelProviderConfig"]
|
||||
end
|
||||
subgraph "业务处理器层"
|
||||
B["chat_handler.handle_chat"]
|
||||
end
|
||||
subgraph "代理服务层"
|
||||
C["agent_service.AcpAgentService"]
|
||||
end
|
||||
subgraph "实时通知层"
|
||||
D["agent_session_notification.SSE"]
|
||||
E["session_cache.SessionData<br/>SessionWorker"]
|
||||
end
|
||||
B --> A
|
||||
B --> C
|
||||
C --> E
|
||||
E --> D
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- ChatPrompt：承载一次聊天请求的全部上下文，包括项目ID、工作目录、会话ID、提示词、附件、数据源附件、代理类型、服务类型、请求ID与模型提供商配置
|
||||
- ChatResponse：统一的聊天响应载体，包含项目ID、会话ID、可选错误信息与请求ID
|
||||
- Attachment：多形态附件抽象，支持文本、图像、音频、文档，统一通过 AttachmentSource 表达数据来源（文件路径、Base64、URL）
|
||||
- ModelProviderConfig：模型提供商配置，决定代理类型与 API 协议
|
||||
- HttpResult：统一的 HTTP 响应包装，包含 code、message、data、tid 与 success 字段
|
||||
- AppError：应用级错误封装，统一映射为 HTTP 响应
|
||||
|
||||
章节来源
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L1-L132)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 架构总览
|
||||
下图展示从 HTTP 请求到 SSE 实时推送的整体流程，涵盖提示词构造、代理调度、会话管理与事件分发。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "chat_handler.handle_chat"
|
||||
participant Builder as "ChatPromptBuilder"
|
||||
participant Agent as "AcpAgentService"
|
||||
participant Worker as "LocalSetAgentRequest"
|
||||
participant Cache as "SessionData/SessionWorker"
|
||||
participant SSE as "agent_session_notification.SSE"
|
||||
Client->>Handler : POST /chat {prompt, attachments, ...}
|
||||
Handler->>Handler : 校验参数/生成project_id/request_id
|
||||
Handler->>Builder : 构建ChatPrompt
|
||||
Builder-->>Handler : ChatPrompt
|
||||
Handler->>Worker : 发送LocalSetAgentRequest
|
||||
Worker->>Agent : 启动代理服务并执行
|
||||
Agent->>Cache : 推送SessionNotify消息
|
||||
Cache-->>SSE : 通过mpsc通道分发消息
|
||||
SSE-->>Client : 事件流prompt_start/prompt_end/agent_message_chunk/heartbeat
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### ChatPrompt 与 ChatResponse 数据模型
|
||||
- ChatPrompt 字段要点
|
||||
- project_id：项目唯一标识，用于隔离工作空间
|
||||
- project_path：项目工作目录路径
|
||||
- session_id：会话标识，可选；若未提供则由代理自动创建并返回
|
||||
- prompt：用户提示词
|
||||
- attachments：附件列表，支持文本、图像、音频、文档
|
||||
- data_source_attachments：数据源附件（JSON 字符串数组），用于外部数据源信息传递
|
||||
- agent_type：代理类型（由模型提供商配置推导）
|
||||
- service_type：服务类型（固定为 RCoder）
|
||||
- request_id：请求追踪ID，可选
|
||||
- model_provider：模型提供商配置，决定代理与协议
|
||||
- ChatResponse 字段要点
|
||||
- project_id：项目ID
|
||||
- session_id：会话ID
|
||||
- error：可选错误信息
|
||||
- request_id：可选请求追踪ID
|
||||
|
||||
提示词构造规则
|
||||
- 若未提供 project_id，处理器会自动生成 UUID 并移除连字符，随后创建项目工作目录
|
||||
- 若未提供 session_id，处理器会清理该项目下的所有旧会话，确保全新开始
|
||||
- 若未提供 request_id，处理器会自动生成 UUID 并移除连字符
|
||||
- 代理类型由模型提供商配置推导，服务类型固定为 RCoder
|
||||
|
||||
附件处理方式
|
||||
- 附件通过统一的 Attachment 抽象表达，支持三种数据源：
|
||||
- FilePath：相对项目目录的文件路径
|
||||
- Base64：包含数据与 MIME 类型
|
||||
- Url：远程链接
|
||||
- 附件类型包括 Text、Image、Audio、Document，均包含可选的元数据（如文件名、尺寸、时长、大小）
|
||||
|
||||
章节来源
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L1-L132)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L198-L210)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L225-L258)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L266-L283)
|
||||
|
||||
### 上下文管理机制
|
||||
- 项目与会话映射
|
||||
- 通过 PROJECT_SESSION_MAP 确保同一 project_id 仅对应一个活跃 session_id
|
||||
- 当 session_id 变化时，自动清理旧 session 的数据并更新映射
|
||||
- 会话缓存与推送
|
||||
- SessionData 维护当前连接与取消令牌，支持即时推送与环形缓冲
|
||||
- SessionWorker 负责将消息写入环形缓冲并实时推送到当前连接
|
||||
- 心跳消息定期发送，保持连接活性
|
||||
- 会话清理策略
|
||||
- 处理器在收到请求时，若指定 session_id 则移除该会话；否则清理该项目下所有会话
|
||||
- 取消任务时，主动触发 CancellationToken 并关闭发送端，确保连接及时断开
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L224-L355)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L225-L258)
|
||||
|
||||
### 流式响应（SSE）数据分块格式与终止条件
|
||||
SSE 事件格式
|
||||
- 事件名称与消息类型映射
|
||||
- prompt_start：会话开始
|
||||
- prompt_end：会话结束（包含停止原因与可选错误信息）
|
||||
- agent_message_chunk：代理输出片段
|
||||
- user_message_chunk：用户输入片段
|
||||
- agent_thought_chunk：代理思考片段
|
||||
- tool_call/tool_call_update：工具调用与更新
|
||||
- plan/available_commands_update/current_mode_update：计划、可用命令与当前模式更新
|
||||
- heartbeat：心跳事件
|
||||
- 数据内容
|
||||
- 统一以 UnifiedSessionMessage 形式推送，包含 session_id、message_type、sub_type、data 与时间戳
|
||||
- data 内容根据子类型不同而异，例如 agent_message_chunk 的 data.content 包含文本内容与类型
|
||||
|
||||
进度更新机制
|
||||
- SSE 连接建立后立即发送 heartbeat，随后持续推送实时更新
|
||||
- 心跳定时器每 30 秒发送一次，用于维持连接活性
|
||||
- 当取消令牌被触发或发送端被关闭时，SSE 自然断开
|
||||
|
||||
终止条件
|
||||
- 会话结束事件（prompt_end）携带停止原因（如 EndTurn、MaxTokens、MaxTurnRequests、Refusal、Cancelled）
|
||||
- 取消任务时，主动关闭连接并清理旧消息
|
||||
- 容器连接失败或读取 SSE 流失败时，发送 error 事件并断开连接
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L36-L57)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L1-L180)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
|
||||
### 请求到响应的完整数据转换流程
|
||||
- 输入：HTTP 请求体包含 prompt、可选 project_id、session_id、attachments、data_source_attachments、model_provider、request_id
|
||||
- 处理：
|
||||
- 参数校验（prompt 非空）
|
||||
- 自动生成 project_id 与 request_id（如缺失）
|
||||
- 清理旧会话（按 session_id 或项目维度）
|
||||
- 构建 ChatPrompt 并发送到本地任务通道
|
||||
- 等待 ChatPromptResponse，若包含错误则返回统一错误响应
|
||||
- 输出：HttpResult<ChatResponse>，包含项目ID、会话ID与可选错误信息
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入 handle_chat"]) --> Validate["校验 prompt 非空"]
|
||||
Validate --> GenIds{"是否提供 project_id/request_id?"}
|
||||
GenIds --> |否| GenPid["生成 project_id 并创建工作目录"]
|
||||
GenIds --> |是| UseProvided["使用提供的 project_id/request_id"]
|
||||
GenPid --> CleanSessions["清理旧会话按 session_id 或项目"]
|
||||
UseProvided --> CleanSessions
|
||||
CleanSessions --> BuildPrompt["构建 ChatPrompt"]
|
||||
BuildPrompt --> SendTask["发送 LocalSetAgentRequest"]
|
||||
SendTask --> AwaitResp{"收到 ChatPromptResponse?"}
|
||||
AwaitResp --> |是且有错误| ReturnErr["返回统一错误响应"]
|
||||
AwaitResp --> |是且无错误| ReturnOk["返回 HttpResult.success(ChatResponse)"]
|
||||
AwaitResp --> |否| ReturnLocalErr["返回本地发送错误"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
### 代理类型与模型提供商配置
|
||||
- 代理类型选择
|
||||
- 根据模型提供商配置推导代理类型（Claude、Codex 等）
|
||||
- 通过 AcpAgentService trait 启动对应代理服务
|
||||
- 模型提供商配置
|
||||
- 包含 id、name、base_url、api_key、requires_openai_auth、default_model、api_protocol
|
||||
- api_protocol 默认 OpenAI，支持 Anthropic 与 OpenAI
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L1-L132)
|
||||
|
||||
## 依赖关系分析
|
||||
- 组件耦合与内聚
|
||||
- chat_handler 与 shared_types 的 ChatPrompt/ChatResponse 强耦合，但通过 Builder 模式降低复杂度
|
||||
- 代理服务通过 trait 解耦，便于扩展新代理类型
|
||||
- SSE 层通过 SessionData/SessionWorker 与处理器解耦，实现高内聚低耦合
|
||||
- 外部依赖
|
||||
- Axum 路由与响应封装
|
||||
- Tokio mpsc 通道用于异步消息传递
|
||||
- DashMap 用于全局会话缓存
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
chat_handler["chat_handler.handle_chat"] --> shared_types["shared_types.ChatPrompt/ChatResponse"]
|
||||
chat_handler --> agent_service["AcpAgentService"]
|
||||
agent_service --> session_cache["SessionData/SessionWorker"]
|
||||
session_cache --> agent_session_notification["SSE 事件推送"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 性能考量
|
||||
- 会话消息缓冲
|
||||
- 使用环形缓冲（ringbuf）提升消息吞吐，避免阻塞
|
||||
- 心跳消息不入环形缓冲，确保实时性
|
||||
- 连接管理
|
||||
- 通过 CancellationToken 主动关闭旧连接，避免资源泄漏
|
||||
- 即时推送失败时自动降级为丢弃，保证系统稳定性
|
||||
- 并发控制
|
||||
- 项目级并发限制：同一项目仅允许一个活跃代理任务
|
||||
- 会话级清理：确保新会话不会混入旧消息
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L140-L222)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L224)
|
||||
|
||||
## 故障排查指南
|
||||
常见错误与处理
|
||||
- 参数校验失败
|
||||
- prompt 为空：返回统一错误响应
|
||||
- 并发请求限制
|
||||
- 项目存在活跃代理任务：返回“Agent正在执行任务，请等待当前任务完成后再发送新请求”
|
||||
- 本地发送错误
|
||||
- 任务通道发送失败：返回本地发送错误
|
||||
- SSE 连接问题
|
||||
- 容器连接失败或读取流失败：发送 error 事件并断开连接
|
||||
- 未找到对应容器：返回“未找到 session_id 对应的活跃容器”
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L137-L168)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L224)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L135-L153)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L231-L244)
|
||||
|
||||
## 结论
|
||||
本文系统梳理了聊天数据模型的核心结构与处理流程，明确了提示词构造规则、上下文管理机制与附件处理方式，并深入解析了 SSE 的事件格式、进度更新与终止条件。结合 chat_handler 的实现逻辑，读者可以准确把握从请求到响应的全链路数据转换过程，并据此编写正确的 HTTP 请求与客户端消费逻辑。
|
||||
|
||||
## 附录
|
||||
|
||||
### HTTP 请求/响应示例
|
||||
- 创建聊天会话（POST /chat）
|
||||
- 请求体字段：prompt、project_id（可选）、session_id（可选）、attachments（可选）、data_source_attachments（可选）、model_provider（可选）、request_id（可选）
|
||||
- 成功响应：HttpResult.success(ChatResponse)，包含 project_id、session_id、request_id
|
||||
- 错误响应：HttpResult.error(code, message)
|
||||
- 建立 SSE 连接（GET /agent/progress/{session_id}）
|
||||
- 事件类型：prompt_start、prompt_end、agent_message_chunk、user_message_chunk、agent_thought_chunk、tool_call、tool_call_update、plan、available_commands_update、current_mode_update、heartbeat
|
||||
- 断开条件：取消令牌触发、发送端关闭、容器连接失败
|
||||
- 取消会话（POST /agent/session/cancel）
|
||||
- 参数：project_id、session_id
|
||||
- 行为：主动关闭 SSE 连接并清理旧消息
|
||||
|
||||
章节来源
|
||||
- [http_test.rest](file://http_test.rest#L1-L109)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L102-L173)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
413
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/附件模型.md
Normal file
413
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/附件模型.md
Normal file
@@ -0,0 +1,413 @@
|
||||
# 附件模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [lib.rs（shared_types）](file://crates/shared_types/src/lib.rs)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件系统化阐述附件模型的设计与用途，覆盖以下方面：
|
||||
- Attachment 结构体族的组成与职责边界
|
||||
- 文件元数据（路径、大小、MIME 类型）的存储方式与来源
|
||||
- 附件在聊天上下文中的引用机制、与提示词构造的关系
|
||||
- 安全检查策略（文件扩展名、大小限制、来源类型）
|
||||
- 资源清理流程（临时文件、会话与代理资源）
|
||||
- 实际用例：附件如何参与 AI 代理交互并影响提示词构造
|
||||
|
||||
## 项目结构
|
||||
附件模型位于共享类型模块中，围绕该模型构建了聊天提示、内容转换、文件工具与代理交互链路。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "共享类型"
|
||||
A["attachment.rs<br/>定义 Attachment/AttachmentSource 及错误"]
|
||||
B["chat_prompt.rs<br/>ChatPrompt 含 attachments 字段"]
|
||||
C["chat_response.rs<br/>通用聊天响应结构"]
|
||||
D["agent.proto<br/>gRPC ChatRequest 含 attachments 字段"]
|
||||
end
|
||||
subgraph "代理运行时"
|
||||
E["content_builder.rs<br/>将 Attachment 转为 ContentBlock"]
|
||||
F["file_utils.rs<br/>文件校验/读取/创建附件"]
|
||||
G["acp_agent.rs<br/>构建 Prompt 并发送给代理"]
|
||||
H["chat_handler.rsrcoder<br/>接收请求并转发"]
|
||||
I["chat_handler.rsagent_runner<br/>接收请求并构建 ChatPrompt"]
|
||||
end
|
||||
A --> B
|
||||
B --> G
|
||||
E --> G
|
||||
F --> E
|
||||
H --> I
|
||||
I --> G
|
||||
D --> H
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs#L1-L18)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
章节来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
## 核心组件
|
||||
- 附件数据源类型：支持文件路径、Base64、URL 三种来源，统一通过枚举承载
|
||||
- 附件类型：文本、图像、音频、文档四类，均包含 id、source、可选元数据（如 filename、description、size、mime_type、dimensions、duration）
|
||||
- 附件错误：集中定义文件读取、类型不支持、Base64 解码、大小超限、URL 访问等错误
|
||||
- 聊天提示：ChatPrompt 携带 attachments 与 data_source_attachments，驱动代理侧提示词构建
|
||||
- 内容构建：将附件转换为 ACP ContentBlock，支撑多模态提示词
|
||||
- 文件工具：校验扩展名、大小限制、读取与创建附件、清理临时文件
|
||||
- 代理交互：构建 PromptRequest，将附件内容块注入提示词，并携带 request_id 等元信息
|
||||
|
||||
章节来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
|
||||
## 架构总览
|
||||
附件在系统中的流转路径如下：
|
||||
- 客户端/上游服务通过 gRPC/HTTP 请求携带附件
|
||||
- 服务端解析请求，构建 ChatPrompt（含 attachments 与 data_source_attachments）
|
||||
- 代理侧将附件转换为 ContentBlock，拼接到提示词中
|
||||
- 代理执行推理，返回结果；同时进行资源清理
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "聊天处理器"
|
||||
participant Prompt as "ChatPrompt"
|
||||
participant Builder as "ContentBuilder"
|
||||
participant Agent as "代理ACPI"
|
||||
participant Resp as "响应"
|
||||
Client->>Handler : "提交聊天请求含附件"
|
||||
Handler->>Prompt : "构建 ChatPrompt包含 attachments"
|
||||
Prompt->>Builder : "将附件转换为 ContentBlock"
|
||||
Builder-->>Prompt : "返回内容块列表"
|
||||
Prompt->>Agent : "构建 PromptRequest含附件内容块"
|
||||
Agent-->>Resp : "返回聊天响应"
|
||||
Resp-->>Client : "返回结果"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 附件数据模型与元数据
|
||||
- 数据源类型
|
||||
- 文件路径：相对项目路径，便于在工作区定位
|
||||
- Base64：携带数据与 MIME 类型，适合内联传输
|
||||
- URL：远程资源，需网络访问
|
||||
- 附件类型与元数据
|
||||
- 文本附件：id、source、filename、description
|
||||
- 图像附件：id、source、mime_type、filename、description、dimensions
|
||||
- 音频附件：id、source、mime_type、filename、description、duration
|
||||
- 文档附件：id、source、mime_type、filename、description、size
|
||||
- 元数据来源
|
||||
- MIME 类型：由创建时指定或从扩展名推断
|
||||
- 大小：文档附件可选 size 字段
|
||||
- 尺寸/时长：图像/音频附件可选 dimensions/duration
|
||||
- 访问与查询
|
||||
- 提供 id()、mime_type()、source() 等便捷方法
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AttachmentSource {
|
||||
<<enum>>
|
||||
+FilePath(path)
|
||||
+Base64(data,mime_type)
|
||||
+Url(url)
|
||||
}
|
||||
class TextAttachment {
|
||||
+string id
|
||||
+AttachmentSource source
|
||||
+string? filename
|
||||
+string? description
|
||||
}
|
||||
class ImageAttachment {
|
||||
+string id
|
||||
+AttachmentSource source
|
||||
+string mime_type
|
||||
+string? filename
|
||||
+string? description
|
||||
+ImageDimensions? dimensions
|
||||
}
|
||||
class AudioAttachment {
|
||||
+string id
|
||||
+AttachmentSource source
|
||||
+string mime_type
|
||||
+string? filename
|
||||
+string? description
|
||||
+f64? duration
|
||||
}
|
||||
class DocumentAttachment {
|
||||
+string id
|
||||
+AttachmentSource source
|
||||
+string mime_type
|
||||
+string? filename
|
||||
+string? description
|
||||
+u64? size
|
||||
}
|
||||
class Attachment {
|
||||
<<enum>>
|
||||
+Text(TextAttachment)
|
||||
+Image(ImageAttachment)
|
||||
+Audio(AudioAttachment)
|
||||
+Document(DocumentAttachment)
|
||||
+id() &str
|
||||
+mime_type() &str?
|
||||
+source() &AttachmentSource
|
||||
}
|
||||
Attachment --> AttachmentSource : "包含"
|
||||
Attachment --> TextAttachment : "分支"
|
||||
Attachment --> ImageAttachment : "分支"
|
||||
Attachment --> AudioAttachment : "分支"
|
||||
Attachment --> DocumentAttachment : "分支"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
|
||||
章节来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
|
||||
### 文件元数据存储与验证规则
|
||||
- 存储方式
|
||||
- MIME 类型：显式传入或通过扩展名推断
|
||||
- 大小：文档附件可选 size 字段；文件工具在读取时校验大小
|
||||
- 尺寸/时长：图像/音频附件可选 dimensions/duration 字段
|
||||
- 验证规则
|
||||
- 扩展名白名单：仅允许预设扩展名集合
|
||||
- 文件大小上限：默认 50MB，可通过配置调整
|
||||
- 来源类型约束：
|
||||
- 文本附件：禁止压缩文件作为文本附件
|
||||
- 图像/音频/文档：按来源类型分别读取或下载
|
||||
- 错误类型
|
||||
- 文件读取失败、不支持的文件类型、Base64 解码失败、文件大小超限、URL 访问失败
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Ext["校验扩展名"]
|
||||
Ext --> ExtOK{"扩展名合法？"}
|
||||
ExtOK -- 否 --> ErrExt["返回不支持的文件类型错误"]
|
||||
ExtOK -- 是 --> Size["校验文件大小"]
|
||||
Size --> SizeOK{"未超限？"}
|
||||
SizeOK -- 否 --> ErrSize["返回文件大小超限错误"]
|
||||
SizeOK -- 是 --> Read["按来源类型读取/解码"]
|
||||
Read --> Done(["结束"])
|
||||
ErrExt --> Done
|
||||
ErrSize --> Done
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L184-L216)
|
||||
|
||||
章节来源
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L184-L216)
|
||||
|
||||
### 附件在聊天上下文中的引用机制
|
||||
- 请求结构
|
||||
- rcoder 与 agent_runner 的聊天处理器均支持 attachments 字段
|
||||
- ChatPromptBuilder 用于组装 ChatPrompt，包含 attachments 与 data_source_attachments
|
||||
- 引用与传递
|
||||
- ChatRequest/ChatPrompt 持有附件列表
|
||||
- gRPC ChatRequest 也包含 attachments 字段，便于跨服务传递
|
||||
- 会话与请求追踪
|
||||
- request_id 可选，若未提供则自动生成
|
||||
- 构建 PromptRequest 时将 request_id 放入 meta，便于后续追踪
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder 聊天处理器"
|
||||
participant AR as "agent_runner 聊天处理器"
|
||||
participant CP as "ChatPromptBuilder"
|
||||
participant PR as "PromptRequest"
|
||||
RC->>AR : "转发聊天请求含 attachments"
|
||||
AR->>CP : "构建 ChatPromptproject_id/session_id/prompt/attachments"
|
||||
CP-->>AR : "返回 ChatPrompt"
|
||||
AR->>PR : "构建 PromptRequest附加附件内容块"
|
||||
PR-->>AR : "返回 PromptRequest"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
### 安全检查策略
|
||||
- 文件扩展名校验：仅允许白名单扩展名，避免恶意文件
|
||||
- 文件大小限制：防止过大附件导致内存压力与网络开销
|
||||
- 来源类型安全：
|
||||
- 文本附件禁止压缩文件
|
||||
- URL 读取采用网络客户端，失败即忽略并记录告警
|
||||
- 附件转换容错：读取失败或网络异常时静默忽略，不影响主流程
|
||||
|
||||
章节来源
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
|
||||
### 资源清理流程
|
||||
- 临时文件清理：文件工具提供批量清理临时文件的能力
|
||||
- 代理与会话资源：代理侧通过生命周期守卫与连接池管理，结合定时清理任务，确保代理进程、会话与 SSE 消息得到回收
|
||||
- 清理策略要点：
|
||||
- 基于 RAII 的自动清理：移除映射后由生命周期守卫触发资源回收
|
||||
- 超时保护：清理过程设置超时，避免阻塞
|
||||
- 统计与日志：记录清理统计，便于运维监控
|
||||
|
||||
章节来源
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L312-L322)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
|
||||
### 附件与 AI 代理交互及提示词构造
|
||||
- 附件到内容块的转换
|
||||
- 文本：优先按文本读取，失败则忽略
|
||||
- 图像/音频：按来源读取为 Base64，附带 URI
|
||||
- 文档：按 MIME 类型区分文本/二进制，文本走 TextResourceContents，二进制走 BlobResourceContents，URL 走 ResourceLink
|
||||
- 提示词构造
|
||||
- 将最终提示词与附件内容块合并为 ContentBlocks
|
||||
- 若存在 data_source_attachments，则在构建时加入数据源信息
|
||||
- 将 request_id 放入 meta，便于通道层追踪
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
P["ChatPrompt.attachments"] --> CB["ContentBuilder.attachments_to_content_blocks"]
|
||||
CB --> Blocks{"每种附件类型？"}
|
||||
Blocks --> |文本| T["TextContent"]
|
||||
Blocks --> |图像| I["ImageContent(Base64)"]
|
||||
Blocks --> |音频| A["AudioContent(Base64)"]
|
||||
Blocks --> |文档| D{"MIME 类型为 text/* ?"}
|
||||
D --> |是| DT["TextResourceContents"]
|
||||
D --> |否| DB["BlobResourceContents"]
|
||||
T --> Merge["合并为 ContentBlocks"]
|
||||
I --> Merge
|
||||
A --> Merge
|
||||
DT --> Merge
|
||||
DB --> Merge
|
||||
Merge --> PR["PromptRequest含附件内容块"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
|
||||
章节来源
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
|
||||
## 依赖分析
|
||||
- 低耦合高内聚
|
||||
- shared_types 的附件模型独立于具体实现，便于跨服务复用
|
||||
- 代理侧通过 ContentBuilder 与 file_utils 解耦附件读取与转换
|
||||
- 关键依赖关系
|
||||
- ChatPrompt 依赖 Attachment/AttachmentSource
|
||||
- ContentBuilder 依赖 agent_client_protocol 的 ContentBlock 类型
|
||||
- file_utils 依赖 base64、tokio fs、reqwest
|
||||
- 聊天处理器依赖 ChatPromptBuilder 与模型提供商配置
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Shared["shared_types: attachment.rs"] --> Prompt["chat_prompt.rs"]
|
||||
Prompt --> Builder["content_builder.rs"]
|
||||
Builder --> Utils["file_utils.rs"]
|
||||
HandlerR["chat_handler.rsrcoder"] --> HandlerA["chat_handler.rsagent_runner"]
|
||||
HandlerA --> Prompt
|
||||
Proto["agent.proto"] --> HandlerR
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
章节来源
|
||||
- [lib.rs（shared_types）](file://crates/shared_types/src/lib.rs#L1-L71)
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L1-L216)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs#L1-L52)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [chat_handler.rs（rcoder）](file://crates/rcoder/src/handler/chat_handler.rs#L17-L53)
|
||||
- [chat_handler.rs（agent_runner）](file://crates/agent_runner/src/handler/chat_handler.rs#L1-L275)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L43)
|
||||
|
||||
## 性能考虑
|
||||
- 附件读取与转换
|
||||
- 优先使用 Base64 内联传输，减少磁盘 IO；对大文件建议使用 URL 或文件路径
|
||||
- 文档附件优先按文本读取，失败再降级为二进制，避免不必要的解码
|
||||
- 网络访问
|
||||
- URL 读取采用异步客户端，失败即短路，避免阻塞
|
||||
- 大小限制
|
||||
- 默认 50MB 上限，可根据部署环境调优，平衡吞吐与稳定性
|
||||
- 清理与回收
|
||||
- 定时清理代理与会话资源，避免长期运行导致资源泄漏
|
||||
|
||||
## 故障排查指南
|
||||
- 常见错误与定位
|
||||
- 文件读取失败：检查路径是否存在、权限是否足够
|
||||
- 不支持的文件类型：确认扩展名在白名单中
|
||||
- Base64 解码失败：确认数据格式正确且未被截断
|
||||
- 文件大小超限：调整上传策略或增大阈值
|
||||
- URL 访问失败：检查网络连通性与目标可达性
|
||||
- 日志与追踪
|
||||
- 附件转换失败会记录告警日志，建议结合 request_id 追踪
|
||||
- 清理任务输出统计信息，便于发现异常增长
|
||||
|
||||
章节来源
|
||||
- [attachment.rs](file://crates/shared_types/src/model/attachment.rs#L184-L216)
|
||||
- [file_utils.rs](file://crates/agent_runner/src/utils/file_utils.rs#L1-L339)
|
||||
- [content_builder.rs](file://crates/agent_runner/src/utils/content_builder.rs#L1-L418)
|
||||
|
||||
## 结论
|
||||
附件模型通过统一的数据源与类型抽象，为多模态聊天提供了清晰的扩展点。配合严格的验证规则与容错转换，既保证了安全性，又提升了可用性。在代理交互层面，附件被无缝注入提示词，显著增强了 AI 的上下文理解能力。建议在生产环境中合理设置大小阈值与扩展名白名单，并持续监控清理任务与日志，确保系统稳定高效运行。
|
||||
328
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/项目状态模型.md
Normal file
328
qiming-rcoder/.qoder/repowiki/zh/content/数据模型与类型/项目状态模型.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# 项目状态模型
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件围绕“项目状态模型”展开，重点解析 ProjectCoreState、ProjectExtendedState、ProjectState 以及 ProjectAndAgentInfo 等核心状态结构，阐明其字段语义、变更触发条件与同步机制；结合 agent_runner 与 rcoder 模块的实际用例，说明状态在 AI 代理生命周期中的流转；提供状态图示例与典型场景下的数据快照；解释线程安全处理方式（如 Arc、DashMap、Arc::make_mut、CancellationToken 等）与并发访问模式，并给出一致性保障措施。
|
||||
|
||||
## 项目结构
|
||||
本仓库采用多 crate 分层组织，其中与“项目状态模型”直接相关的模块包括：
|
||||
- shared_types：跨模块共享的模型定义，包含 ProjectCoreState、ProjectExtendedState、ProjectState、ProjectAndAgentInfo、AgentStatus 等。
|
||||
- agent_runner：会话缓存与消息推送，涉及 session_id 与 Project 的映射管理。
|
||||
- rcoder：代理容器化启动、状态清理与生命周期管理，涉及 Docker 容器生命周期与状态清理。
|
||||
- specs：抽象层设计文档，描述 AgentStatus 的状态机与生命周期管理。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "共享类型"
|
||||
A["ProjectCoreState<br/>ProjectExtendedState<br/>ProjectState<br/>ProjectAndAgentInfo<br/>AgentStatus"]
|
||||
end
|
||||
subgraph "agent_runner"
|
||||
B["SessionData<br/>SESSION_CACHE<br/>PROJECT_SESSION_MAP"]
|
||||
C["push_session_update<br/>ensure_project_session"]
|
||||
end
|
||||
subgraph "rcoder"
|
||||
D["Docker 容器代理启动<br/>start_docker_container_agent_service"]
|
||||
E["清理任务<br/>cleanup_task"]
|
||||
F["聊天处理器<br/>chat_handler"]
|
||||
end
|
||||
A --> B
|
||||
B --> C
|
||||
D --> E
|
||||
F --> A
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L130)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
|
||||
章节来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L130)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
|
||||
## 核心组件
|
||||
本节聚焦“项目状态模型”的核心结构及其职责边界。
|
||||
|
||||
- ProjectCoreState
|
||||
- 字段语义：project_id（项目唯一标识）、session_id（会话标识，可选）、last_activity（最后活动时间）、created_at（创建时间）。
|
||||
- 变更触发：update_session 在创建会话时设置 session_id 并刷新 last_activity；update_activity 仅刷新 last_activity。
|
||||
- 访问模式：高频读写，适合通过 Arc 共享与写时复制更新。
|
||||
|
||||
- ProjectExtendedState
|
||||
- 字段语义：model_provider（模型提供商配置，可选）、container（容器信息，可选）、request_id（当前活跃请求ID，可选）、status（Agent 服务状态，可选）。
|
||||
- 变更触发：update_from_request 批量更新容器、模型提供商与请求ID；也可通过可变访问器逐项更新。
|
||||
- 访问模式：相对稳定的扩展字段，适合 Arc 共享与写时复制更新。
|
||||
|
||||
- ProjectState
|
||||
- 设计要点：将 core 与 extended 分离，分别使用 Arc 共享，提供 update_core/update_extended 方法，内部通过 Arc::make_mut 实现写时复制，避免不必要的深拷贝。
|
||||
- 便捷访问器：project_id、session_id、last_activity。
|
||||
|
||||
- ProjectAndAgentInfo
|
||||
- 字段语义：在共享类型中提供向后兼容的结构，内部持有 ProjectState，暴露与 ProjectState 对应的更新与访问方法。
|
||||
- 变更触发：update_session、update_activity、set_* 系列方法触发状态更新。
|
||||
|
||||
- AgentStatus
|
||||
- 枚举值：Active（活跃）、Idle（空闲）、Terminating（正在终止）。
|
||||
- 用途：表示 Agent 服务的运行状态，配合 last_activity、request_id 等字段共同反映代理生命周期。
|
||||
|
||||
章节来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L41)
|
||||
|
||||
## 架构总览
|
||||
下图展示“项目状态模型”在 rcoder 与 agent_runner 之间的交互，以及状态在代理生命周期中的流转。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant RC as "rcoder 聊天处理器(chat_handler)"
|
||||
participant PS as "ProjectAndAgentInfo(ProjectState)"
|
||||
participant AR as "agent_runner 会话缓存(session_cache)"
|
||||
participant DC as "Docker 容器代理(docker_container_agent)"
|
||||
Client->>RC : "发起聊天/会话请求"
|
||||
RC->>PS : "update_session(session_id)"
|
||||
RC->>PS : "update_activity()"
|
||||
RC->>AR : "push_session_update_with_project(project_id, session_id, notify)"
|
||||
AR->>AR : "ensure_project_session(project_id, session_id)"
|
||||
AR-->>RC : "推送消息到 SessionData"
|
||||
RC->>DC : "启动容器化 Agent 服务(若需要)"
|
||||
DC-->>RC : "返回容器信息与服务URL"
|
||||
RC-->>Client : "返回会话状态与服务信息"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L259-L355)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L130)
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L170-L202)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### ProjectCoreState 与 ProjectExtendedState 的字段语义与更新流程
|
||||
- 字段语义
|
||||
- project_id：项目唯一标识，贯穿整个生命周期。
|
||||
- session_id：会话标识，首次创建会话时设置，用于区分不同会话。
|
||||
- last_activity：最近一次活动时间，用于空闲检测与清理策略。
|
||||
- created_at：创建时间，用于统计与审计。
|
||||
- model_provider/container/request_id/status：扩展状态，承载容器、模型提供商、请求ID与服务状态等信息。
|
||||
|
||||
- 更新流程
|
||||
- update_session：设置 session_id 并刷新 last_activity。
|
||||
- update_activity：仅刷新 last_activity。
|
||||
- update_from_request：批量更新容器、模型提供商与请求ID。
|
||||
|
||||
- 写时复制更新
|
||||
- ProjectState.update_core/update_extended 内部使用 Arc::make_mut，在需要修改时才触发写时复制，避免不必要的深拷贝。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入更新流程"]) --> CheckCore["是否更新核心状态?"]
|
||||
CheckCore --> |是| MakeMutCore["Arc::make_mut(core)"]
|
||||
MakeMutCore --> ApplyCore["应用更新: update_session/update_activity"]
|
||||
CheckCore --> |否| CheckExtended["是否更新扩展状态?"]
|
||||
CheckExtended --> |是| MakeMutExtended["Arc::make_mut(extended)"]
|
||||
MakeMutExtended --> ApplyExtended["应用更新: update_from_request/set_*"]
|
||||
CheckExtended --> |否| End(["结束"])
|
||||
ApplyCore --> End
|
||||
ApplyExtended --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L117-L159)
|
||||
|
||||
章节来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
|
||||
### 会话映射与消息推送（agent_runner）
|
||||
- SESSION_CACHE：按 session_id 分组缓存会话消息，使用环形缓冲区与实时推送相结合的方式，减少内存占用并保证消息及时送达。
|
||||
- PROJECT_SESSION_MAP：确保一个 project_id 只对应一个活跃的 session_id。当 session_id 变化时，自动清理旧 session 的缓存数据。
|
||||
- push_session_update/push_session_update_with_project：将通知转换为统一消息并推送到 SessionData；ensure_project_session 负责维护映射关系与清理旧数据。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant AR as "agent_runner"
|
||||
participant PC as "PROJECT_SESSION_MAP"
|
||||
participant SC as "SESSION_CACHE"
|
||||
participant SD as "SessionData"
|
||||
AR->>PC : "ensure_project_session(project_id, session_id)"
|
||||
alt session_id 变化
|
||||
PC-->>SC : "移除旧 session_id 对应的缓存"
|
||||
end
|
||||
AR->>SC : "push_session_update(session_id, notify)"
|
||||
SC->>SD : "实时推送消息"
|
||||
SD-->>AR : "推送完成"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L259-L355)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L259-L355)
|
||||
|
||||
### rcoder 中的状态更新与生命周期清理
|
||||
- 聊天处理器（chat_handler）
|
||||
- 在收到请求时，检查并更新项目会话状态：若 session_id 不同则更新会话并刷新 last_activity；若相同则仅更新活动时间。
|
||||
- 使用 Arc::make_mut 与写时复制更新，避免不必要的深拷贝。
|
||||
|
||||
- 清理任务（cleanup_task）
|
||||
- 通过 DashMap 的 Entry API 原子性地移除项目到代理的映射，触发 AgentLifecycleGuard 的 Drop，从而自动清理资源。
|
||||
- 清理顺序：销毁 Docker 容器 -> 原子性移除项目映射 -> 原子性清理 sessions 映射 -> 输出清理完成日志。
|
||||
- 超时保护：清理过程整体超时控制，防止阻塞。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RT as "清理任务(cleanup_task)"
|
||||
participant PM as "PROJECT_AND_AGENT_INFO_MAP"
|
||||
participant SM as "sessions 映射"
|
||||
participant DM as "DockerManager"
|
||||
RT->>DM : "destroy_docker_container(project_id)"
|
||||
DM-->>RT : "容器销毁完成"
|
||||
RT->>PM : "原子性移除项目映射"
|
||||
PM-->>RT : "返回 session_id"
|
||||
RT->>SM : "原子性清理 sessions 映射(session_id)"
|
||||
SM-->>RT : "清理完成"
|
||||
RT-->>RT : "输出清理完成日志"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L733-L785)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L733-L785)
|
||||
|
||||
### AgentStatus 状态机与生命周期
|
||||
- AgentStatus 枚举：Active、Idle、Terminating。
|
||||
- 状态切换时机（基于现有实现抽象）：
|
||||
- Active：收到 Prompt 请求时。
|
||||
- Idle：Prompt 处理完成或被取消时。
|
||||
- Terminating：Agent 停止过程中。
|
||||
- AgentLifecycleGuard：遵循 RAII 原则，当守卫被 drop 时自动清理资源；提供 graceful_stop、cancel、is_stopped、cancellation_token 等接口。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Active : "收到 Prompt 请求"
|
||||
Active --> Idle : "任务完成/取消"
|
||||
Active --> Terminating : "停止中"
|
||||
Terminating --> [*]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L41)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1157-L1225)
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L32-L41)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1157-L1225)
|
||||
|
||||
### 线程安全与并发访问模式
|
||||
- Arc 共享与写时复制
|
||||
- ProjectState 将 core 与 extended 分离，分别使用 Arc 共享，通过 Arc::make_mut 在需要修改时才触发写时复制，降低锁竞争与内存拷贝成本。
|
||||
- DashMap 原子性操作
|
||||
- cleanup_task 使用 DashMap::entry API 原子性地移除映射，避免读写锁竞争，确保清理过程的一致性。
|
||||
- CancellationToken
|
||||
- AgentLifecycleGuard 使用 CancellationToken 实现非阻塞取消，优雅停止时先 cancel 再强制清理，保证资源释放与一致性。
|
||||
- 会话连接管理
|
||||
- SessionData 直接共享当前连接与取消令牌，避免命令传递带来的额外开销；close_current_connection 主动触发取消令牌并显式关闭发送端，确保接收端能及时感知连接关闭。
|
||||
|
||||
章节来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L117-L159)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L661-L704)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L218-L338)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
|
||||
## 依赖关系分析
|
||||
- ProjectState 依赖于 chrono 时间类型与 serde 序列化能力，用于时间戳与持久化。
|
||||
- ProjectAndAgentInfo 依赖于 shared_types 中的 AgentStatus、ModelProviderConfig 等类型，用于承载代理状态与模型配置。
|
||||
- agent_runner 的 session_cache 依赖 DashMap、ringbuf、tokio channels 等并发与缓冲机制。
|
||||
- rcoder 的清理任务依赖 DockerManager、DashMap、Tokio 定时器与超时控制。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Shared["shared_types 模型"] --> Runner["agent_runner 会话缓存"]
|
||||
Shared --> RC["rcoder 聊天处理器"]
|
||||
Runner --> RC
|
||||
RC --> Docker["DockerManager"]
|
||||
RC --> Cleaner["清理任务"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L130)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
|
||||
章节来源
|
||||
- [agent_project_runner_model.rs](file://crates/shared_types/src/model/agent_project_runner_model.rs#L30-L189)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L120)
|
||||
- [chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L245-L270)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L130)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L650-L720)
|
||||
|
||||
## 性能考量
|
||||
- 写时复制（Arc::make_mut）：在频繁读取、偶发更新的场景下显著降低锁竞争与内存拷贝成本。
|
||||
- 会话缓存优化：RingBuffer 缓冲与实时推送结合，既能保证消息及时性，又能控制内存占用。
|
||||
- 原子性操作：DashMap::entry API 在清理映射时避免读写锁竞争，提升清理吞吐。
|
||||
- 取消令牌：CancellationToken 非阻塞取消，配合优雅停止流程，减少资源泄漏与阻塞风险。
|
||||
- 端口与网络优化：容器内部网络通信，避免宿主机端口映射与释放带来的额外开销。
|
||||
|
||||
## 故障排查指南
|
||||
- 会话映射异常
|
||||
- 现象：同一 project_id 出现多个活跃 session。
|
||||
- 排查：确认 ensure_project_session 是否正确清理旧 session；检查 PROJECT_SESSION_MAP 的原子性插入与移除。
|
||||
- 参考路径：[session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L282-L355)
|
||||
|
||||
- 清理任务超时或阻塞
|
||||
- 现象：清理任务超时或长时间不结束。
|
||||
- 排查：检查 destroy_docker_container 是否成功；确认清理流程中的超时保护与日志输出。
|
||||
- 参考路径：[cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L836)
|
||||
|
||||
- 代理资源未释放
|
||||
- 现象：Agent 停止后仍占用资源。
|
||||
- 排查：确认 AgentLifecycleGuard 的 Drop 是否触发；检查 cancellation_token 是否正确 cancel。
|
||||
- 参考路径：[agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L340-L404)
|
||||
|
||||
- 会话连接无法断开
|
||||
- 现象：SSE 连接长时间不关闭。
|
||||
- 排查：确认 close_current_connection 是否被调用；检查 CancellationToken 与发送端的显式关闭。
|
||||
- 参考路径：[session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L115-L140)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L282-L355)
|
||||
- [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L836)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L340-L404)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L115-L140)
|
||||
|
||||
## 结论
|
||||
本项目通过 ProjectCoreState/ProjectExtendedState/ProjectState 的分层设计，结合 Arc 共享与写时复制，实现了高性能、低锁争用的状态管理；借助 DashMap 原子性操作与 CancellationToken，确保在高并发场景下的一致性与可靠性。agent_runner 的会话缓存与 rcoder 的清理任务共同构成了完整的生命周期管理闭环，覆盖从会话创建、消息推送、状态更新到资源清理的全链路。建议在新增状态字段时，遵循“核心小字段高频更新、扩展大字段低频更新”的设计原则，并优先使用写时复制与原子性操作，以获得最佳的性能与一致性表现。
|
||||
@@ -0,0 +1,279 @@
|
||||
# HTTP API架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [proxy_handler_api.rs](file://crates/agent_runner/src/handler/proxy_handler_api.rs)
|
||||
- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
RCoder AI服务API是一个基于ACP（Agent Client Protocol）的AI驱动开发平台，提供完整的AI代理集成解决方案。该系统采用Rust语言构建，基于Axum框架实现高性能HTTP API服务，通过Server-Sent Events（SSE）协议提供实时通信能力。系统支持多种AI代理类型（Codex、Claude、Proxy），并集成了基于Cloudflare Pingora的高性能反向代理服务。API设计遵循RESTful原则，提供清晰的端点划分和完整的OpenAPI文档支持。
|
||||
|
||||
## 项目结构
|
||||
系统采用Rust工作区（workspace）结构，核心功能模块化组织。HTTP API服务主要由`agent_runner` crate实现，该模块负责处理所有HTTP请求、路由分发和状态管理。系统通过清晰的目录结构分离关注点，包括处理器（handler）、中间件（middleware）、代理代理（proxy_agent）、服务（service）和工具（utils）等模块。这种结构化设计提高了代码的可维护性和可扩展性，同时便于团队协作开发。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "crates"
|
||||
subgraph "agent_runner"
|
||||
H[handler]
|
||||
M[middleware]
|
||||
PA[proxy_agent]
|
||||
S[service]
|
||||
U[utils]
|
||||
R[router]
|
||||
C[config]
|
||||
end
|
||||
subgraph "shared_types"
|
||||
ST[共享类型定义]
|
||||
end
|
||||
subgraph "pingora-proxy"
|
||||
PP[Pingora代理服务]
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
|
||||
**章节来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
|
||||
## 核心组件
|
||||
系统的核心组件包括基于Axum框架的HTTP服务器、基于DashMap的会话状态管理、基于MPMC通道的异步任务处理机制，以及集成的OpenTelemetry遥测系统。`AppState`结构体作为全局应用状态，封装了会话映射、配置信息、任务发送器和Pingora服务引用等关键数据。系统通过`LocalSet`在独立线程中运行非Send的代理工作器，确保了不同类型代理的兼容性。OpenAPI文档通过utoipa自动生成，提供完整的API描述和交互式Swagger UI界面。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 架构概述
|
||||
系统采用分层架构设计，从下到上分别为基础设施层、服务层、应用层和接口层。基础设施层提供日志、遥测和配置管理；服务层封装核心业务逻辑；应用层处理HTTP请求和响应；接口层暴露REST API和SSE流。系统通过清晰的组件分离和依赖注入，实现了高内聚低耦合的设计目标。Pingora反向代理作为独立的服务组件，与主HTTP服务器并行运行，提供高性能的端口路由和负载均衡能力。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "接口层"
|
||||
A[REST API]
|
||||
B[SSE流]
|
||||
C[Swagger UI]
|
||||
end
|
||||
subgraph "应用层"
|
||||
D[Axum服务器]
|
||||
E[路由分发]
|
||||
F[中间件链]
|
||||
end
|
||||
subgraph "服务层"
|
||||
G[代理管理]
|
||||
H[会话缓存]
|
||||
I[任务调度]
|
||||
end
|
||||
subgraph "基础设施层"
|
||||
J[配置管理]
|
||||
K[日志系统]
|
||||
L[遥测系统]
|
||||
end
|
||||
A --> D
|
||||
B --> D
|
||||
C --> D
|
||||
D --> E
|
||||
E --> F
|
||||
F --> G
|
||||
F --> H
|
||||
F --> I
|
||||
G --> J
|
||||
H --> K
|
||||
I --> L
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L1-L200)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 路由设计分析
|
||||
系统基于Axum框架实现RESTful路由设计，通过模块化方式组织API端点。路由配置在`router.rs`文件中集中管理，使用`Router::new()`创建根路由器，并通过`merge()`方法合并多个子路由。API端点按功能分组，包括系统健康检查、聊天交互、代理状态管理和反向代理接口。每个端点通过`route()`方法绑定到相应的处理器函数，并使用`with_state()`方法注入共享的应用状态。OpenAPI文档通过`utoipa`属性宏自动生成，确保API文档与实现保持同步。
|
||||
|
||||
**章节来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
|
||||
#### 路由结构图
|
||||
```mermaid
|
||||
graph TD
|
||||
R[根路由器] --> API[API路由]
|
||||
R --> Proxy[代理API路由]
|
||||
R --> Swagger[Swagger UI]
|
||||
API --> Health[/health]
|
||||
API --> Chat[/chat]
|
||||
API --> Progress[/agent/progress/{session_id}]
|
||||
API --> Cancel[/agent/session/cancel]
|
||||
API --> Status[/agent/status/{project_id}]
|
||||
Proxy --> ProxyStatus[/proxy/status]
|
||||
Proxy --> ProxyStats[/proxy/stats]
|
||||
Proxy --> ProxyConfig[/proxy/config]
|
||||
Proxy --> ProxyPort[/proxy/{port}]
|
||||
Proxy --> ProxyPath[/proxy/{port}/{*path}]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L69)
|
||||
|
||||
### 请求处理流程分析
|
||||
HTTP请求处理流程始于TCP监听器，通过Axum服务器接收请求并应用中间件链。`tracing_middleware`作为核心中间件，负责请求追踪、日志记录和trace_id管理。请求经过路由匹配后，分发到相应的处理器函数。处理器函数从共享状态中获取必要信息，执行业务逻辑，并通过MPMC通道与代理工作器通信。响应结果通过统一的`HttpResult`格式返回，确保API响应的一致性。错误处理通过`AppError`枚举和`IntoResponse` trait实现，提供结构化的错误信息。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L130-L171)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
#### 请求处理序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Server as "Axum服务器"
|
||||
participant Middleware as "tracing_middleware"
|
||||
participant Handler as "处理器"
|
||||
participant Agent as "代理工作器"
|
||||
Client->>Server : HTTP请求
|
||||
Server->>Middleware : 应用中间件
|
||||
Middleware->>Middleware : 生成trace_id
|
||||
Middleware->>Middleware : 创建日志span
|
||||
Middleware->>Handler : 调用处理器
|
||||
Handler->>Handler : 验证请求参数
|
||||
Handler->>Handler : 构建ChatPrompt
|
||||
Handler->>Agent : 发送任务请求
|
||||
Agent->>Handler : 返回响应
|
||||
Handler->>Middleware : 返回结果
|
||||
Middleware->>Middleware : 记录响应信息
|
||||
Middleware->>Client : HTTP响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L130-L171)
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L72-L130)
|
||||
|
||||
### 中间件链分析
|
||||
`tracing_middleware`是系统的核心中间件，负责实现分布式追踪和结构化日志记录。该中间件通过`info_span!`宏创建请求级别的追踪span，包含方法、URI、trace_id等关键信息。trace_id的生成遵循优先级顺序：首先尝试从请求头（x-trace-id、x-request-id等）提取，若不存在则生成新的UUID。中间件使用`instrument`方法将整个请求处理过程包装在span中，确保所有日志都关联到正确的trace上下文。OpenTelemetry集成确保trace信息可以在分布式系统中传播，便于跨服务的性能分析和故障排查。
|
||||
|
||||
**章节来源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L138)
|
||||
|
||||
#### 中间件处理流程图
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([请求进入]) --> Extract["提取trace_id<br/>从请求头"]
|
||||
Extract --> HasTraceId{存在trace_id?}
|
||||
HasTraceId --> |是| UseExisting["使用现有trace_id"]
|
||||
HasTraceId --> |否| Generate["生成新trace_id"]
|
||||
Generate --> UseExisting
|
||||
UseExisting --> CreateSpan["创建tracing span"]
|
||||
CreateSpan --> Execute["执行请求处理"]
|
||||
Execute --> LogResponse["记录响应信息"]
|
||||
LogResponse --> End([响应返回])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L138)
|
||||
|
||||
### 处理器模块分析
|
||||
处理器模块采用模块化设计，每个API端点对应独立的处理器文件。`mod.rs`文件作为公共接口，重新导出所有处理器函数。`chat_handler`处理聊天请求，验证输入参数，管理项目工作目录，并通过MPMC通道与代理工作器通信。`agent_session_notification`实现SSE流，为前端提供实时的代理执行进度更新。`health_handler`提供基本的健康检查功能，返回服务状态和时间戳。`agent_status_handler`查询代理状态，返回详细的会话信息和模型配置。所有处理器函数使用`utoipa::path`宏注解，自动生成OpenAPI文档。
|
||||
|
||||
**章节来源**
|
||||
- [mod.rs](file://crates/agent_runner/src/handler/mod.rs#L1-L17)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L483)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L29-L35)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L121)
|
||||
|
||||
#### 处理器模块类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ChatHandler {
|
||||
+handle_chat(state : Arc~AppState~, request : Json~ChatRequest~) Result~HttpResult~ChatResponse~~, AppError~
|
||||
}
|
||||
class NotificationHandler {
|
||||
+agent_session_notification(params : Path~SessionNotificationParams~) Result~Sse~Stream~, AppError~
|
||||
}
|
||||
class HealthHandler {
|
||||
+health_check() Json~HealthResponse~
|
||||
}
|
||||
class StatusHandler {
|
||||
+agent_status(Path~project_id~) Result~HttpResult~AgentStatusResponse~~, AppError~
|
||||
}
|
||||
ChatHandler --> AppState : "使用"
|
||||
NotificationHandler --> AppState : "使用"
|
||||
StatusHandler --> AppState : "使用"
|
||||
AppState --> DashMap : "包含"
|
||||
AppState --> AppConfig : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L483)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs#L29-L35)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L121)
|
||||
|
||||
## 依赖分析
|
||||
系统依赖关系清晰，核心依赖包括Axum（HTTP框架）、Tokio（异步运行时）、Serde（序列化）、Tracing（日志和追踪）和Utoipa（OpenAPI文档）。`agent_runner` crate依赖`shared_types` crate获取共享的数据结构和枚举类型，依赖`pingora-proxy` crate实现反向代理功能。配置管理通过Clap实现命令行参数解析，通过Serde YAML实现配置文件加载。日志系统使用Tracing Subscriber，支持文件和控制台双输出，文件按天滚动并保留最近5天的日志。遥测系统集成OpenTelemetry，支持trace上下文传播和分布式追踪。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[agent_runner] --> B[axum]
|
||||
A --> C[tokio]
|
||||
A --> D[serde]
|
||||
A --> E[tracing]
|
||||
A --> F[utoipa]
|
||||
A --> G[shared_types]
|
||||
A --> H[pingora-proxy]
|
||||
A --> I[clap]
|
||||
A --> J[serde_yaml]
|
||||
B --> K[tower]
|
||||
C --> L[tokio-util]
|
||||
E --> M[tracing-subscriber]
|
||||
E --> N[tracing-opentelemetry]
|
||||
M --> O[tracing-appender]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
|
||||
## 性能考虑
|
||||
系统在性能方面进行了多项优化。会话状态使用`DashMap`实现，提供高性能的并发访问能力。异步任务通过MPMC通道传递，避免了阻塞操作。SSE流使用`async-stream`库实现，支持高效的异步流处理。日志系统采用非阻塞的`tracing-appender`，确保日志写入不会影响主请求处理流程。Pingora反向代理基于Rust异步I/O构建，提供高性能的代理能力。系统通过`LocalSet`在独立线程中运行代理工作器，避免了Send约束对性能的影响。配置加载采用优先级策略，确保配置解析的高效性。
|
||||
|
||||
## 故障排除指南
|
||||
常见问题包括代理并发请求限制、会话状态不一致和配置加载失败。代理并发请求限制通过在`handle_chat`处理器中检查`PROJECT_AND_AGENT_INFO_MAP`实现，当代理处于活动状态时拒绝新的聊天请求。会话状态不一致问题通过在每次请求时清理旧会话解决，确保状态的纯净性。配置加载失败时系统会自动创建默认配置文件，并提供详细的错误日志。SSE连接问题可以通过检查`SESSION_CACHE`和`create_new_connection`方法的实现来诊断。日志文件位于`logs`目录，按天滚动，便于问题追溯。
|
||||
|
||||
**章节来源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L223)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L364-L369)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L117-L131)
|
||||
|
||||
## 结论
|
||||
RCoder AI服务API架构设计合理，采用现代化的Rust技术栈，实现了高性能、高可用的HTTP服务。系统通过清晰的模块划分和依赖管理，提供了良好的可维护性和可扩展性。Axum框架的使用简化了路由和中间件的实现，Tracing和OpenTelemetry的集成提供了强大的可观测性。SSE流的实现为前端提供了实时的代理执行进度更新，增强了用户体验。整体架构充分考虑了性能、可靠性和可维护性，为AI驱动的开发平台提供了坚实的基础。
|
||||
@@ -0,0 +1,296 @@
|
||||
# 中间件链
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/agent_runner/src/handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
- [crates/rcoder/src/handler/mod.rs](file://crates/rcoder/src/handler/mod.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 引言
|
||||
本文件聚焦于HTTP API中间件链的设计与实现，重点阐述tracing_middleware的作用机制与在Tower Layer模式下的可复用性，说明如何利用该中间件实现请求级别的上下文追踪、日志记录与性能监控；解释OpenTelemetry集成方式，包括trace ID生成、span生命周期管理以及与外部观测系统的对接；梳理中间件执行顺序及其对请求/响应流的影响；并提供自定义中间件扩展的实践建议及在调试与性能分析中的价值。
|
||||
|
||||
## 项目结构
|
||||
本仓库采用多crate工作区组织，其中与HTTP中间件链最相关的两个服务分别为agent_runner与rcoder。两者均内置了相同的tracing_middleware实现，且在各自main中初始化了Tracing与OpenTelemetry传播器，随后在路由上叠加中间件层以形成中间件链。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "agent_runner"
|
||||
ARMain["main.rs<br/>初始化遥测与传播器"]
|
||||
ARRouter["router.rs<br/>创建Axum路由"]
|
||||
ARMW["middleware/tracing_middleware.rs<br/>Tracing中间件"]
|
||||
end
|
||||
subgraph "rcoder"
|
||||
RMain["main.rs<br/>初始化遥测与传播器"]
|
||||
RRouter["router.rs<br/>创建Axum路由"]
|
||||
RMW["middleware/tracing_middleware.rs<br/>Tracing中间件"]
|
||||
end
|
||||
ARMain --> ARRouter
|
||||
ARRouter --> ARMW
|
||||
RMain --> RRouter
|
||||
RRouter --> RMW
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
## 核心组件
|
||||
- Tracing中间件：负责为每个HTTP请求生成或提取trace_id，创建请求span，记录请求/响应信息，并将trace_id注入到请求扩展中，供后续处理器使用。
|
||||
- 遥测初始化：在main中设置全局TextMapPropagator为TraceContext，初始化tracing订阅器，输出到文件与控制台。
|
||||
- 路由与中间件叠加：通过add_tracing_layer将中间件作为Tower Layer叠加到Axum Router上，形成中间件链。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
|
||||
## 架构总览
|
||||
下图展示了请求在中间件链中的流转过程，以及与OpenTelemetry的集成点。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Router as "Axum Router"
|
||||
participant MW as "Tracing中间件"
|
||||
participant Handler as "业务处理器"
|
||||
participant Otel as "OpenTelemetry传播器"
|
||||
Client->>Router : "HTTP请求"
|
||||
Router->>MW : "进入中间件链"
|
||||
MW->>MW : "提取/生成trace_id"
|
||||
MW->>Otel : "设置TraceContext传播器"
|
||||
MW->>MW : "创建请求span并记录开始"
|
||||
MW->>Handler : "next.run(req)"
|
||||
Handler-->>MW : "返回响应"
|
||||
MW->>MW : "记录响应状态"
|
||||
MW-->>Router : "返回响应"
|
||||
Router-->>Client : "HTTP响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Tracing中间件类图
|
||||
Tracing中间件以函数式中间件形式实现，提供add_tracing_layer用于将中间件叠加到Axum Router上；内部通过extract_trace_id_from_headers与generate_trace_id实现trace_id策略；通过info_span与tracing::info记录请求/响应事件；通过req.extensions_mut插入trace_id供后续处理器使用。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class TracingMiddleware {
|
||||
+new() TracingMiddleware
|
||||
}
|
||||
class TracingFunctions {
|
||||
+generate_trace_id() String
|
||||
+extract_trace_id_from_headers(headers) Option~String~
|
||||
+tracing_middleware_handler(req, next) Response
|
||||
+add_tracing_layer(router) Router
|
||||
}
|
||||
TracingMiddleware --> TracingFunctions : "封装函数式中间件逻辑"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L12-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L12-L139)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
|
||||
### 中间件处理流程（序列图）
|
||||
该序列图展示一次请求从进入中间件到返回响应的完整流程，包括trace_id策略、span创建与日志记录。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant R as "Axum Router"
|
||||
participant T as "Tracing中间件"
|
||||
participant N as "Next(下游处理器)"
|
||||
C->>R : "发起请求"
|
||||
R->>T : "进入中间件"
|
||||
T->>T : "尝试从请求头提取trace_id"
|
||||
alt "未提取到"
|
||||
T->>T : "生成新的trace_id"
|
||||
end
|
||||
T->>T : "创建请求span并记录开始"
|
||||
T->>N : "next.run(req)"
|
||||
N-->>T : "返回响应"
|
||||
T->>T : "记录响应状态"
|
||||
T-->>R : "返回响应"
|
||||
R-->>C : "返回HTTP响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
### 中间件执行顺序与对请求/响应流的影响
|
||||
- 叠加位置：add_tracing_layer将中间件作为顶层Layer叠加到Router上，因此它会最先拦截请求，最后才返回响应。
|
||||
- 对请求的影响：中间件在进入下游处理器前记录请求开始、注入trace_id到请求扩展；对上游调用方透明，仅增加少量开销。
|
||||
- 对响应的影响：中间件在下游返回后记录响应状态，便于统一观测与排障。
|
||||
- 与OpenTelemetry的关系：main中设置了TraceContextPropagator，使trace_id在分布式链路中可被传播；中间件通过tracing_span与tracing日志记录，形成可观测闭环。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
### OpenTelemetry集成与span生命周期
|
||||
- TraceContext传播器：在main中设置全局TextMapPropagator为TraceContext，确保trace_id在跨进程/服务间传播。
|
||||
- span创建与记录：中间件创建“http_request”与“http_request_processing”两类span，分别用于请求级追踪与处理阶段记录。
|
||||
- 日志与span关联：通过tracing::info与info_span，将trace_id写入日志字段，便于与span关联检索。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L85-L124)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L85-L124)
|
||||
|
||||
### 外部观测系统对接
|
||||
- 日志输出：main中配置tracing_subscriber输出到文件与控制台，日志为JSON格式，便于后续导入ELK/Promtail等系统。
|
||||
- trace ID与span：通过中间件与传播器，trace_id贯穿请求全链路，可与Jaeger/Tempo等分布式追踪系统对接。
|
||||
- 指标采集：rcoder还集成了Pingora代理，可通过其stats接口获取真实后端指标，结合日志与trace可形成端到端观测。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L190-L210)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L283-L301)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L68-L84)
|
||||
|
||||
### 自定义中间件扩展建议
|
||||
- 设计原则
|
||||
- 保持无状态与纯函数式：中间件应尽量避免持有可变共享状态，减少竞态与副作用。
|
||||
- 明确职责边界：每个中间件专注单一职责（鉴权、限流、日志、追踪等），通过Tower Layer组合。
|
||||
- 顺序敏感性：将更通用的中间件置于外层，将更具体的中间件置于内层；例如鉴权/限流在外层，业务处理器在内层。
|
||||
- 实现要点
|
||||
- 使用axum::middleware::from_fn或实现tower::Layer，将中间件以Layer形式叠加到Router。
|
||||
- 在进入下游前记录关键信息（如trace_id、用户标识、请求参数摘要），在返回后记录响应状态与耗时。
|
||||
- 通过req.extensions_mut传递上下文数据，避免全局状态污染。
|
||||
- 调试与性能分析价值
|
||||
- trace_id串联：便于跨服务定位问题，快速回溯请求路径。
|
||||
- 统一日志字段：统一的trace_id与span字段，便于日志聚合与检索。
|
||||
- 性能瓶颈定位：结合响应状态与日志时间戳，识别慢请求与异常路径。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
|
||||
## 依赖关系分析
|
||||
- 依赖组件
|
||||
- axum：HTTP框架，提供Router、Request、Response、Next等。
|
||||
- tower/tower-http：中间件与服务抽象，支持Layer叠加。
|
||||
- tracing/tracing-opentelemetry：日志与OpenTelemetry集成。
|
||||
- opentelemetry/opentelemetry_sdk：SDK与传播器。
|
||||
- uuid：生成trace_id。
|
||||
- 关键依赖关系
|
||||
- main中设置TraceContextPropagator，为后续中间件与OpenTelemetry提供传播基础。
|
||||
- 中间件通过tracing与tracing_opentelemetry记录span与日志。
|
||||
- Router通过add_tracing_layer叠加中间件，形成Tower Layer链。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cargo["Cargo.toml 依赖声明"] --> Axum["axum"]
|
||||
Cargo --> Tower["tower / tower-http"]
|
||||
Cargo --> Tracing["tracing / tracing-opentelemetry"]
|
||||
Cargo --> Otel["opentelemetry / opentelemetry_sdk"]
|
||||
Cargo --> Uuid["uuid"]
|
||||
ARMain["agent_runner/main.rs"] --> Otel
|
||||
RMain["rcoder/main.rs"] --> Otel
|
||||
ARMW["agent_runner/tracing_middleware.rs"] --> Tracing
|
||||
RMW["rcoder/tracing_middleware.rs"] --> Tracing
|
||||
ARRouter["agent_runner/router.rs"] --> Axum
|
||||
RRouter["rcoder/router.rs"] --> Axum
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L59-L105)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L1-L139)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L59-L105)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L212-L225)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L302-L314)
|
||||
|
||||
## 性能考量
|
||||
- 中间件开销：中间件在请求进入与返回时各做一次日志记录与span创建，开销极低，适合在生产环境长期开启。
|
||||
- trace_id生成：使用UUID v4简单格式，长度固定，生成成本低。
|
||||
- 日志落盘：按天滚动与保留策略，避免日志膨胀；JSON格式利于外部系统解析。
|
||||
- 观测成本：trace_id与span字段统一，便于日志聚合与检索，但需关注日志量与存储成本。
|
||||
|
||||
## 故障排查指南
|
||||
- trace_id缺失
|
||||
- 检查请求头是否携带trace_id或x-request-id等常见头；若无则中间件会自动生成。
|
||||
- 确认main中已设置TraceContextPropagator，确保trace_id在跨服务传播。
|
||||
- 日志未输出或格式异常
|
||||
- 检查tracing_subscriber初始化与EnvFilter配置；确认文件appender路径与权限。
|
||||
- 响应异常
|
||||
- 通过中间件记录的trace_id在日志中定位具体请求，结合span层级排查下游处理器异常。
|
||||
- 与外部观测系统对接
|
||||
- 确保OpenTelemetry SDK与Exporter配置正确；trace_id字段与span字段一致，便于检索。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L49-L69)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L49-L69)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L190-L210)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L283-L301)
|
||||
|
||||
## 结论
|
||||
本项目通过Tower Layer模式将Tracing中间件以可复用的方式叠加到Axum Router上，实现了请求级上下文追踪、统一日志记录与性能监控。OpenTelemetry传播器在main中初始化，配合中间件的span与日志，形成了从请求入口到响应返回的完整可观测闭环。该设计易于扩展，可按需叠加更多中间件以满足安全、限流、审计等需求，并在调试与性能分析中具有显著价值。
|
||||
|
||||
## 附录
|
||||
- 中间件叠加位置
|
||||
- agent_runner：在路由创建后通过add_tracing_layer叠加。
|
||||
- rcoder：同样在路由创建后通过add_tracing_layer叠加。
|
||||
- 路由与处理器
|
||||
- 两个服务的router.rs均定义了API路由与代理路由，并通过with_state注入应用状态。
|
||||
- Handler模块
|
||||
- 两个服务的handler/mod.rs导出了各自的处理器模块，供路由绑定。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L132-L139)
|
||||
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/agent_runner/src/handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs#L1-L17)
|
||||
- [crates/rcoder/src/handler/mod.rs](file://crates/rcoder/src/handler/mod.rs#L1-L19)
|
||||
@@ -0,0 +1,334 @@
|
||||
# 请求处理流程
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文件深入解析 RCoder Agent Runner 服务的 HTTP API 请求处理生命周期，重点覆盖以下方面：
|
||||
- 从请求进入路由到最终响应返回的完整链路
|
||||
- chat_handler、agent_status_handler、agent_session_notification、agent_cancel_handler 等核心处理器的实现逻辑
|
||||
- 请求体解析、服务调用（container_manager 或 agent_runner）、响应构造的细节
|
||||
- SSE 流式响应在进度通知中的应用机制
|
||||
- 典型请求处理链路的时序图，展示数据在 handler、service 与 proxy_agent 之间的流转
|
||||
- 错误处理模式与状态码映射策略
|
||||
|
||||
## 项目结构
|
||||
Agent Runner 采用模块化组织，核心模块包括：
|
||||
- handler：HTTP 路由与处理器
|
||||
- proxy_agent：ACPI 协议代理与会话管理
|
||||
- service：会话缓存与消息推送
|
||||
- model：共享模型与错误类型
|
||||
- router：Axum 路由注册与 OpenAPI 文档
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "HTTP 层"
|
||||
R["Router<br/>注册路由"]
|
||||
CH["chat_handler<br/>POST /chat"]
|
||||
ASH["agent_status_handler<br/>GET /agent/status/{project_id}"]
|
||||
ASN["agent_session_notification<br/>GET /agent/progress/{session_id}<br/>SSE"]
|
||||
AC["agent_cancel_handler<br/>POST /agent/session/cancel"]
|
||||
end
|
||||
subgraph "业务层"
|
||||
PA["proxy_agent<br/>ACPI 代理与会话管理"]
|
||||
SVC["service<br/>会话缓存与消息推送"]
|
||||
MOD["model<br/>共享模型与错误类型"]
|
||||
end
|
||||
R --> CH
|
||||
R --> ASH
|
||||
R --> ASN
|
||||
R --> AC
|
||||
CH --> PA
|
||||
CH --> SVC
|
||||
ASH --> PA
|
||||
ASH --> SVC
|
||||
AC --> PA
|
||||
AC --> SVC
|
||||
PA --> SVC
|
||||
SVC --> ASN
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 核心组件
|
||||
- 路由与状态
|
||||
- AppState：持有会话映射、本地任务发送器、Pingora 代理服务引用
|
||||
- 路由注册：/health、/chat、/agent/progress/{session_id}、/agent/session/cancel、/agent/status/{project_id}、/proxy/*
|
||||
- 处理器
|
||||
- chat_handler：解析 ChatRequest，校验参数，生成或复用 project_id 与 session_id，构建 ChatPrompt，发送到本地任务通道，等待 oneshot 响应并返回 HttpResult
|
||||
- agent_status_handler：查询 PROJECT_AND_AGENT_INFO_MAP，返回 AgentStatusResponse
|
||||
- agent_session_notification：建立 SSE 连接，推送 UnifiedSessionMessage，支持心跳与取消
|
||||
- agent_cancel_handler：通过 cancel_tx 发送取消通知，清理 SSE 连接与缓存
|
||||
- 代理与会话
|
||||
- proxy_agent：维护 PROJECT_AND_AGENT_INFO_MAP，封装 ACP 连接信息，启动代理服务，转发 session_notification
|
||||
- channel_utils：通用的 Prompt/Cancellation 处理任务，负责状态更新、消息推送与超时保护
|
||||
- session_cache：全局 SESSION_CACHE，RingBuffer 缓冲与实时推送，支持连接级取消令牌与显式关闭
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L25-L70)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
## 架构总览
|
||||
整体架构围绕“请求-代理-通知”三段式展开：
|
||||
- 请求阶段：Axum 路由将 HTTP 请求交由对应 handler 解析与校验
|
||||
- 代理阶段：handler 将 ChatPrompt 通过本地任务通道发送给 agent_worker，后者启动 ACPI 代理并发送 Prompt
|
||||
- 通知阶段：代理通过 session_notification 回调，经由 push_session_update 推送到 SESSION_CACHE，SSE 连接从 SESSION_CACHE 拉取并推送至客户端
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant H as "chat_handler"
|
||||
participant W as "agent_worker"
|
||||
participant P as "ACPI 代理"
|
||||
participant S as "SESSION_CACHE"
|
||||
participant N as "agent_session_notification"
|
||||
C->>H : POST /chat
|
||||
H->>H : 校验参数/生成 project_id/session_id/request_id
|
||||
H->>W : 发送 LocalSetAgentRequest(含 ChatPrompt)
|
||||
W->>P : 启动代理并发送 Prompt
|
||||
P-->>W : 返回 ChatPromptResponse
|
||||
W-->>H : oneshot 响应
|
||||
H-->>C : HttpResult 成功/错误
|
||||
C->>N : GET /agent/progress/{session_id}
|
||||
N->>S : 创建/获取 SessionData 并建立连接
|
||||
P-->>S : session_notification -> 推送 UnifiedSessionMessage
|
||||
S-->>N : 拉取消息并转为SSE事件
|
||||
N-->>C : 事件流推送(progress_start/end/updates/heartbeat)
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L164-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### chat_handler：聊天请求处理
|
||||
- 输入解析：Json<ChatRequest>，包含 prompt、project_id、session_id、attachments、data_source_attachments、model_provider、request_id
|
||||
- 参数校验：prompt 非空校验
|
||||
- 项目与会话管理：
|
||||
- 若未提供 project_id，自动生成 UUID（去除横杠）并创建 ./project_workspace/{project_id}
|
||||
- 若 Agent 正处于 Active 状态，拒绝并发请求
|
||||
- 若提供了 session_id，移除该 session；否则清空该项目下的所有 session
|
||||
- 任务构建：根据 model_provider 自动选择 AgentType，构建 ChatPrompt，并通过 LocalSetAgentRequest.new 生成 oneshot 通道
|
||||
- 任务提交：通过 AppState.local_task_sender 发送 LocalSetAgentRequest
|
||||
- 响应构造：等待 chat_prompt_rx.await，若 error 非空返回 PROMPT001，否则返回 HttpResult.success，包含 project_id、session_id、request_id
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入 handle_chat"]) --> Validate["校验 prompt 非空"]
|
||||
Validate --> GenPID{"是否提供 project_id?"}
|
||||
GenPID --> |否| CreateWS["生成 project_id 并创建工作目录"]
|
||||
GenPID --> |是| UsePID["使用请求中的 project_id"]
|
||||
CreateWS --> CheckAgent["检查 Agent 是否 Active"]
|
||||
UsePID --> CheckAgent
|
||||
CheckAgent --> |Active| Reject["返回并发请求错误"]
|
||||
CheckAgent --> |Idle| CleanSess["清理旧 session按 session_id 或按 project_id"]
|
||||
CleanSess --> BuildPrompt["构建 ChatPrompt含 attachments、data_source_attachments、model_provider"]
|
||||
BuildPrompt --> SendTask["发送 LocalSetAgentRequest 到本地任务通道"]
|
||||
SendTask --> AwaitResp{"等待 oneshot 响应"}
|
||||
AwaitResp --> |error 非空| RespErr["返回 PROMPT001 错误"]
|
||||
AwaitResp --> |成功| RespOK["返回 HttpResult.success包含 project_id/session_id/request_id"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
|
||||
### agent_status_handler：Agent 状态查询
|
||||
- 路径参数：project_id
|
||||
- 参数校验：project_id 非空
|
||||
- 查询逻辑：从 PROJECT_AND_AGENT_INFO_MAP 获取 Agent 信息
|
||||
- 若存在：返回包含 is_alive=true、session_id、status、last_activity、created_at、model_provider 的 AgentStatusResponse
|
||||
- 若不存在：返回 is_alive=false 的简化响应
|
||||
|
||||
章节来源
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L22-L39)
|
||||
|
||||
### agent_session_notification：SSE 实时进度
|
||||
- 路径参数：session_id
|
||||
- 连接建立：为 session_id 创建新的 SessionData，插入 SESSION_CACHE
|
||||
- 连接管理：
|
||||
- 立即发送 heartbeat 事件，随后每 30 秒发送一次心跳
|
||||
- 使用 CancellationToken 监听取消信号：当新连接建立或用户取消任务时，旧连接自然断开
|
||||
- 当 channel 发送端被 drop 时，recv() 返回 None，连接自然断开
|
||||
- 事件类型映射：根据 UnifiedSessionMessage.message_type 动态设置事件名（prompt_start、prompt_end、各类 agent_session_update、heartbeat）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "客户端"
|
||||
participant H as "agent_session_notification"
|
||||
participant S as "SESSION_CACHE"
|
||||
participant W as "SessionWorker"
|
||||
participant P as "ACPI 代理"
|
||||
C->>H : GET /agent/progress/{session_id}
|
||||
H->>S : SessionData : : new + 插入 SESSION_CACHE
|
||||
H->>S : create_new_connection(1000)
|
||||
H-->>C : 发送 initial heartbeat 事件
|
||||
loop 心跳/消息循环
|
||||
alt 收到 CancellationToken
|
||||
H-->>C : 断开旧连接
|
||||
else 收到 UnifiedSessionMessage
|
||||
H-->>C : 事件流推送按 message_type 映射
|
||||
else 心跳定时器
|
||||
H-->>C : 发送 heartbeat 事件
|
||||
end
|
||||
end
|
||||
note over P,S : 代理通过 session_notification 推送消息到 SESSION_CACHE
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L142-L207)
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
### agent_cancel_handler：任务取消
|
||||
- 查询参数：project_id（可选 session_id）
|
||||
- 逻辑：
|
||||
- 若未提供 session_id，从 PROJECT_AND_AGENT_INFO_MAP 中解析
|
||||
- 通过 cancel_tx 发送 CancelNotificationRequest，并等待响应
|
||||
- 成功后：主动关闭 SSE 连接（close_current_connection），移除 SESSION_CACHE 条目
|
||||
- 未找到活跃连接：同样主动关闭并清理 SESSION_CACHE
|
||||
- 返回：HttpResult.success(CancelResponse{success, session_id})
|
||||
|
||||
章节来源
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L91)
|
||||
|
||||
### 代理与会话管理（proxy_agent 与 channel_utils）
|
||||
- AcpAgentService：根据 AgentType 启动 Claude 或 Codex 代理服务，返回 AcpConnectionInfo（包含 session_id、prompt_tx、cancel_tx、stop_handle）
|
||||
- AcpAgentClient：实现 agent_client_protocol::Client，处理权限请求、文件读写、session_notification 回调
|
||||
- session_notification：将 AgentSessionUpdate 包装为 SessionNotify，调用 push_session_update 推送
|
||||
- request_id 优先从 SessionNotification.meta 获取，否则通过 PROJECT_AND_AGENT_INFO_MAP + SESSION_REQUEST_CONTEXT 解析
|
||||
- channel_utils：
|
||||
- spawn_prompt_handler_for_agent：监听 prompt_rx，更新 Agent 状态为 Active，推送 SessionPromptStart，调用 Agent.prompt，推送 SessionPromptEnd 或 SessionPromptError
|
||||
- spawn_cancel_handler_for_agent：监听 cancel_rx，调用 Agent.cancel，超时保护，完成后将 Agent 状态恢复为 Idle
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
## 依赖关系分析
|
||||
- handler 依赖
|
||||
- chat_handler 依赖 AppState（sessions、local_task_sender）、ChatPromptBuilder、AgentType、HttpResult/AppError
|
||||
- agent_status_handler 依赖 PROJECT_AND_AGENT_INFO_MAP
|
||||
- agent_session_notification 依赖 SESSION_CACHE、UnifiedSessionMessage
|
||||
- agent_cancel_handler 依赖 PROJECT_AND_AGENT_INFO_MAP、CancelNotificationRequest
|
||||
- proxy_agent 依赖
|
||||
- AcpAgentService/AcpAgentClient、PROJECT_AND_AGENT_INFO_MAP、AcpConnectionInfo
|
||||
- service 依赖
|
||||
- SESSION_CACHE、PROJECT_SESSION_MAP、SessionData、SessionWorker、UnifiedSessionMessage
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CH["chat_handler"] --> PA["proxy_agent"]
|
||||
CH --> SVC["service"]
|
||||
ASH["agent_status_handler"] --> PA
|
||||
ASN["agent_session_notification"] --> SVC
|
||||
AC["agent_cancel_handler"] --> PA
|
||||
AC --> SVC
|
||||
PA --> SVC
|
||||
SVC --> ASN
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_status_handler.rs](file://crates/agent_runner/src/handler/agent_status_handler.rs#L70-L122)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L200)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
章节来源
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L41-L70)
|
||||
|
||||
## 性能考量
|
||||
- 会话缓存与推送
|
||||
- SessionData 使用 mpsc::channel 与 CancellationToken 管理连接，避免命令传递的额外开销
|
||||
- SessionWorker 使用 RingBuffer 缓冲消息，实时推送至当前连接，丢弃心跳消息以节省带宽
|
||||
- 通过 PROJECT_SESSION_MAP 确保 project_id 仅对应一个活跃 session，避免旧数据污染
|
||||
- 取消与断开
|
||||
- CancellationToken 与显式 drop Sender 实现快速断开，减少资源占用
|
||||
- 取消超时保护（默认 10 秒），避免阻塞
|
||||
- 并发控制
|
||||
- chat_handler 在 Agent Active 时拒绝并发请求，避免资源争用
|
||||
- 通过 oneshot 通道保证 ChatPromptResponse 的顺序性与一致性
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 常见错误与状态码映射
|
||||
- 参数错误：chat_handler 对 prompt 校验失败返回 400（AppError::Generic -> INTERNAL_SERVER_ERROR），但 OpenAPI 注释中明确 400 场景
|
||||
- 并发请求：Agent Active 时返回 409（自定义错误码），提示“Agent正在执行任务，请等待当前任务完成后再发送新请求”
|
||||
- 内部错误：AppError::AnyhowError/IOError -> 500（IntoResponse 默认 INTERNAL_SERVER_ERROR）
|
||||
- SSE 连接异常：心跳丢失、连接断开、取消后清理不彻底
|
||||
- 排查步骤
|
||||
- chat_handler：确认 project_id 生成与工作目录创建、session 清理逻辑、LocalSetAgentRequest 发送与 oneshot 响应
|
||||
- agent_session_notification：检查 SessionData::new、create_new_connection、CancellationToken 与心跳定时器
|
||||
- agent_cancel_handler：确认 cancel_tx 发送、响应等待、SSE 连接关闭与 SESSION_CACHE 清理
|
||||
- proxy_agent：核对 PROJECT_AND_AGENT_INFO_MAP 更新、AcpAgentService 启动、session_notification 推送
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L321)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L356-L484)
|
||||
- [agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs#L110-L258)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [http_result.rs](file://crates/shared_types/src/model/http_result.rs#L1-L103)
|
||||
|
||||
## 结论
|
||||
本文件梳理了 RCoder Agent Runner 的 HTTP API 请求处理全生命周期，明确了 chat_handler、agent_status_handler、agent_session_notification、agent_cancel_handler 的职责边界与协作关系。通过 SSE 实时推送与会话缓存机制，系统实现了低延迟、高可靠的状态反馈；通过代理层与通道工具的解耦设计，保障了并发安全与可扩展性。建议在生产环境中关注：
|
||||
- 参数校验与错误映射的一致性
|
||||
- SSE 连接的健壮性与自动重连策略
|
||||
- 取消超时与资源回收的可观测性
|
||||
- 代理启动失败的兜底处理与告警
|
||||
@@ -0,0 +1,312 @@
|
||||
# 路由配置
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [项目结构](#项目结构)
|
||||
2. [核心路由注册机制](#核心路由注册机制)
|
||||
3. [模块化路由组织结构](#模块化路由组织结构)
|
||||
4. [全局中间件应用](#全局中间件应用)
|
||||
5. [路由层级划分逻辑](#路由层级划分逻辑)
|
||||
6. [动态路由参数处理](#动态路由参数处理)
|
||||
7. [错误传播模式](#错误传播模式)
|
||||
8. [API端点详细说明](#api端点详细说明)
|
||||
9. [OpenAPI文档集成](#openapi文档集成)
|
||||
|
||||
## 项目结构
|
||||
|
||||
本项目采用模块化设计，HTTP API路由配置主要分布在`crates/agent_runner`和`crates/rcoder`两个核心模块中。路由配置的核心文件位于`src/router.rs`，通过Axum框架实现路由注册。处理器函数分布在`src/handler`目录下，按功能模块组织。中间件定义在`src/middleware`目录中，用于处理全局请求拦截和日志追踪。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[HTTP API路由系统] --> B[路由注册]
|
||||
A --> C[处理器模块]
|
||||
A --> D[中间件]
|
||||
A --> E[应用状态]
|
||||
B --> F[router.rs]
|
||||
C --> G[handler/mod.rs]
|
||||
D --> H[middleware/tracing_middleware.rs]
|
||||
E --> I[AppState结构]
|
||||
F --> J[create_router函数]
|
||||
G --> K[health_handler]
|
||||
G --> L[chat_handler]
|
||||
G --> M[agent_session_notification]
|
||||
G --> N[proxy_api]
|
||||
H --> O[tracing_middleware_handler]
|
||||
I --> P[sessions]
|
||||
I --> Q[config]
|
||||
I --> R[local_task_sender]
|
||||
I --> S[pingora_service]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
|
||||
**节源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
|
||||
## 核心路由注册机制
|
||||
|
||||
基于Axum框架的路由注册机制通过`create_router`函数实现，该函数接收应用状态并返回配置好的Router实例。路由注册采用链式调用方式，将不同功能的路由分组后合并到主路由中。
|
||||
|
||||
路由注册的核心流程如下：
|
||||
1. 创建API路由组，包含健康检查、聊天、代理会话通知等核心接口
|
||||
2. 创建代理API路由组，提供Pingora反向代理相关的状态查询接口
|
||||
3. 将各路由组合并到主路由中
|
||||
4. 集成Swagger UI路由，提供API文档界面
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as 应用启动
|
||||
participant Router as 路由创建
|
||||
participant API as API路由组
|
||||
participant Proxy as 代理API路由组
|
||||
participant Swagger as Swagger UI
|
||||
App->>Router : create_router(state)
|
||||
Router->>API : 创建API路由组
|
||||
API->>API : route("/health", get(health_check))
|
||||
API->>API : route("/chat", post(handle_chat))
|
||||
API->>API : route("/agent/progress/{session_id}", get(agent_session_notification))
|
||||
API->>Router : 返回API路由组
|
||||
Router->>Proxy : 创建代理API路由组
|
||||
Proxy->>Proxy : route("/proxy/status", get(proxy_status))
|
||||
Proxy->>Proxy : route("/proxy/stats", get(proxy_stats))
|
||||
Proxy->>Router : 返回代理API路由组
|
||||
Router->>Swagger : 创建Swagger UI路由
|
||||
Swagger->>Router : 返回Swagger路由
|
||||
Router->>App : 合并所有路由并返回
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
|
||||
**节源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
|
||||
|
||||
## 模块化路由组织结构
|
||||
|
||||
路由处理器采用模块化组织结构，通过`handler/mod.rs`文件统一导出所有处理器模块。这种设计实现了关注点分离，使代码结构更加清晰和易于维护。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[handler/mod.rs] --> B[agent_cancel_handler]
|
||||
A --> C[agent_session_notification]
|
||||
A --> D[chat_handler]
|
||||
A --> E[agent_status_handler]
|
||||
A --> F[health_handler]
|
||||
A --> G[proxy_api]
|
||||
A --> H[proxy_handler_api]
|
||||
B --> I[agent_session_cancel]
|
||||
C --> J[agent_session_notification]
|
||||
D --> K[handle_chat]
|
||||
E --> L[agent_status]
|
||||
F --> M[health_check]
|
||||
G --> N[proxy_status]
|
||||
G --> O[proxy_stats]
|
||||
G --> P[proxy_config]
|
||||
G --> Q[proxy_to_port]
|
||||
G --> R[proxy_to_port_with_path]
|
||||
G --> S[proxy_with_query_params]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
|
||||
**节源**
|
||||
- [handler/mod.rs](file://crates/agent_runner/src/handler/mod.rs)
|
||||
|
||||
## 全局中间件应用
|
||||
|
||||
通过Layer堆叠机制应用全局中间件，实现请求的统一处理。主要中间件包括追踪中间件，用于记录请求日志和生成trace_id。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[HTTP请求] --> B[Tracing中间件]
|
||||
B --> C[提取或生成trace_id]
|
||||
C --> D[创建日志span]
|
||||
D --> E[记录请求开始]
|
||||
E --> F[执行后续处理器]
|
||||
F --> G[记录响应完成]
|
||||
G --> H[返回响应]
|
||||
subgraph 中间件处理流程
|
||||
C
|
||||
D
|
||||
E
|
||||
F
|
||||
G
|
||||
end
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
|
||||
**节源**
|
||||
- [middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
|
||||
## 路由层级划分逻辑
|
||||
|
||||
路由系统采用清晰的层级划分逻辑，将公共接口与代理专用接口分离。这种设计提高了系统的可维护性和安全性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[主路由] --> B[API路由组]
|
||||
A --> C[代理API路由组]
|
||||
A --> D[Swagger UI路由]
|
||||
B --> E[公共接口]
|
||||
E --> F[/health]
|
||||
E --> G[/chat]
|
||||
E --> H[/agent/progress/{session_id}]
|
||||
E --> I[/agent/session/cancel]
|
||||
E --> J[/agent/status/{project_id}]
|
||||
C --> K[代理专用接口]
|
||||
K --> L[/proxy/status]
|
||||
K --> M[/proxy/stats]
|
||||
K --> N[/proxy/config]
|
||||
K --> O[/proxy/{port}]
|
||||
K --> P[/proxy/{port}/{*path}]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L42-L69)
|
||||
|
||||
**节源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L42-L69)
|
||||
|
||||
## 动态路由参数处理
|
||||
|
||||
动态路由参数通过Axum的路径参数机制处理，支持路径参数和通配符参数。系统能够正确解析和验证动态路由参数。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[接收到请求] --> B{路径匹配}
|
||||
B --> |/agent/progress/{session_id}| C[提取session_id]
|
||||
B --> |/proxy/{port}| D[提取port]
|
||||
B --> |/proxy/{port}/{*path}| E[提取port和path]
|
||||
B --> |其他路径| F[返回404]
|
||||
C --> G[验证session_id]
|
||||
G --> H[调用agent_session_notification]
|
||||
D --> I[验证port]
|
||||
I --> J[调用proxy_to_port]
|
||||
E --> K[验证port和path]
|
||||
K --> L[调用proxy_to_port_with_path]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L46-L47)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L59-L63)
|
||||
|
||||
**节源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L46-L63)
|
||||
|
||||
## 错误传播模式
|
||||
|
||||
系统采用统一的错误传播模式，通过Result类型传递错误信息。错误处理遵循以下原则：
|
||||
|
||||
1. 处理器函数返回Result类型，包含成功值或错误
|
||||
2. 使用AppError类型封装各种错误情况
|
||||
3. 错误信息包含错误代码和描述
|
||||
4. 通过HttpResult包装器提供一致的响应格式
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 请求处理
|
||||
请求处理 --> 验证输入
|
||||
验证输入 --> |有效| 业务逻辑
|
||||
验证输入 --> |无效| 返回验证错误
|
||||
业务逻辑 --> |成功| 构建成功响应
|
||||
业务逻辑 --> |失败| 构建错误响应
|
||||
构建成功响应 --> 返回响应
|
||||
构建错误响应 --> 返回响应
|
||||
返回响应 --> [*]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L179)
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs)
|
||||
|
||||
**节源**
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L179)
|
||||
|
||||
## API端点详细说明
|
||||
|
||||
### 健康检查端点
|
||||
- 路径: `/health`
|
||||
- 方法: GET
|
||||
- 功能: 检查服务的健康状态
|
||||
- 响应: 返回服务状态、时间戳和服务名称
|
||||
|
||||
### 聊天端点
|
||||
- 路径: `/chat`
|
||||
- 方法: POST
|
||||
- 功能: 发送聊天消息并获取AI响应
|
||||
- 请求体: 包含prompt、project_id、session_id等信息
|
||||
- 响应: 返回项目ID和会话ID
|
||||
|
||||
### 代理会话通知端点
|
||||
- 路径: `/agent/progress/{session_id}`
|
||||
- 方法: GET
|
||||
- 功能: 通过SSE协议实时推送AI代理执行进度
|
||||
- 参数: session_id
|
||||
- 响应: SSE流，包含各种类型的消息事件
|
||||
|
||||
### 代理API端点
|
||||
- 路径: `/proxy/status`, `/proxy/stats`, `/proxy/config`等
|
||||
- 方法: GET
|
||||
- 功能: 提供Pingora反向代理的状态、统计和配置信息
|
||||
- 参数: port, path等动态参数
|
||||
|
||||
**节源**
|
||||
- [health_handler.rs](file://crates/agent_runner/src/handler/health_handler.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [proxy_api.rs](file://crates/agent_runner/src/handler/proxy_api.rs)
|
||||
|
||||
## OpenAPI文档集成
|
||||
|
||||
系统集成了OpenAPI文档功能，通过utoipa和utoipa_swagger_ui crate提供API文档界面。文档包含所有API端点的详细描述、请求参数、响应格式和示例。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[OpenAPI文档] --> B[API端点]
|
||||
A --> C[组件定义]
|
||||
A --> D[标签]
|
||||
A --> E[信息]
|
||||
B --> F[health_check]
|
||||
B --> G[handle_chat]
|
||||
B --> H[agent_session_notification]
|
||||
B --> I[proxy_status]
|
||||
B --> J[proxy_stats]
|
||||
B --> K[proxy_config]
|
||||
C --> L[请求体]
|
||||
C --> M[响应体]
|
||||
C --> N[参数]
|
||||
D --> O[system]
|
||||
D --> P[chat]
|
||||
D --> Q[agent]
|
||||
D --> R[proxy]
|
||||
E --> S[描述]
|
||||
E --> T[标题]
|
||||
E --> U[版本]
|
||||
E --> V[许可证]
|
||||
E --> W[联系人]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L73-L208)
|
||||
|
||||
**节源**
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs#L73-L208)
|
||||
@@ -0,0 +1,345 @@
|
||||
# ACP代理集成
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [acp_adapter/src/types.rs](file://crates/acp_adapter/src/types.rs)
|
||||
- [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [agent_runner/src/handler/agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_runner/src/model.rs](file://crates/agent_runner/src/model.rs)
|
||||
- [shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档详细阐述了ACP代理集成的技术实现，重点说明acp_agent模块如何通过acp_adapter crate实现与ACP协议适配器的通信。文档涵盖了请求转发、状态同步、错误传播机制，以及消息序列化/反序列化过程、连接管理策略和超时处理机制。同时，文档还解释了协议版本兼容性、异常处理和性能优化措施，并通过实际交互示例展示聊天请求的完整流程。
|
||||
|
||||
## 项目结构
|
||||
项目采用模块化设计，主要分为以下几个核心模块：
|
||||
- `acp_adapter`: 提供与ACP协议适配器通信的核心功能
|
||||
- `agent_runner`: 负责代理服务的运行和管理
|
||||
- `shared_types`: 共享的数据类型和模型定义
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "核心模块"
|
||||
A[acp_adapter] --> |提供| B[agent_runner]
|
||||
C[shared_types] --> |共享类型| A
|
||||
C --> |共享类型| B
|
||||
end
|
||||
subgraph "代理类型"
|
||||
B --> D[Claude Code Agent]
|
||||
B --> E[Codex Agent]
|
||||
end
|
||||
subgraph "通信协议"
|
||||
A --> F[ACP协议]
|
||||
F --> G[子进程通信]
|
||||
end
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
**本节源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
## 核心组件
|
||||
系统的核心组件包括ACP适配器、代理服务管理器和会话状态管理器。ACP适配器负责处理与代理的底层通信，代理服务管理器负责启动和管理不同类型的代理服务，会话状态管理器则负责维护会话的生命周期和状态同步。
|
||||
|
||||
**本节源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
|
||||
## 架构概述
|
||||
系统采用分层架构设计，通过抽象层实现不同AI代理的统一接入。核心架构包括协议抽象层、代理管理层和会话管理层。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[客户端] --> B[HTTP API]
|
||||
B --> C[代理管理层]
|
||||
C --> D[协议抽象层]
|
||||
D --> E[ACP适配器]
|
||||
E --> F[具体代理]
|
||||
F --> G[Claude Code]
|
||||
F --> H[Codex]
|
||||
style D fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style C fill:#bbf,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### ACP适配器分析
|
||||
ACP适配器模块提供了与ACP兼容的AI代理通信的核心功能，包括连接管理、会话生命周期、消息处理和MCP集成。
|
||||
|
||||
#### 类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAdapter {
|
||||
+initialize()
|
||||
+new_session()
|
||||
+load_session()
|
||||
+prompt()
|
||||
+cancel()
|
||||
}
|
||||
class SessionState {
|
||||
+Initializing
|
||||
+Connected
|
||||
+Prompting
|
||||
+Paused
|
||||
+Closed
|
||||
+Error
|
||||
}
|
||||
class StreamUpdate {
|
||||
+UserMessageChunk
|
||||
+AgentMessageChunk
|
||||
+AgentThoughtChunk
|
||||
+ToolCall
|
||||
+SessionStateChanged
|
||||
+PromptStarted
|
||||
+PromptCompleted
|
||||
+Error
|
||||
}
|
||||
AcpAdapter --> SessionState : "使用"
|
||||
AcpAdapter --> StreamUpdate : "生成"
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [acp_adapter/src/types.rs](file://crates/acp_adapter/src/types.rs)
|
||||
|
||||
#### 请求处理流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "Chat Handler"
|
||||
participant Agent as "ACP Agent"
|
||||
participant Adapter as "ACP Adapter"
|
||||
Client->>Handler : 发送聊天请求
|
||||
Handler->>Agent : 创建代理服务
|
||||
Agent->>Adapter : 初始化连接
|
||||
Adapter->>Agent : 返回连接信息
|
||||
Agent->>Adapter : 发送Prompt请求
|
||||
Adapter->>Client : 流式返回响应
|
||||
Client->>Handler : 接收响应
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
|
||||
**本节源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [acp_adapter/src/types.rs](file://crates/acp_adapter/src/types.rs)
|
||||
- [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
### 代理服务管理分析
|
||||
代理服务管理器负责启动和管理不同类型的代理服务，通过统一的接口实现不同AI代理的接入。
|
||||
|
||||
#### 代理服务类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service()
|
||||
+agent_type_name()
|
||||
}
|
||||
class ClaudeCodeAgent {
|
||||
+start_claude_code_acp_agent_service()
|
||||
}
|
||||
class CodexAgent {
|
||||
+start_codex_acp_agent_service()
|
||||
}
|
||||
AcpAgentService <|-- ClaudeCodeAgent
|
||||
AcpAgentService <|-- CodexAgent
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
#### 代理启动流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([启动代理服务]) --> CheckExistence["检查代理是否存在"]
|
||||
CheckExistence --> |存在| Reuse["复用现有代理"]
|
||||
CheckExistence --> |不存在| Create["创建新代理"]
|
||||
Create --> StartProcess["启动子进程"]
|
||||
StartProcess --> Initialize["初始化ACP连接"]
|
||||
Initialize --> CreateSession["创建会话"]
|
||||
CreateSession --> SetupChannels["设置通信通道"]
|
||||
SetupChannels --> Monitor["监控代理状态"]
|
||||
Monitor --> End([代理服务启动完成])
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
**本节源**
|
||||
- [agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
### 会话状态管理分析
|
||||
会话状态管理器负责维护会话的生命周期和状态同步，确保消息的正确传递和状态的一致性。
|
||||
|
||||
#### 会话缓存流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[客户端建立SSE连接] --> B[创建SessionData]
|
||||
B --> C[插入SESSION_CACHE]
|
||||
C --> D[创建消息通道]
|
||||
D --> E[监听消息队列]
|
||||
E --> F[推送消息到客户端]
|
||||
F --> G{连接是否活跃?}
|
||||
G --> |是| E
|
||||
G --> |否| H[清理资源]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
|
||||
#### 消息处理流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "Handler"
|
||||
participant Cache as "SessionCache"
|
||||
participant Agent as "Agent"
|
||||
Client->>Handler : 建立SSE连接
|
||||
Handler->>Cache : 创建SessionData
|
||||
Cache->>Handler : 返回消息通道
|
||||
loop 消息处理
|
||||
Agent->>Cache : 发送消息
|
||||
Cache->>Handler : 推送消息
|
||||
Handler->>Client : 发送SSE事件
|
||||
end
|
||||
Client->>Handler : 断开连接
|
||||
Handler->>Cache : 清理资源
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [agent_runner/src/proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
|
||||
**本节源**
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_runner/src/handler/agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [agent_runner/src/proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
|
||||
## 依赖分析
|
||||
系统依赖关系清晰，各模块之间通过定义良好的接口进行通信，降低了耦合度。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[agent_runner] --> B[acp_adapter]
|
||||
A --> C[shared_types]
|
||||
B --> D[agent_client_protocol]
|
||||
C --> E[protobuf]
|
||||
style A fill:#f96,stroke:#333
|
||||
style B fill:#6f9,stroke:#333
|
||||
style C fill:#96f,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [crates/acp_adapter/Cargo.toml](file://crates/acp_adapter/Cargo.toml)
|
||||
|
||||
**本节源**
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [crates/acp_adapter/Cargo.toml](file://crates/acp_adapter/Cargo.toml)
|
||||
|
||||
## 性能考虑
|
||||
系统在设计时充分考虑了性能优化，主要体现在以下几个方面：
|
||||
|
||||
1. **连接复用**: 通过PROJECT_AND_AGENT_INFO_MAP静态映射，实现项目与代理服务的一对一复用，避免频繁创建和销毁代理服务。
|
||||
2. **异步处理**: 使用Tokio异步运行时，通过LocalSet管理非Send的ACP连接，确保高性能的异步I/O操作。
|
||||
3. **通道优化**: 采用无界通道(unbounded_channel)进行消息传递，避免阻塞，同时通过环形缓冲区(HeapRb)管理消息队列，提高内存使用效率。
|
||||
4. **锁优化**: 使用DashMap替代传统HashMap，提供高性能的并发访问，减少锁竞争。
|
||||
5. **资源管理**: 通过CancellationToken实现优雅的资源清理，确保代理服务在取消时能够正确释放资源。
|
||||
|
||||
**本节源**
|
||||
- [agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_runner/src/service/session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
|
||||
## 故障排除指南
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 代理启动失败
|
||||
**症状**: 启动代理服务时返回"启动ACP Agent服务失败"错误。
|
||||
|
||||
**可能原因**:
|
||||
1. 环境变量配置不正确
|
||||
2. 代理可执行文件未找到
|
||||
3. 项目目录权限问题
|
||||
|
||||
**解决方案**:
|
||||
1. 检查相关环境变量(如ANTHROPIC_API_KEY)是否正确设置
|
||||
2. 确认`claude-code-acp`或`codex-acp-agent`命令是否在PATH中
|
||||
3. 检查项目目录的读写权限
|
||||
|
||||
#### 消息推送中断
|
||||
**症状**: SSE连接建立后，消息推送突然中断。
|
||||
|
||||
**可能原因**:
|
||||
1. 代理服务异常退出
|
||||
2. 网络连接问题
|
||||
3. 超时设置过短
|
||||
|
||||
**解决方案**:
|
||||
1. 检查代理服务的日志输出
|
||||
2. 增加连接超时时间
|
||||
3. 实现客户端重连机制
|
||||
|
||||
#### 并发请求被拒绝
|
||||
**症状**: 连续发送多个请求时，后续请求返回"Agent正在执行任务"错误。
|
||||
|
||||
**原因**: 系统设计为每个项目ID对应一个代理服务，禁止并发请求以避免状态混乱。
|
||||
|
||||
**解决方案**:
|
||||
1. 等待当前任务完成后发送新请求
|
||||
2. 为不同任务使用不同的项目ID
|
||||
3. 实现请求队列机制
|
||||
|
||||
**本节源**
|
||||
- [agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [agent_runner/src/handler/agent_cancel_handler.rs](file://crates/agent_runner/src/handler/agent_cancel_handler.rs)
|
||||
- [agent_runner/src/proxy_agent/claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
|
||||
## 结论
|
||||
ACP代理集成系统通过清晰的分层架构和模块化设计，实现了与不同AI代理的统一接入。系统通过acp_adapter crate提供了协议抽象层，使得上层应用可以无缝切换不同的代理实现。通过高效的连接管理、状态同步和错误处理机制，系统确保了稳定可靠的通信。未来可以考虑增加更多类型的代理支持，以及优化资源利用率和响应性能。
|
||||
@@ -0,0 +1,333 @@
|
||||
# Claude Code代理实现
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向系统集成者与开发者，全面阐述Claude Code代理在rcoder中的实现细节与使用方式。重点覆盖以下方面：
|
||||
- 如何封装Claude Code代理的特定行为（子进程启动、ACPI/O协议交互、MCP服务器配置、会话管理等）
|
||||
- 初始化参数、运行时配置与自定义通信模式
|
||||
- 与通用代理框架的集成方式（AcpAgentService、AgentType、生命周期管理）
|
||||
- 特殊错误处理逻辑与异常传播机制
|
||||
- 性能特征、资源消耗模式与与其他代理的差异点
|
||||
- 配置示例与调用流程说明，帮助在系统中启用与使用Claude Code代理
|
||||
|
||||
## 项目结构
|
||||
Claude Code代理位于agent_runner的代理层，围绕“子进程+ACPI/O协议”的模式实现，配合通用代理框架与生命周期管理，形成稳定的运行时闭环。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "代理运行器"
|
||||
AR["agent_runner<br/>代理运行与调度"]
|
||||
ACP["ACPI/O客户端<br/>AcpAgentClient"]
|
||||
SVC["AcpAgentService<br/>统一启动接口"]
|
||||
CHU["通道工具<br/>channel_utils"]
|
||||
LIFECYCLE["生命周期守卫<br/>AgentLifecycleGuard"]
|
||||
end
|
||||
subgraph "Claude Code库"
|
||||
LIB["claude-code-agent<br/>lib.rs"]
|
||||
UTIL["util.rs<br/>安装/命令/状态管理"]
|
||||
end
|
||||
subgraph "共享类型"
|
||||
AT["AgentType<br/>代理类型"]
|
||||
AM["Agent模型<br/>AgentStatus/ProjectAndAgentInfo"]
|
||||
ERR["AppError<br/>应用错误"]
|
||||
MCP["MCP配置<br/>create_default_mcp_servers"]
|
||||
end
|
||||
AR --> SVC
|
||||
SVC --> |"Claude"| AR
|
||||
AR --> |"启动子进程"| LIB
|
||||
LIB --> UTIL
|
||||
AR --> |"会话/通道"| CHU
|
||||
AR --> |"生命周期管理"| LIFECYCLE
|
||||
AR --> |"模型/环境变量"| AT
|
||||
AR --> |"会话状态/错误"| AM
|
||||
AR --> |"错误处理"| ERR
|
||||
AR --> |"MCP服务器"| MCP
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs#L1-L9)
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs#L1-L9)
|
||||
|
||||
## 核心组件
|
||||
- Claude Code代理启动器：负责启动子进程、建立ACPI/O连接、创建会话、配置MCP服务器、管理通道与生命周期。
|
||||
- 通用代理服务接口：AcpAgentService为不同代理类型提供统一启动入口，Claude分支委托给claude_code_agent.rs。
|
||||
- 通道工具：统一处理取消与Prompt请求的发送、超时保护、状态更新与错误上报。
|
||||
- 生命周期管理：AgentLifecycleGuard封装子进程、stderr任务与取消令牌，支持优雅停止与强制清理。
|
||||
- 模型/环境变量映射：AgentType提供Claude所需的环境变量映射，支持从配置覆盖与环境变量注入。
|
||||
- MCP服务器配置：默认启用context7与fetch等MCP服务器，便于增强能力。
|
||||
- Claude Code库：提供安装、命令选择、状态检查与登录命令生成等辅助能力。
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
|
||||
## 架构总览
|
||||
Claude Code代理采用“子进程+ACPI/O协议”的架构，通过AgentType与AcpAgentService抽象，实现与通用代理框架的无缝集成；同时利用生命周期守卫与通道工具，保障运行时稳定性与可观测性。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Caller as "调用方"
|
||||
participant AcpSvc as "AcpAgentService"
|
||||
participant Runner as "Claude启动器"
|
||||
participant Proc as "子进程(claude-code-acp)"
|
||||
participant AcpCli as "ACPI/O客户端"
|
||||
participant Utils as "通道工具"
|
||||
participant Life as "生命周期守卫"
|
||||
Caller->>AcpSvc : "start_agent_service(chat_prompt, model_provider)"
|
||||
AcpSvc->>Runner : "start_claude_code_acp_agent_service(...)"
|
||||
Runner->>Proc : "spawn子进程(工作目录/环境变量)"
|
||||
Runner->>AcpCli : "ClientSideConnection.new(...)"
|
||||
Runner->>AcpCli : "initialize(...)"
|
||||
Runner->>AcpCli : "new_session/load_session(...)"
|
||||
Runner->>Utils : "spawn_cancel_handler_for_agent(...)"
|
||||
Runner->>Utils : "spawn_prompt_handler_for_agent(...)"
|
||||
Runner->>Life : "new_claude(...)"
|
||||
Runner-->>Caller : "返回AcpConnectionInfo(会话ID/通道/停止句柄)"
|
||||
Note over Runner,AcpCli : "stderr读取任务独立运行"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Claude Code代理启动器（claude_code_agent.rs）
|
||||
- 启动子进程：以claude-code-acp为命令，合并模型提供商配置生成环境变量，设置工作目录，捕获stdin/stdout/stderr。
|
||||
- ACPI/O连接：使用ClientSideConnection建立双向通信，LocalSet保证非Send任务在本地线程运行。
|
||||
- 初始化与会话：initialize后尝试load_session（兼容未来SDK），失败则回退new_session；会话ID通过oneshot通道返回。
|
||||
- MCP服务器：通过create_default_mcp_servers创建context7与fetch等服务器，注入会话请求。
|
||||
- 通道与任务：spawn_cancel_handler_for_agent与spawn_prompt_handler_for_agent分别处理取消与Prompt；stderr独立任务读取并记录。
|
||||
- 生命周期：new_claude创建AgentLifecycleGuard，结合CancellationToken与子进程/stderr任务，支持优雅停止与强制清理。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动Claude代理"]) --> Spawn["启动子进程<br/>合并环境变量/工作目录"]
|
||||
Spawn --> IO["创建ACPI/O连接<br/>ClientSideConnection"]
|
||||
IO --> Init["initialize()"]
|
||||
Init --> Session{"load_session成功？"}
|
||||
Session --> |是| GotSession["使用已有会话ID"]
|
||||
Session --> |否| NewSession["new_session()"]
|
||||
GotSession --> Ready["会话就绪"]
|
||||
NewSession --> Ready
|
||||
Ready --> MCP["配置MCP服务器(context7/ fetch)"]
|
||||
MCP --> Channels["启动取消/Prompt通道任务"]
|
||||
Channels --> Stderr["启动stderr读取任务"]
|
||||
Stderr --> Guard["创建生命周期守卫"]
|
||||
Guard --> Done(["返回AcpConnectionInfo"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
|
||||
### 通用代理服务接口（agent_service.rs）
|
||||
- AcpAgentService为不同代理类型提供统一启动入口，Claude分支委托给claude_code_agent.rs。
|
||||
- AgentType::Claude实现agent_type_name返回“Claude”，便于日志与监控识别。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
|
||||
### 通道工具（channel_utils.rs）
|
||||
- 取消处理：超时保护（默认10秒），发送CancelNotification，返回成功/失败响应，并将Agent状态恢复为Idle。
|
||||
- Prompt处理：校验session_id一致性，提取request_id写入会话上下文MAP，发送SessionPromptStart；成功发送SessionPromptEnd，失败发送SessionPromptError与SessionPromptEnd。
|
||||
- 状态管理：通过PROJECT_AND_AGENT_INFO_MAP更新Agent状态与最后活动时间。
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### 生命周期管理（agent_model.rs）
|
||||
- AgentLifecycleGuard封装Claude资源（子进程、stderr任务、取消令牌），支持graceful_stop与force_cleanup。
|
||||
- 提供cancel、is_stopped、cancellation_token、agent_type等统一接口，实现AgentLifecycle trait。
|
||||
- Drop时自动清理，确保资源不泄漏。
|
||||
|
||||
章节来源
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### 模型/环境变量映射（agent_type.rs）
|
||||
- Claude环境变量映射：从进程环境变量聚合ANTHROPIC_*键，固定开启“跳过权限”参数，支持从ModelProviderConfig覆盖。
|
||||
- 从ModelProviderConfig推断Agent类型：anthropic->Claude，默认Claude。
|
||||
|
||||
章节来源
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
|
||||
### MCP服务器配置（mcp_config.rs）
|
||||
- 默认启用context7与fetch MCP服务器，不使用API密钥，提供基础能力。
|
||||
- 提供创建默认MCP服务器列表的函数，便于在会话创建时注入。
|
||||
|
||||
章节来源
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
|
||||
### Claude Code库（util.rs/lib.rs）
|
||||
- ClaudeCodeAcpManager：安装/更新、状态检查、命令获取、登录命令生成、清理旧版本等。
|
||||
- ClaudeCodeAcpConfig：最小版本、包名、入口路径、二进制名、自定义命令、忽略系统版本等。
|
||||
- lib.rs：导出util模块，提供安装与命令相关便捷函数。
|
||||
|
||||
章节来源
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs#L1-L9)
|
||||
|
||||
### 与通用代理框架的集成（acp_agent.rs）
|
||||
- 通过AgentType::start_agent_service分派到Claude实现，创建ProjectAndAgentInfo并插入全局映射。
|
||||
- 若模型配置变化，触发Agent重启；否则复用现有Agent服务，直接发送Prompt请求。
|
||||
- 构建PromptRequest时将request_id放入meta，便于通道工具提取与上下文关联。
|
||||
|
||||
章节来源
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
|
||||
## 依赖关系分析
|
||||
- Claude启动器依赖：
|
||||
- AgentType（环境变量映射、代理类型）
|
||||
- AcpAgentClient/AcpConnectionInfo（ACPI/O连接信息）
|
||||
- create_default_mcp_servers（MCP服务器）
|
||||
- channel_utils（取消/Prompt通道）
|
||||
- AgentLifecycleGuard（生命周期）
|
||||
- 通用代理服务：
|
||||
- AcpAgentService为AgentType实现具体代理启动逻辑
|
||||
- Claude Code库：
|
||||
- util.rs提供安装与命令管理能力，lib.rs导出
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
AT["AgentType"] --> SVC["AcpAgentService"]
|
||||
SVC --> CC["Claude启动器"]
|
||||
CC --> CHU["通道工具"]
|
||||
CC --> LIFECYCLE["生命周期守卫"]
|
||||
CC --> MCP["MCP配置"]
|
||||
CC --> LIB["claude-code-agent(lib)"]
|
||||
LIB --> UTIL["util.rs"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs#L1-L9)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [lib.rs](file://crates/claude-code-agent/src/lib.rs#L1-L9)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
|
||||
## 性能考量
|
||||
- 子进程与I/O：
|
||||
- 子进程stdin/stdout/stderr通过tokio::process与tokio-util compat封装，避免阻塞。
|
||||
- ACPI/O连接在LocalSet中运行，避免跨线程Send限制。
|
||||
- 通道与任务：
|
||||
- 取消/Prompt通道均为无缓冲或有限缓冲，避免内存膨胀；stderr独立任务降低主循环压力。
|
||||
- 取消超时保护（默认10秒），防止阻塞导致的资源占用。
|
||||
- 会话与复用：
|
||||
- 以project_id为维度复用Agent服务，减少重复启动成本；模型配置变更时触发重启，避免状态污染。
|
||||
- MCP服务器：
|
||||
- 默认启用context7/ fetch，按需扩展，避免不必要的依赖。
|
||||
- 资源清理：
|
||||
- 生命周期守卫支持优雅停止与强制清理，避免僵尸进程与资源泄漏。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败：
|
||||
- 子进程无法启动：检查claude-code-acp命令是否存在、工作目录权限、环境变量是否正确注入。
|
||||
- ACPI/O初始化失败：查看initialize返回错误，确认协议版本与客户端信息。
|
||||
- 会话创建失败：回退load_session失败时自动new_session，若仍失败，检查MCP服务器配置与网络访问。
|
||||
- 运行时错误：
|
||||
- 取消超时：通道工具默认10秒超时，适当调整或检查远端Agent处理能力。
|
||||
- 通道发送失败：检查接收端是否关闭，或上游是否频繁重启。
|
||||
- stderr异常：stderr任务独立运行，注意日志中警告与错误行。
|
||||
- 生命周期问题：
|
||||
- 优雅停止无效：确认CancellationToken是否被正确取消，子进程与stderr任务是否被清理。
|
||||
- 资源泄漏：检查Drop逻辑是否触发，必要时强制清理。
|
||||
|
||||
章节来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
## 结论
|
||||
Claude Code代理通过“子进程+ACPI/O协议”的稳定架构，结合通用代理框架与生命周期管理，提供了可复用、可观测、可扩展的代理实现。其特性包括：
|
||||
- 明确的初始化与会话管理流程
|
||||
- 可配置的MCP服务器与环境变量映射
|
||||
- 统一的取消/Prompt通道与状态管理
|
||||
- 完备的生命周期与资源清理
|
||||
- 与通用代理框架的无缝集成
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置示例与调用流程
|
||||
- 启用Claude Code代理：
|
||||
- 在配置中将default_agent设为Claude，或通过AgentType::Claude显式指定。
|
||||
- 确保环境变量包含ANTHROPIC_*（如ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL等），或通过ModelProviderConfig注入。
|
||||
- 启动时会自动尝试加载或安装claude-code-acp，必要时可使用登录命令生成凭据。
|
||||
- 调用流程：
|
||||
- 调用AcpAgentService::start_agent_service(chat_prompt, model_provider)
|
||||
- 返回AcpConnectionInfo，包含session_id、prompt_tx、cancel_tx与stop_handle
|
||||
- 通过prompt_tx发送PromptRequest，通过cancel_tx发送CancelNotification
|
||||
- 使用stop_handle进行优雅停止或强制清理
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [util.rs](file://crates/claude-code-agent/src/util.rs#L1-L758)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L308-L375)
|
||||
@@ -0,0 +1,364 @@
|
||||
# Codex代理实现
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs)
|
||||
- [crates/agent_runner/src/utils/mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [crates/shared_types/src/model/agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [crates/codex-acp-agent/src/lib.rs](file://crates/codex-acp-agent/src/lib.rs)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“Codex代理实现”的技术文档，聚焦于rcoder工程中codex_agent模块的设计与实现，阐述其与Codex ACP代理的交互方式、启动流程、命令执行与结果解析，以及特定于Codex代理的配置选项、性能特征与限制条件。同时记录与通用代理运行时环境的集成细节，以及与其他AI代理的兼容性处理，并提供实际使用示例与最佳实践建议。
|
||||
|
||||
## 项目结构
|
||||
- 代码组织采用多crate工作区，核心运行时位于agent_runner，Codex ACP代理以独立二进制形式存在，通过子进程方式启动并与主服务建立ACP连接。
|
||||
- 关键模块：
|
||||
- codex_agent：负责启动Codex ACP子进程、建立ACP连接、会话管理、Prompt与取消处理。
|
||||
- acp_agent：通用代理服务调度与复用逻辑，按项目维度管理Agent生命周期。
|
||||
- channel_utils：统一的Prompt与Cancel通道处理，封装会话通知与状态更新。
|
||||
- agent_service：ACP代理服务抽象与实现选择（Codex/Claude）。
|
||||
- agent_stop_handle：生命周期守卫，统一优雅停止与资源回收。
|
||||
- mcp_config：默认MCP服务器配置，增强代理能力。
|
||||
- shared_types：跨crate共享的数据结构与生命周期接口。
|
||||
- codex-acp-agent：Codex ACP代理二进制入口与库导出。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "运行时"
|
||||
AR["agent_runner<br/>代理运行时"]
|
||||
CFG["配置系统<br/>config.rs"]
|
||||
ST["共享类型<br/>shared_types"]
|
||||
end
|
||||
subgraph "Codex ACP"
|
||||
BIN["codex-acp-agent 二进制<br/>bin/codex-acp-agent.rs"]
|
||||
LIB["codex-acp-agent 库<br/>lib.rs"]
|
||||
end
|
||||
subgraph "协议与工具"
|
||||
ACP["Agent Client Protocol<br/>外部协议"]
|
||||
MCP["MCP 服务器配置<br/>mcp_config.rs"]
|
||||
end
|
||||
AR --> BIN
|
||||
AR --> ST
|
||||
AR --> CFG
|
||||
AR --> MCP
|
||||
BIN --> ACP
|
||||
LIB --> ACP
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/agent_runner/src/utils/mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs#L1-L46)
|
||||
- [crates/codex-acp-agent/src/lib.rs](file://crates/codex-acp-agent/src/lib.rs#L1-L18)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/agent_runner/src/utils/mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs#L1-L46)
|
||||
- [crates/codex-acp-agent/src/lib.rs](file://crates/codex-acp-agent/src/lib.rs#L1-L18)
|
||||
|
||||
## 核心组件
|
||||
- Codex ACP子进程启动与连接管理：负责启动codex-acp-agent二进制、准备环境变量与CLI覆盖参数、建立ClientSideConnection、初始化ACP、创建/加载会话、管理stderr输出与生命周期。
|
||||
- 代理服务调度与复用：按项目维度缓存Agent信息，支持模型配置变化时的重启，复用现有Agent减少启动开销。
|
||||
- 通道处理工具：统一处理Prompt与Cancel请求，发送会话开始/结束/错误通知，更新Agent状态。
|
||||
- 生命周期守卫：统一管理子进程与stderr任务，支持优雅停止与强制清理。
|
||||
- MCP服务器配置：默认启用context7与fetch等MCP服务器，增强代理能力。
|
||||
- 配置系统：命令行、环境变量、配置文件与默认配置的多层优先级。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L82-L126)
|
||||
- [crates/agent_runner/src/utils/mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
|
||||
## 架构总览
|
||||
Codex代理通过子进程方式与主服务交互，主服务负责：
|
||||
- 选择Agent类型（Codex/Claude），并调用相应启动函数。
|
||||
- 为Codex准备模型提供商配置与环境变量，构建CLI覆盖参数。
|
||||
- 启动codex-acp-agent二进制，建立ACP连接，初始化会话。
|
||||
- 通过通道将用户Prompt发送到代理，接收结果并通过SSE通知前端。
|
||||
- 管理生命周期，支持取消与优雅停止。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Runner as "代理运行时<br/>acp_agent.rs"
|
||||
participant Codex as "Codex ACP 启动器<br/>codex_agent.rs"
|
||||
participant Proc as "子进程<br/>codex-acp-agent"
|
||||
participant Conn as "ACP 连接"
|
||||
participant Chan as "通道处理<br/>channel_utils.rs"
|
||||
Client->>Runner : "提交聊天请求"
|
||||
Runner->>Codex : "start_codex_acp_agent_service(...)"
|
||||
Codex->>Proc : "spawn 子进程并传入CLI覆盖参数"
|
||||
Proc-->>Conn : "建立ClientSideConnection"
|
||||
Codex->>Conn : "initialize / new_session"
|
||||
Conn-->>Codex : "返回SessionId"
|
||||
Runner->>Chan : "发送PromptRequest"
|
||||
Chan->>Conn : "prompt(...)"
|
||||
Conn-->>Chan : "返回结果/错误"
|
||||
Chan-->>Runner : "推送Session通知"
|
||||
Runner-->>Client : "SSE 实时进度/结果"
|
||||
Client->>Runner : "取消请求"
|
||||
Runner->>Chan : "发送Cancel通知"
|
||||
Chan->>Conn : "cancel(...)"
|
||||
Conn-->>Chan : "取消结果"
|
||||
Chan-->>Runner : "推送Session结束"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs#L1-L46)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Codex ACP启动与会话管理
|
||||
- 启动流程
|
||||
- 依据ModelProviderConfig生成环境变量与CLI覆盖参数，固定使用“custom”模型提供商名称，确保与后续配置一致。
|
||||
- 通过tokio::process::Command启动codex-acp-agent二进制，设置stdin/stdout/stderr管道与工作目录。
|
||||
- 建立ClientSideConnection并初始化ACP，随后创建或加载会话，返回会话ID与Prompt/Cancel通道。
|
||||
- 启动stderr读取任务，将子进程输出转发到日志。
|
||||
- 创建生命周期守卫，绑定项目ID、会话ID、子进程与取消令牌，支持优雅停止。
|
||||
- 命令执行与结果解析
|
||||
- 通过通道将PromptRequest发送到代理，代理执行后返回stop_reason等信息。
|
||||
- 通道处理工具负责将开始、结束、错误等会话通知推送给前端。
|
||||
- 取消与错误处理
|
||||
- 通过CancelNotification在超时时间内调用代理cancel，超时则返回超时响应。
|
||||
- 后台任务失败时，通过Prompt通道发送错误内容块，触发错误通知与结束事件。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动Codex ACP子进程"]) --> Env["准备环境变量与CLI覆盖参数"]
|
||||
Env --> Spawn["spawn 子进程"]
|
||||
Spawn --> IO["建立ClientSideConnection"]
|
||||
IO --> Init["initialize / new_session"]
|
||||
Init --> Session["获得SessionId"]
|
||||
Session --> Prompt["发送PromptRequest"]
|
||||
Prompt --> Result{"执行结果"}
|
||||
Result --> |成功| NotifyOK["推送SessionPromptEnd"]
|
||||
Result --> |失败| NotifyErr["推送SessionPromptError<br/>再推送SessionPromptEnd"]
|
||||
NotifyOK --> Stop["优雅停止/取消"]
|
||||
NotifyErr --> Stop
|
||||
Stop --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
### 代理服务调度与复用
|
||||
- 项目维度的Agent复用：以DashMap存储ProjectAndAgentInfo，按project_id映射到Agent服务，避免重复启动。
|
||||
- 模型配置变化检测：当ModelProviderConfig变化时，删除旧Agent并重建新Agent，保证配置一致性。
|
||||
- Prompt构建：将系统提示词、用户输入与附件合并为ContentBlocks，注入request_id到meta，便于会话上下文追踪。
|
||||
- 会话通知：通过push_session_update_with_project推送SessionPromptStart/End/Error事件。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
+start_agent_service(chat_prompt, model_provider) AcpConnectionInfo
|
||||
+agent_type_name() str
|
||||
}
|
||||
class AgentType {
|
||||
+from_model_provider(model_provider) AgentType
|
||||
+codex_model_provider(model_provider) (ConfigToml, envs)
|
||||
}
|
||||
class AcpAgentWorker {
|
||||
+agent_worker(request_rx)
|
||||
+build_prompt_to_acp_agent(prompt, session_id) PromptRequest
|
||||
}
|
||||
class ProjectAndAgentInfo {
|
||||
+project_id : string
|
||||
+session_id : SessionId
|
||||
+prompt_tx : mpsc
|
||||
+cancel_tx : mpsc
|
||||
+model_provider : Option<ModelProviderConfig>
|
||||
+status : AgentStatus
|
||||
+last_activity : DateTime
|
||||
+created_at : DateTime
|
||||
+stop_handle : Option<AgentLifecycle>
|
||||
}
|
||||
AcpAgentService <|.. AgentType : "实现"
|
||||
AcpAgentWorker --> AcpAgentService : "调用"
|
||||
AcpAgentWorker --> ProjectAndAgentInfo : "读写"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/shared_types/src/model/agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [crates/shared_types/src/model/agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
|
||||
### 生命周期与资源管理
|
||||
- 生命周期守卫：统一管理子进程与stderr任务，支持graceful_stop、cancel、force_cleanup等操作。
|
||||
- 资源类型：CodexSubProcess与Claude类似，均包含child_process与stderr_task。
|
||||
- 取消令牌：通过CancellationToken协调取消信号，确保任务自然退出后再强制清理。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> 启动
|
||||
启动 --> 运行中 : "子进程启动/会话创建"
|
||||
运行中 --> 取消中 : "收到取消信号"
|
||||
取消中 --> 停止中 : "超时/取消完成"
|
||||
停止中 --> 已停止 : "优雅停止/强制清理"
|
||||
已停止 --> [*]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L82-L126)
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L82-L126)
|
||||
|
||||
### MCP服务器与能力增强
|
||||
- 默认MCP服务器：context7与fetch，用于扩展代理能力（如网络访问、前端模板等）。
|
||||
- 配置生成：create_default_mcp_servers返回MCP服务器列表，可在会话创建时传入。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/utils/mcp_config.rs](file://crates/agent_runner/src/utils/mcp_config.rs#L1-L225)
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L228-L246)
|
||||
|
||||
### 配置与兼容性
|
||||
- 模型提供商配置：ModelProviderConfig包含id/name/base_url/api_key/requires_openai_auth/default_model/api_protocol等字段。
|
||||
- Agent类型映射：AgentType::from_model_provider根据provider.name映射到Codex/Claude。
|
||||
- 环境变量与CLI覆盖：Codex通过codex_model_provider生成环境变量与CLI覆盖参数，固定使用“custom”模型提供商名称。
|
||||
- 兼容性：AgentType实现AcpAgentService，支持按AgentType选择启动函数；README提供多代理配置示例。
|
||||
|
||||
章节来源
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L1-L132)
|
||||
- [crates/shared_types/src/model/agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L1-L257)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [README.md](file://README.md#L107-L130)
|
||||
|
||||
## 依赖关系分析
|
||||
- 运行时依赖
|
||||
- agent_client_protocol：ACP协议类型与ClientSideConnection。
|
||||
- tokio/tokio-util：异步运行时与流适配。
|
||||
- tracing/dashmap：日志与并发Map。
|
||||
- 外部二进制
|
||||
- codex-acp-agent：通过子进程方式运行，支持-cli覆盖配置。
|
||||
- 共享类型
|
||||
- AgentType、ModelProviderConfig、AgentLifecycle等跨crate共享。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
codex_agent["codex_agent.rs"] --> acp_proto["agent_client_protocol"]
|
||||
codex_agent --> tokio["tokio/tokio_util"]
|
||||
codex_agent --> tracing_dash["tracing/dashmap"]
|
||||
acp_agent["acp_agent.rs"] --> shared_types["shared_types"]
|
||||
channel_utils["channel_utils.rs"] --> shared_types
|
||||
agent_service["agent_service.rs"] --> shared_types
|
||||
codex_bin["codex-acp-agent 二进制"] --> codex_lib["codex-acp-agent 库"]
|
||||
codex_lib --> acp_proto
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/codex-acp-agent/src/lib.rs](file://crates/codex-acp-agent/src/lib.rs#L1-L18)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs#L1-L46)
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L1-L398)
|
||||
- [crates/agent_runner/src/proxy_agent/acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L1-L392)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [crates/codex-acp-agent/src/lib.rs](file://crates/codex-acp-agent/src/lib.rs#L1-L18)
|
||||
- [crates/codex-acp-agent/src/bin/codex-acp-agent.rs](file://crates/codex-acp-agent/src/bin/codex-acp-agent.rs#L1-L46)
|
||||
|
||||
## 性能考量
|
||||
- 启动开销
|
||||
- 子进程启动与ACP初始化带来额外开销；通过项目维度复用Agent可显著降低重复启动成本。
|
||||
- 模型配置变化触发Agent重启，应在配置稳定时减少频繁变更。
|
||||
- I/O与通道
|
||||
- Prompt与Cancel通过无阻塞通道传输，避免阻塞主循环；通道处理工具对取消调用设置超时，防止阻塞。
|
||||
- MCP服务器
|
||||
- 默认启用context7与fetch等MCP服务器，可能增加额外I/O与资源消耗；可根据需求裁剪。
|
||||
- 日志与stderr
|
||||
- 后台stderr读取任务在取消时会退出，避免长时间占用；建议在生产环境合理设置日志级别。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败
|
||||
- 检查codex-acp-agent二进制是否可执行、CLI覆盖参数是否正确、环境变量是否包含API密钥。
|
||||
- 查看stderr任务输出，定位初始化失败原因（如base_url/api_key/model_provider配置错误）。
|
||||
- 取消超时
|
||||
- 通道处理工具对cancel调用设置了超时保护，超时会返回超时响应；适当调整代理侧处理能力或网络状况。
|
||||
- 会话不一致
|
||||
- 通道处理工具会在收到Prompt时强制覆盖session_id为当前会话，确保一致性；若出现异常，检查会话ID传递与Meta字段。
|
||||
- 生命周期清理
|
||||
- 优雅停止会先发送取消信号，再强制清理子进程与stderr任务；若出现僵尸进程，检查取消令牌与Drop逻辑。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L313-L335)
|
||||
- [crates/agent_runner/src/proxy_agent/channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
## 结论
|
||||
Codex代理通过子进程与ACP协议实现与主服务的解耦集成，具备良好的可配置性与可扩展性。通过项目维度的Agent复用、统一的通道处理与生命周期管理，系统在稳定性与性能之间取得平衡。结合MCP服务器与模型提供商配置，可灵活适配多种场景。建议在生产环境中关注stderr日志、取消超时与模型配置变更策略，以提升整体可靠性。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 使用示例与最佳实践
|
||||
- 启动与配置
|
||||
- 使用命令行参数或环境变量设置端口与项目目录；首次运行会自动生成默认配置文件。
|
||||
- Codex代理需要正确的API密钥与base_url；可通过ModelProviderConfig或环境变量注入。
|
||||
- 交互流程
|
||||
- 提交聊天请求后，系统会按项目维度复用Agent；若模型配置变化则自动重启Agent。
|
||||
- 通过SSE实时接收会话开始、结束与错误通知；支持取消正在执行的任务。
|
||||
- 最佳实践
|
||||
- 将模型配置与API密钥集中管理，避免频繁变更导致Agent重启。
|
||||
- 合理裁剪MCP服务器，减少不必要的I/O与资源消耗。
|
||||
- 在生产环境开启适当的日志级别，便于快速定位问题。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [crates/shared_types/src/model/model_provider.rs](file://crates/shared_types/src/model/model_provider.rs#L1-L132)
|
||||
- [README.md](file://README.md#L440-L527)
|
||||
249
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/代理服务.md
Normal file
249
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/代理服务.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 代理服务
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [docker_manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [介绍](#介绍)
|
||||
2. [核心组件](#核心组件)
|
||||
3. [代理服务设计与实现](#代理服务设计与实现)
|
||||
4. [与Docker管理器的集成](#与docker管理器的集成)
|
||||
5. [异步任务调度与会话管理](#异步任务调度与会话管理)
|
||||
6. [错误恢复与生命周期管理](#错误恢复与生命周期管理)
|
||||
7. [与ACP适配器的交互模式](#与acp适配器的交互模式)
|
||||
8. [多代理类型支持](#多代理类型支持)
|
||||
9. [服务初始化与关闭逻辑](#服务初始化与关闭逻辑)
|
||||
10. [结论](#结论)
|
||||
|
||||
## 介绍
|
||||
代理服务是AI开发平台的核心组件，负责管理AI代理的整个生命周期。该服务通过统一的接口抽象，支持多种AI代理类型（如Codex、Claude Code），并利用容器化技术实现资源隔离和高效管理。本文档详细阐述了代理服务的设计与实现，重点分析了AgentService结构体的核心作用、与Docker管理器的集成方式、异步任务调度机制以及错误恢复策略。
|
||||
|
||||
## 核心组件
|
||||
代理服务的核心组件包括AgentService结构体、Docker管理器、会话缓存和清理任务。这些组件协同工作，确保AI代理的高效、稳定运行。AgentService结构体作为统一接口，封装了不同代理类型的启动和管理逻辑。Docker管理器负责容器的创建、启动和销毁，实现资源的动态分配和隔离。会话缓存用于存储和管理会话状态，支持SSE（Server-Sent Events）实时消息推送。清理任务则定期检查并清理闲置的代理实例，优化资源利用率。
|
||||
|
||||
## 代理服务设计与实现
|
||||
代理服务的设计遵循模块化和可扩展的原则，通过定义清晰的接口和抽象，实现了不同代理类型的统一管理。核心是`AcpAgentService` trait，它定义了启动和管理ACP代理服务的统一接口。该trait的实现通过为`AgentType`枚举类型提供`async_trait`，实现了对不同代理类型的统一处理。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class AgentType {
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
AcpAgentService <|-- AgentType
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L61)
|
||||
|
||||
`AcpConnectionInfo`结构体封装了与代理通信所需的关键信息，包括会话ID、用于发送提示的通道、用于发送取消通知的通道以及代理停止句柄。这种设计使得外部组件可以通过这些通道与代理进行异步通信，实现了非阻塞的消息传递。
|
||||
|
||||
**本节源码**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L31-L41)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L31-L41)
|
||||
|
||||
## 与Docker管理器的集成
|
||||
代理服务通过`docker_manager` crate与Docker守护进程进行交互，实现了AI代理的容器化运行。`DockerManager`结构体作为核心管理器，封装了Docker客户端和配置信息，提供了创建、启动、停止和清理容器的高级接口。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 代理服务
|
||||
participant Docker管理器
|
||||
participant Docker守护进程
|
||||
代理服务->>Docker管理器 : create_container(config)
|
||||
Docker管理器->>Docker守护进程 : 检查镜像是否存在
|
||||
alt 镜像不存在
|
||||
Docker守护进程-->>Docker管理器 : 返回不存在
|
||||
Docker管理器->>Docker守护进程 : pull_image(image)
|
||||
end
|
||||
Docker管理器->>Docker守护进程 : create_container(options, config)
|
||||
Docker守护进程-->>Docker管理器 : container_id
|
||||
Docker管理器->>Docker守护进程 : start_container(container_id)
|
||||
Docker守护进程-->>Docker管理器 : 启动成功
|
||||
Docker管理器-->>代理服务 : DockerContainerInfo
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker_manager.rs](file://crates/docker_manager/src/manager.rs#L81-L294)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L129)
|
||||
|
||||
`DockerManager`的`create_container`方法是容器化运行AI代理实例的关键。该方法首先检查指定的镜像是否存在于本地，如果不存在则从远程仓库拉取。然后，它使用提供的配置创建容器，包括挂载点、环境变量、端口映射和资源限制。最后，启动容器并返回包含容器信息的`DockerContainerInfo`结构体。这种设计确保了每个AI代理实例都在独立的容器环境中运行，实现了资源隔离和安全防护。
|
||||
|
||||
**本节源码**
|
||||
- [docker_manager.rs](file://crates/docker_manager/src/manager.rs#L81-L294)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L21-L129)
|
||||
|
||||
## 异步任务调度与会话管理
|
||||
代理服务采用异步任务调度机制，通过`tokio`运行时和`mpsc`通道实现高效的并发处理。`AcpAgentClient`结构体实现了`agent_client_protocol::Client` trait，处理来自代理的会话通知。当收到`session_notification`时，它会解析通知内容，提取`request_id`，并将其与`session_id`关联，然后将更新推送到全局会话缓存。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([收到session_notification]) --> ExtractSessionId["提取session_id"]
|
||||
ExtractSessionId --> CheckMeta["检查meta中是否有request_id"]
|
||||
CheckMeta --> |有| UseMetaId["使用meta中的request_id"]
|
||||
CheckMeta --> |无| FindProjectId["通过session_id查找project_id"]
|
||||
FindProjectId --> GetRequestId["从SESSION_REQUEST_CONTEXT获取request_id"]
|
||||
GetRequestId --> |获取成功| UseContextId["使用context中的request_id"]
|
||||
GetRequestId --> |获取失败| NoRequestId["未找到request_id"]
|
||||
UseMetaId --> PushUpdate["推送AgentSessionUpdate"]
|
||||
UseContextId --> PushUpdate
|
||||
NoRequestId --> PushUpdate
|
||||
PushUpdate --> End([完成])
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L232-L257)
|
||||
|
||||
会话管理通过`SESSION_CACHE`和`PROJECT_SESSION_MAP`两个全局`DashMap`实现。`SESSION_CACHE`以`session_id`为键，存储`SessionData`，后者包含用于SSE消息推送的通道和取消令牌。`PROJECT_SESSION_MAP`则维护`project_id`到`session_id`的映射，确保一个项目只对应一个活跃的会话。`push_session_update_with_project`函数在推送消息时，会自动检查并清理旧的会话数据，保证了会话状态的一致性。
|
||||
|
||||
**本节源码**
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L16-L355)
|
||||
|
||||
## 错误恢复与生命周期管理
|
||||
代理服务通过`AgentLifecycleGuard`结构体实现基于RAII（Resource Acquisition Is Initialization）原则的生命周期管理。当`AgentLifecycleGuard`被`drop`时，其内部的`Drop`实现会自动清理代理资源，如停止子进程和取消异步任务。这种设计简化了资源管理，避免了资源泄漏。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentLifecycleGuard {
|
||||
+new_claude(...) AgentLifecycleGuard
|
||||
+new_codex(...) AgentLifecycleGuard
|
||||
+graceful_stop() Result~()~
|
||||
+cancel()
|
||||
+is_stopped() bool
|
||||
}
|
||||
class AgentResources {
|
||||
<<enumeration>>
|
||||
+Claude
|
||||
+CodexSubProcess
|
||||
+CodexEmbedded
|
||||
}
|
||||
AgentLifecycleGuard --> AgentLifecycleInner : 包含
|
||||
AgentLifecycleInner --> AgentResources : 包含
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L326)
|
||||
|
||||
`AgentLifecycleGuard`的`graceful_stop`方法实现了优雅停止代理的逻辑。它首先发送取消信号，然后根据代理类型执行相应的清理操作，如等待子进程退出或取消异步任务。`cancel`方法则用于非阻塞地发送取消信号。`is_stopped`方法检查代理是否已停止。这些方法共同构成了一个健壮的错误恢复机制，确保在各种异常情况下都能正确清理资源。
|
||||
|
||||
**本节源码**
|
||||
- [agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L140-L204)
|
||||
|
||||
## 与ACP适配器的交互模式
|
||||
代理服务通过`AcpAgentClient`与ACP（Agent Client Protocol）适配器进行交互。`AcpAgentClient`实现了`agent_client_protocol::Client` trait，处理来自代理的各种请求，如权限请求、文件读写和会话通知。当代理需要执行文件操作时，`AcpAgentClient`会调用相应的`tokio::fs`函数，并将结果返回给代理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 代理
|
||||
participant AcpAgentClient
|
||||
participant 文件系统
|
||||
代理->>AcpAgentClient : write_text_file(args)
|
||||
AcpAgentClient->>文件系统 : create_dir_all(parent)
|
||||
文件系统-->>AcpAgentClient : 创建成功
|
||||
AcpAgentClient->>文件系统 : create_file(path)
|
||||
文件系统-->>AcpAgentClient : 文件句柄
|
||||
AcpAgentClient->>文件系统 : write_all(content)
|
||||
文件系统-->>AcpAgentClient : 写入成功
|
||||
AcpAgentClient-->>代理 : WriteTextFileResponse
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L78-L98)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L100-L110)
|
||||
|
||||
`AcpAgentClient`还负责处理会话通知，如`AgentMessageChunk`和`AgentMessageComplete`。它将这些通知转换为`UnifiedSessionMessage`，并通过`push_session_update`函数推送到会话缓存，最终通过SSE推送给前端客户端。这种交互模式实现了代理与外部系统的松耦合，提高了系统的可维护性和可扩展性。
|
||||
|
||||
**本节源码**
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L232-L257)
|
||||
|
||||
## 多代理类型支持
|
||||
代理服务通过`AgentType`枚举和`AcpAgentService` trait的实现，支持多种代理类型，如Codex和Claude Code。`AgentType`枚举定义了不同的代理类型，而`AcpAgentService` trait的实现则为每种类型提供了具体的启动逻辑。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(...) Result~AcpConnectionInfo~
|
||||
}
|
||||
class AgentType {
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
AcpAgentService <|-- AgentType
|
||||
class start_claude_code_acp_agent_service {
|
||||
+command_path : &str
|
||||
+command_args : Vec~String~
|
||||
+spawn_args : Vec~String~
|
||||
+merged_envs : HashMap~String, String~
|
||||
}
|
||||
class start_codex_acp_agent_service {
|
||||
+command_path : &str
|
||||
+cli_args : Vec~String~
|
||||
+merged_envs : HashMap~String, String~
|
||||
}
|
||||
AgentType --> start_claude_code_acp_agent_service : 启动
|
||||
AgentType --> start_codex_acp_agent_service : 启动
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L30-L59)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L310)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L25-L397)
|
||||
|
||||
`start_claude_code_acp_agent_service`和`start_codex_acp_agent_service`函数分别负责启动Claude Code和Codex代理。它们通过`tokio::process::Command`启动子进程，并建立`ClientSideConnection`进行通信。这些函数还处理环境变量和CLI参数的配置，确保代理能够正确初始化。这种设计实现了多代理类型的统一接口抽象，使得添加新的代理类型变得简单而直观。
|
||||
|
||||
**本节源码**
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L310)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L25-L397)
|
||||
|
||||
## 服务初始化与关闭逻辑
|
||||
代理服务的初始化在`main.rs`文件的`main`函数中完成。它首先初始化遥测系统，然后解析命令行参数和配置文件。接着，它创建项目工作目录，并启动清理任务。最后，它创建HTTP服务器并监听指定端口。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([main函数开始]) --> InitTelemetry["初始化遥测系统"]
|
||||
InitTelemetry --> ParseArgs["解析命令行参数"]
|
||||
ParseArgs --> LoadConfig["加载配置文件"]
|
||||
LoadConfig --> CreateDir["创建项目工作目录"]
|
||||
CreateDir --> StartCleanup["启动清理任务"]
|
||||
StartCleanup --> SpawnWorker["启动agent_worker线程"]
|
||||
SpawnWorker --> StartProxy["启动Pingora代理服务"]
|
||||
StartProxy --> CreateRouter["创建HTTP路由"]
|
||||
CreateRouter --> BindListener["绑定TCP监听器"]
|
||||
BindListener --> Serve["启动HTTP服务器"]
|
||||
Serve --> AwaitProxy["等待代理服务完成"]
|
||||
AwaitProxy --> End([main函数结束])
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L29-L178)
|
||||
|
||||
服务的关闭逻辑由`tokio`运行时的正常退出机制处理。当HTTP服务器停止时，`main`函数会等待代理服务完成，然后正常退出。清理任务和`agent_worker`线程也会随之停止。`init_telemetry`函数设置了全局的文本传播器，确保了`trace_id`的生成和传播，便于后续的性能分析和故障排查。
|
||||
|
||||
**本节源码**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L29-L178)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
|
||||
## 结论
|
||||
代理服务通过精心设计的架构和实现，成功地管理了AI代理的整个生命周期。它利用Rust的异步特性和类型系统，实现了高效、安全和可扩展的代理管理。与Docker管理器的集成确保了资源的隔离和安全，而异步任务调度和会话管理机制则保证了系统的高性能和实时性。错误恢复和生命周期管理策略进一步增强了系统的健壮性。通过统一的接口抽象，代理服务支持多种代理类型，为未来的扩展奠定了坚实的基础。整体而言，该服务是AI开发平台中不可或缺的核心组件，为用户提供了一个稳定、高效的AI代理运行环境。
|
||||
@@ -0,0 +1,536 @@
|
||||
# 代理运行器架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [lib.rs](file://crates/shared_types/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
代理运行器是一个基于Rust的高性能AI代理管理平台，旨在为AI驱动的开发提供完整的代理集成解决方案。该系统通过ACP（Agent Client Protocol）协议与不同的AI代理（如Codex、Claude Code）进行通信，实现了代理生命周期管理、会话状态维护和异步任务调度等核心功能。系统采用模块化设计，通过Pingora反向代理实现高性能的请求路由，并通过Docker管理器实现资源隔离和容器化部署。代理运行器支持多代理架构，通过抽象层设计实现了不同AI代理的无缝集成。
|
||||
|
||||
## 项目结构
|
||||
代理运行器采用Rust工作区（workspace）结构，包含多个独立的crates，每个crate负责特定的功能模块。这种模块化设计提高了代码的可维护性和可扩展性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[代理运行器] --> B[agent_runner]
|
||||
A --> C[acp_adapter]
|
||||
A --> D[claude-code-agent]
|
||||
A --> E[codex-acp-agent]
|
||||
A --> F[docker_manager]
|
||||
A --> G[pingora-proxy]
|
||||
A --> H[rcoder]
|
||||
A --> I[shared_types]
|
||||
B --> J[HTTP服务器]
|
||||
B --> K[代理服务]
|
||||
B --> L[会话管理]
|
||||
C --> M[ACP协议适配]
|
||||
F --> N[Docker容器管理]
|
||||
G --> O[反向代理]
|
||||
I --> P[共享数据类型]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
|
||||
## 核心组件
|
||||
代理运行器的核心组件包括代理服务管理、会话状态维护、ACP协议适配和Docker资源管理。这些组件协同工作，实现了AI代理的全生命周期管理。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
|
||||
## 架构概述
|
||||
代理运行器采用分层架构设计，从上到下分为HTTP接口层、业务逻辑层、代理服务层和基础设施层。这种分层设计确保了系统的高内聚、低耦合特性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[HTTP接口层] --> B[业务逻辑层]
|
||||
B --> C[代理服务层]
|
||||
C --> D[基础设施层]
|
||||
A --> E[API路由]
|
||||
A --> F[请求处理]
|
||||
B --> G[会话管理]
|
||||
B --> H[状态维护]
|
||||
C --> I[ACP适配]
|
||||
C --> J[代理通信]
|
||||
D --> K[Docker管理]
|
||||
D --> L[资源隔离]
|
||||
E --> M[chat_handler]
|
||||
F --> N[agent_service]
|
||||
G --> O[session_cache]
|
||||
H --> P[AgentStatus]
|
||||
I --> Q[acp_adapter]
|
||||
J --> R[claude_code_agent]
|
||||
K --> S[docker_manager]
|
||||
L --> T[container隔离]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 代理生命周期管理
|
||||
代理运行器通过`agent_worker`任务管理所有AI代理的生命周期。每个代理服务与一个项目ID关联，实现了代理的复用和资源优化。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "chat_handler"
|
||||
participant AgentWorker as "agent_worker"
|
||||
participant AgentService as "代理服务"
|
||||
Client->>Handler : POST /chat
|
||||
Handler->>AgentWorker : 发送LocalSetAgentRequest
|
||||
AgentWorker->>AgentWorker : 检查现有代理
|
||||
alt 代理存在
|
||||
AgentWorker->>AgentService : 复用现有代理
|
||||
AgentService-->>AgentWorker : 返回会话ID
|
||||
else 代理不存在
|
||||
AgentWorker->>AgentService : 创建新代理
|
||||
AgentService-->>AgentWorker : 返回会话ID
|
||||
end
|
||||
AgentWorker->>Handler : 发送ChatPromptResponse
|
||||
Handler-->>Client : 返回响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L58-L76)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L341)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
### 会话状态维护
|
||||
会话状态维护是代理运行器的核心功能之一，通过`SESSION_CACHE`和`PROJECT_SESSION_MAP`两个全局数据结构实现。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SessionData {
|
||||
+command_tx : UnboundedSender~SessionCommand~
|
||||
+current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~
|
||||
+current_cancel : Arc~Mutex~Option~CancellationToken~~~
|
||||
+new(max_size : usize) Arc~Self~
|
||||
+message_count() usize
|
||||
+create_new_connection(buffer_size : usize) Result~(Receiver~UnifiedSessionMessage~, CancellationToken)~
|
||||
+push_message(message : UnifiedSessionMessage)
|
||||
+close_current_connection()
|
||||
}
|
||||
class SessionWorker {
|
||||
-max_size : usize
|
||||
-command_rx : UnboundedReceiver~SessionCommand~
|
||||
-current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~
|
||||
-current_cancel : Arc~Mutex~Option~CancellationToken~~~
|
||||
+spawn(max_size : usize, command_rx : UnboundedReceiver~SessionCommand~, current_sender : Arc~Mutex~Option~Sender~UnifiedSessionMessage~~~~, current_cancel : Arc~Mutex~Option~CancellationToken~~~)
|
||||
+run()
|
||||
}
|
||||
class SessionCommand {
|
||||
+Push{message : UnifiedSessionMessage}
|
||||
+Clear{ack : oneshot : : Sender~usize~}
|
||||
+MessageCount{ack : oneshot : : Sender~usize~}
|
||||
}
|
||||
SessionData --> SessionWorker : "spawn"
|
||||
SessionWorker --> SessionCommand : "处理"
|
||||
SessionData --> SessionCommand : "发送命令"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L25-L222)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L142-L171)
|
||||
|
||||
**章节来源**
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
|
||||
### ACP协议适配器
|
||||
ACP协议适配器是代理运行器与AI代理通信的核心组件，实现了ACP协议的客户端功能。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentClient {
|
||||
+request_permission(args : RequestPermissionRequest) Result~RequestPermissionResponse, Error~
|
||||
+write_text_file(args : WriteTextFileRequest) Result~WriteTextFileResponse, Error~
|
||||
+read_text_file(args : ReadTextFileRequest) Result~ReadTextFileResponse, Error~
|
||||
+session_notification(args : SessionNotification) Result~(), Error~
|
||||
+ext_method(request : ExtRequest) Result~ExtResponse, Error~
|
||||
+ext_notification(notification : ExtNotification) Result~(), Error~
|
||||
}
|
||||
class Client {
|
||||
<<trait>>
|
||||
+request_permission(args : RequestPermissionRequest) Result~RequestPermissionResponse, Error~
|
||||
+write_text_file(args : WriteTextFileRequest) Result~WriteTextFileResponse, Error~
|
||||
+read_text_file(args : ReadTextFileRequest) Result~ReadTextFileResponse, Error~
|
||||
+session_notification(args : SessionNotification) Result~(), Error~
|
||||
+ext_method(request : ExtRequest) Result~ExtResponse, Error~
|
||||
+ext_notification(notification : ExtNotification) Result~(), Error~
|
||||
}
|
||||
AcpAgentClient --|> Client : "实现"
|
||||
class AcpConnectionInfo {
|
||||
+session_id : SessionId
|
||||
+prompt_tx : UnboundedSender~PromptRequest~
|
||||
+cancel_tx : UnboundedSender~CancelNotificationRequest~
|
||||
+stop_handle : Option~AgentStopHandleArc~
|
||||
}
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
AcpAgentService <-- AcpConnectionInfo : "返回"
|
||||
AcpAgentClient <-- AcpConnectionInfo : "使用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L43-L255)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
|
||||
**章节来源**
|
||||
- [acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
|
||||
### 多代理支持实现
|
||||
代理运行器通过`AgentType`枚举和特征对象实现了对多种AI代理的支持，包括Claude和Codex。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentType {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
AgentType --|> AcpAgentService : "实现"
|
||||
class ClaudeCodeAgent {
|
||||
+start_claude_code_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
}
|
||||
class CodexAgent {
|
||||
+start_codex_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
}
|
||||
AcpAgentService <|-- ClaudeCodeAgent : "具体实现"
|
||||
AcpAgentService <|-- CodexAgent : "具体实现"
|
||||
AgentType --> ClaudeCodeAgent : "调用"
|
||||
AgentType --> CodexAgent : "调用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
|
||||
**章节来源**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
|
||||
### 异步任务调度
|
||||
代理运行器采用Rust的异步运行时模型，通过Tokio运行时和LocalSet实现了高效的异步任务调度。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[主异步运行时] --> B[HTTP服务器]
|
||||
A --> C[清理任务]
|
||||
A --> D[代理服务]
|
||||
D --> E[独立OS线程]
|
||||
E --> F[单线程Tokio运行时]
|
||||
F --> G[LocalSet]
|
||||
G --> H[agent_worker]
|
||||
H --> I[ACP连接]
|
||||
H --> J[通道处理器]
|
||||
B --> K[请求处理]
|
||||
K --> L[发送LocalSetAgentRequest]
|
||||
L --> H
|
||||
C --> M[定期清理]
|
||||
M --> N[清理空闲会话]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L58-L76)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L341)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
### 资源隔离策略
|
||||
代理运行器通过Docker管理器实现了严格的资源隔离，确保每个AI代理在独立的容器环境中运行。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DockerManager {
|
||||
+new(config : DockerManagerConfig) DockerResult~Self~
|
||||
+create_container(config : ContainerConfig) DockerResult~Container~
|
||||
+start_container(container_id : &str) DockerResult~()
|
||||
+stop_container(container_id : &str) DockerResult~()
|
||||
+remove_container(container_id : &str) DockerResult~()
|
||||
+list_containers() DockerResult~Vec~ContainerInfo~~
|
||||
}
|
||||
class ContainerConfig {
|
||||
+image : String
|
||||
+name : String
|
||||
+ports : Vec~PortMapping~
|
||||
+volumes : Vec~VolumeMapping~
|
||||
+env_vars : Vec~EnvVar~
|
||||
+network_mode : String
|
||||
}
|
||||
class PortMapping {
|
||||
+host_port : u16
|
||||
+container_port : u16
|
||||
}
|
||||
class VolumeMapping {
|
||||
+host_path : String
|
||||
+container_path : String
|
||||
}
|
||||
class EnvVar {
|
||||
+name : String
|
||||
+value : String
|
||||
}
|
||||
DockerManager --> ContainerConfig : "使用"
|
||||
ContainerConfig --> PortMapping : "包含"
|
||||
ContainerConfig --> VolumeMapping : "包含"
|
||||
ContainerConfig --> EnvVar : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
|
||||
**章节来源**
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
|
||||
### 错误恢复机制
|
||||
代理运行器实现了多层次的错误恢复机制，确保系统的稳定性和可靠性。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[错误发生] --> B{错误类型}
|
||||
B --> C[可恢复错误]
|
||||
B --> D[不可恢复错误]
|
||||
C --> E[重试机制]
|
||||
E --> F[指数退避]
|
||||
F --> G[最大重试次数]
|
||||
G --> H{重试成功?}
|
||||
H --> |是| I[继续执行]
|
||||
H --> |否| J[降级处理]
|
||||
D --> K[优雅降级]
|
||||
K --> L[返回默认值]
|
||||
L --> M[记录错误日志]
|
||||
M --> N[发送告警]
|
||||
I --> O[正常流程]
|
||||
J --> O
|
||||
N --> O
|
||||
P[监控系统] --> Q[错误指标]
|
||||
Q --> R[告警系统]
|
||||
R --> S[运维人员]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L31-L232)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L142-L161)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L235-L247)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
### 可扩展性考虑
|
||||
代理运行器的设计充分考虑了可扩展性，通过模块化架构和配置驱动的方式支持未来的功能扩展。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[核心框架] --> B[插件系统]
|
||||
A --> C[配置管理]
|
||||
A --> D[服务发现]
|
||||
B --> E[新代理类型]
|
||||
B --> F[新协议适配]
|
||||
B --> G[新存储后端]
|
||||
C --> H[动态配置]
|
||||
C --> I[热更新]
|
||||
C --> J[配置验证]
|
||||
D --> K[服务注册]
|
||||
D --> L[健康检查]
|
||||
D --> M[负载均衡]
|
||||
A --> N[监控系统]
|
||||
N --> O[指标收集]
|
||||
N --> P[日志聚合]
|
||||
N --> Q[分布式追踪]
|
||||
O --> R[Prometheus]
|
||||
P --> S[ELK]
|
||||
Q --> T[OpenTelemetry]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
|
||||
### 性能监控
|
||||
代理运行器集成了全面的性能监控系统，通过OpenTelemetry实现分布式追踪和指标收集。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[应用代码] --> B[Tracing]
|
||||
B --> C[OpenTelemetry]
|
||||
C --> D[Exporter]
|
||||
D --> E[Jaeger]
|
||||
D --> F[Prometheus]
|
||||
D --> G[Zipkin]
|
||||
A --> H[Metrics]
|
||||
H --> I[Counter]
|
||||
H --> J[Histogram]
|
||||
H --> K[Gauge]
|
||||
I --> L[请求计数]
|
||||
J --> M[响应时间]
|
||||
K --> N[并发数]
|
||||
A --> O[Logging]
|
||||
O --> P[JSON日志]
|
||||
P --> Q[ELK]
|
||||
C --> R[Trace Context]
|
||||
R --> S[跨服务追踪]
|
||||
T[监控面板] --> U[指标可视化]
|
||||
U --> V[告警规则]
|
||||
V --> W[通知系统]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L181-L231)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L65-L69)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
|
||||
### 与docker_manager的集成
|
||||
代理运行器与Docker管理器深度集成，实现了容器化部署和资源管理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant AgentRunner as "代理运行器"
|
||||
participant DockerManager as "Docker管理器"
|
||||
participant DockerDaemon as "Docker守护进程"
|
||||
AgentRunner->>DockerManager : 创建容器请求
|
||||
DockerManager->>DockerDaemon : 创建容器
|
||||
DockerDaemon-->>DockerManager : 容器ID
|
||||
DockerManager->>DockerDaemon : 启动容器
|
||||
DockerDaemon-->>DockerManager : 启动成功
|
||||
DockerManager-->>AgentRunner : 容器准备就绪
|
||||
AgentRunner->>DockerManager : 发送命令
|
||||
DockerManager->>DockerDaemon : 执行命令
|
||||
DockerDaemon-->>DockerManager : 命令输出
|
||||
DockerManager-->>AgentRunner : 返回结果
|
||||
AgentRunner->>DockerManager : 停止容器
|
||||
DockerManager->>DockerDaemon : 停止容器
|
||||
DockerDaemon-->>DockerManager : 停止成功
|
||||
DockerManager-->>AgentRunner : 清理完成
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
|
||||
**章节来源**
|
||||
- [docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
|
||||
## 依赖分析
|
||||
代理运行器的依赖关系清晰，各模块之间的耦合度低，便于维护和扩展。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[agent_runner] --> B[acp_adapter]
|
||||
A --> C[shared_types]
|
||||
A --> D[pingora-proxy]
|
||||
A --> E[claude-code-agent]
|
||||
A --> F[codex-acp-agent]
|
||||
A --> G[docker_manager]
|
||||
B --> H[agent-client-protocol]
|
||||
C --> I[grpc]
|
||||
D --> J[axum]
|
||||
D --> K[reqwest]
|
||||
E --> L[agent-client-protocol]
|
||||
F --> M[agent-client-protocol]
|
||||
G --> N[bollard]
|
||||
A --> O[tokio]
|
||||
A --> P[axum]
|
||||
A --> Q[tracing]
|
||||
A --> R[serde]
|
||||
A --> S[dashmap]
|
||||
O --> T[异步运行时]
|
||||
P --> U[Web框架]
|
||||
Q --> V[日志追踪]
|
||||
R --> W[序列化]
|
||||
S --> X[并发映射]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/acp_adapter/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
|
||||
## 性能考虑
|
||||
代理运行器在设计时充分考虑了性能因素，采用了多种优化策略。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
|
||||
## 故障排除指南
|
||||
当代理运行器出现问题时，可以按照以下步骤进行排查。
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
|
||||
## 结论
|
||||
代理运行器通过精心设计的架构和实现，提供了一个高性能、可扩展的AI代理管理平台。系统采用模块化设计，各组件职责清晰，耦合度低。通过ACP协议适配器，实现了与不同AI代理的无缝集成。异步任务调度和资源隔离策略确保了系统的高效性和稳定性。全面的监控和错误恢复机制为系统的可靠运行提供了保障。整体架构具有良好的可扩展性，能够适应未来的需求变化。
|
||||
@@ -0,0 +1,356 @@
|
||||
# 会话缓存机制
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs)
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件系统性阐述 session_cache 模块如何管理 AI 代理会话状态，涵盖缓存数据结构设计、生命周期管理策略、并发访问控制机制、缓存项的创建/更新/清理流程，以及与代理服务的交互模式。文档还记录内存使用特征、过期策略与性能优化措施，并提供聊天交互与进度查询的实际使用场景示例。
|
||||
|
||||
## 项目结构
|
||||
围绕会话缓存的关键文件组织如下：
|
||||
- 会话缓存核心：session_cache.rs
|
||||
- SSE 进度通知：agent_session_notification.rs
|
||||
- 聊天入口与会话清理：chat_handler.rs
|
||||
- 清理任务与资源回收：cleanup_task.rs
|
||||
- 统一消息模型与通知：agent_session_notify.rs、model.rs
|
||||
- 代理侧会话通知转发：proxy_agent/mod.rs
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "会话缓存层"
|
||||
SC["SessionData<br/>环形缓冲区+命令通道"]
|
||||
PC["PROJECT_SESSION_MAP<br/>项目-会话映射"]
|
||||
GC["全局缓存 SESSION_CACHE<br/>按session_id索引"]
|
||||
end
|
||||
subgraph "代理侧"
|
||||
AC["AcpAgentClient<br/>session_notification回调"]
|
||||
PRJ["PROJECT_AND_AGENT_INFO_MAP<br/>项目-代理状态"]
|
||||
end
|
||||
subgraph "HTTP处理层"
|
||||
SSE["SSE 进度接口<br/>agent_session_notification.rs"]
|
||||
CHAT["聊天接口<br/>chat_handler.rs"]
|
||||
end
|
||||
subgraph "清理与回收"
|
||||
CLEAN["清理任务<br/>cleanup_task.rs"]
|
||||
end
|
||||
AC --> |"推送通知"| SC
|
||||
SSE --> |"建立SSE并创建SessionData"| GC
|
||||
CHAT --> |"清理旧会话/新会话"| GC
|
||||
CLEAN --> |"定期扫描并清理"| GC
|
||||
CLEAN --> |"清理映射"| PC
|
||||
AC --> |"回填request_id上下文"| AC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L258)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L258)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
|
||||
## 核心组件
|
||||
- 全局会话缓存 SESSION_CACHE：以 session_id 为键，存储每个会话的 SessionData。
|
||||
- 项目-会话映射 PROJECT_SESSION_MAP：确保同一项目仅有一个活跃会话，变更时自动清理旧会话。
|
||||
- SessionData：封装环形缓冲区、命令通道、当前发送器与取消令牌，负责消息入队、实时推送与连接关闭。
|
||||
- SessionWorker：后台工作者，消费命令通道，维护环形缓冲区，按需实时推送消息。
|
||||
- 统一会话消息 UnifiedSessionMessage 与通知 SessionNotify：标准化消息格式，便于跨组件传递。
|
||||
- SSE 进度接口 agent_session_notification：为前端建立 SSE 连接，实时推送会话状态。
|
||||
- 清理任务 cleanup_task：定期扫描并清理闲置代理与孤立会话。
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L1-L180)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L1-L120)
|
||||
|
||||
## 架构总览
|
||||
会话缓存的整体交互链路如下：
|
||||
- 代理侧 AcpAgentClient 在收到 session_notification 后，构造 SessionNotify 并调用 push_session_update，统一转为 UnifiedSessionMessage 写入 SessionData。
|
||||
- SSE 进度接口 agent_session_notification 为每个 session_id 创建新的 SessionData 并插入 SESSION_CACHE，随后创建连接并持续推送消息。
|
||||
- 聊天接口 chat_handler 在发起新请求前，会清理旧会话，确保全新开始。
|
||||
- 清理任务定期扫描 PROJECT_SESSION_MAP 与 SESSION_CACHE，清理孤立会话与闲置代理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Agent as "代理(AcpAgentClient)"
|
||||
participant Cache as "SessionData/Worker"
|
||||
participant SSE as "SSE接口"
|
||||
participant Front as "前端"
|
||||
Agent->>Cache : "push_session_update(SessionNotify)"
|
||||
Cache->>Cache : "SessionWorker : Push消息到环形缓冲区"
|
||||
Cache->>Cache : "尝试实时推送至当前发送器"
|
||||
SSE->>Cache : "create_new_connection(新建SessionData)"
|
||||
Cache-->>SSE : "返回接收端+取消令牌"
|
||||
loop "SSE循环"
|
||||
Cache-->>SSE : "推送UnifiedSessionMessage"
|
||||
SSE-->>Front : "SSE事件"
|
||||
end
|
||||
Note over SSE,Cache : "取消令牌触发或发送端关闭时，SSE断开"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L105-L221)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 会话缓存数据结构与生命周期
|
||||
- 数据结构设计
|
||||
- SESSION_CACHE：全局 DashMap，键为 session_id，值为 Arc<SessionData>，保证并发安全与零拷贝共享。
|
||||
- SessionData：包含命令发送端、当前发送器与取消令牌的互斥保护，避免竞态。
|
||||
- SessionWorker：持有环形缓冲区（HeapRb），按最大容量维护消息队列，实时推送失败时自动清理当前发送器。
|
||||
- PROJECT_SESSION_MAP：全局 DashMap，键为 project_id，值为 session_id，确保同一项目仅有一个活跃会话。
|
||||
- 生命周期管理
|
||||
- 新建：SSE 接口为每个 session_id 创建新的 SessionData 并插入 SESSION_CACHE，覆盖旧值，确保“全新开始”。
|
||||
- 销毁：SessionWorker 退出时，SessionData 仍驻留缓存；清理任务通过移除映射与缓存条目实现资源回收。
|
||||
- 连接关闭：主动触发 CancellationToken 或显式关闭发送端，使接收端 recv() 返回 None，SSE 自然断开。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SessionData {
|
||||
+command_tx
|
||||
+current_sender
|
||||
+current_cancel
|
||||
+new(max_size)
|
||||
+create_new_connection(buffer_size)
|
||||
+push_message(message)
|
||||
+close_current_connection()
|
||||
+message_count()
|
||||
}
|
||||
class SessionWorker {
|
||||
-max_size
|
||||
-command_rx
|
||||
-current_sender
|
||||
-current_cancel
|
||||
+spawn(...)
|
||||
+run()
|
||||
}
|
||||
class UnifiedSessionMessage {
|
||||
+session_id
|
||||
+message_type
|
||||
+sub_type
|
||||
+data
|
||||
+timestamp
|
||||
+heartbeat(session_id)
|
||||
}
|
||||
class SessionNotify {
|
||||
+to_unified_message()
|
||||
}
|
||||
SessionData --> SessionWorker : "spawn并消费命令"
|
||||
SessionWorker --> UnifiedSessionMessage : "生产消息"
|
||||
SessionNotify --> UnifiedSessionMessage : "转换"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L24-L221)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L1-L180)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L1-L180)
|
||||
|
||||
### 并发访问控制机制
|
||||
- 全局缓存与映射
|
||||
- 使用 LazyLock 初始化 DashMap，保证线程安全与延迟初始化。
|
||||
- SessionData 内部对 current_sender/current_cancel 使用 Mutex 包裹，避免多处同时写入导致的竞争。
|
||||
- 命令通道
|
||||
- SessionData 内部使用无界 mpsc 通道接收命令，SessionWorker 异步消费，避免阻塞代理通知路径。
|
||||
- 取消令牌
|
||||
- 每次创建新连接都会生成新的 CancellationToken，旧连接一旦被新连接抢占或用户取消，立即触发取消，确保旧连接快速失效。
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
|
||||
### 缓存项创建、更新与清理流程
|
||||
- 创建
|
||||
- SSE 接口为 session_id 创建 SessionData 并插入 SESSION_CACHE，同时创建连接并返回接收端与取消令牌。
|
||||
- 更新
|
||||
- 代理侧 session_notification 回调将 SessionUpdate 转为 SessionNotify，再转为 UnifiedSessionMessage，通过 SessionData.push_message 入队。
|
||||
- SessionWorker 将消息写入环形缓冲区，并尝试实时推送至当前发送器；若推送失败则清空当前发送器，避免脏写。
|
||||
- 清理
|
||||
- SSE 接口：当取消令牌被触发或发送端关闭时，SSE 断开，旧 SessionData 仍保留，等待清理任务回收。
|
||||
- 清理任务：扫描 PROJECT_SESSION_MAP 与 SESSION_CACHE，移除孤立会话与空闲代理，减少内存占用。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> Create["SSE接口创建SessionData并插入缓存"]
|
||||
Create --> Push["代理推送SessionNotify->UnifiedSessionMessage"]
|
||||
Push --> Buffer["SessionWorker写入环形缓冲区"]
|
||||
Buffer --> Realtime{"实时推送成功?"}
|
||||
Realtime --> |是| SSELoop["SSE循环推送消息"]
|
||||
Realtime --> |否| ClearSender["清空当前发送器"]
|
||||
SSELoop --> Cancel{"取消令牌触发/发送端关闭?"}
|
||||
Cancel --> |是| Close["SSE断开，旧SessionData保留"]
|
||||
Cancel --> |否| Heartbeat["周期心跳"]
|
||||
Close --> Cleanup["清理任务扫描并移除"]
|
||||
Cleanup --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L105-L221)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L105-L221)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
|
||||
### 与代理服务的交互模式
|
||||
- 代理侧 AcpAgentClient 实现 session_notification 回调，将 ACP SessionUpdate 转为 AgentSessionUpdate，再包装为 SessionNotify，最终调用 push_session_update 写入缓存。
|
||||
- 若 SessionNotification.meta 中未携带 request_id，则通过 PROJECT_AND_AGENT_INFO_MAP 查找 project_id，再从 SESSION_REQUEST_CONTEXT 获取 request_id，确保消息携带 request_id 以便前端关联。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant ACP as "ACP客户端"
|
||||
participant Client as "AcpAgentClient"
|
||||
participant Cache as "push_session_update"
|
||||
participant Worker as "SessionWorker"
|
||||
participant SSE as "SSE接口"
|
||||
ACP->>Client : "session_notification(SessionUpdate)"
|
||||
Client->>Client : "提取/回填request_id"
|
||||
Client->>Cache : "SessionNotify -> UnifiedSessionMessage"
|
||||
Cache->>Worker : "命令 : Push"
|
||||
Worker->>Worker : "写入环形缓冲区"
|
||||
Worker->>SSE : "尝试实时推送"
|
||||
SSE-->>Client : "SSE循环接收并转发"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L231-L257)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
|
||||
章节来源
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L231-L257)
|
||||
|
||||
### 过期策略与内存使用特征
|
||||
- 过期策略
|
||||
- 心跳消息：SSE 接口在建立连接后立即发送心跳，并按周期发送心跳事件，用于维持连接活性。
|
||||
- 取消与断开：取消令牌触发或发送端关闭时，SSE 断开；SessionWorker 退出后，SessionData 仍驻留缓存，等待清理任务回收。
|
||||
- 孤立会话清理：清理任务扫描 SESSION_CACHE 中不在活跃映射中的 session_id，若消息计数大于 0 则移除条目，否则标记为空会话清理。
|
||||
- 内存使用特征
|
||||
- 环形缓冲区：按最大容量维护最近消息，满时淘汰最旧消息，避免无限增长。
|
||||
- 连接级缓存：每次 SSE 连接都会创建新的 SessionData，覆盖旧值，确保不会累积历史消息。
|
||||
- 映射表：PROJECT_SESSION_MAP 仅保存活跃映射，清理任务移除无效映射，降低内存压力。
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L385-L475)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L173-L221)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
|
||||
### 性能优化措施
|
||||
- 极简设计
|
||||
- SessionData 直接共享当前发送器与取消令牌，避免命令传递带来的额外开销。
|
||||
- SessionWorker 直接从共享状态获取发送器，实时推送失败时立即清空，避免后续无效尝试。
|
||||
- 通道与锁粒度
|
||||
- 使用无界命令通道与细粒度 Mutex，降低锁竞争概率。
|
||||
- 心跳与断开
|
||||
- 心跳事件降低连接空闲时的网络压力；取消令牌与发送端关闭确保旧连接快速失效，避免资源浪费。
|
||||
- 清理策略
|
||||
- 定期清理孤立会话与闲置代理，减少缓存与映射膨胀。
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L105-L221)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L241)
|
||||
|
||||
## 依赖关系分析
|
||||
- 组件耦合
|
||||
- session_cache 与 agent_session_notification：SSE 接口依赖 SessionData 的创建与连接能力。
|
||||
- proxy_agent/mod 与 session_cache：代理侧通知通过 push_session_update 写入缓存，二者通过统一消息模型解耦。
|
||||
- chat_handler 与 session_cache：聊天接口在发起新请求前清理旧会话，确保全新开始。
|
||||
- cleanup_task 与 session_cache/PROJECT_SESSION_MAP：清理孤立会话与映射，避免资源泄漏。
|
||||
- 外部依赖
|
||||
- DashMap 提供并发安全的哈希表。
|
||||
- ringbuf HeapRb 提供高效环形缓冲区。
|
||||
- tokio mpsc 提供异步通道与取消令牌。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["agent_session_notification.rs"] --> B["session_cache.rs"]
|
||||
C["proxy_agent/mod.rs"] --> B
|
||||
D["chat_handler.rs"] --> B
|
||||
E["cleanup_task.rs"] --> B
|
||||
E --> F["PROJECT_SESSION_MAP"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L140)
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L211-L258)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
|
||||
章节来源
|
||||
- [model.rs](file://crates/agent_runner/src/model.rs#L1-L12)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L1-L180)
|
||||
|
||||
## 性能考量
|
||||
- 环形缓冲区容量：根据业务负载调整最大容量，平衡内存占用与消息保留范围。
|
||||
- 实时推送失败处理：推送失败时清空发送器，避免后续无效尝试；必要时增加接收端缓冲大小。
|
||||
- 心跳频率：合理的心跳间隔可在保持连接活性与网络开销之间取得平衡。
|
||||
- 清理周期：清理任务的间隔与闲置超时可根据系统负载动态调整，避免过于频繁或过少。
|
||||
|
||||
## 故障排查指南
|
||||
- SSE 连接无法建立
|
||||
- 检查 SSE 接口是否成功创建 SessionData 并插入 SESSION_CACHE。
|
||||
- 确认 create_new_connection 是否返回接收端与取消令牌。
|
||||
- 实时消息未到达前端
|
||||
- 检查 SessionWorker 是否成功写入环形缓冲区与尝试实时推送。
|
||||
- 若推送失败，确认当前发送器是否被清空，以及取消令牌是否被触发。
|
||||
- 旧会话消息残留
|
||||
- 确认 SSE 接口是否为每个 session_id 创建新的 SessionData 并覆盖旧值。
|
||||
- 检查清理任务是否正确扫描并移除孤立会话。
|
||||
- 代理通知未写入缓存
|
||||
- 确认 AcpAgentClient 的 session_notification 回调是否正确提取 request_id 并调用 push_session_update。
|
||||
- 检查 SessionData 是否存在且未被清理。
|
||||
|
||||
章节来源
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L105-L221)
|
||||
- [proxy_agent/mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L240)
|
||||
- [cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L156-L241)
|
||||
|
||||
## 结论
|
||||
session_cache 模块通过 SessionData + SessionWorker + 环形缓冲区的组合，实现了高并发、低开销的会话状态缓存与实时推送。配合 SSE 进度接口、聊天入口清理策略与定期清理任务，系统在保证消息实时性的同时，有效控制内存与资源占用，满足 AI 代理会话状态管理的需求。
|
||||
|
||||
## 附录
|
||||
|
||||
### 实际使用场景示例
|
||||
- 聊天交互
|
||||
- 前端调用聊天接口，后端为项目生成或复用会话，清理旧会话后启动代理任务，SSE 接口实时推送执行进度。
|
||||
- 进度查询
|
||||
- 前端通过 /agent/progress/{session_id} 建立 SSE 连接，接收 prompt_start、agent_message_chunk、tool_call 等事件，结合心跳维持连接活性。
|
||||
|
||||
章节来源
|
||||
- [chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L176-L320)
|
||||
- [agent_session_notification.rs](file://crates/agent_runner/src/handler/agent_session_notification.rs#L355-L483)
|
||||
314
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/清理任务.md
Normal file
314
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/清理任务.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 清理任务
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“清理任务”模块，系统性阐述其如何在代理终止后回收系统资源，包括定时调度、闲置检测、容器与端口释放、SSE会话清理、孤立容器扫描、超时与错误处理策略，以及与代理停止处理器的协作方式。文档同时提供配置项说明、性能影响评估与最佳实践建议，帮助读者在不同场景下正确使用与扩展该模块。
|
||||
|
||||
## 项目结构
|
||||
清理任务位于 rcoder 与 agent_runner 两个子 crate 中，分别针对不同的运行形态与状态管理：
|
||||
- rcoder 清理任务：面向基于容器的代理，具备更完善的资源回收与超时控制，包含孤立容器扫描与端口释放。
|
||||
- agent_runner 清理任务：面向本地进程型代理，采用 RAII 模式，通过移除映射触发生命周期守卫自动清理。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 清理任务"
|
||||
RC_Config["CleanupConfig<br/>闲置超时/清理间隔/Docker停止超时"]
|
||||
RC_AgentCleaner["AgentCleaner<br/>扫描/清理/统计"]
|
||||
RC_State["AppState<br/>project_and_agent_map/sessions"]
|
||||
RC_Docker["DockerManager<br/>统一停止接口"]
|
||||
RC_PortMgr["PortManager<br/>端口分配/释放"]
|
||||
RC_CleanupTask["start_cleanup_task()"]
|
||||
end
|
||||
subgraph "agent_runner 清理任务"
|
||||
AR_Config["CleanupConfig<br/>闲置超时/清理间隔"]
|
||||
AR_AgentCleaner["AgentCleaner<br/>扫描/清理/统计"]
|
||||
AR_Maps["PROJECT_AND_AGENT_INFO_MAP<br/>SESSION_CACHE/PROJECT_SESSION_MAP"]
|
||||
AR_CleanupTask["start_cleanup_task()"]
|
||||
end
|
||||
subgraph "代理停止处理器"
|
||||
StopGuard["AgentLifecycleGuard<br/>Drop自动清理"]
|
||||
end
|
||||
RC_AgentCleaner --> RC_State
|
||||
RC_AgentCleaner --> RC_Docker
|
||||
RC_AgentCleaner --> RC_PortMgr
|
||||
RC_CleanupTask --> RC_AgentCleaner
|
||||
AR_AgentCleaner --> AR_Maps
|
||||
AR_CleanupTask --> AR_AgentCleaner
|
||||
StopGuard -.协作.-> AR_AgentCleaner
|
||||
StopGuard -.协作.-> RC_AgentCleaner
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L67-L106)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L18-L36)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L32)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L20)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L67-L106)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L18-L36)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L32)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L20)
|
||||
|
||||
## 核心组件
|
||||
- 清理配置 CleanupConfig
|
||||
- rcoder 版本包含闲置超时、清理间隔、Docker 停止超时；agent_runner 版本仅包含闲置超时与清理间隔。
|
||||
- 清理统计 CleanupStats
|
||||
- 记录清理总量、成功/失败数、孤立会话/SSE 消息清理数与最后清理时间。
|
||||
- AgentCleaner
|
||||
- 扫描闲置代理、清理孤立会话、销毁容器、释放端口、移除映射、触发生命周期守卫 Drop。
|
||||
- AgentLifecycleGuard（代理停止处理器）
|
||||
- 通过 Drop 自动清理资源，保证容器、进程、通道等资源得到回收。
|
||||
- 端口管理 PortManager
|
||||
- 在容器销毁时释放端口，避免端口泄漏。
|
||||
- DockerManager 统一停止接口
|
||||
- 提供运行时清理策略，支持优雅停止与强制停止，配合超时控制。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L67-L106)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L18-L36)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L21-L32)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L1-L20)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L252-L269)
|
||||
|
||||
## 架构总览
|
||||
清理任务以“定时轮询 + RAII 回收”的方式工作：
|
||||
- 定时器按清理间隔触发清理流程。
|
||||
- 扫描阶段识别 Idle 状态且超时的代理，同时清理孤立会话与 SSE 消息。
|
||||
- 对于 rcoder 场景，先销毁容器并释放端口，再移除映射，触发生命周期守卫 Drop 完成其余资源回收。
|
||||
- 对于 agent_runner 场景，直接移除映射，生命周期守卫 Drop 触发资源清理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Timer as "定时器(interval)"
|
||||
participant Cleaner as "AgentCleaner"
|
||||
participant State as "AppState/Maps"
|
||||
participant Docker as "DockerManager"
|
||||
participant Guard as "AgentLifecycleGuard"
|
||||
participant Port as "PortManager"
|
||||
Timer->>Cleaner : tick()
|
||||
Cleaner->>State : 读取project_and_agent_map/sessions
|
||||
Cleaner->>Cleaner : 扫描Idle且超时的代理
|
||||
alt rcoder场景
|
||||
Cleaner->>Docker : 停止容器(runtime_cleanup)
|
||||
Docker-->>Cleaner : 结果
|
||||
Cleaner->>Port : 释放端口
|
||||
Port-->>Cleaner : 完成
|
||||
end
|
||||
Cleaner->>State : 原子性移除映射(entry.remove_entry)
|
||||
State-->>Guard : Drop触发自动清理
|
||||
Cleaner-->>Timer : 统计与日志
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L815)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L278-L292)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L236-L292)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L51-L59)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L252-L269)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 定时调度与清理流程
|
||||
- rcoder 清理任务
|
||||
- 使用 tokio::time::interval 控制清理间隔，每次清理前为整个清理流程设置超时上限，避免长时间阻塞。
|
||||
- 清理流程包含：孤立会话清理、代理扫描与判定、容器销毁与端口释放、映射移除、生命周期守卫 Drop、统计更新。
|
||||
- agent_runner 清理任务
|
||||
- 同样使用 interval 驱动，但不涉及容器销毁与端口释放，直接移除映射触发 Drop。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["定时tick"]) --> Scan["扫描project_and_agent_map"]
|
||||
Scan --> Filter{"Idle且超时?"}
|
||||
Filter -- 否 --> NextTick["等待下次tick"]
|
||||
Filter -- 是 --> Cleanup["执行清理"]
|
||||
Cleanup --> RC{"rcoder场景?"}
|
||||
RC -- 是 --> Stop["停止容器(runtime_cleanup)"]
|
||||
Stop --> Release["释放端口"]
|
||||
RC -- 否 --> Remove["移除映射(entry.remove_entry)"]
|
||||
Release --> Remove
|
||||
Remove --> Drop["生命周期守卫Drop自动清理"]
|
||||
Drop --> Stats["更新统计/日志"]
|
||||
Stats --> NextTick
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L815)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L278-L292)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L815)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L278-L292)
|
||||
|
||||
### 闲置检测与保护期
|
||||
- 闲置超时判定：比较 last_activity 与当前时间，超过 idle_timeout 则视为可清理。
|
||||
- 保护期策略：新增最小保护时间（例如容器创建后5分钟内不清理），避免刚创建的容器被误清理。
|
||||
- 缓冲时间：在 rcoder 版本中对 idle_timeout 添加1秒缓冲，降低时间误差导致的误判。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L136-L200)
|
||||
|
||||
### 资源释放流程
|
||||
- rcoder 场景
|
||||
- 容器销毁：通过统一运行时清理接口停止容器，支持优雅停止与强制停止。
|
||||
- 端口释放：若容器存在端口绑定，清理时释放对应端口。
|
||||
- 映射移除：使用 DashMap 的 Entry API 原子性移除，触发生命周期守卫 Drop。
|
||||
- agent_runner 场景
|
||||
- 直接移除映射，生命周期守卫 Drop 自动清理子进程、stderr 任务等资源。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L643-L731)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L243-L276)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L236-L292)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L51-L59)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L252-L269)
|
||||
|
||||
### SSE 会话与孤立会话清理
|
||||
- 扫描活跃会话集合，定位不在活跃映射中的会话作为“孤立会话”，清理其缓存与消息。
|
||||
- 统计孤立会话数量与清理的 SSE 消息数量，便于监控与审计。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L202-L246)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L81-L154)
|
||||
|
||||
### 孤立容器扫描与清理（rcoder）
|
||||
- 通过 DockerManager 列出匹配模式的容器，快速筛选 MAP 中缺失的“孤立容器”。
|
||||
- 限制单次清理数量与总超时，避免阻塞主清理流程。
|
||||
- 并行清理多个孤立容器，提升效率。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L602)
|
||||
|
||||
### 与代理停止处理器的协作
|
||||
- 生命周期守卫在 Drop 时自动清理资源，确保即使清理任务未及时触发，也能回收资源。
|
||||
- rcoder 场景下，清理任务优先销毁容器并释放端口，再移除映射，保证一致性。
|
||||
- agent_runner 场景下，清理任务移除映射即可，守卫负责清理本地资源。
|
||||
|
||||
章节来源
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L236-L292)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L643-L731)
|
||||
|
||||
### 超时处理与重试机制
|
||||
- 整体清理超时：为一次完整的清理周期设置超时上限，超时后强制结束，避免阻塞。
|
||||
- 单次清理超时：对容器销毁、孤立容器清理等关键步骤设置超时，超时后记录告警并继续后续流程。
|
||||
- 重试策略：未实现显式的重试；遇到超时或错误时记录日志并继续，保证清理任务持续运行。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L815)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L431-L453)
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L540-L599)
|
||||
|
||||
### 日志记录实践
|
||||
- 关键节点均输出 info/warn/debug/error 日志，包含项目ID、状态、耗时、清理结果等。
|
||||
- 对超时、失败、保护期内跳过等情况进行明确标注，便于问题定位与审计。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L407-L419)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L214-L232)
|
||||
|
||||
## 依赖分析
|
||||
- 清理任务依赖
|
||||
- rcoder：AppState（DashMap）、DockerManager、PortManager、AgentLifecycleGuard。
|
||||
- agent_runner：全局映射（PROJECT_AND_AGENT_INFO_MAP、SESSION_CACHE、PROJECT_SESSION_MAP）、AgentLifecycleGuard。
|
||||
- 外部依赖
|
||||
- DockerManager 提供统一的容器停止接口，支持运行时清理策略。
|
||||
- DashMap 提供并发安全的映射与原子性 Entry API，保障清理过程的一致性。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Cleanup["AgentCleaner"] --> State["AppState/DashMap"]
|
||||
Cleanup --> Docker["DockerManager"]
|
||||
Cleanup --> Port["PortManager"]
|
||||
Cleanup --> Guard["AgentLifecycleGuard"]
|
||||
Docker --> Stop["runtime_cleanup_container"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L108-L113)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L252-L269)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L26-L36)
|
||||
- [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs#L252-L269)
|
||||
|
||||
## 性能考虑
|
||||
- 定时轮询频率
|
||||
- 默认清理间隔为 5 分钟，建议结合业务负载与资源占用调整，避免过于频繁导致 CPU 唤醒开销。
|
||||
- 扫描与清理复杂度
|
||||
- 扫描阶段遍历映射，复杂度 O(N)；rcoder 场景额外包含容器查询与并行清理，注意 Docker API 调用次数。
|
||||
- 并发与超时
|
||||
- 孤立容器清理采用并行任务，限制单次清理数量，避免阻塞主流程；整体清理设置超时上限，保证稳定性。
|
||||
- 端口与容器资源
|
||||
- 端口释放与容器停止均设置超时，防止长时间阻塞；建议监控清理耗时与失败率，及时调整超时参数。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 清理任务未生效
|
||||
- 检查定时器是否启动、清理间隔是否合理、日志中是否有“定时清理完成/失败/超时”记录。
|
||||
- 容器未被清理
|
||||
- rcoder 场景确认容器停止接口是否成功、端口是否释放、映射是否移除；查看超时与错误日志。
|
||||
- 代理资源未回收
|
||||
- 确认生命周期守卫 Drop 是否触发；检查映射移除是否成功；核对本地进程资源清理日志。
|
||||
- 端口泄漏
|
||||
- 检查容器销毁后是否调用端口释放；核对端口管理器释放日志。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L787-L815)
|
||||
- [crates/rcoder/src/proxy_agent/port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L51-L59)
|
||||
- [crates/agent_runner/src/proxy_agent/agent_stop_handle.rs](file://crates/agent_runner/src/proxy_agent/agent_stop_handle.rs#L236-L292)
|
||||
|
||||
## 结论
|
||||
清理任务通过“定时轮询 + RAII 回收”的设计，在代理终止后可靠地回收容器、端口与会话等资源。rcoder 场景提供了更完善的超时控制、孤立容器扫描与端口释放能力；agent_runner 场景则通过映射移除触发生命周期守卫 Drop，实现轻量级资源回收。结合合理的配置与监控，可在保证稳定性的同时最大化资源利用率。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置选项说明
|
||||
- rcoder 清理配置 CleanupConfig
|
||||
- idle_timeout：代理闲置超时时间，默认 30 分钟。
|
||||
- cleanup_interval：清理检查间隔，默认 5 分钟。
|
||||
- docker_stop_timeout：Docker 容器停止超时，默认 30 秒。
|
||||
- agent_runner 清理配置 CleanupConfig
|
||||
- idle_timeout：代理闲置超时时间，默认 30 分钟。
|
||||
- cleanup_interval：清理检查间隔，默认 5 分钟。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L67-L89)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L18-L36)
|
||||
|
||||
### 启动与集成
|
||||
- rcoder 启动清理任务
|
||||
- 通过 start_cleanup_task(config, state) 启动，传入 AppState 与 CleanupConfig。
|
||||
- agent_runner 启动清理任务
|
||||
- 通过 start_cleanup_task(config) 启动，传入 CleanupConfig。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/proxy_agent/cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs#L823-L835)
|
||||
- [crates/agent_runner/src/proxy_agent/cleanup_task.rs](file://crates/agent_runner/src/proxy_agent/cleanup_task.rs#L300-L310)
|
||||
360
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/通道工具.md
Normal file
360
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/通道工具.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# 通道工具
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件系统性地介绍代理运行器中“通道工具”（channel_utils）模块提供的异步通信能力，重点说明其如何简化 Tokio 通道的使用，包括通道创建、消息转发、状态更新与错误处理等辅助函数。文档还解释了在代理运行器中各组件间通信的应用场景，如命令传递、状态更新和结果返回，并给出设计理念、性能特征与使用注意事项，以及典型使用模式的路径指引。
|
||||
|
||||
## 项目结构
|
||||
通道工具位于代理运行器的代理层，围绕 ACP 协议的客户端连接与会话管理展开，配合全局会话缓存与通知广播，形成“命令通道 + 数据通道”的双通道通信体系。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "代理层"
|
||||
CU["channel_utils<br/>通用通道处理工具"]
|
||||
MOD["proxy_agent/mod.rs<br/>会话上下文与通知入口"]
|
||||
AS["agent_service.rs<br/>代理服务抽象"]
|
||||
CA["claude_code_agent.rs<br/>Claude代理启动"]
|
||||
CO["codex_agent.rs<br/>Codex代理启动"]
|
||||
end
|
||||
subgraph "服务层"
|
||||
SC["service/session_cache.rs<br/>会话缓存与推送"]
|
||||
end
|
||||
subgraph "共享类型"
|
||||
AM["shared_types/agent_model.rs<br/>模型与生命周期"]
|
||||
AN["shared_types/agent_session_notify.rs<br/>统一通知模型"]
|
||||
AE["shared_types/app_error.rs<br/>错误类型"]
|
||||
end
|
||||
CA --> CU
|
||||
CO --> CU
|
||||
CU --> SC
|
||||
MOD --> SC
|
||||
SC --> AN
|
||||
AM --> CU
|
||||
AE --> SC
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
|
||||
## 核心组件
|
||||
- 通用通道处理工具（channel_utils）
|
||||
- 提供两类可复用的任务：取消处理任务与提示处理任务，分别封装对 Agent 的 cancel 与 prompt 调用、状态更新与通知广播。
|
||||
- 设计要点：超时保护、状态机切换、请求上下文透传、错误链路闭环。
|
||||
- 会话级上下文与通知入口（proxy_agent/mod.rs）
|
||||
- 维护会话级 request_id 上下文映射，支持 session_notification 回调中获取 request_id。
|
||||
- 实现 ACP 客户端的 session_notification，将 Agent 的会话更新转换为统一通知并推送。
|
||||
- 会话缓存与推送（service/session_cache.rs）
|
||||
- 全局会话缓存、项目-会话映射、环形缓冲区与实时推送，提供 push_session_update 与 push_session_update_with_project 两个便捷函数。
|
||||
- 代理服务抽象（agent_service.rs）
|
||||
- 定义 AcpAgentService trait，统一启动流程与代理类型名。
|
||||
- 代理启动与通道绑定（claude_code_agent.rs、codex_agent.rs）
|
||||
- 启动子进程/代理实例，创建 unbounded channel 用于取消与提示，绑定到通用通道处理工具。
|
||||
- 共享模型与错误（shared_types）
|
||||
- 统一的 Agent 状态、生命周期、通知模型与错误类型，保证跨模块一致性。
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 架构总览
|
||||
通道工具在代理运行器中的作用是“桥接外部命令与内部 Agent 执行”，并通过统一的通知模型将状态与结果广播给前端或上层服务。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RC as "rcoder/上层"
|
||||
participant AG as "代理启动器<br/>claude_code_agent.rs/codex_agent.rs"
|
||||
participant CH as "通道工具<br/>channel_utils.rs"
|
||||
participant AC as "Agent 客户端连接"
|
||||
participant SV as "会话缓存<br/>session_cache.rs"
|
||||
participant FE as "前端/订阅者"
|
||||
RC->>AG : 发送取消/提示命令
|
||||
AG->>CH : 通过 unbounded channel 分发
|
||||
CH->>AC : 调用 cancel/prompt
|
||||
AC-->>CH : 返回执行结果/错误
|
||||
CH->>SV : 推送 SessionPromptStart/End/Error
|
||||
SV-->>FE : 通过 SSE 广播统一通知
|
||||
CH->>CH : 更新 Agent 状态Active/Idle
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L232-L278)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 通用通道处理工具（channel_utils）
|
||||
- 功能概览
|
||||
- 取消处理任务：接收取消通知，调用 Agent.cancel，带超时保护，发送响应并恢复 Agent 状态。
|
||||
- 提示处理任务：接收提示请求，校验/修正会话 ID，提取 request_id，更新 Agent 状态，发送开始通知，执行 prompt，按成功/失败路径发送结束通知并恢复状态。
|
||||
- 设计理念
|
||||
- 超时保护：对 Agent.cancel 加入固定超时，避免阻塞通道处理。
|
||||
- 状态机：在处理前后维护 Agent 状态（Active/Idle），确保状态与实际执行一致。
|
||||
- 请求上下文：从 PromptRequest.meta 提取 request_id 并写入会话级上下文，便于后续通知携带。
|
||||
- 通知闭环：无论成功或失败，均发送 SessionPromptEnd，确保会话结束语义明确。
|
||||
- 性能特征
|
||||
- 使用 unbounded channel 降低背压压力，适合高吞吐的提示处理。
|
||||
- 通过 tokio::task::spawn_local 在本地任务集中运行，减少跨线程调度开销。
|
||||
- 通知广播通过统一模型与会话缓存，避免重复序列化与多路分发。
|
||||
- 使用注意事项
|
||||
- 会话 ID 不一致时会强制覆盖为目标会话，确保消息路由正确。
|
||||
- request_id 为空时不会影响整体流程，但可能影响前端关联。
|
||||
- 错误路径会同时发送 SessionPromptError 与 SessionPromptEnd，确保前端能感知错误并结束会话。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入提示处理任务"]) --> CheckSID["校验/修正 session_id"]
|
||||
CheckSID --> ExtractRID["从 meta 提取 request_id"]
|
||||
ExtractRID --> UpdateStatus["更新 Agent 状态为 Active"]
|
||||
UpdateStatus --> SaveCtx["写入会话级上下文project_id->request_id"]
|
||||
SaveCtx --> NotifyStart["发送 SessionPromptStart"]
|
||||
NotifyStart --> CallPrompt["调用 Agent.prompt()"]
|
||||
CallPrompt --> Ok{"执行成功？"}
|
||||
Ok --> |是| NotifyEnd["发送 SessionPromptEndstop_reason"]
|
||||
Ok --> |否| NotifyErr["发送 SessionPromptError含 code/message"]
|
||||
NotifyErr --> NotifyEnd2["发送 SessionPromptEndCancelled"]
|
||||
NotifyEnd --> ResetStatus["恢复 Agent 状态为 Idle"]
|
||||
NotifyEnd2 --> ResetStatus
|
||||
ResetStatus --> End(["任务继续监听新消息"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L229)
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
|
||||
### 会话级上下文与通知入口（proxy_agent/mod.rs）
|
||||
- 功能概览
|
||||
- 维护会话级 request_id 上下文映射（project_id -> request_id），避免锁竞争。
|
||||
- 实现 ACP 客户端的 session_notification，优先从 meta 获取 request_id，否则通过 session_id 查找 project_id 再从上下文获取，最终将 AgentSessionUpdate 转换为统一通知并推送。
|
||||
- 设计理念
|
||||
- 以 project_id 为键的上下文映射，确保同一项目多次请求自动覆盖为最新值，避免过期 request_id 影响。
|
||||
- 通知转换严格遵循统一模型，保证前端消费一致性。
|
||||
- 使用注意事项
|
||||
- 若 meta 与上下文均无 request_id，通知仍会成功推送，但前端可能缺少请求关联信息。
|
||||
|
||||
章节来源
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
|
||||
### 会话缓存与推送（service/session_cache.rs）
|
||||
- 功能概览
|
||||
- 全局会话缓存（DashMap），按 session_id 分组，使用环形缓冲区保存最近消息，实时推送至当前连接。
|
||||
- 提供 push_session_update 与 push_session_update_with_project 两个便捷函数，后者自动处理项目-会话映射变更并清理旧数据。
|
||||
- SessionWorker 通过命令通道管理推送、清理与统计。
|
||||
- 设计理念
|
||||
- 极简优化：直接共享当前连接状态，避免命令传递带来的额外复杂度。
|
||||
- 心跳与实时推送：心跳消息单独处理，避免缓冲区占用。
|
||||
- 会话映射一致性：ensure_project_session 在 session_id 变更时清理旧数据并更新映射，避免脏数据污染。
|
||||
- 使用注意事项
|
||||
- 当前连接关闭时会显式 drop 发送端，接收端 recv() 立即返回 None，确保及时感知断开。
|
||||
- 清理旧会话数据时会移除缓存条目，注意不要在清理后继续向旧会话推送。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class SessionData {
|
||||
+command_tx
|
||||
+current_sender
|
||||
+current_cancel
|
||||
+create_new_connection(buffer_size)
|
||||
+push_message(message)
|
||||
+close_current_connection()
|
||||
}
|
||||
class SessionWorker {
|
||||
+max_size
|
||||
+command_rx
|
||||
+current_sender
|
||||
+current_cancel
|
||||
+run()
|
||||
}
|
||||
class SessionCache {
|
||||
+push_session_update(session_id, notify)
|
||||
+push_session_update_with_project(project_id, session_id, notify)
|
||||
+ensure_project_session(project_id, session_id)
|
||||
}
|
||||
SessionData --> SessionWorker : "spawn"
|
||||
SessionCache --> SessionData : "管理"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
|
||||
章节来源
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
|
||||
### 代理服务抽象与启动（agent_service.rs、claude_code_agent.rs、codex_agent.rs）
|
||||
- 功能概览
|
||||
- AcpAgentService 抽象统一启动流程，不同代理类型通过其实现启动。
|
||||
- 启动时创建取消与提示通道，绑定到通用通道处理工具，启动后等待取消信号。
|
||||
- 设计理念
|
||||
- 通过 trait 解耦代理类型，统一生命周期管理。
|
||||
- 通道绑定与任务分离，便于扩展与维护。
|
||||
- 使用注意事项
|
||||
- 通道使用 unbounded channel，注意避免无限增长导致内存压力。
|
||||
- 取消信号通过 CancellationToken 传播，确保子进程/连接正确退出。
|
||||
|
||||
章节来源
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L1-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
|
||||
### 统一通知模型与错误类型（shared_types）
|
||||
- 功能概览
|
||||
- 统一通知模型（SessionNotify）与统一消息（UnifiedSessionMessage），支持多种消息类型与子类型。
|
||||
- 错误类型（AppError）统一错误表示，支持从 tokio mpsc SendError 转换。
|
||||
- 设计理念
|
||||
- 前后端一致的事件模型，便于前端消费与状态机驱动。
|
||||
- 错误结构保留 code 与 message，便于前端展示与诊断。
|
||||
- 使用注意事项
|
||||
- 错误路径中 data 直接包含 code 与 message，前端无需二次解析。
|
||||
|
||||
章节来源
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
|
||||
## 依赖分析
|
||||
- 组件耦合
|
||||
- channel_utils 依赖代理运行器的全局映射（项目-代理信息）与会话缓存推送函数。
|
||||
- proxy_agent/mod.rs 依赖 shared_types 的通知模型与会话缓存推送函数。
|
||||
- 代理启动器（claude_code_agent.rs、codex_agent.rs）依赖 channel_utils 与 ACP 客户端连接。
|
||||
- 外部依赖
|
||||
- tokio mpsc、dashmap、ringbuf、tokio-util CancellationToken 等。
|
||||
- 循环依赖
|
||||
- 通过模块拆分与函数边界清晰，未发现循环依赖迹象。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CU["channel_utils.rs"] --> SC["service/session_cache.rs"]
|
||||
CU --> AM["shared_types/agent_model.rs"]
|
||||
MOD["proxy_agent/mod.rs"] --> SC
|
||||
MOD --> AN["shared_types/agent_session_notify.rs"]
|
||||
CA["claude_code_agent.rs"] --> CU
|
||||
CO["codex_agent.rs"] --> CU
|
||||
SC --> AN
|
||||
AM --> CU
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L1-L230)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L1-L256)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L1-L355)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
- [agent_session_notify.rs](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
|
||||
## 性能考量
|
||||
- 通道选择
|
||||
- 提示处理使用 unbounded channel，降低背压，适合高并发提示场景。
|
||||
- 取消处理使用 unbounded channel，结合超时保护，避免阻塞。
|
||||
- 状态与上下文
|
||||
- 使用 DashMap 与 LazyLock 保证全局状态访问的低锁争用。
|
||||
- 会话级上下文使用 project_id 作为键，避免锁竞争。
|
||||
- 缓冲与推送
|
||||
- 环形缓冲区限制内存占用，实时推送失败时自动降级为丢弃旧数据。
|
||||
- 心跳消息不计入缓冲，避免阻塞。
|
||||
- 生命周期
|
||||
- CancellationToken 与显式 drop 发送端，确保连接断开的确定性与及时性。
|
||||
|
||||
[本节为通用性能讨论，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 取消超时
|
||||
- 现象：取消请求响应为超时。
|
||||
- 排查：确认 Agent.cancel 是否阻塞，检查超时阈值与网络状况。
|
||||
- 参考路径：[取消处理任务](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L89)
|
||||
- 提示失败
|
||||
- 现象：提示执行失败，前端收到错误通知。
|
||||
- 排查：检查 Agent.prompt 返回的错误结构，确认错误消息是否包含 code 与 message。
|
||||
- 参考路径：[提示处理任务错误分支](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L190-L224)
|
||||
- 通知未到达
|
||||
- 现象：前端未收到 SessionPromptStart/End/Error。
|
||||
- 排查：确认 push_session_update_with_project 是否正确更新项目-会话映射；检查 SessionData 是否仍在运行。
|
||||
- 参考路径：[会话缓存推送](file://crates/agent_runner/src/service/session_cache.rs#L232-L278)
|
||||
- request_id 缺失
|
||||
- 现象：前端无法关联请求。
|
||||
- 排查：确认 PromptRequest.meta 是否包含 request_id；若缺失，检查 session_notification 是否能通过 project_id 从上下文获取。
|
||||
- 参考路径：[会话通知入口](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L209)
|
||||
|
||||
章节来源
|
||||
- [channel_utils.rs](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L224)
|
||||
- [session_cache.rs](file://crates/agent_runner/src/service/session_cache.rs#L232-L278)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L209)
|
||||
|
||||
## 结论
|
||||
通道工具通过“取消处理任务 + 提示处理任务”的双通道模式，将外部命令与内部 Agent 执行解耦，配合统一通知模型与会话缓存，实现了高效、稳定且可扩展的异步通信。其设计理念强调超时保护、状态机一致性与上下文透传，既满足高并发场景下的性能需求，又保证了错误路径的可观测性与前端体验的一致性。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 典型使用模式（路径指引）
|
||||
- 启动代理并绑定通道
|
||||
- Claude 代理：[启动流程与通道绑定](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L1-L311)
|
||||
- Codex 代理：[启动流程与通道绑定](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L294-L318)
|
||||
- 取消处理任务
|
||||
- [通用取消处理函数](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L18-L89)
|
||||
- 提示处理任务
|
||||
- [通用提示处理函数](file://crates/agent_runner/src/proxy_agent/channel_utils.rs#L92-L229)
|
||||
- 会话通知入口
|
||||
- [session_notification 实现](file://crates/agent_runner/src/proxy_agent/mod.rs#L149-L209)
|
||||
- 会话缓存与推送
|
||||
- [统一推送函数](file://crates/agent_runner/src/service/session_cache.rs#L232-L278)
|
||||
- [项目-会话映射更新](file://crates/agent_runner/src/service/session_cache.rs#L282-L354)
|
||||
- 统一通知模型
|
||||
- [通知转统一消息](file://crates/shared_types/src/model/agent_session_notify.rs#L82-L163)
|
||||
- 错误类型
|
||||
- [AppError 定义与转换](file://crates/shared_types/src/model/app_error.rs#L1-L65)
|
||||
348
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/反向代理架构.md
Normal file
348
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/反向代理架构.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# 反向代理架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [proxy_handler_api.rs](file://crates/rcoder/src/handler/proxy_handler_api.rs)
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障恢复机制](#故障恢复机制)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
本文档详细描述了基于Cloudflare Pingora构建的高性能反向代理架构。该架构设计用于在Docker容器环境中统一端口访问多个前端应用，通过端口参数实现灵活的请求路由。文档涵盖了端口路由机制、请求转发流程、状态监控和与主应用的集成模式，解释了选择Pingora而非Nginx的技术决策、性能优化策略和资源隔离方案。
|
||||
|
||||
## 项目结构
|
||||
反向代理功能主要由`pingora-proxy` crate实现，该模块提供了完整的基于Pingora的高性能代理服务。主应用通过集成此模块，实现了对多个后端服务的统一访问和管理。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "主应用"
|
||||
A[rcoder]
|
||||
B[agent_runner]
|
||||
end
|
||||
subgraph "反向代理模块"
|
||||
C[pingora-proxy]
|
||||
D[config]
|
||||
E[service]
|
||||
F[server]
|
||||
G[pingora_server]
|
||||
end
|
||||
A --> C
|
||||
B --> C
|
||||
C --> D
|
||||
C --> E
|
||||
C --> F
|
||||
C --> G
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
|
||||
**章节来源**
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
|
||||
## 核心组件
|
||||
反向代理的核心组件包括配置管理、服务实现、服务器管理和请求处理。`ProxyConfig`定义了代理服务的配置参数，`PingoraProxyService`实现了核心的代理逻辑，`ProxyServer`提供了服务器的启动和管理功能，而`PingoraServerManager`则负责完整的Pingora服务器生命周期管理。
|
||||
|
||||
**章节来源**
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
- [pingora_server.rs](file://crates/pingora-proxy/src/pingora_server.rs)
|
||||
|
||||
## 架构概述
|
||||
基于Pingora的反向代理架构采用分层设计，从配置层到服务层再到服务器层，每一层都有明确的职责。该架构支持HTTP/1.1和HTTP/2，利用Pingora的异步I/O能力实现高性能请求处理。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[客户端请求] --> B[端口路由]
|
||||
B --> C{路由规则}
|
||||
C --> |/proxy/{port}| D[提取目标端口]
|
||||
C --> |?port={port}| E[提取查询参数]
|
||||
C --> |默认端口| F[使用默认端口]
|
||||
D --> G[动态后端管理]
|
||||
E --> G
|
||||
F --> G
|
||||
G --> H[健康检查]
|
||||
H --> I[连接池管理]
|
||||
I --> J[请求转发]
|
||||
J --> K[后端服务]
|
||||
K --> L[响应处理]
|
||||
L --> M[客户端响应]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 端口路由机制
|
||||
端口路由机制支持两种方式：路径方式（/proxy/{port}/{path}）和查询参数方式（?port={port}）。路径方式优先级高于查询参数方式，系统会首先尝试从路径中提取端口号，如果失败则尝试从查询参数中提取，最后使用默认端口。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> CheckPath{"路径是否以<br/>/proxy/开头?"}
|
||||
CheckPath --> |是| ExtractPortFromPath["从路径提取端口<br/>(parts[2].parse())"]
|
||||
CheckPath --> |否| CheckQuery{"查询参数中<br/>是否有port?"}
|
||||
CheckQuery --> |是| ExtractPortFromQuery["从查询参数提取端口<br/>(param.split_once('=')"]
|
||||
CheckQuery --> |否| UseDefaultPort["使用默认端口<br/>(3000)"]
|
||||
ExtractPortFromPath --> ValidatePort{"端口有效?"}
|
||||
ExtractPortFromQuery --> ValidatePort
|
||||
ValidatePort --> |是| ReturnPort["返回提取的端口"]
|
||||
ValidatePort --> |否| ReturnDefault["返回默认端口"]
|
||||
ReturnPort --> End([结束])
|
||||
ReturnDefault --> End
|
||||
UseDefaultPort --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L358-L375)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L478-L507)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
|
||||
### 请求转发流程
|
||||
请求转发流程由`PortProxy`实现，该组件实现了Pingora的`ProxyHttp` trait，负责处理请求的完整生命周期，包括请求头过滤、上游服务器选择和响应过滤。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Proxy as "反向代理"
|
||||
participant Backend as "后端服务"
|
||||
Client->>Proxy : HTTP请求
|
||||
Proxy->>Proxy : 提取目标端口
|
||||
Proxy->>Proxy : 动态添加后端(如需要)
|
||||
Proxy->>Proxy : 重写Host头为127.0.0.1
|
||||
Proxy->>Proxy : 添加代理头(X-Forwarded-Proto等)
|
||||
Proxy->>Proxy : 重写请求路径
|
||||
Proxy->>Backend : 转发请求
|
||||
Backend-->>Proxy : 响应
|
||||
Proxy->>Proxy : 记录指标(响应时间等)
|
||||
Proxy->>Client : 返回响应
|
||||
Note over Proxy,Backend : 基于Pingora的异步代理流程
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L247-L353)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L397)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
|
||||
### 状态监控与统计
|
||||
反向代理提供了全面的状态监控和统计功能，包括请求计数、成功率、响应时间、活跃连接数等指标。这些指标通过`ProxyMetrics`结构体进行管理，并可通过API接口查询。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ProxyMetrics {
|
||||
+total_requests : AtomicU64
|
||||
+total_responses : AtomicU64
|
||||
+successful_responses : AtomicU64
|
||||
+failed_responses : AtomicU64
|
||||
+total_response_time_ns : AtomicU64
|
||||
+active_connections : AtomicU64
|
||||
+port_map : RwLock~HashMap<u16, Arc<PerPortMetrics>>~
|
||||
+record_request()
|
||||
+record_response()
|
||||
+avg_response_time_ms()
|
||||
+port_snapshots()
|
||||
}
|
||||
class PerPortMetrics {
|
||||
+requests : AtomicU64
|
||||
+successes : AtomicU64
|
||||
+failures : AtomicU64
|
||||
+total_response_time_ns : AtomicU64
|
||||
}
|
||||
class PortSnapshot {
|
||||
+port : u16
|
||||
+requests : u64
|
||||
+successes : u64
|
||||
+failures : u64
|
||||
+total_response_time_ns : u64
|
||||
}
|
||||
ProxyMetrics --> PerPortMetrics : "包含"
|
||||
ProxyMetrics --> PortSnapshot : "生成"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L26-L180)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L598-L607)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
|
||||
### 与主应用的集成模式
|
||||
反向代理通过`AppState`与主应用集成，主应用在启动时创建`PingoraProxyService`实例并将其注入应用状态，从而实现状态监控API与实际代理服务的数据共享。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppState {
|
||||
+sessions : DashMap~String, Arc<ProjectAndContainerInfo>~
|
||||
+project_and_agent_map : DashMap~String, Arc<ProjectAndContainerInfo>~
|
||||
+config : AppConfig
|
||||
+pingora_service : Option~Arc<PingoraProxyService>~
|
||||
}
|
||||
class PingoraProxyService {
|
||||
+config : ProxyConfig
|
||||
+backends : Arc~RwLock<HashMap<u16, String>>~
|
||||
+use_round_robin : bool
|
||||
+metrics : Arc~ProxyMetrics~
|
||||
+health_map : Arc~RwLock<HashMap<u16, HealthInfo>>~
|
||||
+new(config)
|
||||
+create_pingora_proxy()
|
||||
+add_backend()
|
||||
+remove_backend()
|
||||
+list_backends()
|
||||
+start_health_check_loop()
|
||||
}
|
||||
class AppConfig {
|
||||
+proxy_config : Option~ProxyConfig~
|
||||
+projects_dir : String
|
||||
+agent : AgentConfig
|
||||
}
|
||||
AppState --> PingoraProxyService : "引用"
|
||||
AppState --> AppConfig : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [router.rs](file://crates/rcoder/src/router.rs#L27-L35)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L224-L233)
|
||||
|
||||
**章节来源**
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
|
||||
## 依赖分析
|
||||
反向代理模块依赖于多个关键的Rust库，包括Pingora系列库用于高性能代理，Tokio用于异步运行时，Tracing用于日志记录，以及Axum用于HTTP服务构建。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[pingora-proxy] --> B[pingora]
|
||||
A --> C[pingora-core]
|
||||
A --> D[pingora-http]
|
||||
A --> E[pingora-proxy]
|
||||
A --> F[pingora-load-balancing]
|
||||
A --> G[tokio]
|
||||
A --> H[tracing]
|
||||
A --> I[axum]
|
||||
A --> J[reqwest]
|
||||
A --> K[async-trait]
|
||||
B --> L[Cloudflare Pingora]
|
||||
C --> L
|
||||
D --> L
|
||||
E --> L
|
||||
F --> L
|
||||
G --> M[Tokio Runtime]
|
||||
H --> N[Tracing Framework]
|
||||
I --> O[Axum Web Framework]
|
||||
J --> P[HTTP Client]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
|
||||
## 性能考虑
|
||||
基于Pingora的反向代理在性能方面进行了多项优化，包括异步I/O处理、连接池管理、负载均衡和健康检查。与Nginx相比，Pingora作为Rust编写的库，提供了更好的内存安全性和性能表现。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[性能优化策略] --> B[异步I/O]
|
||||
A --> C[连接池]
|
||||
A --> D[负载均衡]
|
||||
A --> E[健康检查]
|
||||
A --> F[零拷贝]
|
||||
A --> G[内存安全]
|
||||
B --> H["基于Tokio的异步运行时<br/>避免线程阻塞"]
|
||||
C --> I["复用TCP连接<br/>减少握手开销"]
|
||||
D --> J["Round Robin/Ketama算法<br/>均匀分发请求"]
|
||||
E --> K["定期TCP健康检查<br/>自动剔除故障节点"]
|
||||
F --> L["避免数据复制<br/>提高吞吐量"]
|
||||
G --> M["Rust所有权模型<br/>防止内存泄漏"]
|
||||
style A fill:#f9f,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [server.rs](file://crates/pingora-proxy/src/server.rs)
|
||||
|
||||
## 故障恢复机制
|
||||
反向代理实现了完善的故障恢复机制，包括健康检查、自动故障转移和连接重试。健康检查定期检测后端服务的可用性，并在服务恢复后自动重新加入负载均衡。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Healthy
|
||||
Healthy --> Unhealthy : "健康检查失败"
|
||||
Unhealthy --> Healthy : "健康检查通过"
|
||||
Unhealthy --> Timeout : "连接超时"
|
||||
Timeout --> Unhealthy : "重试失败"
|
||||
Timeout --> Healthy : "重试成功"
|
||||
state Healthy {
|
||||
[*] --> Active
|
||||
Active --> Draining : "服务停止"
|
||||
Draining --> [*]
|
||||
}
|
||||
state Unhealthy {
|
||||
[*] --> Inactive
|
||||
Inactive --> [*]
|
||||
}
|
||||
state Timeout {
|
||||
[*] --> Retrying
|
||||
Retrying --> Healthy : "成功"
|
||||
Retrying --> Unhealthy : "失败"
|
||||
}
|
||||
note right of Healthy
|
||||
健康状态：可正常处理请求
|
||||
定期健康检查：每5秒一次
|
||||
end note
|
||||
note right of Unhealthy
|
||||
不健康状态：从负载均衡中移除
|
||||
不再接收新请求
|
||||
end note
|
||||
note right of Timeout
|
||||
超时状态：连接失败
|
||||
进行重试机制
|
||||
end note
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L556-L591)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L182-L197)
|
||||
|
||||
**章节来源**
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
|
||||
## 结论
|
||||
基于Pingora的反向代理架构提供了一个高性能、高可靠性的解决方案，特别适合在容器化环境中统一管理多个前端应用的访问。通过端口路由机制，实现了灵活的服务访问；通过健康检查和负载均衡，确保了服务的高可用性；通过详细的指标统计，提供了全面的监控能力。与主应用的紧密集成使得状态监控和配置管理更加便捷，整体架构设计合理，性能优越。
|
||||
278
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/容器管理架构.md
Normal file
278
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/容器管理架构.md
Normal file
@@ -0,0 +1,278 @@
|
||||
# 容器管理架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [Cargo.toml](file://crates/docker_manager/Cargo.toml)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [service_type.rs](file://crates/shared_types/src/service_type.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档详细描述了RCoder系统中容器管理架构的设计与实现。该架构基于Docker API，通过bollard客户端库实现对Docker容器的全生命周期管理，包括容器的创建、启动、停止和清理。系统支持多Docker镜像配置，能够根据服务类型和硬件架构自动选择最合适的镜像。架构设计中包含了启动时清理和运行时清理两种策略，确保系统稳定性和资源高效利用。同时，文档还涵盖了资源隔离、网络配置、安全性考虑和性能优化等关键方面。
|
||||
|
||||
## 项目结构
|
||||
容器管理功能主要位于`crates/docker_manager`目录下，作为一个独立的Rust crate实现。该模块通过bollard库与Docker守护进程交互，提供了完整的容器管理API。系统通过`MultiImageConfig`和`ServiceImageConfig`等配置结构支持多镜像配置，能够根据服务类型和硬件架构动态选择镜像。容器管理器与RCoder主应用通过`rcoder/src/service/container_manager.rs`进行集成，为上层应用提供容器生命周期管理服务。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
subgraph "容器管理模块"
|
||||
DM[crates/docker_manager]
|
||||
DM --> Lib[lib.rs]
|
||||
DM --> Manager[manager.rs]
|
||||
DM --> ImageSelector[image_selector.rs]
|
||||
DM --> Types[types.rs]
|
||||
DM --> Utils[utils.rs]
|
||||
DM --> ContainerStop[container_stop.rs]
|
||||
DM --> ContainerInspector[container_self_inspector.rs]
|
||||
end
|
||||
subgraph "共享类型"
|
||||
ST[crates/shared_types]
|
||||
ST --> MultiImageConfig[multi_image_config.rs]
|
||||
ST --> ServiceConfig[service_config.rs]
|
||||
ST --> ServiceType[service_type.rs]
|
||||
end
|
||||
subgraph "RCoder主应用"
|
||||
RC[crates/rcoder]
|
||||
RC --> ContainerAgent[docker_container_agent.rs]
|
||||
RC --> ContainerManager[container_manager.rs]
|
||||
end
|
||||
DM --> ST
|
||||
RC --> DM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
|
||||
**Section sources**
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
|
||||
## 核心组件
|
||||
容器管理架构的核心组件包括DockerManager、ImageSelector和ContainerStop模块。DockerManager是主要的容器管理器，负责容器的创建、启动、停止和状态监控。ImageSelector模块根据服务类型和项目配置选择合适的Docker镜像，支持多架构镜像的自动选择。ContainerStop模块提供了启动时清理和运行时清理两种策略，确保系统在启动和运行过程中都能有效管理容器资源。这些组件共同构成了一个健壮的容器管理解决方案，支持RCoder系统的动态容器化需求。
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
|
||||
## 架构概述
|
||||
容器管理架构采用分层设计，上层为业务逻辑层，中层为容器管理服务层，底层为Docker API交互层。系统通过DockerManager单例模式提供全局容器管理服务，确保资源的统一管理和高效利用。架构支持动态网络配置，所有容器共享同一网络以便互相通信，同时通过环境变量和挂载点实现服务间的隔离。多镜像配置系统允许根据服务类型和硬件架构灵活选择镜像，提高了系统的可扩展性和适应性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[业务应用] --> B[容器管理服务]
|
||||
B --> C[DockerManager]
|
||||
C --> D[ImageSelector]
|
||||
C --> E[ContainerStop]
|
||||
C --> F[ContainerInspector]
|
||||
C --> G[Bollard Docker Client]
|
||||
G --> H[Docker Daemon]
|
||||
style A fill:#f9f,stroke:#333
|
||||
style B fill:#bbf,stroke:#333
|
||||
style C fill:#f96,stroke:#333
|
||||
style D fill:#9f9,stroke:#333
|
||||
style E fill:#9f9,stroke:#333
|
||||
style F fill:#9f9,stroke:#333
|
||||
style G fill:#9f9,stroke:#333
|
||||
style H fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### DockerManager分析
|
||||
DockerManager是容器管理的核心组件，负责容器的全生命周期管理。它通过bollard库与Docker守护进程交互，提供了创建、启动、停止、重启和清理容器的完整功能。管理器使用DashMap数据结构维护容器映射，确保多线程环境下的安全访问。系统在初始化时会自动检测主网络名称，确保新创建的容器能够正确连接到主网络。
|
||||
|
||||
#### DockerManager类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DockerManager {
|
||||
+docker : Docker
|
||||
+config : DockerManagerConfig
|
||||
+containers : DashMap~String, DockerContainerInfo~
|
||||
+main_network_name : Arc~RwLock~String~~
|
||||
+new(config : DockerManagerConfig) DockerResult~Self~
|
||||
+create_container(config : DockerContainerConfig) DockerResult~DockerContainerInfo~
|
||||
+stop_container(project_id : &str) DockerResult~()~
|
||||
+get_container_info(project_id : &str) Option~DockerContainerInfo~
|
||||
+list_containers() Vec~DockerContainerInfo~
|
||||
+update_container_status(project_id : &str) DockerResult~Option~ContainerStatus~~
|
||||
+cleanup_all_containers() DockerResult~()~
|
||||
+get_container_logs(project_id : &str, lines : i64) DockerResult~String~
|
||||
+restart_container(project_id : &str) DockerResult~()~
|
||||
}
|
||||
class DockerContainerConfig {
|
||||
+project_id : String
|
||||
+image : String
|
||||
+name_prefix : String
|
||||
+host_path : String
|
||||
+container_path : String
|
||||
+work_dir : String
|
||||
+env_vars : HashMap~String, String~
|
||||
+port_bindings : HashMap~String, String~
|
||||
+network_mode : String
|
||||
+auto_remove : bool
|
||||
+resource_limits : Option~ResourceLimits~
|
||||
+extra_mounts : Vec~MountPoint~
|
||||
+command : Option~Vec~String~~
|
||||
+entrypoint : Option~Vec~String~~
|
||||
+network_name : Option~String~
|
||||
}
|
||||
class DockerContainerInfo {
|
||||
+container_id : String
|
||||
+container_name : String
|
||||
+project_id : String
|
||||
+image : String
|
||||
+status : ContainerStatus
|
||||
+created_at : DateTime~Utc~
|
||||
+started_at : Option~DateTime~Utc~~
|
||||
+host_path : String
|
||||
+container_path : String
|
||||
+port_bindings : HashMap~String, String~
|
||||
+assigned_port : u16
|
||||
+health_status : Option~String~
|
||||
+internal_port : u16
|
||||
+network_name : String
|
||||
}
|
||||
class DockerManagerConfig {
|
||||
+docker_host : Option~String~
|
||||
+default_image : String
|
||||
+default_platform : String
|
||||
+default_network_mode : String
|
||||
+default_work_dir : String
|
||||
+auto_cleanup : bool
|
||||
+container_ttl_seconds : Option~u64~
|
||||
+multi_image_config : MultiImageConfig
|
||||
}
|
||||
DockerManager --> DockerContainerConfig : "使用"
|
||||
DockerManager --> DockerContainerInfo : "管理"
|
||||
DockerManager --> DockerManagerConfig : "配置"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
|
||||
### ImageSelector分析
|
||||
ImageSelector模块负责根据服务类型和项目配置选择合适的Docker镜像。它实现了灵活的镜像选择策略，支持服务特定配置、架构特定镜像和全局默认配置。选择器会优先使用服务特定的通用镜像，如果没有则根据当前平台选择ARM64或AMD64架构的镜像，最后使用默认回退镜像。这种分层选择策略确保了系统在不同环境下的兼容性和稳定性。
|
||||
|
||||
#### 镜像选择流程图
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始选择镜像]) --> CheckServiceEnabled["检查服务是否启用"]
|
||||
CheckServiceEnabled --> |是| CheckServiceConfig["检查服务特定配置"]
|
||||
CheckServiceConfig --> CheckGenericImage["检查服务级通用镜像"]
|
||||
CheckGenericImage --> |存在| ReturnGenericImage["返回服务通用镜像"]
|
||||
CheckGenericImage --> |不存在| CheckPlatform["检查当前平台"]
|
||||
CheckPlatform --> |linux/arm64| CheckARM64Image["检查ARM64镜像"]
|
||||
CheckPlatform --> |linux/amd64| CheckAMD64Image["检查AMD64镜像"]
|
||||
CheckARM64Image --> |存在| ReturnARM64Image["返回ARM64镜像"]
|
||||
CheckARM64Image --> |不存在| ReturnDefaultImage["返回默认镜像"]
|
||||
CheckAMD64Image --> |存在| ReturnAMD64Image["返回AMD64镜像"]
|
||||
CheckAMD64Image --> |不存在| ReturnDefaultImage
|
||||
ReturnGenericImage --> End([返回镜像])
|
||||
ReturnARM64Image --> End
|
||||
ReturnAMD64Image --> End
|
||||
ReturnDefaultImage --> End
|
||||
CheckServiceEnabled --> |否| ReturnError["返回配置错误"]
|
||||
ReturnError --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
|
||||
### ContainerStop分析
|
||||
ContainerStop模块提供了两种容器清理策略：启动时清理和运行时清理。启动时清理用于服务启动时快速清理遗留容器，使用5秒超时并过滤409冲突错误，确保服务能快速启动。运行时清理用于运行时快速清理容器，使用3秒优雅停止超时，超时后立即强制停止，快速释放资源。两种策略都支持批量操作，通过并发处理提高清理效率。
|
||||
|
||||
#### 容器清理序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Startup as 启动时清理
|
||||
participant Runtime as 运行时清理
|
||||
participant DockerManager as DockerManager
|
||||
participant Bollard as Bollard Client
|
||||
Startup->>DockerManager : startup_cleanup_containers(pattern)
|
||||
DockerManager->>DockerManager : list_containers_with_pattern(pattern)
|
||||
loop 每个匹配的容器
|
||||
DockerManager->>DockerManager : spawn async task
|
||||
DockerManager->>DockerManager : stop_container_startup_mode(container_id)
|
||||
DockerManager->>Bollard : stop_container_by_id_with_timeout(5s)
|
||||
Bollard-->>DockerManager : 响应
|
||||
DockerManager->>DockerManager : 处理结果
|
||||
end
|
||||
DockerManager-->>Startup : 返回清理结果
|
||||
Runtime->>DockerManager : runtime_cleanup_container(container_id)
|
||||
DockerManager->>DockerManager : stop_container_runtime_mode(container_id)
|
||||
DockerManager->>Bollard : stop_container_by_id_with_timeout(3s)
|
||||
Bollard-->>DockerManager : 响应
|
||||
DockerManager->>DockerManager : 等待POST_STOP_WAIT_MS
|
||||
DockerManager-->>Runtime : 响应
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
|
||||
## 依赖分析
|
||||
容器管理模块依赖于多个外部库和内部组件。主要依赖包括bollard（Docker API客户端）、tokio（异步运行时）、serde（序列化）、tracing（日志记录）和shared_types（共享类型定义）。模块通过Cargo.toml文件管理这些依赖，确保版本的一致性和兼容性。内部依赖关系清晰，docker_manager模块依赖shared_types模块获取配置类型，而rcoder主应用依赖docker_manager模块提供容器管理服务。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[docker_manager] --> B[bollard]
|
||||
A --> C[tokio]
|
||||
A --> D[serde]
|
||||
A --> E[tracing]
|
||||
A --> F[shared_types]
|
||||
G[rcoder] --> A
|
||||
H[agent_runner] --> A
|
||||
style A fill:#f96,stroke:#333
|
||||
style B fill:#9f9,stroke:#333
|
||||
style C fill:#9f9,stroke:#333
|
||||
style D fill:#9f9,stroke:#333
|
||||
style E fill:#9f9,stroke:#333
|
||||
style F fill:#9f9,stroke:#333
|
||||
style G fill:#bbf,stroke:#333
|
||||
style H fill:#bbf,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cargo.toml](file://crates/docker_manager/Cargo.toml)
|
||||
|
||||
## 性能考虑
|
||||
容器管理架构在设计时充分考虑了性能因素。通过使用Arc和RwLock等并发原语，确保多线程环境下的高效访问。容器操作采用异步模式，避免阻塞主线程。批量操作通过并发处理提高效率，如启动时清理会并发停止所有匹配的容器。资源限制配置允许为每个容器设置内存和CPU限制，防止资源耗尽。网络配置优化减少了端口映射的需求，通过内部网络通信提高性能。
|
||||
|
||||
## 故障排除指南
|
||||
当容器管理出现问题时，可以按照以下步骤进行排查：首先检查Docker守护进程是否正常运行，然后查看容器日志获取详细错误信息。对于镜像拉取失败，检查网络连接和镜像仓库权限。对于容器启动失败，检查资源限制是否过于严格。对于网络连接问题，验证容器是否正确连接到主网络。系统提供了详细的日志记录，包括DEBUG级别的调试信息，有助于快速定位问题。
|
||||
|
||||
**Section sources**
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [container_stop.rs](file://crates/docker_manager/src/container_stop.rs)
|
||||
|
||||
## 结论
|
||||
RCoder的容器管理架构设计合理，功能完整，能够有效支持系统的动态容器化需求。通过DockerManager、ImageSelector和ContainerStop等组件的协同工作，实现了容器全生命周期的自动化管理。架构支持多镜像配置和动态网络，具有良好的可扩展性和适应性。安全性考虑和性能优化措施确保了系统的稳定运行。未来可以进一步优化资源利用率和故障恢复机制，提升整体系统性能。
|
||||
218
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/核心模块架构.md
Normal file
218
qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/核心模块架构.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 核心模块架构
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [lib.rs](file://crates/rcoder/src/lib.rs)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [pingora-proxy](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [docker_manager](file://crates/docker_manager/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
rcoder 是一个基于 Rust 的 AI 代理框架，旨在为 AI 驱动的开发平台提供核心服务。该系统通过集成多种 AI 代理（如 Claude 和 Codex），为项目提供智能开发支持。架构设计强调模块化、可扩展性和容器化部署，通过反向代理和 Docker 管理实现灵活的服务集成和资源隔离。
|
||||
|
||||
## 项目结构
|
||||
项目采用多 crate 的 Rust 工作区结构，核心模块包括 rcoder、agent_runner、shared_types、docker_manager 和 pingora-proxy。这种模块化设计实现了关注点分离，每个 crate 负责特定功能，通过工作区依赖进行集成。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[crates/] --> B[rcoder]
|
||||
A --> C[agent_runner]
|
||||
A --> D[shared_types]
|
||||
A --> E[docker_manager]
|
||||
A --> F[pingora-proxy]
|
||||
A --> G[acp_adapter]
|
||||
A --> H[claude-code-agent]
|
||||
A --> I[codex-acp-agent]
|
||||
B --> J[src/]
|
||||
C --> K[src/]
|
||||
D --> L[src/]
|
||||
E --> M[src/]
|
||||
F --> N[src/]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
**本节来源**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 核心组件
|
||||
系统核心由 rcoder 主服务、agent_runner 代理管理、shared_types 共享类型、docker_manager 容器管理和 pingora-proxy 反向代理组成。rcoder 作为主入口，协调各组件工作；agent_runner 管理 AI 代理生命周期；shared_types 提供跨 crate 的数据结构；docker_manager 处理容器操作；pingora-proxy 实现动态请求代理。
|
||||
|
||||
**本节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
## 架构概述
|
||||
系统采用微服务架构，以 rcoder 为核心协调器，通过 HTTP API 接收外部请求，动态创建和管理 AI 代理容器。架构支持多代理类型，通过 ACP 协议与代理通信，并利用反向代理实现服务发现和负载均衡。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Client[客户端] --> |HTTP请求| Rcoder[rcoder主服务]
|
||||
Rcoder --> |创建容器| Docker[Docker引擎]
|
||||
Docker --> |运行| AgentContainer[AI代理容器]
|
||||
AgentContainer --> |ACP协议| Rcoder
|
||||
Rcoder --> |SSE流| Client
|
||||
Rcoder --> |反向代理| Pingora[pingora-proxy]
|
||||
Pingora --> |动态路由| Backend[后端服务]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [pingora-proxy](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||||
|
||||
**本节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [pingora-proxy](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### rcoder 主服务分析
|
||||
rcoder 是系统的核心服务，负责处理客户端请求、管理代理生命周期和协调系统组件。它通过 Axum 框架提供 REST API，集成 OpenTelemetry 进行遥测，并支持优雅关闭。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppConfig {
|
||||
+default_agent : AgentType
|
||||
+projects_dir : PathBuf
|
||||
+port : u16
|
||||
+proxy_config : Option<ProxyConfig>
|
||||
+docker_config : Option<DockerConfig>
|
||||
}
|
||||
class CliArgs {
|
||||
+port : Option<u16>
|
||||
+projects_dir : Option<String>
|
||||
+enable_proxy : bool
|
||||
+proxy_port : Option<u16>
|
||||
+default_backend_port : Option<u16>
|
||||
}
|
||||
class AppState {
|
||||
+config : AppConfig
|
||||
+pingora_service : Option<PingoraProxyService>
|
||||
}
|
||||
AppConfig --> CliArgs : "命令行参数覆盖"
|
||||
AppState --> AppConfig : "包含配置"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
**本节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
|
||||
### Agent 生命周期管理
|
||||
系统通过 RAII 模式管理 AI 代理的生命周期，确保资源的正确清理。AgentLifecycleGuard 在 drop 时自动执行清理操作，防止资源泄漏。
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Idle
|
||||
Idle --> Active : "收到请求"
|
||||
Active --> Terminating : "收到取消信号"
|
||||
Terminating --> Idle : "清理完成"
|
||||
Active --> Idle : "任务完成"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
**本节来源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L1-L483)
|
||||
|
||||
### 多镜像配置系统
|
||||
系统支持灵活的多镜像配置，允许为不同服务类型指定不同的 Docker 镜像。配置系统包含全局默认、服务特定配置和选择策略。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+global_defaults : GlobalImageDefaults
|
||||
+services : HashMap<String, ServiceImageConfig>
|
||||
+selection_strategy : ImageSelectionStrategy
|
||||
+cache_config : ImageCacheConfig
|
||||
}
|
||||
class GlobalImageDefaults {
|
||||
+image : Option<String>
|
||||
+arm64_image : Option<String>
|
||||
+amd64_image : Option<String>
|
||||
+default_image : Option<String>
|
||||
+registry_prefix : Option<String>
|
||||
}
|
||||
class ServiceImageConfig {
|
||||
+service_type : ServiceType
|
||||
+image : Option<String>
|
||||
+arm64_image : Option<String>
|
||||
+amd64_image : Option<String>
|
||||
+default_image : Option<String>
|
||||
+mounts : Vec<ServiceMountConfig>
|
||||
+environment : HashMap<String, String>
|
||||
+enabled : bool
|
||||
}
|
||||
MultiImageConfig --> GlobalImageDefaults : "包含"
|
||||
MultiImageConfig --> ServiceImageConfig : "包含多个"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
|
||||
**本节来源**
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
|
||||
## 依赖分析
|
||||
系统依赖关系清晰，rcoder 依赖 agent_runner、shared_types、docker_manager 和 pingora-proxy。shared_types 作为共享库，被多个 crate 依赖，提供统一的数据结构和协议定义。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Rcoder[rcoder] --> AgentRunner[agent_runner]
|
||||
Rcoder --> SharedTypes[shared_types]
|
||||
Rcoder --> DockerManager[docker_manager]
|
||||
Rcoder --> PingoraProxy[pingora-proxy]
|
||||
AgentRunner --> SharedTypes
|
||||
DockerManager --> SharedTypes
|
||||
PingoraProxy --> SharedTypes
|
||||
SharedTypes --> ACP[agent-client-protocol]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
|
||||
**本节来源**
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
|
||||
## 性能考虑
|
||||
系统在性能方面进行了多项优化：使用 Tokio 异步运行时处理并发请求，通过 DashMap 实现高效的状态管理，利用连接池减少资源开销。日志系统采用按天滚动策略，平衡了性能和可维护性。
|
||||
|
||||
**本节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
|
||||
## 故障排除指南
|
||||
系统提供了完善的故障排除机制，包括详细的日志记录、健康检查端点和调试工具。Docker 配置问题可通过环境变量和挂载检查解决，代理通信问题可通过日志级别调整进行诊断。
|
||||
|
||||
**本节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [Dockerfile](file://docker/Dockerfile#L1-L305)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
## 结论
|
||||
rcoder 架构设计合理，模块化程度高，具备良好的可扩展性和可维护性。通过微服务架构和容器化部署，系统能够灵活适应不同规模和需求的 AI 开发场景。未来可进一步优化性能监控和自动化部署流程。
|
||||
255
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/gRPC迁移设计.md
Normal file
255
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/gRPC迁移设计.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# gRPC迁移设计
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [build.rs](file://crates/shared_types/build.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
本文档全面阐述了从现有HTTP/SSE接口向gRPC协议迁移的架构演进路径。基于shared_types/proto/agent.proto定义，解析gRPC服务契约、消息结构和流式调用模式。说明迁移如何提升系统性能、降低延迟并增强类型安全性。对比Axum REST API与Pingora gRPC代理的性能差异，提供基准测试数据参考。描述双协议共存期间的兼容性策略，包括请求转换中间件和版本路由机制。结合Tracing中间件展示跨协议链路追踪的实现方式。解释proto定义与Rust模型（如AgentStatusResponse、ChatPrompt）的映射关系及序列化优化技巧。为开发者提供从REST到gRPC客户端的迁移指南，包含错误码映射、超时控制和流控策略调整等实践建议。
|
||||
|
||||
## 项目结构
|
||||
项目采用模块化设计，主要包含crates、docker、scripts、specs等目录。crates目录下包含多个Rust crate，如acp_adapter、agent_runner、claude-code-agent、codex-acp-agent、docker_manager、pingora-proxy、rcoder和shared_types。其中shared_types模块负责定义gRPC协议的proto文件和生成的Rust代码，agent_runner和rcoder分别作为gRPC服务端和客户端。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "crates"
|
||||
shared_types["shared_types (proto定义)"]
|
||||
agent_runner["agent_runner (gRPC Server)"]
|
||||
rcoder["rcoder (gRPC Client)"]
|
||||
pingora_proxy["pingora-proxy (代理)"]
|
||||
end
|
||||
shared_types --> agent_runner
|
||||
shared_types --> rcoder
|
||||
agent_runner --> pingora_proxy
|
||||
rcoder --> pingora_proxy
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
|
||||
**章节来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
|
||||
## 核心组件
|
||||
核心组件包括gRPC服务契约定义、服务端实现和客户端调用。通过shared_types模块中的proto文件定义服务接口，agent_runner实现服务端逻辑，rcoder作为客户端调用服务。迁移后，原有的HTTP/SSE通信将被gRPC取代，提升通信效率和类型安全性。
|
||||
|
||||
**章节来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
|
||||
## 架构概述
|
||||
系统架构从原有的HTTP/SSE通信模式演进为gRPC通信模式。在新的架构中，rcoder与agent-runner之间通过gRPC进行通信，使用二进制协议（Protobuf）替代JSON/文本协议，提升性能。gRPC Server Streaming替代SSE，简化实时进度通知的实现。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
rcoder["rcoder (gRPC Client)"] --> |gRPC| agent_runner["agent-runner (gRPC Server)"]
|
||||
agent_runner --> |HTTP/SSE| frontend["前端"]
|
||||
rcoder --> |HTTP| frontend
|
||||
style rcoder fill:#f9f,stroke:#333
|
||||
style agent_runner fill:#bbf,stroke:#333
|
||||
style frontend fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### gRPC服务契约分析
|
||||
gRPC服务契约在shared_types/proto/agent.proto中定义，包含AgentService服务和相关消息类型。服务定义了Chat、SubscribeProgress、CancelSession和GetStatus四个RPC方法，分别对应聊天对话、订阅进度、取消会话和获取状态功能。
|
||||
|
||||
#### 服务契约类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentService {
|
||||
+Chat(ChatRequest) ChatResponse
|
||||
+SubscribeProgress(ProgressRequest) stream ProgressEvent
|
||||
+CancelSession(CancelRequest) CancelResponse
|
||||
+GetStatus(GetStatusRequest) GetStatusResponse
|
||||
}
|
||||
class ChatRequest {
|
||||
+string project_id
|
||||
+string session_id
|
||||
+string prompt
|
||||
+optional ModelProviderConfig model_config
|
||||
+repeated Attachment attachments
|
||||
+optional string request_id
|
||||
}
|
||||
class ChatResponse {
|
||||
+string request_id
|
||||
+bool success
|
||||
+optional string error
|
||||
}
|
||||
class ProgressRequest {
|
||||
+string session_id
|
||||
}
|
||||
class ProgressEvent {
|
||||
+oneof event
|
||||
+string json_payload
|
||||
+int64 timestamp
|
||||
}
|
||||
class CancelRequest {
|
||||
+string session_id
|
||||
+string reason
|
||||
}
|
||||
class CancelResponse {
|
||||
+bool success
|
||||
}
|
||||
class GetStatusRequest {
|
||||
+string project_id
|
||||
}
|
||||
class GetStatusResponse {
|
||||
+string status
|
||||
}
|
||||
class ModelProviderConfig {
|
||||
+string provider
|
||||
+string model
|
||||
+optional string api_key
|
||||
+optional string api_base
|
||||
}
|
||||
class Attachment {
|
||||
+string name
|
||||
+string kind
|
||||
+string content
|
||||
+string source
|
||||
+optional string language
|
||||
}
|
||||
AgentService --> ChatRequest : "使用"
|
||||
AgentService --> ChatResponse : "使用"
|
||||
AgentService --> ProgressRequest : "使用"
|
||||
AgentService --> ProgressEvent : "使用"
|
||||
AgentService --> CancelRequest : "使用"
|
||||
AgentService --> CancelResponse : "使用"
|
||||
AgentService --> GetStatusRequest : "使用"
|
||||
AgentService --> GetStatusResponse : "使用"
|
||||
AgentService --> ModelProviderConfig : "使用"
|
||||
AgentService --> Attachment : "使用"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
|
||||
**章节来源**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
|
||||
### 服务端实现分析
|
||||
agent_runner作为gRPC服务端，实现了AgentService服务。在main.rs中启动Tonic gRPC Server，同时保留Axum HTTP Server用于健康检查。通过tokio::sync::mpsc接收内部事件总线的消息，并通过ReceiverStream转换为gRPC流返回。
|
||||
|
||||
#### 服务端启动序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Main as "main.rs"
|
||||
participant GRPC as "Tonic gRPC Server"
|
||||
participant Axum as "Axum HTTP Server"
|
||||
participant AppState as "AppState"
|
||||
Main->>GRPC : 启动gRPC Server
|
||||
Main->>Axum : 启动HTTP Server
|
||||
GRPC->>AppState : 注册服务实现
|
||||
Axum->>AppState : 注册健康检查路由
|
||||
GRPC->>GRPC : 监听gRPC端口
|
||||
Axum->>Axum : 监听HTTP端口
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [router.rs](file://crates/agent_runner/src/router.rs)
|
||||
|
||||
### 客户端实现分析
|
||||
rcoder作为gRPC客户端，调用agent-runner的gRPC服务。维护gRPC Channel连接池，根据project_id动态构建Endpoint。将原有的SSE转发逻辑改造为调用gRPC SubscribeProgress接口，并将接收到的ProgressEvent消息转换为Axum SSE Event返回给前端。
|
||||
|
||||
#### 客户端调用序列图
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Frontend as "前端"
|
||||
participant Rcoder as "rcoder"
|
||||
participant AgentRunner as "agent-runner"
|
||||
Frontend->>Rcoder : GET /agent/progress/{session_id}
|
||||
Rcoder->>AgentRunner : gRPC SubscribeProgress(ProgressRequest)
|
||||
AgentRunner->>Rcoder : stream ProgressEvent
|
||||
Rcoder->>Frontend : SSE Event
|
||||
loop 实时进度推送
|
||||
AgentRunner->>Rcoder : ProgressEvent
|
||||
Rcoder->>Frontend : SSE Event
|
||||
end
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
|
||||
**章节来源**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [router.rs](file://crates/rcoder/src/router.rs)
|
||||
|
||||
## 依赖分析
|
||||
项目依赖关系清晰，shared_types作为公共依赖被agent_runner和rcoder引用。agent_runner和rcoder分别依赖pingora-proxy用于反向代理功能。通过Cargo.toml管理依赖，确保版本一致性。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
shared_types["shared_types"]
|
||||
agent_runner["agent_runner"]
|
||||
rcoder["rcoder"]
|
||||
pingora_proxy["pingora-proxy"]
|
||||
shared_types --> agent_runner
|
||||
shared_types --> rcoder
|
||||
agent_runner --> pingora_proxy
|
||||
rcoder --> pingora_proxy
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://crates/shared_types/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
|
||||
**章节来源**
|
||||
- [Cargo.toml](file://crates/shared_types/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
|
||||
## 性能考量
|
||||
gRPC迁移带来显著性能提升。二进制协议减少网络传输开销，强类型契约避免运行时类型检查，Server Streaming简化流式数据处理。相比HTTP/SSE，gRPC在延迟、吞吐量和资源利用率方面均有改善。通过基准测试验证性能差异，确保迁移后系统性能满足要求。
|
||||
|
||||
## 故障排除指南
|
||||
常见问题包括gRPC连接失败、proto编译错误和流式通信中断。检查网络连接、proto文件语法和gRPC服务配置。使用tracing中间件进行跨协议链路追踪，定位问题根源。确保shared_types版本一致，避免兼容性问题。
|
||||
|
||||
**章节来源**
|
||||
- [tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
|
||||
- [tracing_middleware.rs](file://crodes/src/middleware/tracing_middleware.rs)
|
||||
|
||||
## 结论
|
||||
gRPC迁移是系统架构演进的重要一步，通过二进制协议和强类型契约提升通信效率和类型安全性。服务端和客户端实现清晰，依赖关系明确。迁移后系统性能得到提升，为后续功能扩展奠定基础。开发者应遵循迁移指南，确保平滑过渡。
|
||||
226
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/代理抽象层设计.md
Normal file
226
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/代理抽象层设计.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# 代理抽象层设计
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [types.rs](file://crates/acp_adapter/src/types.rs)
|
||||
- [lib.rs](file://crates/agent_runner/src/lib.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs)
|
||||
- [chat_prompt.rs](file://crates/shared_types/src/model/chat_prompt.rs)
|
||||
- [chat_response.rs](file://crates/shared_types/src/model/chat_response.rs)
|
||||
- [model_provider.rs](file://crates/shared_types/src/model/model_provider.rs)
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [核心抽象机制](#核心抽象机制)
|
||||
3. [运行时调度逻辑](#运行时调度逻辑)
|
||||
4. [状态同步与会话管理](#状态同步与会话管理)
|
||||
5. [ACP协议设计决策](#acp协议设计决策)
|
||||
6. [插件式扩展设计](#插件式扩展设计)
|
||||
7. [集成问题排查](#集成问题排查)
|
||||
8. [调用链路与性能分析](#调用链路与性能分析)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
|
||||
本文档详细阐述了RCoder项目中代理抽象层的设计与实现。该设计旨在通过统一的接口管理异构AI代理（如Codex、Claude Code），实现对不同AI代理的无缝集成与扩展。系统通过ACP（Agent Client Protocol）协议作为通用通信标准，结合`agent_runner`和`acp_adapter`模块，构建了一个灵活、可扩展的代理管理框架。此抽象层不仅支持当前的AI代理，还为未来新代理的插件式扩展提供了坚实的基础，并与`docker_manager`和`shared_types`组件协同工作，确保系统的稳定性和可维护性。
|
||||
|
||||
## 核心抽象机制
|
||||
|
||||
代理抽象层的核心在于通过ACP协议实现对不同AI代理的统一管理。`acp_adapter`模块提供了与ACP兼容的AI代理通信的核心功能，包括连接管理、会话生命周期和消息处理。`agent_runner`模块则负责代理的启动、停止和状态监控。通过`AcpAgentService` trait，系统定义了启动代理服务的统一接口，使得不同类型的代理可以以一致的方式被调用。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class AgentType {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
class AcpConnectionInfo {
|
||||
+session_id : SessionId
|
||||
+prompt_tx : UnboundedSender~PromptRequest~
|
||||
+cancel_tx : UnboundedSender~CancelNotificationRequest~
|
||||
+stop_handle : Option~AgentStopHandleArc~
|
||||
}
|
||||
AcpAgentService <|-- ClaudeCodeAgent
|
||||
AcpAgentService <|-- CodexAgent
|
||||
AcpConnectionInfo --> AgentStopHandleArc
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L24)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L164-L191)
|
||||
- [mod.rs](file://crates/agent_runner/src/proxy_agent/mod.rs#L31-L41)
|
||||
|
||||
## 运行时调度逻辑
|
||||
|
||||
运行时调度逻辑通过`agent_worker`任务实现，该任务在本地线程中运行，监听来自前端的请求。当接收到请求时，系统首先检查是否存在对应的代理服务，若不存在则创建新的代理服务。对于已存在的代理服务，系统会复用现有服务，从而提高资源利用率。`agent_worker`通过`LocalSet`管理代理请求，确保每个项目ID对应一个代理服务，实现资源的高效利用。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Frontend as 前端
|
||||
participant AgentRunner as Agent Runner
|
||||
participant AgentService as Agent Service
|
||||
Frontend->>AgentRunner : 发送ChatPrompt请求
|
||||
AgentRunner->>AgentRunner : 检查PROJECT_AND_AGENT_INFO_MAP
|
||||
alt 代理服务存在
|
||||
AgentRunner->>AgentService : 复用现有代理服务
|
||||
else 代理服务不存在
|
||||
AgentRunner->>AgentService : 创建新的代理服务
|
||||
end
|
||||
AgentService->>AgentRunner : 返回AcpConnectionInfo
|
||||
AgentRunner->>Frontend : 发送ChatPromptResponse
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L340)
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
|
||||
## 状态同步与会话管理
|
||||
|
||||
状态同步与会话管理通过`ProjectAndAgentInfo`结构体实现，该结构体记录了项目ID与代理服务的映射关系。系统使用`DashMap`来管理这些映射，确保线程安全。当代理服务启动时，系统会创建一个会话ID，并将其与项目ID关联。通过`SESSION_REQUEST_CONTEXT`，系统能够在会话通知回调中获取当前请求的request_id，从而实现状态的精确同步。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ProjectAndAgentInfo {
|
||||
+project_id : String
|
||||
+session_id : SessionId
|
||||
+prompt_tx : UnboundedSender~PromptRequest~
|
||||
+cancel_tx : UnboundedSender~CancelNotificationRequest~
|
||||
+model_provider : Option~ModelProviderConfig~
|
||||
+request_id : Option~String~
|
||||
+status : AgentStatus
|
||||
+last_activity : DateTime~Utc~
|
||||
+created_at : DateTime~Utc~
|
||||
+stop_handle : Option~Arc~dyn AgentLifecycle~~
|
||||
}
|
||||
class SESSION_REQUEST_CONTEXT {
|
||||
+project_id : String
|
||||
+request_id : String
|
||||
}
|
||||
ProjectAndAgentInfo --> SESSION_REQUEST_CONTEXT
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L47-L68)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L25-L29)
|
||||
|
||||
## ACP协议设计决策
|
||||
|
||||
选择ACP协议作为通用通信标准的设计决策基于其灵活性和可扩展性。ACP协议不仅支持基本的文本消息传递，还支持附件、数据源信息等复杂数据类型。通过`PromptBuilder`和`ContentBuilder`，系统能够构建包含系统提示词、用户输入和数据源信息的最终提示词，从而实现丰富的交互功能。此外，ACP协议的版本管理机制确保了向后兼容性，使得系统能够平滑地升级到新版本。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class PromptBuilder {
|
||||
+build(prompt : &str) String
|
||||
+build_with_data_sources(prompt : &str, data_sources : &[String]) String
|
||||
}
|
||||
class ContentBuilder {
|
||||
+attachments_to_content_blocks(attachments : &[Attachment], project_path : &PathBuf) Result~Vec~ContentBlock~~
|
||||
}
|
||||
PromptBuilder --> ContentBuilder
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L343-L391)
|
||||
- [utils.rs](file://crates/agent_runner/src/utils/mod.rs#L1-L10)
|
||||
|
||||
## 插件式扩展设计
|
||||
|
||||
插件式扩展设计通过`AgentType`枚举和`AcpAgentService` trait实现。`AgentType`枚举定义了支持的代理类型，而`AcpAgentService` trait则提供了启动代理服务的统一接口。通过这种方式，系统能够轻松地添加新的代理类型，只需实现相应的`AcpAgentService` trait即可。此外，系统还支持通过配置文件动态加载代理配置，进一步增强了扩展性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AgentType {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class ClaudeCodeAgent {
|
||||
+start_claude_code_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
}
|
||||
class CodexAgent {
|
||||
+start_codex_acp_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
}
|
||||
AcpAgentService <|-- ClaudeCodeAgent
|
||||
AcpAgentService <|-- CodexAgent
|
||||
AgentType --> ClaudeCodeAgent
|
||||
AgentType --> CodexAgent
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_type.rs](file://crates/shared_types/src/model/agent_type.rs#L16-L24)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L25-L398)
|
||||
|
||||
## 集成问题排查
|
||||
|
||||
常见集成问题包括会话状态丢失和响应格式不兼容。会话状态丢失通常是由于代理服务未正确启动或会话ID未正确传递导致的。响应格式不兼容则可能是由于代理返回的数据类型与预期不符。为解决这些问题，系统提供了详细的日志记录和错误处理机制。通过`AgentLifecycleGuard`，系统能够确保代理资源的正确清理，从而避免资源泄漏。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> CheckSessionState["检查会话状态"]
|
||||
CheckSessionState --> SessionValid{"会话有效?"}
|
||||
SessionValid --> |是| ProcessRequest["处理请求"]
|
||||
SessionValid --> |否| RestartAgent["重启代理服务"]
|
||||
ProcessRequest --> CheckResponseFormat["检查响应格式"]
|
||||
CheckResponseFormat --> FormatValid{"格式有效?"}
|
||||
FormatValid --> |是| ReturnResponse["返回响应"]
|
||||
FormatValid --> |否| LogError["记录错误日志"]
|
||||
LogError --> ReturnErrorResponse["返回错误响应"]
|
||||
ReturnResponse --> End([结束])
|
||||
ReturnErrorResponse --> End
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs#L102-L357)
|
||||
- [acp_adapter.rs](file://crates/acp_adapter/src/lib.rs#L1-L13)
|
||||
|
||||
## 调用链路与性能分析
|
||||
|
||||
从请求入口到代理调用的完整调用链路如下：前端发送`ChatPrompt`请求，`agent_runner`接收请求并检查是否存在对应的代理服务，若不存在则创建新的代理服务，代理服务启动后返回`AcpConnectionInfo`，`agent_runner`将`AcpConnectionInfo`封装为`ChatPromptResponse`返回给前端。性能瓶颈主要集中在代理服务的启动时间和消息传递的延迟。通过并发控制策略，系统能够有效管理多个代理服务的并发执行，从而提高整体性能。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Frontend as 前端
|
||||
participant AgentRunner as Agent Runner
|
||||
participant AgentService as Agent Service
|
||||
participant AcpAdapter as ACP Adapter
|
||||
Frontend->>AgentRunner : 发送ChatPrompt请求
|
||||
AgentRunner->>AgentRunner : 检查PROJECT_AND_AGENT_INFO_MAP
|
||||
alt 代理服务存在
|
||||
AgentRunner->>AgentService : 复用现有代理服务
|
||||
else 代理服务不存在
|
||||
AgentRunner->>AgentService : 创建新的代理服务
|
||||
AgentService->>AcpAdapter : 启动ACP连接
|
||||
AcpAdapter->>AgentService : 返回会话ID
|
||||
end
|
||||
AgentService->>AgentRunner : 返回AcpConnectionInfo
|
||||
AgentRunner->>Frontend : 发送ChatPromptResponse
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs#L196-L340)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L311)
|
||||
|
||||
## 结论
|
||||
|
||||
代理抽象层设计通过ACP协议实现了对异构AI代理的统一管理，提供了灵活、可扩展的代理管理框架。系统通过`agent_runner`和`acp_adapter`模块，结合`docker_manager`和`shared_types`组件，确保了系统的稳定性和可维护性。未来，系统将继续优化性能，支持更多类型的AI代理，并提供更丰富的功能，以满足不断变化的需求。
|
||||
407
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/多Docker镜像设计.md
Normal file
407
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/多Docker镜像设计.md
Normal file
@@ -0,0 +1,407 @@
|
||||
# 多Docker镜像设计
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
|
||||
- [test_auto_arch_detection.sh](file://test_auto_arch_detection.sh)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“多Docker镜像设计”，系统阐述如何在RCoder项目中支持多种AI代理运行环境的容器化策略，覆盖基础镜像选择、依赖隔离、资源配额管理、镜像架构适配（x86_64与ARM64）、宿主机路径安全挂载、网络与存储卷配置、安全上下文差异、镜像版本管理与CVE扫描集成、以及启动健康检查的最佳实践。文档同时提供从用户请求到容器启动的完整生命周期图，并对专家用户提供cgroup限制、seccomp配置与容器逃逸防护机制的深入分析。
|
||||
|
||||
## 项目结构
|
||||
围绕多镜像设计，系统由以下关键模块构成：
|
||||
- 镜像选择与配置：基于多镜像配置结构与镜像选择器，按服务类型与平台自动匹配最优镜像。
|
||||
- 容器管理：统一的Docker管理器负责拉取镜像、创建容器、网络接入、资源限制与健康检查。
|
||||
- 宿主机路径解析：在容器内自动检测挂载信息，将容器内路径安全转换为宿主机绝对路径。
|
||||
- 运行时集成：容器管理服务协调容器生命周期，结合Compose网络与健康检查。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "镜像与配置"
|
||||
MIC["多镜像配置<br/>multi_image_config.rs"]
|
||||
IS["镜像选择器<br/>image_selector.rs"]
|
||||
DU["平台与工具<br/>utils.rs"]
|
||||
end
|
||||
subgraph "容器运行"
|
||||
DM["Docker管理器<br/>manager.rs"]
|
||||
CT["容器类型定义<br/>types.rs"]
|
||||
end
|
||||
subgraph "宿主机路径"
|
||||
HPR["宿主机路径解析器<br/>host_path_resolver.rs"]
|
||||
CSI["容器自检测器<br/>container_self_inspector.rs"]
|
||||
end
|
||||
subgraph "运行时集成"
|
||||
CM["容器管理服务<br/>container_manager.rs"]
|
||||
DC["Compose配置<br/>docker-compose.yml"]
|
||||
DF["镜像构建脚本<br/>Dockerfile"]
|
||||
SH["启动脚本<br/>start-rcoder.sh"]
|
||||
end
|
||||
MIC --> IS
|
||||
IS --> DU
|
||||
IS --> DM
|
||||
CT --> DM
|
||||
HPR --> CSI
|
||||
CM --> DM
|
||||
CM --> HPR
|
||||
DC --> CM
|
||||
DF --> DM
|
||||
SH --> DM
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [Dockerfile](file://docker/Dockerfile#L1-L120)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L200)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [Dockerfile](file://docker/Dockerfile#L1-L120)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
|
||||
## 核心组件
|
||||
- 多镜像配置结构：定义全局默认镜像、服务特定镜像、镜像选择策略与缓存配置，支持项目级镜像覆盖与环境变量覆盖。
|
||||
- 镜像选择器：根据服务类型与平台（自动检测或环境变量）选择镜像；支持服务特定镜像优先、架构适配与回退镜像。
|
||||
- Docker管理器：负责镜像拉取、容器创建、网络接入、资源限制、健康检查与销毁；提供安全上下文基础配置。
|
||||
- 宿主机路径解析器：在容器内自动检测挂载信息，将容器内路径转换为宿主机绝对路径，保障安全挂载。
|
||||
- 容器管理服务：协调容器生命周期，动态获取网络名称，构建服务URL，封装容器创建与查询流程。
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L200)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
|
||||
## 架构总览
|
||||
多镜像设计采用“配置驱动+运行时选择”的架构：配置层提供全局与服务特定镜像，运行时通过镜像选择器按平台与服务类型选择镜像；容器管理器负责镜像拉取、容器创建、网络与资源限制；宿主机路径解析器保障挂载安全；容器管理服务贯穿请求到容器启动的完整生命周期。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant CM as "容器管理服务"
|
||||
participant DM as "Docker管理器"
|
||||
participant IS as "镜像选择器"
|
||||
participant MIC as "多镜像配置"
|
||||
participant CSI as "容器自检测器"
|
||||
participant HPR as "宿主机路径解析器"
|
||||
Client->>CM : 请求创建容器(项目ID, 服务类型)
|
||||
CM->>IS : 选择镜像(服务类型, 项目覆盖)
|
||||
IS->>MIC : 读取配置(全局/服务特定/架构)
|
||||
IS-->>CM : 返回镜像名称
|
||||
CM->>DM : 拉取镜像/创建容器(网络, 资源, 挂载)
|
||||
DM-->>CM : 返回容器信息
|
||||
CM->>HPR : 解析宿主机路径(容器内路径)
|
||||
HPR->>CSI : 自检容器挂载(宿主机路径)
|
||||
CSI-->>HPR : 返回宿主机路径
|
||||
HPR-->>CM : 返回解析结果
|
||||
CM-->>Client : 返回服务URL/容器信息
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L275)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L32-L116)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L200)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 镜像选择与多镜像配置
|
||||
- 配置结构：支持全局默认镜像、服务特定镜像（含arm64/amd64专用镜像）、镜像选择策略（ServiceOnly）与缓存配置。
|
||||
- 选择策略：强制明确指定服务类型；优先使用服务特定镜像，其次按平台选择架构镜像，最后回退到全局默认镜像。
|
||||
- 项目级覆盖：支持在项目维度覆盖镜像与环境变量，适用于灰度发布与特殊项目定制。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckEnabled["校验服务是否启用"]
|
||||
CheckEnabled --> |否| Err["返回配置错误"]
|
||||
CheckEnabled --> |是| TryProjectOverride["尝试项目级镜像覆盖"]
|
||||
TryProjectOverride --> FoundOverride{"找到覆盖?"}
|
||||
FoundOverride --> |是| UseOverride["使用项目覆盖镜像"]
|
||||
FoundOverride --> |否| TryServiceImage["尝试服务特定镜像"]
|
||||
TryServiceImage --> FoundService{"找到服务镜像?"}
|
||||
FoundService --> |是| UseService["使用服务镜像"]
|
||||
FoundService --> |否| TryPlatform["按平台选择架构镜像"]
|
||||
TryPlatform --> FoundPlatform{"找到平台镜像?"}
|
||||
FoundPlatform --> |是| UsePlatform["使用平台镜像"]
|
||||
FoundPlatform --> |否| Fallback["回退到全局默认镜像"]
|
||||
Fallback --> Done(["结束"])
|
||||
UseOverride --> Done
|
||||
UseService --> Done
|
||||
UsePlatform --> Done
|
||||
Err --> End(["结束"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L92-L158)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L200)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
|
||||
### 平台检测与架构适配
|
||||
- 平台检测：优先使用环境变量DOCKER_DEFAULT_PLATFORM，否则自动检测当前系统架构并映射为Docker平台字符串。
|
||||
- 架构兼容性：根据镜像标签判断镜像架构，若不匹配则提示不兼容；默认情况下若标签不含架构信息则视为兼容。
|
||||
- 自动检测脚本：提供测试脚本验证自动检测与环境变量优先级。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["获取平台配置"] --> Env{"存在环境变量?"}
|
||||
Env --> |是| UseEnv["使用环境变量平台"]
|
||||
Env --> |否| AutoDetect["自动检测系统架构"]
|
||||
AutoDetect --> Map["映射为Docker平台字符串"]
|
||||
UseEnv --> Out["返回平台"]
|
||||
Map --> Out
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L39-L73)
|
||||
- [test_auto_arch_detection.sh](file://test_auto_arch_detection.sh#L1-L81)
|
||||
|
||||
章节来源
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
- [test_auto_arch_detection.sh](file://test_auto_arch_detection.sh#L1-L81)
|
||||
|
||||
### 容器创建与资源配额管理
|
||||
- 网络策略：容器统一连接到主网络，便于容器间通信；支持host网络模式与动态网络名称。
|
||||
- 存储卷配置：绑定挂载项目工作目录与日志目录；支持额外挂载点与只读挂载。
|
||||
- 资源限制：支持内存限制、CPU限制（nano_cpus）与交换空间限制；默认启用自动清理与TTL。
|
||||
- 健康检查：容器启动后进行健康检查，确保服务可用；Compose层面也提供健康检查配置。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DockerContainerConfig {
|
||||
+string project_id
|
||||
+string image
|
||||
+string name_prefix
|
||||
+string host_path
|
||||
+string container_path
|
||||
+string work_dir
|
||||
+map env_vars
|
||||
+map port_bindings
|
||||
+string network_mode
|
||||
+bool auto_remove
|
||||
+ResourceLimits resource_limits
|
||||
+vector extra_mounts
|
||||
+vector command
|
||||
+vector entrypoint
|
||||
+string network_name
|
||||
}
|
||||
class ResourceLimits {
|
||||
+i64 memory_limit
|
||||
+double cpu_limit
|
||||
+i64 swap_limit
|
||||
}
|
||||
class MountPoint {
|
||||
+string host_path
|
||||
+string container_path
|
||||
+bool read_only
|
||||
}
|
||||
DockerContainerConfig --> ResourceLimits : "包含"
|
||||
DockerContainerConfig --> MountPoint : "包含"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L80-L200)
|
||||
|
||||
章节来源
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L200)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
|
||||
### 宿主机路径安全挂载
|
||||
- 容器内自检测：通过Docker API获取当前容器的挂载信息，解析容器内路径对应的宿主机路径。
|
||||
- 路径解析器：在容器内自动检测挂载，若失败则回退到项目工作目录映射；支持诊断输出与Docker连接验证。
|
||||
- 安全性：优先通过容器自检测获取真实宿主机路径，避免路径注入与越权访问；对非项目工作目录路径进行严格验证。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant C as "容器"
|
||||
participant HPR as "宿主机路径解析器"
|
||||
participant CSI as "容器自检测器"
|
||||
participant FS as "宿主机文件系统"
|
||||
C->>HPR : resolve_to_host_path(容器内路径)
|
||||
HPR->>CSI : detect_host_path_for_container_dir(容器内路径)
|
||||
CSI->>FS : 通过Docker API inspect容器挂载
|
||||
FS-->>CSI : 返回宿主机路径
|
||||
CSI-->>HPR : 返回宿主机路径
|
||||
HPR-->>C : 返回解析结果
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L60-L140)
|
||||
|
||||
章节来源
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L200)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L200)
|
||||
|
||||
### 容器生命周期与运行时集成
|
||||
- 生命周期：容器管理服务负责检查容器是否存在、不存在则创建；创建后获取网络信息并构建服务URL。
|
||||
- 网络名称：动态获取主网络名称，确保容器连接到正确的网络。
|
||||
- 启动脚本：Compose挂载启动脚本并在容器内执行，配合健康检查保证服务可用。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CM as "容器管理服务"
|
||||
participant DM as "Docker管理器"
|
||||
participant DC as "Docker Compose"
|
||||
participant SH as "启动脚本"
|
||||
CM->>DM : 查询容器(项目ID)
|
||||
alt 已存在
|
||||
DM-->>CM : 返回容器信息
|
||||
else 不存在
|
||||
CM->>DM : 创建容器(镜像/网络/资源/挂载)
|
||||
DM-->>CM : 返回容器信息
|
||||
end
|
||||
CM->>DC : 获取动态网络名称
|
||||
DC-->>CM : 返回网络名称
|
||||
CM->>SH : 启动服务(端口/日志/脚本)
|
||||
SH-->>CM : 服务运行中
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L150-L275)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
|
||||
章节来源
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L200)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
|
||||
## 依赖关系分析
|
||||
- 配置到选择器：多镜像配置驱动镜像选择器，决定最终镜像名称。
|
||||
- 选择器到管理器：镜像选择器返回镜像名称，管理器据此拉取镜像并创建容器。
|
||||
- 管理器到类型定义：容器配置结构与资源限制类型定义支撑容器创建。
|
||||
- 路径解析器到自检测器：路径解析器依赖自检测器获取挂载信息。
|
||||
- 容器管理服务到管理器与解析器：服务协调容器生命周期并进行路径解析。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
MIC["多镜像配置"] --> IS["镜像选择器"]
|
||||
IS --> DM["Docker管理器"]
|
||||
CT["容器类型定义"] --> DM
|
||||
HPR["宿主机路径解析器"] --> CSI["容器自检测器"]
|
||||
CM["容器管理服务"] --> DM
|
||||
CM --> HPR
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L120)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L200)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [types.rs](file://crates/docker_manager/src/types.rs#L1-L120)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L120)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L120)
|
||||
- [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs#L1-L120)
|
||||
|
||||
## 性能考量
|
||||
- 镜像缓存：镜像选择器支持缓存机制，减少重复计算与配置解析开销。
|
||||
- 并发安全：使用读写锁与并发容器保证多线程下的配置与缓存一致性。
|
||||
- 资源限制：通过内存/CPU/交换限制避免资源争抢；合理设置TTL与自动清理降低资源占用。
|
||||
- 健康检查：容器启动后进行健康检查，及时发现异常并触发重试或重建。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 镜像选择失败：检查服务是否启用、配置是否正确、平台是否匹配；查看镜像选择器日志。
|
||||
- 容器创建失败：检查镜像是否存在、网络是否可用、挂载路径是否可访问；查看Docker管理器错误信息。
|
||||
- 路径解析失败：确认容器内Docker socket权限、cgroup文件可读性；使用诊断接口输出挂载信息。
|
||||
- 健康检查失败：检查容器内部服务端口、健康检查脚本与网络连通性。
|
||||
|
||||
章节来源
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L200)
|
||||
- [host_path_resolver.rs](file://crates/rcoder/src/utils/host_path_resolver.rs#L1-L200)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L1-L200)
|
||||
|
||||
## 结论
|
||||
多Docker镜像设计通过“配置驱动+运行时选择”实现了对多种AI代理运行环境的灵活支持。镜像选择器与多镜像配置共同确保镜像与平台匹配；容器管理器提供统一的网络、存储与资源管理；宿主机路径解析器保障挂载安全；容器管理服务贯穿请求到容器启动的完整生命周期。结合健康检查与缓存优化，系统在易用性与安全性之间取得平衡。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 多镜像构建流程与缓存优化
|
||||
- 构建策略：采用多阶段构建，编译产物与运行时环境分离；调试镜像包含完整调试工具链。
|
||||
- 缓存优化：镜像选择器内置缓存，避免重复解析；平台检测优先使用环境变量，减少运行时开销。
|
||||
- 架构适配：镜像标签区分arm64/amd64，平台检测自动选择对应镜像；不匹配时回退到默认镜像。
|
||||
|
||||
章节来源
|
||||
- [Dockerfile](file://docker/Dockerfile#L1-L120)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [utils.rs](file://crates/docker_manager/src/utils.rs#L1-L120)
|
||||
|
||||
### 网络策略、存储卷与安全上下文差异化
|
||||
- 网络：容器统一连接到主网络，便于服务间通信；支持host网络模式与动态网络名称。
|
||||
- 存储：绑定挂载项目工作目录与日志目录；支持额外挂载点与只读挂载。
|
||||
- 安全：移除NET_RAW与NET_ADMIN能力，禁用特权模式，提供基础隔离；完全内网隔离需在宿主机配置防火墙规则。
|
||||
|
||||
章节来源
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L140-L200)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
### 镜像版本管理与CVE扫描集成
|
||||
- 版本管理：镜像标签区分架构与版本；通过全局默认镜像与服务特定镜像实现版本控制。
|
||||
- CVE扫描：建议在CI流水线中集成镜像扫描工具，对镜像进行漏洞扫描与合规检查；结合健康检查与日志监控持续改进。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
### 专家视角：cgroup限制、seccomp与容器逃逸防护
|
||||
- cgroup限制：通过内存与CPU限制约束容器资源使用，避免资源争用；结合swap限制防止OOM。
|
||||
- seccomp：在容器运行时启用受限的系统调用集，减少攻击面；结合capabilities drop进一步降低权限。
|
||||
- 逃逸防护：仅靠容器安全配置无法完全阻止容器逃逸；建议在宿主机层面配置iptables规则与内核加固，结合运行时审计与入侵检测系统。
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
165
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/设计文档.md
Normal file
165
qiming-rcoder/.qoder/repowiki/zh/content/设计文档/设计文档.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 设计文档
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [grpc-migration-design.md](file://specs/grpc-migration-design.md)
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs)
|
||||
- [acp_agent.rs](file://crates/agent_runner/src/proxy_agent/acp_agent.rs)
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [代理抽象层设计](#代理抽象层设计)
|
||||
3. [gRPC迁移设计](#grpc迁移设计)
|
||||
4. [多Docker镜像设计](#多docker镜像设计)
|
||||
5. [常见问题与解决方案](#常见问题与解决方案)
|
||||
6. [结论](#结论)
|
||||
|
||||
## 引言
|
||||
本文档详细阐述了RCoder项目中三个核心架构设计的实现细节：代理抽象层、gRPC通信迁移和多Docker镜像支持。这些设计旨在提升系统的可扩展性、性能和灵活性。代理抽象层通过统一的接口管理不同类型的AI代理，gRPC迁移通过二进制协议替代文本流提升通信效率，多Docker镜像设计则支持在同一系统中运行不同功能的服务。本文将深入分析每个设计的实现原理、决策依据和组件关系，为开发人员提供全面的技术参考。
|
||||
|
||||
## 代理抽象层设计
|
||||
|
||||
代理抽象层是RCoder系统的核心，它提供了一个统一的接口来管理和启动不同类型的AI代理（如Claude和Codex），实现了系统的可扩展性和配置灵活性。该设计的核心是通过`AcpAgentService` trait定义一个通用的代理服务接口，允许系统在不修改核心逻辑的情况下集成新的代理类型。
|
||||
|
||||
### 核心组件与实现
|
||||
|
||||
代理抽象层的设计围绕几个关键组件展开：`AcpAgentService` trait、`AgentType`枚举以及具体的代理实现模块。`AcpAgentService` trait定义了所有代理必须实现的`start_agent_service`方法，该方法负责启动代理服务并返回连接信息。`AgentType`枚举则作为代理类型的标识符，通过为该枚举实现`AcpAgentService` trait，系统可以根据运行时的类型选择正确的代理启动逻辑。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AcpAgentService {
|
||||
<<trait>>
|
||||
+start_agent_service(chat_prompt : ChatPrompt, model_provider : Option~ModelProviderConfig~) Result~AcpConnectionInfo~
|
||||
+agent_type_name() &'static str
|
||||
}
|
||||
class AgentType {
|
||||
<<enum>>
|
||||
+Claude
|
||||
+Codex
|
||||
}
|
||||
class ClaudeCodeAgent {
|
||||
-start_claude_code_acp_agent_service()
|
||||
}
|
||||
class CodexAgent {
|
||||
-start_codex_acp_agent_service()
|
||||
}
|
||||
AcpAgentService <|.. AgentType : 实现
|
||||
AgentType --> ClaudeCodeAgent : 调用
|
||||
AgentType --> CodexAgent : 调用
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [agent_service.rs](file://crates/agent_runner/src/proxy_agent/agent_service.rs#L7-L62)
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L25-L398)
|
||||
|
||||
#### 启动流程与生命周期管理
|
||||
|
||||
代理的启动流程遵循一个标准化的模式。以`claude_code_agent`为例，其`start_claude_code_acp_agent_service`函数首先构建子进程的启动参数和环境变量，然后使用`tokio::process::Command`启动`claude-code-acp`子进程。成功启动后，它会通过`ClientSideConnection`建立与代理的ACP（Agent Client Protocol）连接，并初始化会话。整个过程通过`CancellationToken`和`AgentLifecycleGuard`进行生命周期管理，确保在任务取消时能正确清理子进程和相关资源。
|
||||
|
||||
**Section sources**
|
||||
- [claude_code_agent.rs](file://crates/agent_runner/src/proxy_agent/claude_code_agent.rs#L28-L311)
|
||||
- [codex_agent.rs](file://crates/agent_runner/src/proxy_agent/codex_agent.rs#L25-L398)
|
||||
|
||||
#### 配置与环境变量映射
|
||||
|
||||
为了实现配置的灵活性，系统设计了环境变量映射机制。代理的配置（如API密钥、模型名称）通过`ModelProviderConfig`结构体传递。在启动代理时，系统会将这些配置值映射到代理期望的环境变量名上。例如，`ModelProviderConfig`中的`api_key`字段会被映射到`ANTHROPIC_API_KEY`或`CODEX_API_KEY`等环境变量中。这种设计允许代理使用自己特定的环境变量名，同时从统一的配置源获取值，实现了配置的标准化和灵活性。
|
||||
|
||||
## gRPC迁移设计
|
||||
|
||||
gRPC迁移设计旨在将`rcoder`与`agent-runner`之间的通信协议从HTTP/SSE（Server-Sent Events）升级为gRPC，以提升通信性能、增强类型安全并简化流式数据处理。
|
||||
|
||||
### 架构变更与协议定义
|
||||
|
||||
迁移前，系统使用HTTP POST命令通道和SSE数据通道进行通信。迁移后，所有通信都通过单一的gRPC通道完成。核心的通信契约在`crates/shared_types/proto/agent.proto`文件中定义。`AgentService`服务定义了四个核心RPC方法：`Chat`（一元调用，用于发送聊天请求）、`SubscribeProgress`（服务器流式调用，用于订阅进度事件）、`CancelSession`（一元调用，用于取消会话）和`GetStatus`（一元调用，用于获取状态）。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Rcoder as rcoder (客户端)
|
||||
participant AgentRunner as agent-runner (服务端)
|
||||
Rcoder->>AgentRunner : gRPC Channel (50051)
|
||||
Rcoder->>AgentRunner : Chat(ChatRequest)
|
||||
AgentRunner->>Rcoder : ChatResponse
|
||||
Rcoder->>AgentRunner : SubscribeProgress(ProgressRequest)
|
||||
loop 流式事件
|
||||
AgentRunner->>Rcoder : ProgressEvent(log/thought/chunk)
|
||||
end
|
||||
Rcoder->>AgentRunner : CancelSession(CancelRequest)
|
||||
AgentRunner->>Rcoder : CancelResponse
|
||||
Note over Rcoder,AgentRunner : 所有业务通信通过gRPC完成
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [agent.proto](file://crates/shared_types/proto/agent.proto#L1-L98)
|
||||
- [agent.rs](file://crates/shared_types/src/grpc/agent.rs#L1-L651)
|
||||
|
||||
#### 模块改造与实现
|
||||
|
||||
`shared_types` crate负责`.proto`文件的编译和代码生成，使用`tonic`和`prost`库生成Rust代码。`agent_runner`作为gRPC服务端，在其`main.rs`中启动Tonic gRPC服务器，同时保留Axum HTTP服务器用于健康检查。`rcoder`作为gRPC客户端，通过维护gRPC Channel连接池来与`agent-runner`通信。在`agent_session_notification.rs`中，原有的SSE转发逻辑被改造为调用`SubscribeProgress` gRPC方法，并将接收到的`ProgressEvent`消息转换为Axum SSE事件流，从而实现了与前端的无缝兼容。
|
||||
|
||||
**Section sources**
|
||||
- [grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L163)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L232)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
|
||||
## 多Docker镜像设计
|
||||
|
||||
多Docker镜像设计支持在动态创建容器时指定不同的服务类型（如`rcoder`或`agent-runner`），以满足当前功能和未来新功能的开发需求。
|
||||
|
||||
### 配置结构与选择策略
|
||||
|
||||
该设计的核心是`MultiImageConfig`结构，它定义了多层级的镜像配置体系。配置层级从上到下依次为：全局默认镜像配置、服务类型特定配置（如`rcoder`和`agent-runner`）、以及可选的项目级镜像覆盖。`ServiceType`枚举定义了支持的服务类型，`ImageSelector`组件则根据服务类型和项目配置，按照预定义的策略（如`ServiceOnly`）选择最终的Docker镜像。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[全局默认配置] --> B[服务类型配置]
|
||||
B --> C[rcoder服务]
|
||||
B --> D[agent-runner服务]
|
||||
C --> E[项目级覆盖]
|
||||
D --> F[项目级覆盖]
|
||||
G[API请求] --> H[ImageSelector]
|
||||
H --> I[选择最终镜像]
|
||||
I --> J[创建容器]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L710)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
|
||||
#### 镜像选择器与容器创建
|
||||
|
||||
`ImageSelector`是镜像选择逻辑的核心。它首先验证请求的服务类型是否已启用，然后根据平台（ARM64/AMD64）和配置优先级（服务通用镜像 > 平台专用镜像 > 默认镜像）来确定最终的镜像名称。`DockerManager`的`create_container_with_service_type`方法利用`ImageSelector`选择镜像，并将服务特定的环境变量和挂载点应用到容器配置中，最后调用`create_container`完成容器的创建。
|
||||
|
||||
**Section sources**
|
||||
- [image_selector.rs](file://crates/docker_manager/src/image_selector.rs#L1-L160)
|
||||
- [manager.rs](file://crates/docker_manager/src/manager.rs#L1-L800)
|
||||
|
||||
## 常见问题与解决方案
|
||||
|
||||
### 代理启动失败
|
||||
**问题**：代理子进程启动失败，日志中出现“无法启动 claude-code-acp 子进程”。
|
||||
**解决方案**：检查`PATH`环境变量是否包含`claude-code-acp`命令，或确认该命令已正确安装。确保`agent_servers`配置中的`command`字段指向正确的可执行文件路径。
|
||||
|
||||
### gRPC连接超时
|
||||
**问题**：`rcoder`客户端调用gRPC服务时出现连接超时。
|
||||
**解决方案**：确认`agent-runner`容器内部的gRPC端口（如50051）已在`docker-compose.yml`中正确暴露，并且`rcoder`能够通过容器网络访问该端口。检查防火墙设置。
|
||||
|
||||
### 镜像选择错误
|
||||
**问题**：创建容器时使用了错误的Docker镜像。
|
||||
**解决方案**：检查`docker_config`中的`services`配置，确保`enabled`字段为`true`，并且`image`、`arm64_image`或`amd64_image`字段的值正确。确认API请求中指定的`service_type`与配置中的键名匹配。
|
||||
|
||||
## 结论
|
||||
本文档详细分析了RCoder项目中代理抽象层、gRPC迁移和多Docker镜像三大核心设计。代理抽象层通过trait和枚举实现了代理的可扩展管理；gRPC迁移通过二进制协议和强类型契约显著提升了通信效率和可靠性；多Docker镜像设计则通过灵活的配置体系支持了服务的多样化部署。这些设计共同构建了一个高性能、高可扩展且易于维护的AI开发平台架构。未来的工作可以在此基础上进一步优化性能监控和资源调度。
|
||||
221
qiming-rcoder/.qoder/repowiki/zh/content/贡献指南.md
Normal file
221
qiming-rcoder/.qoder/repowiki/zh/content/贡献指南.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 贡献指南
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [Makefile](file://Makefile)
|
||||
- [config.yml](file://config.yml)
|
||||
- [install.md](file://install.md)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||||
- [crates/rcoder/tests/container_path_test.rs](file://crates/rcoder/tests/container_path_test.rs)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [.dockerignore](file://.dockerignore)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [贡献流程](#贡献流程)
|
||||
2. [代码规范](#代码规范)
|
||||
3. [测试要求](#测试要求)
|
||||
4. [文档更新](#文档更新)
|
||||
5. [配置选项](#配置选项)
|
||||
6. [组件关系](#组件关系)
|
||||
7. [常见问题与解决方案](#常见问题与解决方案)
|
||||
|
||||
## 贡献流程
|
||||
|
||||
本项目遵循标准的开源贡献流程，旨在确保代码质量和项目稳定性。贡献者应遵循以下步骤进行贡献：
|
||||
|
||||
1. **Fork 仓库**：首先在 GitHub 上 Fork 本项目仓库到自己的账户。
|
||||
2. **创建特性分支**：基于主分支创建新的特性分支，命名规范为 `feature/功能描述`，例如 `feature/add-new-api-endpoint`。
|
||||
3. **开发与提交**：在特性分支上进行开发，完成开发后提交更改，提交信息应清晰描述更改内容。
|
||||
4. **推送分支**：将本地更改推送到自己 Fork 的仓库中。
|
||||
5. **创建 Pull Request**：在 GitHub 上创建 Pull Request，目标为原仓库的主分支。PR 描述应详细说明更改的目的、实现方式和测试情况。
|
||||
|
||||
项目采用工作区（workspace）结构，包含多个独立的 crate，如 `rcoder`、`agent_runner`、`pingora-proxy` 等。每个 crate 都有其独立的 `Cargo.toml` 文件，但共享根目录的 `Cargo.toml` 中定义的依赖和配置。这种模块化设计使得各组件可以独立开发和测试，同时保持整体项目的一致性。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L599-L610)
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 代码规范
|
||||
|
||||
本项目遵循 Rust 社区的最佳实践和编码规范，确保代码的可读性、一致性和安全性。
|
||||
|
||||
### 通用规范
|
||||
- **命名约定**：使用 `snake_case` 命名变量和函数，`PascalCase` 命名类型和模块。
|
||||
- **代码格式化**：所有代码必须使用 `cargo fmt` 进行格式化，确保代码风格统一。
|
||||
- **错误处理**：优先使用 `anyhow` 和 `thiserror` 库进行错误处理，提供清晰的错误信息。
|
||||
- **异步编程**：使用 `tokio` 作为异步运行时，遵循异步编程的最佳实践，避免阻塞操作。
|
||||
|
||||
### 安全禁令
|
||||
为确保系统安全，以下操作是严格禁止的：
|
||||
- **绝对禁止**探测、扫描或访问内网IP地址（如 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8）。
|
||||
- **绝对禁止**尝试访问本地服务（localhost、127.0.0.1、0.0.0.0）。
|
||||
- **绝对禁止**端口扫描、网络探测、内网服务发现等行为。
|
||||
- **绝对禁止**在代码中硬编码内网IP地址或私有网络地址。
|
||||
|
||||
### 前端开发规范
|
||||
当涉及前端开发时，需遵循以下特定规范：
|
||||
- **路由模式**：必须使用 hash 模式。例如，React Router 使用 `HashRouter`，Vue Router 配置 `mode: 'hash'`。
|
||||
- **代码注入保护**：绝对禁止删除或修改被 `DEV-INJECT-START` 和 `DEV-INJECT-END` 标记包围的代码块。这些代码块由开发工具自动注入，必须完整保留。
|
||||
|
||||
**Section sources**
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L90-L96)
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L72-L73)
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L80-L81)
|
||||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L87)
|
||||
|
||||
## 测试要求
|
||||
|
||||
为确保代码质量和功能正确性，所有贡献必须包含相应的测试。
|
||||
|
||||
### 单元测试
|
||||
- **覆盖率**：所有新功能和关键路径必须有单元测试覆盖。
|
||||
- **测试结构**：测试代码应放在 `tests` 目录下，与源代码对应。
|
||||
- **断言库**：使用 `assert_eq!`、`assert_ne!` 等宏进行断言，确保测试的准确性。
|
||||
|
||||
### 集成测试
|
||||
- **环境准备**：集成测试需要启动完整的应用环境，包括数据库、网络服务等。
|
||||
- **测试用例**：覆盖主要的业务流程和边界情况，确保系统在各种场景下的稳定性。
|
||||
- **运行命令**：使用 `cargo test --test integration` 运行集成测试。
|
||||
|
||||
### 测试示例
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
#[test]
|
||||
fn test_default_container_path_template() {
|
||||
let config = default_rcoder_service_config();
|
||||
assert_eq!(
|
||||
config.container_path_template,
|
||||
"/app/project_workspace/{project_id}"
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [crates/rcoder/tests/container_path_test.rs](file://crates/rcoder/tests/container_path_test.rs#L1-L94)
|
||||
- [README.md](file://README.md#L452-L463)
|
||||
|
||||
## 文档更新
|
||||
|
||||
贡献者在添加新功能或修改现有功能时，必须同步更新相关文档。
|
||||
|
||||
### 文档位置
|
||||
- **README.md**：项目概述、快速开始、配置说明等。
|
||||
- **specs/**：设计文档，如 `agent-abstraction-layer-design.md`。
|
||||
- **docs/**：详细的用户和开发者文档。
|
||||
|
||||
### 文档内容
|
||||
- **功能描述**：清晰描述新功能的目的和使用场景。
|
||||
- **API 文档**：更新 API 端点、请求参数、响应格式等。
|
||||
- **配置说明**：更新配置文件的字段说明和示例。
|
||||
|
||||
### 文档示例
|
||||
```yaml
|
||||
# RCoder 配置文件
|
||||
default_agent: "Claude"
|
||||
projects_dir: "./project_workspace"
|
||||
port: 8087
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L384-L438)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L308-L367)
|
||||
|
||||
## 配置选项
|
||||
|
||||
本项目支持多种配置方式，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。
|
||||
|
||||
### 配置文件
|
||||
配置文件 `config.yml` 支持以下主要选项：
|
||||
- **default_agent**：默认使用的 AI 代理类型，可选值为 "Claude" 或 "Codex"。
|
||||
- **projects_dir**：项目工作目录。
|
||||
- **port**：主服务端口。
|
||||
- **proxy_config**：Pingora 反向代理配置，包括监听端口、默认后端端口等。
|
||||
|
||||
### 命令行参数
|
||||
| 参数 | 短参数 | 说明 | 示例 |
|
||||
|------|--------|------|------|
|
||||
| `--port` | `-p` | 设置主服务端口 | `--port 8087` |
|
||||
| `--projects-dir` | `-d` | 设置项目工作目录 | `--projects-dir ./projects` |
|
||||
| `--enable-proxy` | 无 | 启用 Pingora 反向代理 | `--enable-proxy` |
|
||||
| `--proxy-port` | 无 | 设置 Pingora 监听端口 | `--proxy-port 8080` |
|
||||
| `--default-backend-port` | 无 | 未指定端口时的默认后端端口 | `--default-backend-port 3000` |
|
||||
|
||||
### 环境变量
|
||||
- `RCODER_PORT`：服务器端口。
|
||||
- `DATABASE_URL`：数据库连接字符串。
|
||||
- `CLAUDE_CODE_PATH`：Claude Code CLI 路径。
|
||||
- `RUST_LOG`：日志级别。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L88-L104)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [Cargo.toml](file://Cargo.toml#L414-L418)
|
||||
|
||||
## 组件关系
|
||||
|
||||
本项目由多个核心组件构成，各组件之间通过清晰的接口进行交互。
|
||||
|
||||
### 核心组件
|
||||
- **rcoder**：主应用，负责业务 API、会话管理和 SSE 进度流。
|
||||
- **agent_runner**：代理运行器，负责管理 AI 代理的生命周期。
|
||||
- **pingora-proxy**：高性能反向代理，负责端口路由。
|
||||
- **docker_manager**：Docker 容器管理器，负责容器的创建、启动和销毁。
|
||||
|
||||
### 组件交互
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Client] --> B[Axum HTTP Server]
|
||||
A --> C[Pingora Proxy]
|
||||
B --> D[API Routes]
|
||||
B --> E[Agent Worker (LocalSet)]
|
||||
C --> F[Backends: 127.0.0.1:{port}]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [README.md](file://README.md#L18-L25)
|
||||
|
||||
### 依赖关系
|
||||
- **rcoder** 依赖于 `agent_runner` 和 `pingora-proxy`。
|
||||
- **agent_runner** 依赖于 `docker_manager` 进行容器管理。
|
||||
- **pingora-proxy** 独立运行，通过路径前缀 `/proxy/{port}/{path}` 转发请求。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L16-L30)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L16-L77)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml#L16-L79)
|
||||
|
||||
## 常见问题与解决方案
|
||||
|
||||
### 端口被占用
|
||||
**问题**：启动服务时提示端口被占用。
|
||||
**解决方案**：使用 `--port` 参数指定其他端口，例如 `cargo run --bin rcoder -- --port 8087`。
|
||||
|
||||
### AI 代理连接失败
|
||||
**问题**：AI 代理无法连接。
|
||||
**解决方案**：检查 API 密钥和网络连接，确保环境变量 `ANTHROPIC_API_KEY` 已正确设置。
|
||||
|
||||
### 配置文件错误
|
||||
**问题**：配置文件格式错误或字段名称不正确。
|
||||
**解决方案**：检查 YAML 格式，确保字段名称和值正确。参考 `config.yml` 示例文件。
|
||||
|
||||
### Docker 容器启动失败
|
||||
**问题**：Docker 容器无法启动。
|
||||
**解决方案**：检查 Docker socket 路径是否正确，确保容器有权限访问 Docker API。查看日志获取详细错误信息。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L620-L626)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L351)
|
||||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L51-L61)
|
||||
@@ -0,0 +1,328 @@
|
||||
# Docker Compose部署
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [config.yml](file://config.yml)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档全面阐述了RCoder项目的Docker Compose部署方案。通过分析`docker-compose.yml`文件、构建脚本和部署流程，详细说明了一键部署的实现机制。文档涵盖了服务编排、环境配置、多环境差异、部署对比以及常见问题的排查方法，旨在为新手和经验丰富的运维人员提供完整的部署指导。
|
||||
|
||||
## 项目结构
|
||||
RCoder项目采用模块化设计，主要包含crates核心组件、docker部署脚本和配置文件。部署相关文件集中在docker目录下，包括Dockerfile、docker-compose.yml和一系列shell脚本。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "部署脚本"
|
||||
build[build.sh]
|
||||
deploy[deploy.sh]
|
||||
start[start-rcoder.sh]
|
||||
end
|
||||
subgraph "配置文件"
|
||||
compose[docker-compose.yml]
|
||||
dockerfile[Dockerfile]
|
||||
config[config.yml]
|
||||
end
|
||||
subgraph "核心代码"
|
||||
crates[crates/]
|
||||
end
|
||||
build --> dockerfile
|
||||
deploy --> compose
|
||||
deploy --> build
|
||||
start --> compose
|
||||
config --> compose
|
||||
compose --> dockerfile
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
**节源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
## 核心组件
|
||||
本节分析Docker Compose部署的核心组件，包括服务定义、构建流程和启动机制。通过环境变量注入、卷挂载和网络配置，实现了灵活的部署方案。
|
||||
|
||||
**节源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
|
||||
## 架构概述
|
||||
RCoder的Docker Compose部署采用单服务架构，主服务rcoder包含所有必要组件。部署架构通过分层设计实现了构建、部署和运行的分离。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[用户] --> B[deploy.sh]
|
||||
B --> C{镜像存在?}
|
||||
C --> |否| D[build.sh]
|
||||
C --> |是| E[docker-compose up]
|
||||
D --> F[Docker构建]
|
||||
F --> G[rcoder镜像]
|
||||
G --> E
|
||||
E --> H[rcoder容器]
|
||||
H --> I[项目工作目录]
|
||||
H --> J[Docker Socket]
|
||||
H --> K[日志目录]
|
||||
style H fill:#f9f,stroke:#333
|
||||
style I fill:#bbf,stroke:#333
|
||||
style J fill:#f96,stroke:#333
|
||||
style K fill:#6f9,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
## 详细组件分析
|
||||
### Docker Compose配置分析
|
||||
`docker-compose.yml`文件定义了rcoder服务的完整配置，包括镜像、端口、环境变量、卷挂载和健康检查。
|
||||
|
||||
#### 服务定义
|
||||
```mermaid
|
||||
classDiagram
|
||||
class RcoderService {
|
||||
+image : string
|
||||
+ports : array
|
||||
+environment : array
|
||||
+volumes : array
|
||||
+command : array
|
||||
+healthcheck : object
|
||||
+restart : string
|
||||
+networks : array
|
||||
}
|
||||
RcoderService : "使用" --> DockerSocket
|
||||
RcoderService : "挂载" --> ProjectWorkspace
|
||||
RcoderService : "挂载" --> Logs
|
||||
RcoderService : "挂载" --> Specs
|
||||
RcoderService : "连接" --> AgentNetwork
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
#### 环境变量配置
|
||||
服务通过环境变量实现灵活配置，支持默认值和变量替换机制。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([启动]) --> TZ["设置时区: Asia/Shanghai"]
|
||||
TZ --> RUST_LOG["设置日志级别: debug"]
|
||||
RUST_LOG --> RCODER_PORT["设置服务端口: ${RCODER_PORT:-8087}"]
|
||||
RCODER_PORT --> DOCKER_SOCKET["设置Docker Socket路径"]
|
||||
DOCKER_SOCKET --> End([配置完成])
|
||||
style Start fill:#f9f,stroke:#333
|
||||
style End fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
### 构建与部署流程
|
||||
#### 构建脚本分析
|
||||
`build.sh`脚本实现了镜像的自动化构建流程，包含错误检查和构建成功提示。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant BuildScript
|
||||
participant Docker
|
||||
User->>BuildScript : 执行 ./build.sh
|
||||
BuildScript->>BuildScript : 检查 docker-compose.yml
|
||||
alt 文件存在
|
||||
BuildScript->>Docker : docker build 命令
|
||||
Docker-->>BuildScript : 构建结果
|
||||
alt 构建成功
|
||||
BuildScript-->>User : 显示成功信息
|
||||
else 构建失败
|
||||
BuildScript-->>User : 显示失败信息并退出
|
||||
end
|
||||
else 文件不存在
|
||||
BuildScript-->>User : 显示错误并退出
|
||||
end
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
|
||||
#### 部署脚本分析
|
||||
`deploy.sh`脚本实现了完整的部署流程，包括依赖检查、镜像构建和容器启动。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant DeployScript
|
||||
participant BuildScript
|
||||
participant DockerCompose
|
||||
User->>DeployScript : 执行 ./deploy.sh
|
||||
DeployScript->>DeployScript : 检查必要文件
|
||||
alt 文件完整
|
||||
DeployScript->>DeployScript : 检查镜像存在
|
||||
alt 镜像不存在
|
||||
DeployScript->>BuildScript : 调用 ./build.sh
|
||||
BuildScript-->>DeployScript : 构建结果
|
||||
alt 构建失败
|
||||
DeployScript-->>User : 显示失败信息
|
||||
end
|
||||
end
|
||||
DeployScript->>DockerCompose : docker-compose up -d
|
||||
DockerCompose-->>DeployScript : 启动结果
|
||||
alt 启动成功
|
||||
DeployScript-->>User : 显示成功信息和管理命令
|
||||
else 启动失败
|
||||
DeployScript-->>User : 显示失败信息
|
||||
end
|
||||
else 文件缺失
|
||||
DeployScript-->>User : 显示错误并退出
|
||||
end
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
|
||||
### 启动脚本分析
|
||||
`start-rcoder.sh`脚本负责容器内的服务启动和环境初始化。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[启动脚本] --> B[设置环境变量]
|
||||
B --> C[创建必要目录]
|
||||
C --> D[显示环境配置]
|
||||
D --> E[启动rcoder服务]
|
||||
E --> F[执行rcoder二进制]
|
||||
style A fill:#f9f,stroke:#333
|
||||
style F fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
|
||||
## 依赖分析
|
||||
### 服务依赖关系
|
||||
RCoder服务依赖于宿主机的Docker守护进程，通过挂载Docker Socket实现容器管理功能。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
RcoderService --> DockerDaemon
|
||||
DockerDaemon --> HostSystem
|
||||
RcoderService --> ProjectWorkspace
|
||||
RcoderService --> LogStorage
|
||||
RcoderService --> SpecFiles
|
||||
style RcoderService fill:#f9f,stroke:#333
|
||||
style DockerDaemon fill:#f96,stroke:#333
|
||||
style HostSystem fill:#bbf,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
|
||||
### 配置文件依赖
|
||||
系统通过多层配置机制实现灵活的环境适配，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认值。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[命令行参数] --> B[环境变量]
|
||||
B --> C[config.yml]
|
||||
C --> D[默认配置]
|
||||
D --> E[应用]
|
||||
style A fill:#f96,stroke:#333
|
||||
style B fill:#f96,stroke:#333
|
||||
style C fill:#f96,stroke:#333
|
||||
style D fill:#f96,stroke:#333
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [config.yml](file://config.yml)
|
||||
- [README.md](file://README.md)
|
||||
|
||||
## 性能考虑
|
||||
Docker Compose部署方案在性能方面具有以下特点：
|
||||
- **启动时间**：由于需要拉取镜像和启动容器，首次启动时间较长
|
||||
- **资源占用**：容器化部署增加了少量资源开销，但提供了更好的隔离性
|
||||
- **网络性能**：通过端口映射和内部网络通信，网络延迟极低
|
||||
- **存储性能**：使用卷挂载，文件I/O性能接近原生
|
||||
|
||||
对于生产环境，建议：
|
||||
1. 预先构建镜像以减少部署时间
|
||||
2. 配置适当的资源限制防止资源耗尽
|
||||
3. 使用持久化存储确保数据安全
|
||||
4. 启用健康检查确保服务可用性
|
||||
|
||||
## 故障排除指南
|
||||
### 常见问题及解决方案
|
||||
#### 服务启动失败
|
||||
**可能原因**：
|
||||
- 必要文件缺失
|
||||
- 镜像构建失败
|
||||
- 端口被占用
|
||||
- Docker Socket权限不足
|
||||
|
||||
**解决方案**：
|
||||
1. 检查`docker-compose.yml`和`Dockerfile`是否存在
|
||||
2. 确认Docker服务正在运行
|
||||
3. 检查8087端口是否被其他进程占用
|
||||
4. 确保用户有访问`/var/run/docker.sock`的权限
|
||||
|
||||
#### 网络连接超时
|
||||
**可能原因**：
|
||||
- 容器网络配置错误
|
||||
- 防火墙阻止连接
|
||||
- 服务未正确启动
|
||||
|
||||
**解决方案**：
|
||||
1. 检查`docker-compose.yml`中的网络配置
|
||||
2. 验证容器是否在`agent-network`网络中
|
||||
3. 使用`docker logs`查看服务日志
|
||||
4. 检查防火墙设置
|
||||
|
||||
#### 配置加载异常
|
||||
**可能原因**：
|
||||
- 环境变量未正确设置
|
||||
- 配置文件格式错误
|
||||
- 卷挂载路径不正确
|
||||
|
||||
**解决方案**：
|
||||
1. 检查`deploy.sh`中的环境变量设置
|
||||
2. 验证`config.yml`的YAML格式
|
||||
3. 确认卷挂载路径在宿主机上存在
|
||||
4. 使用`docker exec`进入容器验证配置文件位置
|
||||
|
||||
**节源**
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
|
||||
## 结论
|
||||
RCoder的Docker Compose部署方案提供了一套完整、可靠的部署机制。通过`build.sh`和`deploy.sh`脚本实现了一键部署，降低了部署复杂度。`docker-compose.yml`文件清晰地定义了服务配置，包括端口映射、卷挂载和环境变量注入。
|
||||
|
||||
与独立Docker部署相比，Docker Compose方案具有以下优势：
|
||||
- **简化管理**：通过单一配置文件管理多个服务
|
||||
- **环境一致性**：确保开发、测试和生产环境的一致性
|
||||
- **依赖管理**：自动处理服务间的依赖关系
|
||||
- **可移植性**：配置文件可在不同环境中复用
|
||||
|
||||
对于高级用户，可以进一步集成监控系统、实现自动化CI/CD流水线，并配置高可用集群以满足生产环境需求。
|
||||
320
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/Docker部署.md
Normal file
320
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/Docker部署.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# Docker部署
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [.dockerignore](file://.dockerignore)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh)
|
||||
- [config.yml](file://config.yml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概述](#架构概述)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
本文档详细介绍了Rcoder项目的Docker部署方案。文档深入解析了多阶段构建过程、基础镜像选择、依赖安装和二进制文件复制策略。通过实际代码库中的具体示例，展示了构建脚本`build-docker-image.sh`的使用方法和参数配置。文档还记录了环境变量、挂载卷和网络配置的最佳实践，解释了Docker部署与rcoder主服务的集成关系，并提供了常见构建失败、权限问题和容器启动错误的解决方案。为初学者提供逐步指导的同时，也为高级用户提供性能优化和安全加固建议。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Docker["Docker 部署"]
|
||||
Docker --> Scripts["docker/scripts/"]
|
||||
Docker --> Config["docker/"]
|
||||
Docker --> Root["项目根目录"]
|
||||
Scripts --> build_image["build-docker-image.sh"]
|
||||
Scripts --> deploy["deploy.sh"]
|
||||
Scripts --> start["start-rcoder.sh"]
|
||||
Scripts --> analyze["analyze-rcoder.sh"]
|
||||
Scripts --> diagnose["diagnose-blocking.sh"]
|
||||
Scripts --> flamegraph["generate-flamegraph.sh"]
|
||||
Config --> Dockerfile["Dockerfile"]
|
||||
Config --> compose["docker-compose.yml"]
|
||||
Config --> start_script["start-rcoder.sh"]
|
||||
Root --> dockerignore[".dockerignore"]
|
||||
Root --> service_script["rcoder-service.sh"]
|
||||
Root --> config["config.yml"]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/](file://docker/scripts/)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/](file://docker/scripts/)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
## 核心组件
|
||||
|
||||
本文档的核心组件包括Docker多阶段构建系统、调试工具集、部署脚本和配置管理。Dockerfile采用多阶段构建策略，分离编译和运行环境，确保生产镜像的轻量化和安全性。构建脚本`build-docker-image.sh`自动化了镜像构建流程，而`deploy.sh`脚本则提供了完整的部署解决方案。调试工具集包括`analyze-rcoder.sh`、`diagnose-blocking.sh`和`generate-flamegraph.sh`，为生产环境的问题诊断提供了强大支持。
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
## 架构概述
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Build["构建阶段"]
|
||||
Runtime["运行时阶段"]
|
||||
Deployment["部署阶段"]
|
||||
Debug["调试工具"]
|
||||
Build --> |"FROM rust:1.90-bookworm AS builder"| Builder["编译器镜像"]
|
||||
Builder --> |"cargo build --release"| Binary["rcoder 二进制"]
|
||||
Runtime --> |"FROM rust:1.90-bookworm"| RuntimeImage["运行时镜像"]
|
||||
RuntimeImage --> |"COPY --from=builder"| CopyBinary["复制二进制"]
|
||||
RuntimeImage --> |"安装调试工具"| DebugTools["调试工具集"]
|
||||
RuntimeImage --> |"创建用户和目录"| Setup["环境设置"]
|
||||
Deployment --> |"docker-compose up"| Container["容器实例"]
|
||||
Container --> |"挂载卷"| Volumes["卷挂载"]
|
||||
Container --> |"环境变量"| Env["环境配置"]
|
||||
Container --> |"网络配置"| Network["网络设置"]
|
||||
Debug --> |"analyze-rcoder"| Process["进程分析"]
|
||||
Debug --> |"diagnose-blocking"| Blocking["阻塞诊断"]
|
||||
Debug --> |"generate-flamegraph"| Performance["性能分析"]
|
||||
Build --> Runtime
|
||||
Runtime --> Deployment
|
||||
Deployment --> Debug
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [docker/scripts/](file://docker/scripts/)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### Docker多阶段构建分析
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
Stage1["构建阶段"]
|
||||
Stage2["运行时阶段"]
|
||||
subgraph Stage1
|
||||
A["基础镜像: rust:1.90-bookworm"]
|
||||
B["安装编译依赖"]
|
||||
C["复制源码"]
|
||||
D["编译release版本"]
|
||||
E["安装Rust调试工具"]
|
||||
A --> B --> C --> D --> E
|
||||
end
|
||||
subgraph Stage2
|
||||
F["基础镜像: rust:1.90-bookworm"]
|
||||
G["设置环境变量"]
|
||||
H["安装运行时和调试依赖"]
|
||||
I["创建应用用户和目录"]
|
||||
J["从构建阶段复制二进制"]
|
||||
K["复制启动脚本"]
|
||||
L["创建调试工具脚本"]
|
||||
M["设置工作目录和权限"]
|
||||
N["暴露端口"]
|
||||
O["健康检查"]
|
||||
P["启动命令"]
|
||||
F --> G --> H --> I --> J --> K --> L --> M --> N --> O --> P
|
||||
end
|
||||
E --> |"COPY --from=builder"| J
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L12-L304)
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L12-L304)
|
||||
|
||||
### 构建脚本分析
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start["开始构建"]
|
||||
Start --> Check["检查Dockerfile存在"]
|
||||
Check --> |"存在"| BuildBinary["构建rcoder二进制"]
|
||||
Check --> |"不存在"| Error1["报错退出"]
|
||||
BuildBinary --> |"成功"| BuildImage["构建Docker镜像"]
|
||||
BuildBinary --> |"失败"| Error2["报错退出"]
|
||||
BuildImage --> |"成功"| Success["构建成功"]
|
||||
BuildImage --> |"失败"| Error3["报错退出"]
|
||||
Success --> Info["显示使用方式"]
|
||||
Info --> End["结束"]
|
||||
Error1 --> End
|
||||
Error2 --> End
|
||||
Error3 --> End
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh#L1-L38)
|
||||
|
||||
**本节来源**
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh#L1-L38)
|
||||
|
||||
### 部署脚本分析
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start["开始部署"]
|
||||
Start --> CheckFiles["检查必要文件"]
|
||||
CheckFiles --> |"存在"| CheckImage["检查镜像是否存在"]
|
||||
CheckFiles --> |"不存在"| Error1["报错退出"]
|
||||
CheckImage --> |"存在"| StartService["启动服务"]
|
||||
CheckImage --> |"不存在"| BuildImage["构建镜像"]
|
||||
BuildImage --> |"成功"| StartService
|
||||
BuildImage --> |"失败"| Error2["报错退出"]
|
||||
StartService --> |"成功"| Success["部署成功"]
|
||||
StartService --> |"失败"| Error3["报错退出"]
|
||||
Success --> Commands["显示管理命令"]
|
||||
Commands --> End["结束"]
|
||||
Error1 --> End
|
||||
Error2 --> End
|
||||
Error3 --> End
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
|
||||
|
||||
**本节来源**
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
|
||||
|
||||
### 调试工具分析
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
DebugTools["调试工具集"]
|
||||
DebugTools --> Analyze["analyze-rcoder.sh"]
|
||||
DebugTools --> Diagnose["diagnose-blocking.sh"]
|
||||
DebugTools --> Flamegraph["generate-flamegraph.sh"]
|
||||
Analyze --> |"功能"| A1["进程基本信息"]
|
||||
Analyze --> |"功能"| A2["线程状态"]
|
||||
Analyze --> |"功能"| A3["网络连接"]
|
||||
Analyze --> |"功能"| A4["文件描述符"]
|
||||
Analyze --> |"功能"| A5["内存使用"]
|
||||
Diagnose --> |"功能"| D1["进程状态"]
|
||||
Diagnose --> |"功能"| D2["网络队列"]
|
||||
Diagnose --> |"功能"| D3["阻塞线程"]
|
||||
Diagnose --> |"功能"| D4["系统资源"]
|
||||
Diagnose --> |"功能"| D5["错误日志"]
|
||||
Diagnose --> |"功能"| D6["死锁检查"]
|
||||
Flamegraph --> |"功能"| F1["性能采样"]
|
||||
Flamegraph --> |"功能"| F2["火焰图生成"]
|
||||
Flamegraph --> |"功能"| F3["结果分析"]
|
||||
Flamegraph --> |"功能"| F4["问题定位"]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/scripts/analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
|
||||
- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
|
||||
- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
|
||||
**本节来源**
|
||||
- [docker/scripts/analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
|
||||
- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
|
||||
- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
|
||||
## 依赖分析
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Dockerfile --> rust["rust:1.90-bookworm"]
|
||||
Dockerfile --> cargo["Cargo"]
|
||||
Dockerfile --> apt["apt-get"]
|
||||
build_script --> docker["Docker"]
|
||||
build_script --> cargo["Cargo"]
|
||||
deploy_script --> docker_compose["docker-compose"]
|
||||
deploy_script --> build_script["build.sh"]
|
||||
start_script --> rcoder["rcoder 二进制"]
|
||||
start_script --> bash["bash"]
|
||||
config --> yaml["YAML"]
|
||||
rust --> openssl["libssl-dev"]
|
||||
rust --> protobuf["protobuf-compiler"]
|
||||
rust --> build_essential["build-essential"]
|
||||
runtime --> curl["curl"]
|
||||
runtime --> jq["jq"]
|
||||
runtime --> gdb["gdb"]
|
||||
runtime --> strace["strace"]
|
||||
runtime --> htop["htop"]
|
||||
runtime --> tcpdump["tcpdump"]
|
||||
```
|
||||
|
||||
**图源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
Rcoder的Docker部署在性能方面进行了多项优化。多阶段构建确保了运行时镜像的轻量化，减少了攻击面和启动时间。调试镜像包含了完整的性能分析工具集，包括`perf`、`flamegraph`和`strace`，可以进行深入的性能分析。`generate-flamegraph.sh`脚本自动化了火焰图的生成过程，帮助开发者快速定位性能瓶颈。`diagnose-blocking.sh`脚本专门用于诊断阻塞问题，通过分析线程状态和系统调用，快速发现潜在的性能问题。
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见构建失败解决方案
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
BuildFail["构建失败"]
|
||||
BuildFail --> CheckDockerfile["检查Dockerfile存在"]
|
||||
CheckDockerfile --> |"不存在"| CreateDockerfile["创建Dockerfile"]
|
||||
CheckDockerfile --> |"存在"| CheckNetwork["检查网络连接"]
|
||||
CheckNetwork --> |"连接失败"| FixNetwork["修复网络"]
|
||||
CheckNetwork --> |"连接正常"| CheckDependencies["检查依赖"]
|
||||
CheckDependencies --> |"依赖缺失"| InstallDependencies["安装依赖"]
|
||||
CheckDependencies --> |"依赖完整"| CheckSource["检查源码"]
|
||||
CheckSource --> |"源码损坏"| RestoreSource["恢复源码"]
|
||||
CheckSource --> |"源码正常"| CheckDisk["检查磁盘空间"]
|
||||
CheckDisk --> |"空间不足"| FreeSpace["清理空间"]
|
||||
CheckDisk --> |"空间充足"| CheckPermissions["检查权限"]
|
||||
CheckPermissions --> |"权限不足"| FixPermissions["修复权限"]
|
||||
CheckPermissions --> |"权限正常"| CheckConfig["检查配置"]
|
||||
CheckConfig --> |"配置错误"| FixConfig["修复配置"]
|
||||
CheckConfig --> |"配置正确"| SeekHelp["寻求帮助"]
|
||||
```
|
||||
|
||||
**本节来源**
|
||||
- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
|
||||
### 权限问题解决方案
|
||||
|
||||
当遇到权限问题时，首先检查Docker守护进程是否正在运行，并确保当前用户有权限访问Docker socket。如果使用`sudo`运行Docker命令，考虑将用户添加到`docker`组以避免权限问题。对于容器内部的权限问题，检查Dockerfile中是否正确创建了应用用户，并确保挂载卷的权限设置正确。
|
||||
|
||||
**本节来源**
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
|
||||
### 容器启动错误解决方案
|
||||
|
||||
容器启动错误可能由多种原因引起。首先检查`docker-compose.yml`文件中的配置是否正确，特别是端口映射和卷挂载。使用`docker logs`命令查看容器日志，定位具体的错误信息。如果遇到依赖缺失问题，确保所有必要的依赖都已正确安装。对于网络问题，检查容器的网络配置和防火墙设置。
|
||||
|
||||
**本节来源**
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
|
||||
|
||||
## 结论
|
||||
|
||||
Rcoder项目的Docker部署方案设计精良，采用了多阶段构建策略，确保了生产环境的安全性和效率。调试镜像包含了丰富的诊断工具，为生产环境的问题排查提供了强大支持。构建和部署脚本自动化了整个流程，降低了人为错误的风险。通过合理的配置管理和卷挂载策略，实现了配置与代码的分离，提高了部署的灵活性。整体方案既适合初学者快速上手，也为高级用户提供了深入优化和调试的可能性。
|
||||
296
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/systemd服务管理.md
Normal file
296
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/systemd服务管理.md
Normal file
@@ -0,0 +1,296 @@
|
||||
# systemd服务管理
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [rcoder-service.sh](file://rcoder-service.sh)
|
||||
- [README.md](file://README.md)
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向运维与开发团队，系统性阐述如何将 rcoder 服务通过 systemd 进行开机自启、自动重启与状态监控，并结合仓库内的脚本与配置，给出完整的集成方案与最佳实践。重点覆盖：
|
||||
- rcoder-service.sh 与 systemd 的集成方式与差异
|
||||
- systemd 服务单元文件的编写要点（[Service]、[Install]、[Timer]）
|
||||
- start-rcoder.sh 在 systemd 上下文中的执行流程与环境准备
|
||||
- 日志查看、状态查询与故障排查的标准操作
|
||||
- 权限管理、资源限制与安全沙箱的配置建议
|
||||
- 常见问题（启动失败、权限不足、依赖未就绪）的定位与解决
|
||||
|
||||
## 项目结构
|
||||
围绕 systemd 集成的关键文件与位置如下：
|
||||
- systemd 服务单元示例位于 README.md 中，提供标准的 [Unit]/[Service]/[Install] 配置模板
|
||||
- rcoder-service.sh 是传统“手动服务管理脚本”，用于本地或非 systemd 场景
|
||||
- docker/scripts/start-rcoder.sh 是容器场景下的启动脚本，展示环境变量与工作目录准备
|
||||
- docker/Dockerfile 与 docker/docker-compose.yml 展示了容器内健康检查与重启策略
|
||||
- Cargo.toml 描述了项目依赖与运行时特性，有助于理解 systemd 下的运行环境
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["系统服务管理<br/>systemd"] --> B["rcoder 服务单元<br/>rcoder.service"]
|
||||
B --> C["可执行文件<br/>/opt/rcoder/target/release/rcoder"]
|
||||
B --> D["工作目录<br/>/opt/rcoder"]
|
||||
B --> E["环境变量<br/>RUST_LOG, RCODER_PORT 等"]
|
||||
F["rcoder-service.sh<br/>本地脚本管理"] -.-> C
|
||||
G["docker/scripts/start-rcoder.sh<br/>容器启动脚本"] -.-> C
|
||||
H["docker/Dockerfile<br/>健康检查/暴露端口"] --> I["健康检查<br/>/health"]
|
||||
J["docker/docker-compose.yml<br/>重启策略/restart: always"] --> B
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
|
||||
|
||||
## 核心组件
|
||||
- systemd 服务单元：定义服务行为、用户、工作目录、环境变量、重启策略与安装目标
|
||||
- rcoder-service.sh：提供 start/stop/restart/status 的本地脚本化管理，适合非 systemd 场景
|
||||
- start-rcoder.sh：容器内启动脚本，负责环境变量注入、目录创建与执行 rcoder
|
||||
- 健康检查与重启策略：Dockerfile 的 HEALTHCHECK 与 docker-compose.yml 的 restart: always 体现容器层面的自愈能力
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L134-L284)
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
|
||||
|
||||
## 架构总览
|
||||
下图展示了 systemd 与 rcoder 的典型交互：systemd 启动 rcoder，rcoder 通过健康检查对外提供服务；容器场景下，start-rcoder.sh 负责环境准备与进程启动。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant OS as "操作系统"
|
||||
participant SD as "systemd"
|
||||
participant SVC as "rcoder.service"
|
||||
participant BIN as "rcoder 可执行文件"
|
||||
participant LOG as "日志文件"
|
||||
participant NET as "网络端口"
|
||||
OS->>SD : "enable/start"
|
||||
SD->>SVC : "加载单元并初始化"
|
||||
SVC->>BIN : "ExecStart 启动进程"
|
||||
BIN->>LOG : "写入日志"
|
||||
BIN->>NET : "监听端口"
|
||||
SVC-->>SD : "健康检查通过/失败"
|
||||
SD-->>OS : "自动重启/通知"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### systemd 服务单元文件编写指南
|
||||
- [Unit]：描述服务元信息与依赖时机
|
||||
- Description：服务描述
|
||||
- After：在网络就绪后再启动
|
||||
- [Service]：核心执行与生命周期控制
|
||||
- Type：simple（systemd 直接管理 ExecStart 进程）
|
||||
- User：指定运行用户（建议独立非 root 用户）
|
||||
- WorkingDirectory：工作目录（存放配置、日志、PID 文件）
|
||||
- ExecStart：启动命令（建议使用绝对路径）
|
||||
- Restart：always（异常退出后自动重启）
|
||||
- RestartSec：重启间隔（避免频繁抖动）
|
||||
- Environment：注入日志级别、端口等环境变量
|
||||
- [Install]：安装目标
|
||||
- WantedBy：multi-user.target（多用户运行级别）
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
|
||||
### rcoder-service.sh 与 systemd 的差异与迁移建议
|
||||
- rcoder-service.sh 的职责
|
||||
- 依赖检查（可执行文件、Bun/NPM 等）
|
||||
- PID 文件管理与进程状态判断
|
||||
- 日志输出与错误提示
|
||||
- 启停与状态查询
|
||||
- 与 systemd 的差异
|
||||
- rcoder-service.sh 为“前台”脚本，systemd 期望“后台”守护进程
|
||||
- rcoder-service.sh 自带 nohup 与日志重定向，systemd 通过 StandardOutput/StandardError 管理日志
|
||||
- rcoder-service.sh 依赖本地 PATH 与工作目录，systemd 通过 WorkingDirectory 与 Environment 管理
|
||||
- 迁移建议
|
||||
- 若仍使用 rcoder-service.sh，建议将其作为 ExecStart 的入口脚本，但需确保其按 systemd 期望的“后台”方式运行
|
||||
- 更推荐直接使用 ExecStart 指向 rcoder 可执行文件，并通过 Environment 注入所需变量
|
||||
|
||||
章节来源
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L68-L103)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)
|
||||
|
||||
### start-rcoder.sh 在 systemd 上下文中的执行流程与环境准备
|
||||
- 环境变量准备
|
||||
- RUST_LOG：日志级别
|
||||
- PORT：服务端口
|
||||
- DOCKER_SOCKET_PATH：Docker 套接字路径
|
||||
- RCODER_WORKSPACE：工作区目录
|
||||
- 目录创建
|
||||
- logs 与 workspace 目录确保存在
|
||||
- 启动 rcoder
|
||||
- 使用 exec 方式启动，使 systemd 能正确接管进程
|
||||
- 通过 -- 参数传递端口给 rcoder
|
||||
|
||||
章节来源
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
|
||||
|
||||
### systemd 与容器场景的协同
|
||||
- docker/Dockerfile
|
||||
- EXPOSE 暴露端口（含 tokio-console 端口）
|
||||
- HEALTHCHECK 对 /health 进行健康检查
|
||||
- docker/docker-compose.yml
|
||||
- restart: always 提供容器层面的自愈
|
||||
- 健康检查与端口映射配合 systemd 的外部可用性
|
||||
|
||||
章节来源
|
||||
- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
|
||||
|
||||
## 依赖关系分析
|
||||
- rcoder 服务对运行时环境的依赖
|
||||
- Rust 运行时与日志库（tracing、tracing-subscriber）
|
||||
- HTTP 与异步运行时（tokio、axum、tower）
|
||||
- OpenTelemetry 与 Tokio Console（可选）
|
||||
- systemd 对服务的依赖
|
||||
- 可执行文件路径与权限
|
||||
- 工作目录与日志目录的可写权限
|
||||
- 环境变量（端口、日志级别、Docker 套接字等）
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A["rcoder 可执行文件"] --> B["HTTP 服务<br/>端口监听"]
|
||||
A --> C["日志系统<br/>tracing/tracing-subscriber"]
|
||||
A --> D["异步运行时<br/>tokio/axum/tower"]
|
||||
A --> E["可观测性<br/>OpenTelemetry/Tokio Console"]
|
||||
F["systemd"] --> A
|
||||
F --> G["工作目录/日志目录"]
|
||||
F --> H["环境变量"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L54-L102)
|
||||
- [Cargo.toml](file://Cargo.toml#L92-L102)
|
||||
- [Cargo.toml](file://Cargo.toml#L199-L205)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L54-L102)
|
||||
- [Cargo.toml](file://Cargo.toml#L92-L102)
|
||||
- [Cargo.toml](file://Cargo.toml#L199-L205)
|
||||
|
||||
## 性能考虑
|
||||
- 日志级别与性能
|
||||
- RUST_LOG=info 适合生产；debug 会增加 IO 与 CPU 开销
|
||||
- 端口与网络
|
||||
- 确保端口未被占用；合理规划防火墙规则
|
||||
- 健康检查与重启
|
||||
- HEALTHCHECK 与 restart: always 可提升可用性，但需避免过度重启导致抖动
|
||||
- 资源限制
|
||||
- systemd 可通过 LimitNOFILE、LimitMEM/CPU 等进行资源约束（建议在单元文件中配置）
|
||||
|
||||
[本节为通用指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 启动失败
|
||||
- 检查 ExecStart 路径与权限
|
||||
- 查看日志：journalctl -u rcoder -f
|
||||
- 验证环境变量是否正确注入
|
||||
- 权限不足
|
||||
- 确认 User 拥有工作目录与日志目录的读写权限
|
||||
- 端口是否需要 root 权限（建议使用非特权端口）
|
||||
- 依赖服务未就绪
|
||||
- 使用 After=network.target 等依赖时机
|
||||
- 在容器场景下，确认 Docker 套接字挂载与权限
|
||||
- 日志查看与状态查询
|
||||
- 日志：journalctl -u rcoder -n 100
|
||||
- 状态：systemctl status rcoder
|
||||
- 启停：systemctl start/stop/restart rcoder
|
||||
- 常见问题定位
|
||||
- 端口占用：调整 RCODER_PORT 或停止占用进程
|
||||
- 端口被占用：参考 README 中的端口调整示例
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)
|
||||
|
||||
## 结论
|
||||
- systemd 集成 rcoder 的关键在于：明确的单元文件、正确的 ExecStart、合理的环境变量与工作目录、以及可靠的健康检查与重启策略
|
||||
- 若采用容器部署，start-rcoder.sh 提供了清晰的环境准备与启动流程，可作为 systemd ExecStart 的入口脚本
|
||||
- 生产环境中建议结合日志级别控制、资源限制与健康检查，确保服务稳定与可观测
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### systemd 服务单元文件编写示例（基于仓库内容）
|
||||
- [Unit]
|
||||
- Description：RCoder AI Development Platform
|
||||
- After：network.target
|
||||
- [Service]
|
||||
- Type：simple
|
||||
- User：rcoder
|
||||
- WorkingDirectory：/opt/rcoder
|
||||
- ExecStart：/opt/rcoder/target/release/rcoder --port 3000
|
||||
- Restart：always
|
||||
- RestartSec：5
|
||||
- Environment：RUST_LOG=info；RCODER_PORT=3000
|
||||
- [Install]
|
||||
- WantedBy：multi-user.target
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
|
||||
### start-rcoder.sh 在 systemd 上下文中的执行流程
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["进入 systemd"]) --> Prep["准备环境变量<br/>RUST_LOG/PORT/DOCKER_SOCKET_PATH/RCODER_WORKSPACE"]
|
||||
Prep --> Mkdir["创建日志与工作目录"]
|
||||
Mkdir --> Exec["exec 启动 rcoder<br/>传递端口参数"]
|
||||
Exec --> Done(["进程由 systemd 管理"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
|
||||
|
||||
### 日志查看、状态查询与故障排查标准操作
|
||||
- 日志查看
|
||||
- journalctl -u rcoder -f
|
||||
- journalctl -u rcoder -n 100
|
||||
- 状态查询
|
||||
- systemctl status rcoder
|
||||
- 启停控制
|
||||
- systemctl start/stop/restart rcoder
|
||||
- 常见问题
|
||||
- 端口被占用：调整端口或释放占用进程
|
||||
- 权限不足：修正用户与目录权限
|
||||
- 依赖未就绪：检查 After 与 Docker 套接字挂载
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L560-L583)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)
|
||||
485
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/生产环境配置.md
Normal file
485
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/生产环境配置.md
Normal file
@@ -0,0 +1,485 @@
|
||||
# 生产环境配置
|
||||
|
||||
<cite>
|
||||
**本文引用的文件列表**
|
||||
- [config.yml](file://config.yml)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs)
|
||||
- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
|
||||
- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs)
|
||||
- [types.rs（docker_manager）](file://crates/docker_manager/src/types.rs)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs)
|
||||
- [service_config.rs（shared_types）](file://crates/shared_types/src/service_config.rs)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs)
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs)
|
||||
- [main.rs（agent_runner）](file://crates/agent_runner/src/main.rs)
|
||||
- [install.md](file://install.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向系统管理员与运维工程师，系统化梳理生产环境配置，涵盖 config.yml 中的各项参数、性能调优、安全加固、日志级别、资源限制、健康检查、高可用策略、TLS/访问控制/审计日志建议、配置热更新与敏感信息管理、配置版本控制，以及结合 analyze-rcoder.sh、generate-flamegraph.sh 等诊断脚本的生产监控与瓶颈分析方法，并提供生产部署检查清单与优化建议。
|
||||
|
||||
## 项目结构
|
||||
- 配置来源与优先级：命令行参数 > 环境变量 > 配置文件 > 默认值
|
||||
- Docker Compose 通过挂载宿主机 Docker Socket 与工作目录，实现容器内对宿主机资源的可见性与隔离
|
||||
- 服务包含主服务与 AgentRunner 两个子服务，二者共享多镜像配置与资源限制能力
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "宿主机"
|
||||
DC["docker-compose.yml"]
|
||||
WS["项目工作目录<br/>/app/project_workspace"]
|
||||
LOGS["日志目录<br/>/app/logs"]
|
||||
SOCK["Docker Socket<br/>/var/run/docker.sock"]
|
||||
end
|
||||
subgraph "容器: rcoder"
|
||||
SRV["rcoder 主服务"]
|
||||
CFG["配置加载<br/>config.rs"]
|
||||
HEALTH["健康检查端点<br/>/health"]
|
||||
PROXY["Pingora 代理服务"]
|
||||
end
|
||||
DC --> SRV
|
||||
WS --> SRV
|
||||
LOGS --> SRV
|
||||
SOCK --> SRV
|
||||
SRV --> PROXY
|
||||
SRV --> HEALTH
|
||||
SRV --> CFG
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
|
||||
章节来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
|
||||
## 核心组件
|
||||
- 配置加载与优先级
|
||||
- 命令行参数覆盖配置文件；环境变量覆盖所有配置；未设置时回退到默认值
|
||||
- Docker 配置支持环境变量覆盖（如网络模式、工作目录、自动清理、容器 TTL）
|
||||
- 健康检查
|
||||
- 主服务提供 /health 健康端点；Compose 健康检查基于该端点
|
||||
- 代理与负载均衡
|
||||
- 基于 Pingora 的反向代理，支持轮询/一致性哈希、健康检查、连接池与 HTTP/2
|
||||
- 资源限制与容器安全
|
||||
- 多镜像配置支持为 rcoder 与 agent-runner 设置独立资源限制（内存/CPU/交换）
|
||||
- 容器安全通过能力降级与网络隔离策略降低风险
|
||||
- 日志与遥测
|
||||
- 按天滚动 JSON 日志；支持 trace_id 传播；控制台与文件双通道输出
|
||||
|
||||
章节来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [types.rs（docker_manager）](file://crates/docker_manager/src/types.rs#L51-L82)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [main.rs（agent_runner）](file://crates/agent_runner/src/main.rs#L173-L231)
|
||||
|
||||
## 架构总览
|
||||
生产环境采用“主服务 + 代理 + 多镜像容器”的组合，通过 Docker Compose 统一编排，rcoder 主服务负责业务逻辑与健康检查，Pingora 代理负责端口转发与健康检查，容器内通过资源限制与安全策略保障稳定性与安全性。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "客户端"
|
||||
C1["HTTP 客户端"]
|
||||
end
|
||||
subgraph "边缘"
|
||||
PXY["Pingora 代理服务"]
|
||||
HC["健康检查"]
|
||||
end
|
||||
subgraph "应用"
|
||||
RC["rcoder 主服务"]
|
||||
AR["AgentRunner 子服务"]
|
||||
CFG["配置系统"]
|
||||
LOG["日志系统"]
|
||||
end
|
||||
subgraph "运行时"
|
||||
DCK["Docker 引擎"]
|
||||
IMG["镜像仓库"]
|
||||
end
|
||||
C1 --> PXY
|
||||
PXY --> RC
|
||||
RC --> AR
|
||||
RC --> CFG
|
||||
RC --> LOG
|
||||
RC -.-> DCK
|
||||
AR -.-> DCK
|
||||
DCK --> IMG
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 配置系统与优先级
|
||||
- 配置来源与顺序
|
||||
- 命令行参数 > 环境变量 > 配置文件 > 默认值
|
||||
- DockerConfig 支持环境变量覆盖网络模式、工作目录、自动清理、容器 TTL
|
||||
- 关键配置项说明（来自 config.yml 与 rcoder_default.yml）
|
||||
- default_agent：默认 AI 代理类型
|
||||
- projects_dir：项目工作目录
|
||||
- port：主服务端口
|
||||
- proxy_config.listen_port：代理监听端口
|
||||
- proxy_config.default_backend_port：默认后端端口
|
||||
- proxy_config.health_check.*：健康检查策略
|
||||
- docker_config.multi_image_config.*：多镜像配置（含 rcoder 与 agent-runner 的镜像、环境变量、命令、资源限制、挂载、工作目录、网络模式等）
|
||||
- docker_config.auto_cleanup：自动清理
|
||||
- docker_config.container_ttl_seconds：容器存活时间
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["启动"]) --> LoadFile["尝试读取配置文件"]
|
||||
LoadFile --> Parse["解析 YAML 为 AppConfig"]
|
||||
Parse --> ApplyEnv["应用环境变量覆盖"]
|
||||
ApplyEnv --> ApplyCLI["应用命令行参数覆盖"]
|
||||
ApplyCLI --> Validate["校验 Docker 多镜像配置"]
|
||||
Validate --> Final["生成最终配置"]
|
||||
Final --> Run(["运行服务"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
|
||||
章节来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
|
||||
### 健康检查与高可用
|
||||
- 主服务健康端点：/health 返回服务状态与时间戳
|
||||
- Compose 健康检查：基于 /health，重试次数、间隔、超时、启动期均配置
|
||||
- 代理健康检查：proxy_config.health_check.* 控制代理后端健康探测
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Compose as "Docker Compose"
|
||||
participant Service as "rcoder 主服务"
|
||||
participant Handler as "健康检查处理器"
|
||||
Client->>Compose : "健康检查请求"
|
||||
Compose->>Service : "GET /health"
|
||||
Service->>Handler : "路由到健康检查"
|
||||
Handler-->>Service : "构造响应"
|
||||
Service-->>Compose : "200 OK {status,timestamp,service}"
|
||||
Compose-->>Client : "健康状态"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
章节来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
|
||||
### 代理与负载均衡
|
||||
- Pingora 代理支持轮询/一致性哈希、健康检查、连接池与 HTTP/2
|
||||
- 代理端口与后端端口、后端主机、端口参数名均可配置
|
||||
- 代理统计接口可用于观测请求量、成功率、平均响应时间等
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Pxy as "Pingora 代理"
|
||||
participant Svc as "后端服务"
|
||||
participant Stats as "代理统计接口"
|
||||
Client->>Pxy : "请求 /proxy/{port}/path"
|
||||
Pxy->>Svc : "转发到 http : //backend_host : default_backend_port"
|
||||
Svc-->>Pxy : "响应"
|
||||
Pxy-->>Client : "响应"
|
||||
Client->>Stats : "GET /proxy/stats"
|
||||
Stats-->>Client : "统计信息"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L1-L50)
|
||||
|
||||
章节来源
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L1-L50)
|
||||
|
||||
### 资源限制与容器安全
|
||||
- 多镜像配置支持为 rcoder 与 agent-runner 设置资源限制（内存、CPU、交换），并可配置工作目录、网络模式、挂载、命令、入口点等
|
||||
- 容器安全策略：移除 NET_RAW/NET_ADMIN 能力，禁用特权模式，降低容器逃逸与网络攻击面
|
||||
- 容器 TTL 与自动清理：避免僵尸容器积累
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class ServiceResourceLimits {
|
||||
+memory_limit : u64?
|
||||
+cpu_limit : f64?
|
||||
+swap_limit : u64?
|
||||
+disk_limit : u64?
|
||||
+process_limit : u64?
|
||||
}
|
||||
class ServiceImageConfig {
|
||||
+image : string?
|
||||
+arm64_image : string?
|
||||
+amd64_image : string?
|
||||
+default_image : string?
|
||||
+environment : map
|
||||
+mounts : Mount[]
|
||||
+command : string[]
|
||||
+entrypoint : string[]?
|
||||
+work_dir : string
|
||||
+network_mode : string
|
||||
+container_path_template : string
|
||||
+resource_limits : ServiceResourceLimits?
|
||||
}
|
||||
class HostConfig {
|
||||
+cap_drop : string[]
|
||||
+privileged : bool
|
||||
+auto_remove : bool
|
||||
}
|
||||
ServiceImageConfig --> ServiceResourceLimits : "包含"
|
||||
HostConfig --> ServiceImageConfig : "配合运行"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [service_config.rs（shared_types）](file://crates/shared_types/src/service_config.rs#L48-L91)
|
||||
- [types.rs（docker_manager）](file://crates/docker_manager/src/types.rs#L51-L82)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [config.yml](file://config.yml#L31-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L31-L175)
|
||||
|
||||
章节来源
|
||||
- [service_config.rs（shared_types）](file://crates/shared_types/src/service_config.rs#L48-L91)
|
||||
- [types.rs（docker_manager）](file://crates/docker_manager/src/types.rs#L51-L82)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [config.yml](file://config.yml#L31-L161)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L31-L175)
|
||||
|
||||
### 日志级别与遥测
|
||||
- 日志滚动：按天滚动，保留最近 N 天日志
|
||||
- 输出格式：JSON 文件日志便于采集与分析；控制台简洁输出
|
||||
- 环境变量：RUST_LOG 控制日志级别；RCODER_PORT/RCODER_PROJECTS_DIR 等覆盖端口与工作目录
|
||||
- 追踪传播：支持 trace_id 传播，便于分布式链路追踪
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Init["初始化遥测"] --> FileLayer["文件日志层(JSON)"]
|
||||
Init --> ConsoleLayer["控制台日志层"]
|
||||
FileLayer --> Output["按天滚动输出"]
|
||||
ConsoleLayer --> Output
|
||||
Init --> Trace["设置 TraceContextPropagator"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [main.rs（agent_runner）](file://crates/agent_runner/src/main.rs#L173-L231)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L283-L310)
|
||||
|
||||
章节来源
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [main.rs（agent_runner）](file://crates/agent_runner/src/main.rs#L173-L231)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L283-L310)
|
||||
|
||||
### 诊断脚本与性能分析
|
||||
- analyze-rcoder.sh：进程基本信息、线程状态、网络连接、文件描述符、内存、CPU、上下文切换
|
||||
- diagnose-blocking.sh：阻塞线程分析、futex 等待、系统资源、最近错误日志、推荐下一步诊断
|
||||
- generate-flamegraph.sh：perf 采样、火焰图生成、原始 perf 数据保存、输出位置与分析要点
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
AStart["开始诊断"] --> FindPid["查找 rcoder 进程 PID"]
|
||||
FindPid --> Analyze["执行 analyze-rcoder.sh"]
|
||||
Analyze --> BlockDiag["执行 diagnose-blocking.sh"]
|
||||
BlockDiag --> Flame["执行 generate-flamegraph.sh"]
|
||||
Flame --> Review["查看 SVG 火焰图与原始 perf 数据"]
|
||||
Review --> End["结束"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh#L1-L56)
|
||||
- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh#L1-L98)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh#L1-L59)
|
||||
|
||||
章节来源
|
||||
- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh#L1-L56)
|
||||
- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh#L1-L98)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh#L1-L59)
|
||||
|
||||
## 依赖关系分析
|
||||
- 配置依赖
|
||||
- rcoder 主服务依赖配置系统加载 AppConfig，其中包含代理与 Docker 配置
|
||||
- agent_runner 服务同样依赖配置系统，支持独立的端口与代理配置
|
||||
- 运行时依赖
|
||||
- Docker Compose 依赖 Docker Socket 与工作目录挂载
|
||||
- 代理依赖 Pingora 库提供的服务实例
|
||||
- 安全与资源
|
||||
- 容器安全策略依赖 docker_manager 的 HostConfig 配置
|
||||
- 资源限制依赖 shared_types 的 ServiceResourceLimits
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CFG["配置系统<br/>config.rs"] --> RC["rcoder 主服务"]
|
||||
CFG --> AR["AgentRunner 服务"]
|
||||
RC --> PXY["Pingora 代理"]
|
||||
RC --> DCK["Docker 引擎"]
|
||||
AR --> DCK
|
||||
DCK --> DM["docker_manager"]
|
||||
DM --> ST["shared_types"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [service_config.rs（shared_types）](file://crates/shared_types/src/service_config.rs#L48-L91)
|
||||
|
||||
章节来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [server.rs（pingora-proxy）](file://crates/pingora-proxy/src/server.rs#L38-L72)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [service_config.rs（shared_types）](file://crates/shared_types/src/service_config.rs#L48-L91)
|
||||
|
||||
## 性能考量
|
||||
- 端口与代理
|
||||
- 代理监听端口与默认后端端口应与业务端口一致，减少跨端口转发开销
|
||||
- 健康检查间隔与阈值应平衡探测频率与系统负载
|
||||
- 资源限制
|
||||
- 根据业务峰值合理设置内存/CPU/交换限制，避免 OOM 与资源争抢
|
||||
- 容器 TTL 与自动清理避免长期运行导致的资源泄漏
|
||||
- 日志与追踪
|
||||
- 生产环境建议 INFO 或更高级别，必要时通过 RUST_LOG 动态调整
|
||||
- JSON 日志便于集中采集与分析，控制台仅用于实时观察
|
||||
- 代理统计
|
||||
- 定期检查 /proxy/stats，关注请求量、失败率与平均响应时间
|
||||
|
||||
章节来源
|
||||
- [config.yml](file://config.yml#L14-L30)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L14-L30)
|
||||
- [types.rs（docker_manager）](file://crates/docker_manager/src/types.rs#L51-L82)
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [router.rs（rcoder）](file://crates/rcoder/src/router.rs#L1-L50)
|
||||
|
||||
## 故障排查指南
|
||||
- 健康检查失败
|
||||
- 检查 /health 端点可达性与响应体
|
||||
- 查看 Compose 健康检查配置与重试策略
|
||||
- 阻塞与死锁
|
||||
- 使用 diagnose-blocking.sh 检查阻塞线程与 futex 等待
|
||||
- 结合 analyze-rcoder.sh 查看线程、内存、CPU、上下文切换
|
||||
- 性能瓶颈
|
||||
- 使用 generate-flamegraph.sh 生成火焰图，定位热点函数与调用栈
|
||||
- 关注 tokio 运行时、cleanup_task、docker_manager 相关调用
|
||||
- 网络与 I/O
|
||||
- 使用 analyze-rcoder.sh 的网络连接与 FD 统计
|
||||
- 结合 ss、lsof、iostat 等工具进行系统层面分析
|
||||
|
||||
章节来源
|
||||
- [health_handler.rs](file://crates/rcoder/src/handler/health_handler.rs#L1-L36)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
|
||||
- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh#L1-L98)
|
||||
- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh#L1-L56)
|
||||
- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh#L1-L59)
|
||||
|
||||
## 结论
|
||||
生产环境配置应遵循“最小权限、可观测、可恢复”的原则。通过合理的资源限制、健康检查、代理与日志策略，结合诊断脚本与火焰图分析，可以有效提升系统的稳定性与可维护性。建议在上线前完成配置基线评审与演练，并建立变更流程与回滚预案。
|
||||
|
||||
## 附录
|
||||
|
||||
### 生产配置与开发配置的关键差异
|
||||
- 日志级别：生产建议 INFO 或更高；开发可使用 DEBUG
|
||||
- 代理与端口：生产需明确代理监听端口与后端端口，确保与业务端口一致
|
||||
- 资源限制：生产必须设置内存/CPU/交换限制，避免资源滥用
|
||||
- 健康检查：生产需启用并合理配置健康检查间隔与阈值
|
||||
- 安全策略：生产需启用容器安全能力降级与网络隔离
|
||||
|
||||
章节来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L283-L310)
|
||||
- [config.yml](file://config.yml#L14-L30)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L14-L30)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
|
||||
### TLS 加密、访问控制与审计日志（建议）
|
||||
- TLS 加密
|
||||
- 建议在反向代理层（Nginx/Traefik/Caddy）启用 TLS，证书由 ACME 自动签发与续期
|
||||
- 对 rcoder 主服务与 AgentRunner 服务分别配置证书与域名
|
||||
- 访问控制
|
||||
- 在反向代理层添加认证（如 JWT/OAuth）、速率限制与 IP 白名单
|
||||
- 对 /proxy/* 端口访问进行细粒度授权
|
||||
- 审计日志
|
||||
- 启用统一日志采集（Fluent Bit/Vector）与集中存储（ELK/Graylog/Loki）
|
||||
- 对敏感操作（如代理端口访问、容器生命周期事件）进行审计记录
|
||||
|
||||
[本节为概念性建议，不直接分析具体文件，故无章节来源]
|
||||
|
||||
### 配置热更新、敏感信息管理与版本控制
|
||||
- 配置热更新
|
||||
- 通过环境变量覆盖实现动态生效（如 RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL）
|
||||
- 对于 Docker 配置，建议在重启容器或重新拉起服务时应用新配置
|
||||
- 敏感信息管理
|
||||
- 将密钥、令牌放入密钥管理服务（如 HashiCorp Vault、KMS），通过环境变量注入
|
||||
- 避免将敏感信息写入配置文件或镜像
|
||||
- 配置版本控制
|
||||
- 将 config.yml 与 rcoder_default.yml 纳入版本控制，使用分支策略与 PR 审批
|
||||
- 对关键变更进行变更记录与回滚预案
|
||||
|
||||
章节来源
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L283-L310)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L134-L171)
|
||||
|
||||
### 生产部署检查清单
|
||||
- 基础设施
|
||||
- Docker 引擎版本与内核参数满足要求
|
||||
- 系统时间同步（NTP）
|
||||
- 磁盘空间与 inode 足够
|
||||
- 配置验证
|
||||
- config.yml 与 rcoder_default.yml 参数齐全且合理
|
||||
- 环境变量覆盖生效（RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL）
|
||||
- 代理端口与后端端口一致，健康检查阈值合理
|
||||
- 安全加固
|
||||
- 容器能力降级（移除 NET_RAW/NET_ADMIN），禁用特权模式
|
||||
- 网络隔离策略生效
|
||||
- 证书与访问控制已在反向代理层配置
|
||||
- 监控与日志
|
||||
- 日志按天滚动，保留策略合理
|
||||
- /health 与 /proxy/stats 可用
|
||||
- 诊断脚本可用并具备执行权限
|
||||
- 高可用与备份
|
||||
- Compose 健康检查与重启策略配置
|
||||
- 容器 TTL 与自动清理开启
|
||||
- 备份策略（工作目录、日志、配置）
|
||||
|
||||
章节来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [config.rs（rcoder）](file://crates/rcoder/src/config.rs#L253-L354)
|
||||
- [config.rs（agent_runner）](file://crates/agent_runner/src/config.rs#L110-L191)
|
||||
- [manager.rs（docker_manager）](file://crates/docker_manager/src/manager.rs#L147-L165)
|
||||
- [main.rs（rcoder）](file://crates/rcoder/src/main.rs#L274-L320)
|
||||
- [main.rs（agent_runner）](file://crates/agent_runner/src/main.rs#L173-L231)
|
||||
347
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/部署指南.md
Normal file
347
qiming-rcoder/.qoder/repowiki/zh/content/部署指南/部署指南.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# 部署指南
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [Dockerfile](file://docker/Dockerfile)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [rcoder-service.sh](file://rcoder-service.sh)
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [build.sh](file://docker/scripts/build.sh)
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh)
|
||||
- [config.yml](file://config.yml)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [Docker部署](#docker部署)
|
||||
3. [Docker Compose配置](#docker-compose配置)
|
||||
4. [生产环境配置](#生产环境配置)
|
||||
5. [systemd服务实现](#systemd服务实现)
|
||||
6. [常见问题及解决方案](#常见问题及解决方案)
|
||||
7. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
本部署指南详细介绍了RCoder项目的部署流程，包括Docker部署、Docker Compose配置、生产环境配置和systemd服务实现。文档提供了具体的配置选项、参数说明和返回值解释，并阐述了各组件之间的关系。通过本指南，初学者可以快速上手部署，而经验丰富的开发人员可以获得足够的技术深度。
|
||||
|
||||
## Docker部署
|
||||
RCoder项目提供了完整的Docker部署方案，包括多阶段构建、调试工具集成和生产环境优化。
|
||||
|
||||
### Dockerfile分析
|
||||
Dockerfile采用多阶段构建策略，分为编译阶段和运行阶段。编译阶段使用`rust:1.90-bookworm`镜像进行编译，运行阶段则基于相同的镜像但包含完整的调试工具。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Dockerfile] --> B[多阶段构建]
|
||||
B --> C[编译阶段]
|
||||
B --> D[运行阶段]
|
||||
C --> E[安装编译依赖]
|
||||
C --> F[编译release版本]
|
||||
D --> G[安装运行时依赖]
|
||||
D --> H[安装调试工具]
|
||||
D --> I[复制二进制文件]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Dockerfile](file://docker/Dockerfile#L12-L115)
|
||||
|
||||
**Section sources**
|
||||
- [Dockerfile](file://docker/Dockerfile#L1-L305)
|
||||
|
||||
### 构建脚本
|
||||
项目提供了`build.sh`脚本用于构建Docker镜像，该脚本会检查必要的文件并执行构建命令。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始构建]) --> CheckFiles["检查必要文件"]
|
||||
CheckFiles --> BuildImage["执行docker build命令"]
|
||||
BuildImage --> Success["构建成功"]
|
||||
BuildImage --> Failure["构建失败"]
|
||||
Success --> End([结束])
|
||||
Failure --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [build.sh](file://docker/scripts/build.sh#L1-L21)
|
||||
|
||||
**Section sources**
|
||||
- [build.sh](file://docker/scripts/build.sh#L1-L21)
|
||||
|
||||
## Docker Compose配置
|
||||
Docker Compose配置文件定义了RCoder服务的运行环境，包括端口映射、环境变量和卷挂载。
|
||||
|
||||
### docker-compose.yml分析
|
||||
docker-compose.yml文件配置了RCoder服务的关键参数，包括镜像名称、端口映射、环境变量和卷挂载。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[docker-compose.yml] --> B[服务定义]
|
||||
B --> C[镜像配置]
|
||||
B --> D[端口映射]
|
||||
B --> E[环境变量]
|
||||
B --> F[卷挂载]
|
||||
B --> G[健康检查]
|
||||
B --> H[重启策略]
|
||||
C --> I[使用RCODER_IMAGE环境变量]
|
||||
D --> J[映射RCODER_PORT端口]
|
||||
E --> K[设置时区和日志级别]
|
||||
F --> L[挂载Docker socket]
|
||||
F --> M[挂载项目工作目录]
|
||||
F --> N[挂载日志目录]
|
||||
F --> O[挂载启动脚本]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
**Section sources**
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
### 部署脚本
|
||||
`deploy.sh`脚本自动化了部署流程，包括检查必要文件、构建镜像和启动服务。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始部署]) --> CheckFiles["检查必要文件"]
|
||||
CheckFiles --> CheckImage["检查镜像是否存在"]
|
||||
CheckImage --> Build["构建镜像"]
|
||||
CheckImage --> Start["启动服务"]
|
||||
Build --> Start
|
||||
Start --> Success["部署成功"]
|
||||
Start --> Failure["部署失败"]
|
||||
Success --> End([结束])
|
||||
Failure --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
|
||||
|
||||
**Section sources**
|
||||
- [deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
|
||||
|
||||
## 生产环境配置
|
||||
生产环境配置涉及多个方面，包括配置文件、环境变量和安全设置。
|
||||
|
||||
### 配置文件
|
||||
`config.yml`文件包含了RCoder服务的主要配置选项，包括默认代理类型、项目工作目录、端口设置和Docker配置。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[config.yml] --> B[基本配置]
|
||||
A --> C[代理配置]
|
||||
A --> D[Docker配置]
|
||||
B --> E[default_agent]
|
||||
B --> F[projects_dir]
|
||||
B --> G[port]
|
||||
C --> H[listen_port]
|
||||
C --> I[default_backend_port]
|
||||
C --> J[backend_host]
|
||||
C --> K[port_param]
|
||||
D --> L[multi_image_config]
|
||||
D --> M[network_mode]
|
||||
D --> N[work_dir]
|
||||
D --> O[auto_cleanup]
|
||||
D --> P[container_ttl_seconds]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
**Section sources**
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
|
||||
### 环境变量
|
||||
RCoder服务支持通过环境变量覆盖配置文件中的设置，提供了灵活的配置方式。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[环境变量] --> B[RUST_LOG]
|
||||
A --> C[PORT]
|
||||
A --> D[DOCKER_SOCKET_PATH]
|
||||
A --> E[RCODER_WORKSPACE]
|
||||
A --> F[RCODER_LOGS]
|
||||
A --> G[RCODER_NETWORK_MODE]
|
||||
A --> H[RCODER_WORK_DIR]
|
||||
A --> I[RCODER_AUTO_CLEANUP]
|
||||
A --> J[RCODER_CONTAINER_TTL]
|
||||
B --> K[设置日志级别]
|
||||
C --> L[设置服务端口]
|
||||
D --> M[设置Docker socket路径]
|
||||
E --> N[设置工作目录]
|
||||
F --> O[设置日志目录]
|
||||
G --> P[设置网络模式]
|
||||
H --> Q[设置工作目录]
|
||||
I --> R[设置自动清理]
|
||||
J --> S[设置容器存活时间]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L49-L53)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L214-L236)
|
||||
|
||||
### 启动脚本
|
||||
`start-rcoder.sh`脚本负责启动RCoder服务，设置了必要的环境变量并创建了所需的目录。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始启动]) --> SetEnv["设置环境变量"]
|
||||
SetEnv --> CreateDir["创建必要目录"]
|
||||
CreateDir --> PrintConfig["打印环境配置"]
|
||||
PrintConfig --> StartService["启动rcoder服务"]
|
||||
StartService --> End([结束])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L23)
|
||||
|
||||
**Section sources**
|
||||
- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L23)
|
||||
|
||||
## systemd服务实现
|
||||
systemd服务实现通过`rcoder-service.sh`脚本提供，支持启动、停止、重启和状态查询等操作。
|
||||
|
||||
### 服务管理脚本
|
||||
`rcoder-service.sh`脚本提供了完整的服务管理功能，包括依赖检查、PID管理、日志记录和信号处理。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[rcoder-service.sh] --> B[配置区域]
|
||||
A --> C[工具函数]
|
||||
A --> D[服务控制函数]
|
||||
A --> E[主函数]
|
||||
B --> F[端口设置]
|
||||
B --> G[可执行文件路径]
|
||||
B --> H[工作目录]
|
||||
B --> I[日志文件]
|
||||
B --> J[PID文件]
|
||||
B --> K[PATH设置]
|
||||
B --> L[日志级别]
|
||||
C --> M[info函数]
|
||||
C --> N[warn函数]
|
||||
C --> O[error函数]
|
||||
C --> P[status_msg函数]
|
||||
C --> Q[check_dependencies函数]
|
||||
C --> R[get_pid函数]
|
||||
C --> S[is_running函数]
|
||||
D --> T[start函数]
|
||||
D --> U[stop函数]
|
||||
D --> V[restart函数]
|
||||
D --> W[status函数]
|
||||
E --> X[main函数]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
|
||||
|
||||
**Section sources**
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
|
||||
|
||||
### 服务控制流程
|
||||
服务控制流程包括启动、停止、重启和状态查询四个主要操作，每个操作都有详细的错误处理和日志记录。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[主函数] --> B[解析命令行参数]
|
||||
B --> C{命令}
|
||||
C --> D[start]
|
||||
C --> E[stop]
|
||||
C --> F[restart]
|
||||
C --> G[status]
|
||||
D --> H[检查依赖]
|
||||
H --> I[启动服务]
|
||||
I --> J[保存PID]
|
||||
E --> K[检查是否运行]
|
||||
K --> L[停止服务]
|
||||
L --> M[清理PID文件]
|
||||
F --> N[调用stop]
|
||||
N --> O[调用start]
|
||||
G --> P[检查运行状态]
|
||||
P --> Q[显示状态信息]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [rcoder-service.sh](file://rcoder-service.sh#L289-L327)
|
||||
|
||||
## 常见问题及解决方案
|
||||
本节列出了部署过程中可能遇到的常见问题及其解决方案。
|
||||
|
||||
### Docker socket权限问题
|
||||
当容器无法访问Docker socket时，会出现权限错误。
|
||||
|
||||
**问题表现**：
|
||||
- 服务启动失败
|
||||
- 日志中出现"Permission denied"错误
|
||||
- 无法创建或管理容器
|
||||
|
||||
**解决方案**：
|
||||
1. 确保Docker服务正在运行
|
||||
2. 检查Docker socket文件是否存在
|
||||
3. 确保用户在docker组中
|
||||
4. 在docker-compose.yml中正确挂载Docker socket
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[权限问题] --> B[检查Docker服务]
|
||||
B --> C[检查socket文件]
|
||||
C --> D[检查用户组]
|
||||
D --> E[正确挂载socket]
|
||||
E --> F[解决问题]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L49-L53)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L11-L15)
|
||||
|
||||
### 配置文件加载问题
|
||||
当配置文件不存在或格式错误时，服务可能无法正常启动。
|
||||
|
||||
**问题表现**：
|
||||
- 服务启动失败
|
||||
- 日志中出现"Failed to load config"错误
|
||||
- 使用默认配置而非自定义配置
|
||||
|
||||
**解决方案**：
|
||||
1. 检查配置文件是否存在
|
||||
2. 验证YAML格式是否正确
|
||||
3. 确保配置文件路径正确
|
||||
4. 检查文件权限
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[配置问题] --> B[检查文件存在]
|
||||
B --> C[验证YAML格式]
|
||||
C --> D[检查路径正确]
|
||||
D --> E[检查文件权限]
|
||||
E --> F[解决问题]
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L255-L272)
|
||||
|
||||
### 网络隔离配置
|
||||
`setup-network-isolation.sh`脚本用于配置Docker容器的网络隔离规则，防止容器访问内网地址。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始配置]) --> CheckRoot["检查root权限"]
|
||||
CheckRoot --> CheckIptables["检查iptables安装"]
|
||||
CheckIptables --> FindNetworks["查找rcoder-网络"]
|
||||
FindNetworks --> Loop["遍历每个网络"]
|
||||
Loop --> GetSubnet["获取子网"]
|
||||
GetSubnet --> CheckRules["检查规则存在"]
|
||||
CheckRules --> AddRules["添加DROP规则"]
|
||||
AddRules --> Next["下一个网络"]
|
||||
Next --> Loop
|
||||
Loop --> PrintRules["打印当前规则"]
|
||||
PrintRules --> End([结束])
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
|
||||
|
||||
**Section sources**
|
||||
- [setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
|
||||
|
||||
## 总结
|
||||
本部署指南详细介绍了RCoder项目的部署流程，涵盖了Docker部署、Docker Compose配置、生产环境配置和systemd服务实现。通过本指南，用户可以全面了解RCoder的部署架构和配置选项，解决常见问题，并根据实际需求进行定制化部署。文档提供了足够的技术深度，既适合初学者快速上手，也为经验丰富的开发人员提供了详细的参考。
|
||||
405
qiming-rcoder/.qoder/repowiki/zh/content/配置系统.md
Normal file
405
qiming-rcoder/.qoder/repowiki/zh/content/配置系统.md
Normal file
@@ -0,0 +1,405 @@
|
||||
# 配置系统
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件系统化阐述本项目的配置体系，涵盖配置优先级、配置文件、环境变量与命令行参数的实现细节与交互关系。文档以代码为依据，提供面向初学者的循序讲解与面向资深工程师的技术深度，包括数据模型、处理流程、错误处理与常见问题的解决方案。
|
||||
|
||||
## 项目结构
|
||||
配置系统主要分布在以下模块：
|
||||
- rcoder 主服务：负责加载配置、解析命令行参数、应用环境变量覆盖、校验 Docker 多镜像配置，并将最终配置注入到运行时。
|
||||
- agent_runner 服务：同样遵循“命令行 > 环境变量 > 配置文件 > 默认”的优先级，生成自身配置。
|
||||
- 共享类型模块：提供多镜像配置、服务镜像配置、挂载点与资源限制等结构，以及配置验证逻辑。
|
||||
- Pingora 代理：提供独立的代理配置结构，用于端口反向代理场景。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "rcoder 主服务"
|
||||
RCMain["crates/rcoder/src/main.rs"]
|
||||
RCConfig["crates/rcoder/src/config.rs"]
|
||||
end
|
||||
subgraph "agent_runner 服务"
|
||||
ARMain["crates/agent_runner/src/main.rs"]
|
||||
ARConfig["crates/agent_runner/src/config.rs"]
|
||||
end
|
||||
subgraph "共享类型"
|
||||
SvcCfg["crates/shared_types/src/service_config.rs"]
|
||||
MultiImg["crates/shared_types/src/multi_image_config.rs"]
|
||||
end
|
||||
subgraph "代理"
|
||||
PingCfg["crates/pingora-proxy/src/config.rs"]
|
||||
end
|
||||
RCMain --> RCConfig
|
||||
RCMain --> PingCfg
|
||||
RCConfig --> SvcCfg
|
||||
RCConfig --> MultiImg
|
||||
ARMain --> ARConfig
|
||||
ARMain --> PingCfg
|
||||
ARConfig --> SvcCfg
|
||||
ARConfig --> MultiImg
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L272)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L179)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
章节来源
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L1-L272)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L1-L179)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L1-L270)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
## 核心组件
|
||||
- 配置优先级（rcoder 主服务）：命令行参数 > 环境变量 > 配置文件 > 默认配置；Docker 配置还支持环境变量覆盖。
|
||||
- 配置文件：YAML 格式，默认文件由嵌入资源生成；运行时可读取并解析为结构化配置。
|
||||
- 环境变量：用于覆盖端口、项目目录、Docker 网络模式、工作目录、自动清理、容器存活时间等。
|
||||
- 命令行参数：使用 Clap 定义，支持端口、项目目录、代理开关与端口等。
|
||||
- Docker 多镜像配置：集中管理服务镜像、环境变量、挂载点、资源限制、选择策略与缓存配置，并提供验证与摘要。
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
|
||||
## 架构总览
|
||||
下图展示了配置加载与覆盖的总体流程，以及与 Docker 多镜像配置、代理配置的交互。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant CLI as "命令行参数"
|
||||
participant ENV as "环境变量"
|
||||
participant FILE as "配置文件"
|
||||
participant DEF as "默认配置"
|
||||
participant CFG as "AppConfig/DockerConfig"
|
||||
participant PXY as "代理配置"
|
||||
participant DM as "DockerManager"
|
||||
CLI->>CFG : 解析并覆盖端口/目录/代理
|
||||
ENV->>CFG : 覆盖端口/目录/代理
|
||||
FILE->>CFG : 读取并解析 YAML
|
||||
DEF->>CFG : 提供默认值
|
||||
CFG->>CFG : 应用 Docker 环境变量覆盖
|
||||
CFG->>CFG : 校验 Docker 多镜像配置
|
||||
CFG->>PXY : 生成代理配置可选
|
||||
CFG->>DM : 合并多镜像配置并初始化
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L84-L129)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L97-L161)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L93-L165)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### rcoder 主服务配置加载流程
|
||||
- 优先级顺序：命令行参数 > 环境变量 > 配置文件 > 默认配置；Docker 配置支持额外的环境变量覆盖。
|
||||
- 关键行为：
|
||||
- 若配置文件不存在，生成默认配置文件（嵌入资源）。
|
||||
- 代理启用时，使用命令行参数构造代理配置。
|
||||
- 对 Docker 配置应用环境变量覆盖，并执行多镜像配置验证。
|
||||
- 输出最终配置摘要，便于排障。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckFile["是否存在配置文件?"]
|
||||
CheckFile --> |否| GenDefault["生成默认配置文件"]
|
||||
CheckFile --> |是| LoadFile["读取并解析 YAML"]
|
||||
LoadFile --> MergeDefaults["应用默认配置"]
|
||||
GenDefault --> MergeDefaults
|
||||
MergeDefaults --> ApplyCLI["应用命令行参数覆盖"]
|
||||
ApplyCLI --> ApplyENV["应用环境变量覆盖"]
|
||||
ApplyENV --> EnableProxy{"是否启用代理?"}
|
||||
EnableProxy --> |是| BuildProxy["使用 CLI 构造代理配置"]
|
||||
EnableProxy --> |否| SkipProxy["跳过代理配置"]
|
||||
BuildProxy --> ApplyDockerEnv["应用 Docker 环境变量覆盖"]
|
||||
SkipProxy --> ApplyDockerEnv
|
||||
ApplyDockerEnv --> Validate["验证 Docker 多镜像配置"]
|
||||
Validate --> Done(["返回最终 AppConfig"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L347-L403)
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L347-L403)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L84-L129)
|
||||
|
||||
### agent_runner 服务配置加载流程
|
||||
- 优先级顺序：默认配置 → 配置文件 → 环境变量 → 命令行参数（命令行优先级最高）。
|
||||
- 关键行为：
|
||||
- 首次启动若无配置文件，生成带注释的默认配置文件。
|
||||
- 代理启用时，使用命令行参数构造代理配置。
|
||||
- 输出最终配置摘要。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> LoadDefaults["加载默认配置"]
|
||||
LoadDefaults --> TryFile["尝试读取配置文件"]
|
||||
TryFile --> |成功| MergeFile["合并文件配置"]
|
||||
TryFile --> |失败| CreateDefault["生成默认配置文件"]
|
||||
MergeFile --> ApplyENV["应用环境变量覆盖"]
|
||||
ApplyENV --> EnableProxy{"是否启用代理?"}
|
||||
EnableProxy --> |是| BuildProxy["使用 CLI 构造代理配置"]
|
||||
EnableProxy --> |否| SkipProxy["跳过代理配置"]
|
||||
BuildProxy --> ApplyCLI["应用命令行参数覆盖最高优先级"]
|
||||
SkipProxy --> ApplyCLI
|
||||
ApplyCLI --> Done(["返回 AppConfig"])
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L206-L270)
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L206-L270)
|
||||
|
||||
### Docker 多镜像配置与服务镜像配置
|
||||
- 多镜像配置（MultiImageConfig）：
|
||||
- 全局默认镜像配置、服务映射、选择策略（当前为 ServiceOnly）、缓存配置。
|
||||
- 提供验证：全局前缀、缓存 TTL/条目数、服务启用数量等。
|
||||
- 支持全局默认镜像应用到各服务。
|
||||
- 服务镜像配置（ServiceImageConfig）：
|
||||
- 服务类型、镜像选择（通用/架构特定/默认回退）、环境变量、挂载点、命令、入口点、资源限制、工作目录、网络模式、容器路径模板。
|
||||
- 提供验证：至少一个镜像、镜像名称格式、挂载点路径与类型、容器路径模板变量替换。
|
||||
- 项目级镜像覆盖（ProjectImageOverrides）：
|
||||
- 支持按服务覆盖镜像与追加环境变量，提供校验与摘要。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class MultiImageConfig {
|
||||
+GlobalImageDefaults global_defaults
|
||||
+HashMap~String, ServiceImageConfig~ services
|
||||
+ImageSelectionStrategy selection_strategy
|
||||
+ImageCacheConfig cache_config
|
||||
+validate() Result
|
||||
+apply_global_defaults()
|
||||
+get_summary() String
|
||||
}
|
||||
class ServiceImageConfig {
|
||||
+ServiceType service_type
|
||||
+Option~String~ image
|
||||
+Option~String~ arm64_image
|
||||
+Option~String~ amd64_image
|
||||
+Option~String~ default_image
|
||||
+String image_tag_prefix
|
||||
+bool enabled
|
||||
+HashMap~String,String~ environment
|
||||
+Vec~ServiceMountConfig~ mounts
|
||||
+Vec~String~ command
|
||||
+Option~Vec~String~~ entrypoint
|
||||
+ServiceResourceLimits resource_limits
|
||||
+String work_dir
|
||||
+String network_mode
|
||||
+String container_path_template
|
||||
+validate() ConfigValidationResult
|
||||
+get_image_for_platform(platform) Option~String~
|
||||
+merge_environment(base) HashMap~String,String~
|
||||
+resolve_container_path(vars) String
|
||||
}
|
||||
class ProjectImageOverrides {
|
||||
+HashMap~String,String~ images
|
||||
+Vec~String~ enabled_services
|
||||
+HashMap~String,String~ environment
|
||||
+validate() Result
|
||||
+apply_to_service_config(type, config) Result
|
||||
+hash_key() String
|
||||
+is_service_enabled(type) bool
|
||||
+get_summary() String
|
||||
}
|
||||
MultiImageConfig --> ServiceImageConfig : "包含"
|
||||
MultiImageConfig --> ProjectImageOverrides : "可结合使用"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
|
||||
章节来源
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L1-L604)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
|
||||
### 代理配置（Pingora）
|
||||
- 结构：监听端口、默认后端端口、后端主机、端口参数名、配置文件路径、详细日志开关。
|
||||
- 行为：提供默认值与有效性校验（端口非零、主机非空、参数名非空）。
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L1-L95)
|
||||
|
||||
### 配置选项、参数与返回值
|
||||
- rcoder 主服务配置选项（AppConfig）：
|
||||
- default_agent：默认 AI 代理类型（枚举）。
|
||||
- projects_dir：项目工作目录（PathBuf）。
|
||||
- port：主服务端口（u16）。
|
||||
- proxy_config：可选代理配置（ProxyConfig）。
|
||||
- docker_config：可选 Docker 配置（DockerConfig）。
|
||||
- Docker 配置（DockerConfig）：
|
||||
- multi_image_config：可选多镜像配置。
|
||||
- network_mode、work_dir、auto_cleanup、container_ttl_seconds：可选覆盖项。
|
||||
- apply_env_overrides：应用环境变量覆盖。
|
||||
- validate_multi_image_config：验证多镜像配置。
|
||||
- get_summary：获取配置摘要。
|
||||
- 代理配置（ProxyConfig）：
|
||||
- listen_port、default_backend_port、backend_host、port_param、config_file、verbose。
|
||||
- 返回值：
|
||||
- load_config_with_args/load_config 返回 AppConfig。
|
||||
- DockerConfig.apply_env_overrides 返回 Result。
|
||||
- 多镜像配置验证返回 Result。
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L37-L96)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L148-L251)
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L38-L74)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L8-L47)
|
||||
|
||||
## 依赖关系分析
|
||||
- 依赖库：
|
||||
- 命令行解析：clap（含 env 功能）。
|
||||
- YAML 解析：serde_yaml。
|
||||
- 日志与遥测：tracing、tracing-subscriber、opentelemetry。
|
||||
- 异步运行时：tokio。
|
||||
- 代理：pingora。
|
||||
- Docker 管理：bollard。
|
||||
- 组件耦合：
|
||||
- rcoder/agent_runner 通过 AppConfig/DockerConfig 与共享类型解耦。
|
||||
- DockerManager 通过全局配置初始化，避免直接耦合具体服务。
|
||||
- 代理配置独立于业务配置，通过 rcoder/agent_runner 的启动逻辑注入。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Clap["clap"] --> CLI["命令行参数解析"]
|
||||
Serde["serde_yaml"] --> Yaml["YAML 解析"]
|
||||
Tracing["tracing"] --> Log["日志与遥测"]
|
||||
Tokio["tokio"] --> Async["异步运行时"]
|
||||
Pingora["pingora"] --> Proxy["代理服务"]
|
||||
Bollard["bollard"] --> DockerMgr["DockerManager"]
|
||||
CLI --> RCfg["rcoder 配置加载"]
|
||||
CLI --> ACfg["agent_runner 配置加载"]
|
||||
Yaml --> RCfg
|
||||
Yaml --> ACfg
|
||||
RCfg --> DockerMgr
|
||||
ACfg --> DockerMgr
|
||||
RCfg --> Proxy
|
||||
ACfg --> Proxy
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L51-L205)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L84-L129)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L80-L121)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L51-L205)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L84-L129)
|
||||
- [main.rs](file://crates/agent_runner/src/main.rs#L80-L121)
|
||||
|
||||
## 性能考量
|
||||
- 配置加载：
|
||||
- YAML 解析与序列化开销较小，建议将配置文件放置在本地磁盘，避免远程网络 IO。
|
||||
- 首次启动若无配置文件会写入默认配置，注意磁盘写入开销。
|
||||
- Docker 多镜像配置：
|
||||
- 缓存配置（ttl_seconds、max_entries）影响镜像拉取与选择性能，合理设置可减少重复拉取。
|
||||
- 选择策略为 ServiceOnly，避免跨服务模糊匹配带来的额外判断成本。
|
||||
- 代理配置：
|
||||
- 健康检查间隔与超时需权衡探测频率与系统负载。
|
||||
- 日志与遥测：
|
||||
- 控制日志级别与输出目标，避免过多 I/O 影响性能。
|
||||
|
||||
[本节为通用指导，无需列出章节来源]
|
||||
|
||||
## 故障排查指南
|
||||
- 配置文件缺失或损坏：
|
||||
- rcoder 会在首次启动时生成默认配置文件；若解析失败，会回退到默认配置并记录警告。
|
||||
- 排查：确认配置文件路径、权限与 YAML 格式。
|
||||
- 环境变量覆盖无效：
|
||||
- rcoder 主服务支持 RCODER_PORT、RCODER_PROJECTS_DIR、RCODER_NETWORK_MODE、RCODER_WORK_DIR、RCODER_AUTO_CLEANUP、RCODER_CONTAINER_TTL。
|
||||
- agent_runner 服务支持 RCODER_PORT（覆盖端口）。
|
||||
- 排查：确认环境变量名拼写与数值格式（如端口为 u16）。
|
||||
- Docker 配置验证失败：
|
||||
- 多镜像配置会校验全局前缀、缓存 TTL/条目数、服务启用数量、服务镜像与挂载点等。
|
||||
- 排查：检查镜像名称、挂载路径、网络模式、资源限制等。
|
||||
- 代理配置异常：
|
||||
- 监听端口、默认后端端口、后端主机、端口参数名不能为空且需为有效值。
|
||||
- 排查：确认端口范围与主机可达性。
|
||||
- 启动时 Docker 路径解析失败：
|
||||
- rcoder 主服务在启动时会初始化宿主机路径解析器，若失败会给出详细帮助信息与建议。
|
||||
- 排查：确认 Docker socket 路径、挂载与权限。
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
- [multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L97-L161)
|
||||
- [service_config.rs](file://crates/shared_types/src/service_config.rs#L93-L165)
|
||||
- [config.rs](file://crates/pingora-proxy/src/config.rs#L48-L69)
|
||||
- [main.rs](file://crates/rcoder/src/main.rs#L50-L83)
|
||||
|
||||
## 结论
|
||||
本项目的配置系统采用清晰的优先级与模块化设计：rcoder/agent_runner 分别加载自身配置，Docker 多镜像配置集中管理镜像、环境变量与挂载点，并提供严格的验证与摘要能力。通过命令行参数、环境变量与配置文件的组合，系统既满足开发调试的灵活性，又能在生产环境中保证一致性与可观测性。
|
||||
|
||||
[本节为总结性内容，无需列出章节来源]
|
||||
|
||||
## 附录
|
||||
|
||||
### 配置优先级一览
|
||||
- rcoder 主服务：命令行参数 > 环境变量 > 配置文件 > 默认配置；Docker 额外支持环境变量覆盖。
|
||||
- agent_runner 服务：默认配置 → 配置文件 → 环境变量 → 命令行参数（命令行最高优先级）。
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [config.rs](file://crates/agent_runner/src/config.rs#L110-L192)
|
||||
|
||||
### Docker 环境变量覆盖清单（rcoder）
|
||||
- RCODER_NETWORK_MODE：网络模式
|
||||
- RCODER_WORK_DIR：工作目录
|
||||
- RCODER_AUTO_CLEANUP：自动清理（布尔）
|
||||
- RCODER_CONTAINER_TTL：容器存活时间（秒）
|
||||
|
||||
章节来源
|
||||
- [config.rs](file://crates/rcoder/src/config.rs#L212-L239)
|
||||
|
||||
### 默认配置参考
|
||||
- rcoder 默认配置文件（嵌入资源）：包含默认代理、Docker 多镜像配置、端口、项目目录等。
|
||||
- 顶层 config.yml：顶层配置文件，包含 rcoder 与 agent-runner 的 Docker 服务镜像、环境变量、命令、资源限制、挂载点等。
|
||||
|
||||
章节来源
|
||||
- [rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml#L1-L175)
|
||||
- [config.yml](file://config.yml#L1-L161)
|
||||
339
qiming-rcoder/.qoder/repowiki/zh/content/附录/变更日志.md
Normal file
339
qiming-rcoder/.qoder/repowiki/zh/content/附录/变更日志.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# 变更日志
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件旨在系统化梳理 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 等
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L20)
|
||||
- [README.md](file://README.md#L269-L378)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L20)
|
||||
- [README.md](file://README.md#L269-L378)
|
||||
|
||||
## 核心组件
|
||||
- 主应用与配置系统：命令行参数、环境变量、配置文件三段式优先级，支持代理与 Docker 配置的加载与覆盖。
|
||||
- Pingora 反向代理：Axum + Pingora 的双服务架构，主服务提供 API/SSE，Pingora 独立监听代理端口，路径前缀路由到目标后端。
|
||||
- Docker 管理器：全局单例、镜像选择策略、容器生命周期管理、清理任务与网络/挂载配置。
|
||||
- 共享类型：多镜像配置结构、服务类型枚举、镜像选择器与缓存策略。
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L120)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L160-L210)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L40-L120)
|
||||
|
||||
## 架构总览
|
||||
RCoder 采用“主服务 + Pingora 代理”的双服务架构：
|
||||
- 主服务（Axum）：提供健康检查、聊天、SSE 实时进度、代理状态/配置/统计等接口。
|
||||
- Pingora 代理：独立监听代理端口，按路径前缀 /proxy/{port}/{path} 转发到指定后端，支持动态后端发现与健康检查。
|
||||
|
||||
```mermaid
|
||||
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}"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L133-L206)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L133-L206)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 变更日志模板与生成建议
|
||||
为保证变更日志的可追溯性与可维护性，建议采用如下模板（示例，非仓库既有内容）：
|
||||
- 版本号：vX.Y.Z
|
||||
- 发布日期：YYYY-MM-DD
|
||||
- 关键变更
|
||||
- 新增：新增 API 端点、代理支持类型扩展、配置系统优化、可观测性增强等
|
||||
- 修复：缺陷修复、兼容性问题修正、性能回归修复等
|
||||
- 变更：架构调整、依赖升级、行为变更、弃用项等
|
||||
- 升级指引：影响范围、破坏性变更、迁移步骤、兼容性说明
|
||||
- 问题排查：常见问题、诊断方法、相关日志位置
|
||||
|
||||
说明：本仓库未包含 CHANGELOG.md 文件，本文基于现有 README 与源码总结 v0.1.0 的现状与关键特性，作为后续版本变更日志的参考。
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L627-L652)
|
||||
|
||||
### 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](file://README.md#L627-L652)
|
||||
|
||||
### Pingora 反向代理能力与变更要点
|
||||
- 能力概述
|
||||
- 独立监听代理端口，路径前缀路由到目标后端
|
||||
- 支持动态后端发现与健康检查
|
||||
- 提供状态、配置、统计等查询接口（Axum 文档接口）
|
||||
- 关键实现
|
||||
- 主应用在启动时根据配置创建 Pingora 服务器管理器，并在后台启动
|
||||
- 路由中提供 /proxy/* 文档接口，真实代理请求需直接发送到 Pingora 端口
|
||||
- 代理库提供便捷函数与错误类型，支持快速启动与错误处理
|
||||
|
||||
```mermaid
|
||||
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 : "返回代理响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
|
||||
- [crates/rcoder/src/handler/proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L1-L120)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
|
||||
### Docker 容器管理与镜像选择能力
|
||||
- 能力概述
|
||||
- 全局 DockerManager 单例，支持自动检测平台、镜像选择与缓存
|
||||
- 多镜像配置结构，支持服务类型（rcoder/agent-runner）与架构（arm64/amd64）选择
|
||||
- 项目级镜像覆盖与环境变量注入
|
||||
- 关键实现
|
||||
- DockerManagerConfig 默认配置与全局初始化
|
||||
- ImageSelector 选择策略（ServiceOnly），支持缓存与校验
|
||||
- 容器生命周期管理、清理任务与网络/挂载配置
|
||||
|
||||
```mermaid
|
||||
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 : "读取配置"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L140-L211)
|
||||
- [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs#L175-L233)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L120-L200)
|
||||
|
||||
### 配置系统与升级影响评估
|
||||
- 配置优先级
|
||||
- 命令行参数 > 环境变量 > 配置文件 > 默认配置
|
||||
- 代理配置
|
||||
- 主应用根据命令行与配置文件决定是否启用 Pingora 代理及其监听端口、默认后端端口等
|
||||
- 升级影响评估
|
||||
- 若新增代理端口参数或健康检查配置项，需确保命令行与环境变量覆盖逻辑一致
|
||||
- Docker 配置新增字段时，应提供默认值与校验逻辑，避免破坏性变更
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
|
||||
## 依赖关系分析
|
||||
- 工作区与依赖
|
||||
- 工作区包含多个 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 之间传递，避免重复定义
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
rcoder["rcoder"] --> pingora_proxy["pingora-proxy"]
|
||||
rcoder --> docker_manager["docker_manager"]
|
||||
rcoder --> shared_types["shared_types"]
|
||||
docker_manager --> shared_types
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L20)
|
||||
|
||||
章节来源
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L20)
|
||||
|
||||
## 性能考量
|
||||
- 双服务架构
|
||||
- 主服务与 Pingora 代理并行运行，互不阻塞，提高吞吐与隔离性
|
||||
- 代理性能
|
||||
- 基于 Rust 异步 I/O 的高性能代理，支持动态后端发现与健康检查
|
||||
- 观测性
|
||||
- OpenTelemetry 与 Tracing 集成，便于定位性能瓶颈与异常
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L133-L206)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L120)
|
||||
|
||||
## 故障排查指南
|
||||
- 代理请求未转发
|
||||
- 确认请求是否发送到 Pingora 监听端口，而非主服务端口
|
||||
- 检查路径前缀是否符合 /proxy/{port}/{path}
|
||||
- 后端不可达
|
||||
- 确认目标后端端口已启动且可访问
|
||||
- Docker 相关
|
||||
- 检查 Docker socket 路径、权限与挂载
|
||||
- 查看全局 DockerManager 初始化日志与清理任务输出
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L193-L206)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L351)
|
||||
|
||||
## 结论
|
||||
- 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 默认配置与全局初始化，支持项目级镜像覆盖
|
||||
|
||||
章节来源
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L67-L79)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L250-L415)
|
||||
353
qiming-rcoder/.qoder/repowiki/zh/content/附录/常见问题解答.md
Normal file
353
qiming-rcoder/.qoder/repowiki/zh/content/附录/常见问题解答.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# 常见问题解答
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [CLAUDE.md](file://CLAUDE.md)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [config.yml](file://config.yml)
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs)
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本FAQ面向初学者与专家用户，围绕安装配置、AI代理集成、反向代理路由、SSE进度流中断等高频问题，结合代码库中的实际实现，提供现象、根因、解决方案与预防措施，并给出可复现的排查步骤与日志分析技巧。文档同时整合跨组件问题（如配置优先级冲突导致的行为异常），帮助快速定位与修复。
|
||||
|
||||
## 项目结构
|
||||
- 主应用（Axum）负责业务API、会话管理与SSE进度流
|
||||
- Pingora代理独立监听端口，按路径前缀“/proxy/{port}/{path}”转发到指定后端
|
||||
- 两者并行运行，互不阻塞；Axum中的“/proxy/...”路由仅作文档与重定向到Pingora
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["客户端"] --> B["Axum 主服务"]
|
||||
A --> C["Pingora 反向代理"]
|
||||
B --> D["API 路由"]
|
||||
B --> E["Agent 工作者(LocalSet)"]
|
||||
C --> F["后端: 127.0.0.1:{port}"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L16-L30)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L16-L30)
|
||||
|
||||
## 核心组件
|
||||
- 配置系统：命令行 > 环境变量 > 配置文件 > 默认值，优先级明确
|
||||
- 反向代理：Pingora提供端口路由、路径重写、指标统计与健康检查
|
||||
- 观测性：Tracing + OpenTelemetry，统一注入trace_id，便于跨服务串联
|
||||
- 容器化：DockerManager动态创建容器，内部网络通信，自动路径解析与挂载
|
||||
- SSE：统一的实时进度流接口，便于前端消费
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L386-L439)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L108-L114)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [config.yml](file://config.yml#L1-L30)
|
||||
|
||||
## 架构总览
|
||||
- 主服务与代理并行：Axum提供REST API与SSE；Pingora独立监听代理端口
|
||||
- 代理请求必须发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
|
||||
- 代理模式下不支持查询参数提取端口（遵循“代理端口提取规则”）
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Axum as "Axum 主服务"
|
||||
participant Proxy as "Pingora 代理"
|
||||
participant Backend as "后端服务(127.0.0.1 : {port})"
|
||||
Client->>Axum : "GET /proxy/status" (文档/状态)
|
||||
Axum-->>Client : "307 重定向到 Pingora 端口"
|
||||
Client->>Proxy : "GET /proxy/{port}/{path}" (直接请求代理端口)
|
||||
Proxy->>Proxy : "提取端口/重写路径"
|
||||
Proxy->>Backend : "转发请求"
|
||||
Backend-->>Proxy : "响应"
|
||||
Proxy-->>Client : "返回响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L133-L206)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L253-L354)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L133-L206)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 反向代理路由失败
|
||||
- 现象
|
||||
- 请求误发到Axum主服务端口的“/proxy/...”路由，收到307重定向
|
||||
- 收到JSON演示响应而非真实转发
|
||||
- 端口提取失败（路径非“/proxy/{port}/{path}”或端口非法）
|
||||
- 根因
|
||||
- 代理模式仅支持路径前缀提取端口，不解析查询参数
|
||||
- 未指定目标后端端口或端口不可达
|
||||
- 解决方案
|
||||
- 直接请求Pingora监听端口，路径格式为“/proxy/{port}/{path}”
|
||||
- 确认目标后端服务已在本机启动且端口有效
|
||||
- 预防措施
|
||||
- 在客户端或网关层统一走Pingora端口
|
||||
- 使用代理状态/配置/统计接口辅助排障
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> CheckPort["检查路径是否为 /proxy/{port}/{path}"]
|
||||
CheckPort --> ValidPort{"端口是否为有效数字?"}
|
||||
ValidPort --> |否| FixPath["修正路径格式为 /proxy/{port}/{path}"]
|
||||
ValidPort --> |是| BackendUp{"目标后端(127.0.0.1:{port}) 是否启动?"}
|
||||
BackendUp --> |否| StartBackend["启动后端服务"]
|
||||
BackendUp --> |是| Forward["转发到后端"]
|
||||
FixPath --> End(["结束"])
|
||||
StartBackend --> End
|
||||
Forward --> End
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L168-L198)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L168-L198)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
|
||||
|
||||
### SSE进度流中断
|
||||
- 现象
|
||||
- 客户端SSE连接断开，无法持续接收进度事件
|
||||
- 根因
|
||||
- 代理层或上游服务超时、连接中断、NAT/防火墙丢弃空闲连接
|
||||
- 客户端未正确处理长连接或网络波动
|
||||
- 解决方案
|
||||
- 保持客户端长连接，合理设置心跳与重连策略
|
||||
- 在代理层开启健康检查与负载均衡，避免后端不稳定导致中断
|
||||
- 预防措施
|
||||
- 使用代理统计接口观察活跃连接数与失败率
|
||||
- 在主服务侧确保SSE通道稳定，避免阻塞
|
||||
|
||||
章节来源
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
|
||||
|
||||
### Docker权限问题
|
||||
- 现象
|
||||
- 容器创建失败、镜像拉取失败、无法获取容器日志
|
||||
- 根因
|
||||
- Docker socket权限不足或未挂载
|
||||
- 容器内无法访问宿主机路径映射
|
||||
- 解决方案
|
||||
- 确保Docker socket挂载到容器并具备读写权限
|
||||
- 在compose中设置正确的环境变量（如DOCKER_SOCKET_PATH）
|
||||
- 使用容器自检测器进行socket连通性与容器ID解析验证
|
||||
- 预防措施
|
||||
- 启动时先验证Docker连接，再执行容器操作
|
||||
- 在CI/本地开发环境统一挂载策略
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Dev as "开发者"
|
||||
participant Compose as "Docker Compose"
|
||||
participant RC as "RCoder 容器"
|
||||
participant Inspect as "ContainerSelfInspector"
|
||||
Dev->>Compose : "启动服务"
|
||||
Compose->>RC : "挂载 /var/run/docker.sock"
|
||||
RC->>Inspect : "初始化并验证Docker连接"
|
||||
Inspect-->>RC : "连接成功/失败"
|
||||
RC-->>Dev : "日志输出(成功/失败)"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
|
||||
|
||||
章节来源
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
|
||||
|
||||
### AI代理集成（Claude Code代理无法启动）
|
||||
- 现象
|
||||
- Claude Code代理启动失败或无法连接
|
||||
- 根因
|
||||
- Claude Code CLI未安装或环境变量未配置
|
||||
- 容器内网络隔离导致外部服务不可达
|
||||
- 容器内路径解析失败，挂载映射不正确
|
||||
- 解决方案
|
||||
- 安装并配置Claude Code CLI，设置API密钥与模型
|
||||
- 使用内部网络通信，避免宿主机端口映射带来的复杂性
|
||||
- 通过容器自检测器校验挂载点与宿主机路径映射
|
||||
- 预防措施
|
||||
- 在配置文件中明确镜像与资源限制
|
||||
- 启动后检查容器健康状态与日志
|
||||
|
||||
章节来源
|
||||
- [CLAUDE.md](file://CLAUDE.md#L116-L133)
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L132-L242)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
|
||||
|
||||
### 配置优先级冲突导致的行为异常
|
||||
- 现象
|
||||
- 端口、代理监听端口、默认后端端口与期望不一致
|
||||
- 环境变量覆盖配置文件但被命令行参数再次覆盖
|
||||
- 根因
|
||||
- 配置来源优先级顺序：命令行 > 环境变量 > 配置文件 > 默认值
|
||||
- 解决方案
|
||||
- 明确各层配置来源，必要时显式指定命令行参数
|
||||
- 在启动脚本中统一设置环境变量，避免遗漏
|
||||
- 预防措施
|
||||
- 在CI/本地开发环境固化配置来源，减少歧义
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L386-L439)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L108-L114)
|
||||
- [config.yml](file://config.yml#L1-L30)
|
||||
|
||||
## 依赖关系分析
|
||||
- 配置来源与优先级
|
||||
- 命令行参数最高优先级，环境变量次之，配置文件再次之，最后为默认值
|
||||
- 代理与后端
|
||||
- Pingora代理负责端口提取与路径重写，后端映射动态维护
|
||||
- 观测性
|
||||
- Tracing中间件统一注入trace_id，便于跨服务日志关联
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
CLI["命令行参数"] --> Prio["配置优先级"]
|
||||
ENV["环境变量"] --> Prio
|
||||
CFG["配置文件"] --> Prio
|
||||
DEF["默认值"] --> Prio
|
||||
Prio --> AX["Axum 主服务"]
|
||||
Prio --> PRX["Pingora 代理"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L386-L439)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L108-L114)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L386-L439)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L108-L114)
|
||||
|
||||
## 性能考量
|
||||
- 代理层指标
|
||||
- 总请求数、成功率、平均响应时间、按端口统计、活跃连接数
|
||||
- 负载均衡
|
||||
- 支持轮询与健康检查，定期探测后端可达性
|
||||
- 容器化
|
||||
- 内部网络通信，避免端口映射带来的额外开销
|
||||
|
||||
章节来源
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
|
||||
|
||||
## 故障排查指南
|
||||
|
||||
### 通过tracing_middleware日志定位请求失败原因
|
||||
- 步骤
|
||||
- 启用详细日志：设置RUST_LOG为debug或指定模块
|
||||
- 观察请求进入与退出日志，定位trace_id
|
||||
- 在Axum中间件层记录请求开始/结束与状态码
|
||||
- 建议
|
||||
- 在客户端携带trace_id或x-request-id，便于跨服务串联
|
||||
- 使用代理统计接口查看失败率与平均响应时间
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Axum as "Axum 中间件"
|
||||
participant Handler as "业务处理器"
|
||||
Client->>Axum : "请求(携带trace_id)"
|
||||
Axum->>Axum : "记录请求开始"
|
||||
Axum->>Handler : "处理请求"
|
||||
Handler-->>Axum : "返回响应"
|
||||
Axum->>Axum : "记录响应状态"
|
||||
Axum-->>Client : "响应"
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
章节来源
|
||||
- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
|
||||
|
||||
### 通过container_self_inspector诊断容器状态
|
||||
- 步骤
|
||||
- 初始化ContainerSelfInspector，验证Docker socket连接
|
||||
- 获取当前容器ID与挂载信息，核对容器内路径到宿主机路径映射
|
||||
- 若未找到挂载信息，列出所有挂载点辅助定位
|
||||
- 建议
|
||||
- 在容器启动脚本中先验证Docker连接与挂载权限
|
||||
- 使用compose挂载/var/run/docker.sock并设置环境变量
|
||||
|
||||
章节来源
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
|
||||
- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
|
||||
### 代理端口提取失败排查
|
||||
- 步骤
|
||||
- 确认请求路径为“/proxy/{port}/{path}”，端口为有效数字
|
||||
- 如未指定端口，确认默认后端端口配置
|
||||
- 使用代理状态/配置/统计接口查看后端映射与健康状态
|
||||
- 建议
|
||||
- 在客户端统一走Pingora端口，避免误发到Axum主服务端口
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L168-L198)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L63-L118)
|
||||
|
||||
### SSE进度流中断排查
|
||||
- 步骤
|
||||
- 检查代理统计接口，关注活跃连接数与失败率
|
||||
- 确认上游服务健康状态与响应时间
|
||||
- 在客户端侧增加重连与心跳机制
|
||||
- 建议
|
||||
- 使用代理健康检查循环，定期探测后端可达性
|
||||
|
||||
章节来源
|
||||
- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
|
||||
- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
|
||||
|
||||
### 容器内路径解析失败
|
||||
- 步骤
|
||||
- 使用容器自检测器检测容器ID与挂载点
|
||||
- 核对容器内路径到宿主机路径映射是否正确
|
||||
- 在配置文件中明确挂载路径并进行变量替换
|
||||
- 建议
|
||||
- 在启动脚本中统一挂载策略，避免相对路径与容器内绝对路径混淆
|
||||
|
||||
章节来源
|
||||
- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L244-L295)
|
||||
- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L138-L166)
|
||||
|
||||
## 结论
|
||||
- 代理请求必须直接发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
|
||||
- 配置优先级清晰，命令行最高，环境变量次之，配置文件再次之
|
||||
- 观测性与容器化能力完善，建议结合Tracing与代理统计进行问题定位
|
||||
- Docker权限与路径解析是容器化部署的关键，务必在启动阶段验证
|
||||
|
||||
## 附录
|
||||
- 常用命令与接口
|
||||
- 健康检查：/health
|
||||
- 代理状态：/proxy/status
|
||||
- 代理配置：/proxy/config
|
||||
- 代理统计：/proxy/stats
|
||||
- 实时进度流：/agent/progress/{session_id}
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L209-L268)
|
||||
311
qiming-rcoder/.qoder/repowiki/zh/content/附录/相关链接.md
Normal file
311
qiming-rcoder/.qoder/repowiki/zh/content/附录/相关链接.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 相关链接
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [CLAUDE.md](file://CLAUDE.md)
|
||||
- [install.md](file://install.md)
|
||||
- [Makefile](file://Makefile)
|
||||
- [http_test.rest](file://http_test.rest)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh)
|
||||
- [config.yml](file://config.yml)
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本章节聚焦于项目中的“相关链接”，即 README.md 中列出的项目主页、贡献指南、许可证文件、设计文档（specs/目录下）以及其他关键文档（如 CLAUDE.md、install.md）。我们将解释这些文档的作用、访问方式，并给出实际使用场景示例，帮助开发者在开发、部署与故障排除中高效集成这些资源。同时，针对常见问题（如链接失效、文档版本不匹配）提供解决方案，并建议性能优化措施（如本地文档镜像、自动化文档索引）。
|
||||
|
||||
## 项目结构
|
||||
围绕“相关链接”的组织方式，项目提供了如下关键入口与配套资源：
|
||||
- 顶层文档：README.md、CLAUDE.md、install.md
|
||||
- 设计文档：specs/agent-abstraction-layer-design.md、specs/grpc-migration-design.md、specs/multi-docker-image-design.md
|
||||
- 部署与脚本：Makefile、docker/docker-compose.yml、docker/start-rcoder.sh
|
||||
- 配置与测试：config.yml、http_test.rest
|
||||
- 子模块文档：crates/docker_manager/README.md
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A["README.md<br/>项目主页/贡献指南/许可证/相关链接"] --> B["CLAUDE.md<br/>开发指引与环境配置"]
|
||||
A --> C["install.md<br/>安装基础环境"]
|
||||
A --> D["specs/*<br/>设计文档集合"]
|
||||
D --> D1["agent-abstraction-layer-design.md"]
|
||||
D --> D2["grpc-migration-design.md"]
|
||||
D --> D3["multi-docker-image-design.md"]
|
||||
A --> E["Makefile<br/>构建与开发容器命令"]
|
||||
A --> F["docker/docker-compose.yml<br/>容器编排"]
|
||||
F --> G["docker/start-rcoder.sh<br/>容器启动脚本"]
|
||||
A --> H["config.yml<br/>配置文件示例"]
|
||||
A --> I["http_test.rest<br/>API 测试脚本"]
|
||||
A --> J["crates/docker_manager/README.md<br/>Docker 管理模块文档"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L1-L60)
|
||||
- [install.md](file://install.md#L1-L9)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L20)
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L40)
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L20)
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L40)
|
||||
|
||||
## 核心组件
|
||||
- 项目主页与贡献指南：位于 README.md 的“相关链接”区域，提供仓库地址、问题跟踪、贡献指南与变更日志入口。
|
||||
- 许可证文件：位于 README.md 的“许可证”区域，说明采用 MIT 或 Apache-2.0 双许可证。
|
||||
- 设计文档（specs/）：包含 Agent 抽象层、gRPC 迁移、多镜像设计等，指导架构演进与实现。
|
||||
- 开发与安装文档：CLAUDE.md 提供开发命令、环境变量、API 接口与调试方法；install.md 提供安装基础依赖的指引。
|
||||
- 构建与部署：Makefile 提供本地编译、安装、Docker 镜像构建与开发容器的快捷命令；docker/docker-compose.yml 与 docker/start-rcoder.sh 提供容器化运行与健康检查。
|
||||
- 配置与测试：config.yml 展示默认配置项与代理配置；http_test.rest 提供 API 测试脚本，便于手动验证接口行为。
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L27-L120)
|
||||
- [install.md](file://install.md#L1-L9)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L20)
|
||||
|
||||
## 架构总览
|
||||
“相关链接”在整体架构中的作用是为开发者提供从入门到深入实现的路径图。通过 README 的“相关链接”导航到贡献指南与设计文档，再结合 CLAUDE.md 的开发命令与 Makefile 的构建流程，最终落地到 docker-compose 与启动脚本完成部署与运行。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Dev["开发者"] --> R["README.md<br/>相关链接"]
|
||||
R --> Contrib["CONTRIBUTING.md<br/>贡献指南"]
|
||||
R --> License["LICENSE<br/>许可证"]
|
||||
R --> Specs["specs/*<br/>设计文档"]
|
||||
Specs --> AAL["Agent 抽象层设计"]
|
||||
Specs --> GRPC["gRPC 迁移设计"]
|
||||
Specs --> MDI["多镜像设计"]
|
||||
Dev --> CL["CLAUDE.md<br/>开发命令/环境变量/API"]
|
||||
Dev --> MK["Makefile<br/>构建/安装/开发容器"]
|
||||
Dev --> DC["docker-compose.yml<br/>容器编排"]
|
||||
DC --> SH["start-rcoder.sh<br/>启动脚本"]
|
||||
Dev --> CFG["config.yml<br/>配置示例"]
|
||||
Dev --> HT["http_test.rest<br/>API 测试"]
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L27-L120)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L20)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### README.md 的“相关链接”与“许可证”
|
||||
- 项目主页与问题追踪：提供仓库地址与 Issues 页面，便于提交问题与跟踪进展。
|
||||
- 贡献指南与变更日志：CONTRIBUTING.md 与 CHANGELOG.md 提供贡献流程与版本演进记录。
|
||||
- 许可证：LICENSE 文件说明采用 MIT 或 Apache-2.0 双许可证，明确使用范围与分发条件。
|
||||
- 使用场景示例：
|
||||
- 开发者在遇到问题时，先查阅 FAQ（README 的“问题排查”区域），再搜索 Issues，最后在 Issues 中补充详细信息。
|
||||
- 贡献者在提交 PR 前，先阅读 CONTRIBUTING.md 的流程与规范。
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
|
||||
### 设计文档（specs/）的作用与访问方式
|
||||
- agent-abstraction-layer-design.md：定义 Agent 抽象层、Agent Trait、Launcher、Supervisor 与配置管理，指导多 Agent 支持与扩展。
|
||||
- grpc-migration-design.md：规划从 HTTP+SSE 迁移到 gRPC 的接口契约与模块改造计划，统一通信协议与类型安全。
|
||||
- multi-docker-image-design.md：设计双镜像配置系统，支持 rcoder 与 agent-runner 两类服务类型，兼顾向后兼容与未来扩展。
|
||||
- 使用场景示例：
|
||||
- 架构师在评估新 Agent 集成时，参考 agent-abstraction-layer-design.md 的抽象接口与生命周期管理。
|
||||
- 团队在讨论通信协议升级时，参考 grpc-migration-design.md 的 Proto 定义与实施步骤。
|
||||
- 在引入新服务类型时，参考 multi-docker-image-design.md 的镜像选择策略与容器创建接口。
|
||||
|
||||
章节来源
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L120)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L60)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L120)
|
||||
|
||||
### CLAUDE.md 的开发命令与环境配置
|
||||
- 开发命令：提供本地构建、安装、Docker 镜像构建与开发容器的常用命令，便于快速迭代。
|
||||
- 环境变量：列举服务端口、Docker socket、代理密钥等关键环境变量，确保开发与调试一致性。
|
||||
- API 接口：列出核心端点与响应格式，便于前后端联调与测试。
|
||||
- 使用场景示例：
|
||||
- 新成员入职时，先按 install.md 安装基础依赖，再参考 CLAUDE.md 的开发命令搭建本地环境。
|
||||
- 调试阶段，通过 CLAUDE.md 的日志配置与容器调试命令快速定位问题。
|
||||
|
||||
章节来源
|
||||
- [CLAUDE.md](file://CLAUDE.md#L27-L120)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L116-L170)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L139-L190)
|
||||
|
||||
### install.md 的安装基础环境
|
||||
- 提供安装 Claude Code ACP 与 Claude Code CLI 的命令，确保 AI 代理相关能力可用。
|
||||
- 使用场景示例：
|
||||
- 在首次运行前，先执行 install.md 中的安装步骤，避免后续代理调用失败。
|
||||
|
||||
章节来源
|
||||
- [install.md](file://install.md#L1-L9)
|
||||
|
||||
### Makefile 的构建与开发容器命令
|
||||
- 本地编译、安装、卸载二进制与安装 agent 的命令，便于快速构建与分发。
|
||||
- Docker 镜像构建与开发容器的一键流程，支持快速重启与日志查看。
|
||||
- 使用场景示例：
|
||||
- 本地开发：make dev-build 后 make dev-up 启动开发容器；修改代码后 make dev-restart 快速重启。
|
||||
- CI/CD：make docker-build 构建镜像，配合 docker/docker-compose.yml 进行部署。
|
||||
|
||||
章节来源
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [Makefile](file://Makefile#L75-L120)
|
||||
- [Makefile](file://Makefile#L122-L166)
|
||||
|
||||
### docker/docker-compose.yml 与 docker/start-rcoder.sh
|
||||
- docker-compose.yml：定义服务名称、端口映射、环境变量、卷挂载与健康检查，确保容器化运行稳定。
|
||||
- start-rcoder.sh：在容器内初始化必要目录、导出环境变量并启动 rcoder 主程序。
|
||||
- 使用场景示例：
|
||||
- 通过 docker-compose.yml 的 healthcheck 验证服务可用性。
|
||||
- 使用 make dev-logs 查看容器日志，定位启动与运行问题。
|
||||
|
||||
章节来源
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
|
||||
### config.yml 的配置示例与代理配置
|
||||
- 展示默认代理配置（listen_port、default_backend_port、backend_host、port_param）与健康检查参数。
|
||||
- 使用场景示例：
|
||||
- 在本地或生产环境中，根据实际网络与端口策略调整 proxy_config，确保代理请求正确转发。
|
||||
|
||||
章节来源
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [config.yml](file://config.yml#L31-L80)
|
||||
|
||||
### http_test.rest 的 API 测试脚本
|
||||
- 提供 chat、SSE 进度流、取消任务、停止 Agent 等接口的测试用例，支持 REST Client 插件的动态变量。
|
||||
- 使用场景示例：
|
||||
- 在开发阶段，使用 http_test.rest 快速验证聊天、取消与停止等核心流程。
|
||||
- 在回归测试中，复用该脚本进行端到端验证。
|
||||
|
||||
章节来源
|
||||
- [http_test.rest](file://http_test.rest#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L41-L109)
|
||||
|
||||
### crates/docker_manager/README.md 的 Docker 管理模块
|
||||
- 介绍 Docker Manager 的功能特性、核心组件与使用场景，指导如何为项目创建独立运行环境。
|
||||
- 使用场景示例：
|
||||
- 在需要为每个项目创建隔离容器时，参考该文档的配置与最佳实践。
|
||||
|
||||
章节来源
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L60)
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L135-L170)
|
||||
|
||||
## 依赖分析
|
||||
“相关链接”在项目中的依赖关系体现为：README 的“相关链接”作为导航入口，串联起贡献指南、设计文档与许可证；CLAUDE.md 与 Makefile 为开发与部署提供具体命令；docker-compose.yml 与启动脚本负责容器化运行；config.yml 与 http_test.rest 则分别提供配置与测试支撑。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
R["README.md<br/>相关链接"] --> Contrib["CONTRIBUTING.md"]
|
||||
R --> License["LICENSE"]
|
||||
R --> Specs["specs/*"]
|
||||
Specs --> AAL["Agent 抽象层设计"]
|
||||
Specs --> GRPC["gRPC 迁移设计"]
|
||||
Specs --> MDI["多镜像设计"]
|
||||
CL["CLAUDE.md"] --> MK["Makefile"]
|
||||
MK --> DC["docker-compose.yml"]
|
||||
DC --> SH["start-rcoder.sh"]
|
||||
CFG["config.yml"] --> DC
|
||||
HT["http_test.rest"] --> R
|
||||
```
|
||||
|
||||
图表来源
|
||||
- [README.md](file://README.md#L585-L620)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L60)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L40)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L40)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L27-L120)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L20)
|
||||
|
||||
## 性能考量
|
||||
- 文档访问性能优化建议：
|
||||
- 本地文档镜像：在开发机或 CI 机器上维护一份本地文档镜像，减少对外部链接的依赖，提高加载速度与稳定性。
|
||||
- 自动化文档索引：通过脚本定期抓取并生成索引页，便于快速定位设计文档与 API 文档。
|
||||
- 缓存策略：对频繁访问的文档（如 README、设计文档）启用浏览器缓存或静态站点缓存，降低带宽消耗。
|
||||
- 部署与运行性能优化建议：
|
||||
- 使用 Makefile 的开发容器命令进行快速迭代，减少编译与打包时间。
|
||||
- 在 docker-compose.yml 中合理设置资源限制与健康检查，确保容器稳定运行。
|
||||
|
||||
[本节为通用建议，不直接分析具体文件]
|
||||
|
||||
## 故障排除指南
|
||||
- 常见问题与解决方案：
|
||||
- 链接失效：当 README 中的仓库地址或外部文档链接不可用时，优先检查仓库是否迁移或私有化；在内部知识库中同步更新链接。
|
||||
- 文档版本不匹配：设计文档（specs/）与当前实现可能存在差异。建议在 PR 中同步更新相关文档，并在 README 的“更新日志”中标注变更。
|
||||
- 代理配置错误：检查 config.yml 中的 proxy_config，确保 listen_port、default_backend_port 与 backend_host 配置正确。
|
||||
- 容器启动失败：通过 docker-compose.yml 的 healthcheck 与 make dev-logs 查看日志，确认端口冲突、卷挂载权限或镜像拉取问题。
|
||||
- API 测试失败：使用 http_test.rest 的动态变量功能，逐步验证 chat、SSE、取消与停止等流程，定位具体环节的问题。
|
||||
|
||||
章节来源
|
||||
- [README.md](file://README.md#L612-L652)
|
||||
- [config.yml](file://config.yml#L14-L30)
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L24-L30)
|
||||
- [http_test.rest](file://http_test.rest#L1-L40)
|
||||
|
||||
## 结论
|
||||
“相关链接”是开发者从入门到深入实现的重要桥梁。通过 README 的导航、CLAUDE.md 的开发命令、Makefile 的构建流程、docker-compose.yml 的容器化运行以及 config.yml 与 http_test.rest 的配置与测试，开发者可以高效地完成开发、部署与故障排除。建议在团队内部维护本地文档镜像与自动化索引，以提升文档访问效率与一致性。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
- 实际使用场景示例（路径引用）：
|
||||
- 快速定位部署脚本：docker/docker-compose.yml、docker/start-rcoder.sh
|
||||
- 构建工具：Makefile
|
||||
- API 测试：http_test.rest
|
||||
- 设计文档：specs/agent-abstraction-layer-design.md、specs/grpc-migration-design.md、specs/multi-docker-image-design.md
|
||||
- 开发与安装：CLAUDE.md、install.md
|
||||
- 配置参考：config.yml
|
||||
- Docker 管理：crates/docker_manager/README.md
|
||||
|
||||
章节来源
|
||||
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
|
||||
- [docker/start-rcoder.sh](file://docker/start-rcoder.sh#L1-L22)
|
||||
- [Makefile](file://Makefile#L1-L40)
|
||||
- [http_test.rest](file://http_test.rest#L1-L40)
|
||||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L1-L120)
|
||||
- [specs/grpc-migration-design.md](file://specs/grpc-migration-design.md#L1-L60)
|
||||
- [specs/multi-docker-image-design.md](file://specs/multi-docker-image-design.md#L1-L120)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L27-L120)
|
||||
- [install.md](file://install.md#L1-L9)
|
||||
- [config.yml](file://config.yml#L1-L40)
|
||||
- [crates/docker_manager/README.md](file://crates/docker_manager/README.md#L1-L60)
|
||||
216
qiming-rcoder/.qoder/repowiki/zh/content/附录/许可证.md
Normal file
216
qiming-rcoder/.qoder/repowiki/zh/content/附录/许可证.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 许可证
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||||
- [tmp/rust-sdk/LICENSE](file://tmp/rust-sdk/LICENSE)
|
||||
- [tmp/tonic/LICENSE](file://tmp/tonic/LICENSE)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [项目许可证概述](#项目许可证概述)
|
||||
2. [许可证类型详解](#许可证类型详解)
|
||||
3. [用户权利与义务](#用户权利与义务)
|
||||
4. [贡献者指南](#贡献者指南)
|
||||
5. [第三方依赖兼容性分析](#第三方依赖兼容性分析)
|
||||
6. [商业使用与静态链接](#商业使用与静态链接)
|
||||
7. [衍生作品发布](#衍生作品发布)
|
||||
8. [常见问题解答](#常见问题解答)
|
||||
|
||||
## 项目许可证概述
|
||||
|
||||
本项目采用MIT或Apache-2.0双许可证模式，为用户提供灵活的使用选择。项目根目录下的`Cargo.toml`文件明确声明了许可证类型为"MIT OR Apache-2.0"，这一信息也在`README.md`文件中得到确认。这种双许可证策略允许用户根据自身需求选择最适合的许可证条款进行使用、修改和分发。
|
||||
|
||||
项目采用Rust语言开发，基于工作区（workspace）结构组织多个功能模块，包括AI代理适配器、Docker管理器、Pingora代理等组件。每个组件的许可证均继承自工作区配置，确保了整个项目许可证的一致性。尽管项目根目录下未找到独立的LICENSE文件，但通过`Cargo.toml`中的声明和`README.md`的说明，许可证信息已得到充分披露。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
|
||||
## 许可证类型详解
|
||||
|
||||
本项目采用MIT与Apache-2.0双重许可证，用户可选择其中任一许可证的条款来使用本软件。
|
||||
|
||||
MIT许可证是一种宽松的开源许可证，主要要求包括：
|
||||
- 保留原始版权声明和许可声明
|
||||
- 在软件和文档中包含许可证副本
|
||||
- 不提供任何担保，作者不对使用本软件造成的损害负责
|
||||
|
||||
Apache-2.0许可证也是一种宽松的开源许可证，但相比MIT许可证提供了更全面的保护，其主要特点包括：
|
||||
- 明确的专利授权：贡献者自动授予用户必要的专利许可
|
||||
- 详细的归属要求：修改文件必须有显著说明
|
||||
- 专利报复条款：如果用户对项目发起专利诉讼，则其专利许可自动终止
|
||||
- 兼容性良好：与GPLv3等主要开源许可证兼容
|
||||
|
||||
用户可以根据具体使用场景选择最适合的许可证。对于简单的集成和使用，MIT许可证的简洁性更具吸引力；而对于企业级应用和专利敏感的环境，Apache-2.0许可证提供的专利保护更为有利。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
|
||||
## 用户权利与义务
|
||||
|
||||
### 再分发权利
|
||||
用户有权以源代码或编译后的二进制形式再分发本项目，无论是否进行了修改。再分发时必须遵守所选许可证的具体要求：
|
||||
|
||||
对于MIT许可证：
|
||||
- 必须在所有副本或实质性部分中包含原始版权声明和许可声明
|
||||
- 不需要公开修改后的源代码
|
||||
- 可以用于商业目的，无需支付许可费用
|
||||
|
||||
对于Apache-2.0许可证：
|
||||
- 必须在所有副本或实质性部分中包含原始版权声明、专利声明、商标声明和归属声明
|
||||
- 修改的文件必须有显著说明，指出哪些部分被修改
|
||||
- 必须随分发物提供NOTICE文件的副本（如果存在）
|
||||
|
||||
### 修改权利
|
||||
用户有权修改本项目的源代码以满足特定需求。修改后的作品被视为衍生作品，再分发时需要遵守相应的许可证要求。建议在修改文件的头部添加注释，说明修改内容和日期，这虽然不是强制要求，但有助于代码维护和合规性。
|
||||
|
||||
### 专利授权
|
||||
选择Apache-2.0许可证的用户将获得明确的专利授权。每个贡献者都授予用户一项永久的、全球性的、非独占的、免版税的专利许可，用于实施与项目相关的专利权利要求。这一条款为企业用户提供了重要的法律保护，降低了专利侵权风险。
|
||||
|
||||
### 归属要求
|
||||
无论选择哪种许可证，都必须保留原始的版权声明和许可声明。建议在项目的文档或"关于"页面中提及本项目及其许可证信息，这不仅是法律要求，也是对开源社区的尊重。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
|
||||
## 贡献者指南
|
||||
|
||||
### 贡献流程
|
||||
本项目欢迎外部贡献。贡献者应遵循以下流程：
|
||||
1. Fork项目仓库
|
||||
2. 创建特性分支
|
||||
3. 提交更改
|
||||
4. 推送分支
|
||||
5. 创建Pull Request
|
||||
|
||||
贡献者在提交代码时，默认同意其贡献遵循项目的双许可证模式。这意味着贡献者的代码也将以MIT或Apache-2.0许可证发布，用户可以选择其中任一许可证使用。
|
||||
|
||||
### 代码归属
|
||||
贡献者保留其贡献代码的版权，但通过提交贡献，授予项目维护者和其他用户使用、修改和分发其代码的权利。这种模式是开源社区的常规做法，确保了项目的持续发展和广泛使用。
|
||||
|
||||
### 贡献者协议
|
||||
虽然本项目目前没有要求签署正式的贡献者许可协议（CLA），但建议贡献者在首次贡献时明确声明其同意项目的许可证条款。对于重大贡献，项目维护者可能会要求贡献者确认其贡献的许可条款。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L603)
|
||||
|
||||
## 第三方依赖兼容性分析
|
||||
|
||||
### Axum框架兼容性
|
||||
本项目使用Axum作为HTTP框架，Axum本身采用MIT许可证，与本项目的双许可证完全兼容。MIT许可证的宽松性确保了与本项目的无缝集成，用户在使用本项目时无需担心Axum的许可证限制。
|
||||
|
||||
Axum作为Rust生态中流行的Web框架，其MIT许可证允许：
|
||||
- 无限制的商业使用
|
||||
- 私有修改和分发
|
||||
- 与其他许可证的代码静态链接
|
||||
- 无需公开衍生作品的源代码
|
||||
|
||||
### Pingora代理兼容性
|
||||
本项目集成了Pingora作为反向代理，Pingora采用Apache-2.0许可证。由于本项目也提供Apache-2.0许可证选项，两者完全兼容。用户选择Apache-2.0许可证时，可以合法地使用和分发包含Pingora的完整系统。
|
||||
|
||||
Pingora的Apache-2.0许可证提供了：
|
||||
- 明确的专利授权，保护用户免受专利诉讼
|
||||
- 详细的归属要求，确保适当的信用归属
|
||||
- 与本项目相同的许可证选项，简化了合规性管理
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[RCoder项目] --> B[MIT许可证]
|
||||
A --> C[Apache-2.0许可证]
|
||||
B --> D[Axum框架<br>MIT许可证]
|
||||
C --> E[Pingora代理<br>Apache-2.0许可证]
|
||||
D --> F[完全兼容]
|
||||
E --> G[完全兼容]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L60)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml#L22)
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L60)
|
||||
- [crates/pingora-proxy/Cargo.toml](file://crates/pingora-proxy/Cargo.toml)
|
||||
- [README.md](file://README.md#L36)
|
||||
|
||||
## 商业使用与静态链接
|
||||
|
||||
### 商业使用
|
||||
本项目的双许可证模式完全支持商业使用。无论是MIT还是Apache-2.0许可证，都允许将本项目集成到商业产品和服务中，无需支付许可费用或提供源代码。这对于希望利用AI代理功能的企业用户来说是一个重要优势。
|
||||
|
||||
商业用户可以根据自身需求选择合适的许可证：
|
||||
- 选择MIT许可证：适用于希望最小化法律义务的简单集成
|
||||
- 选择Apache-2.0许可证：适用于需要专利保护的企业级应用
|
||||
|
||||
### 静态链接合规性
|
||||
本项目采用Rust语言开发，通常会生成静态链接的二进制文件。两种许可证对静态链接都有明确的规定：
|
||||
|
||||
MIT许可证：完全允许静态链接，无特殊要求，只需保留版权声明和许可声明。
|
||||
|
||||
Apache-2.0许可证：允许静态链接，但要求：
|
||||
- 在文档或"关于"页面中包含NOTICE文件的内容（如果存在）
|
||||
- 对修改的文件进行适当标记
|
||||
- 保留所有原始版权声明
|
||||
|
||||
对于本项目，由于采用工作区结构，所有组件都遵循相同的许可证策略，静态链接后的二进制文件被视为一个整体，只需遵守所选许可证的总体要求即可。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
|
||||
## 衍生作品发布
|
||||
|
||||
当用户基于本项目创建衍生作品时，需要遵守以下准则：
|
||||
|
||||
### 源代码分发
|
||||
如果以源代码形式分发衍生作品，必须：
|
||||
- 包含原始的LICENSE文件或其内容
|
||||
- 在修改的文件中添加适当的修改说明
|
||||
- 保留所有原始版权声明
|
||||
|
||||
### 二进制分发
|
||||
如果以编译后的二进制形式分发衍生作品，必须：
|
||||
- 在文档或"关于"页面中包含原始版权声明和许可声明
|
||||
- 如果选择了Apache-2.0许可证，还需包含NOTICE文件的内容
|
||||
- 提供获取源代码的方式说明（虽然不是强制要求，但推荐）
|
||||
|
||||
### 许可证选择
|
||||
衍生作品的发布者可以选择：
|
||||
- 继续使用MIT或Apache-2.0双许可证模式
|
||||
- 仅选择其中一种许可证
|
||||
- 在Apache-2.0许可证下，还可以选择更宽松的许可证，但不能增加限制
|
||||
|
||||
建议在衍生作品中明确说明其与原始项目的关系，这有助于建立透明的开源生态。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
|
||||
## 常见问题解答
|
||||
|
||||
### 商业使用是否受限？
|
||||
不受限。本项目的双许可证模式完全允许商业使用，无需支付许可费用或提供源代码。
|
||||
|
||||
### 静态链接是否合规？
|
||||
合规。两种许可证都允许静态链接，只需遵守相应的归属要求。
|
||||
|
||||
### 是否需要公开修改后的源代码？
|
||||
不需要。无论是MIT还是Apache-2.0许可证，都不要求公开修改后的源代码。
|
||||
|
||||
### 如何正确归属？
|
||||
在软件和文档中包含原始的版权声明和许可声明。如果选择了Apache-2.0许可证，还需包含NOTICE文件的内容。
|
||||
|
||||
### 可以将许可证更改为其他类型吗？
|
||||
不可以。衍生作品必须遵守原始项目的许可证条款，但可以选择MIT或Apache-2.0中的一种。
|
||||
|
||||
### 专利风险如何？
|
||||
选择Apache-2.0许可证的用户将获得明确的专利授权，大大降低了专利侵权风险。
|
||||
|
||||
**Section sources**
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
- [README.md](file://README.md#L597)
|
||||
153
qiming-rcoder/.qoder/repowiki/zh/content/附录/附录.md
Normal file
153
qiming-rcoder/.qoder/repowiki/zh/content/附录/附录.md
Normal file
@@ -0,0 +1,153 @@
|
||||
# 附录
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [config.yml](file://config.yml)
|
||||
- [CLAUDE.md](file://CLAUDE.md)
|
||||
- [install.md](file://install.md)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs)
|
||||
- [crates/shared_types/src/service_type.rs](file://crates/shared_types/src/service_type.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [相关链接](#相关链接)
|
||||
2. [许可证](#许可证)
|
||||
3. [变更日志](#变更日志)
|
||||
4. [FAQ](#faq)
|
||||
|
||||
## 相关链接
|
||||
|
||||
本项目依赖并关联多个外部资源和文档，以下是关键链接的详细说明：
|
||||
|
||||
- **项目仓库**: [GitHub](https://github.com/your-org/rcoder) - 项目源代码的主仓库，包含所有开发分支和发布版本。
|
||||
- **问题追踪**: [Issues](https://github.com/your-org/rcoder/issues) - 用于报告 bug、提出功能请求和讨论技术问题的平台。
|
||||
- **贡献指南**: [CONTRIBUTING.md](CONTRIBUTING.md) - 详细说明如何为项目贡献代码，包括开发流程、代码风格和提交规范。
|
||||
- **ACP 协议**: [Agent Client Protocol](https://github.com/zed-industries/zed/tree/main/crates/agent_client_protocol) - RCoder 所依赖的 AI 代理通信协议的官方文档。
|
||||
- **Claude Code**: [Anthropic Claude Code](https://docs.anthropic.com/claude/docs) - 集成的 Claude AI 代理的官方文档和 API 参考。
|
||||
- **OpenAI Codex**: [OpenAI Codex Documentation](https://github.com/openai/codex) - 集成的 OpenAI Codex 代理的相关文档。
|
||||
|
||||
这些链接为开发者提供了深入理解项目架构、协议细节和外部依赖的入口。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L585-L593)
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目采用 MIT 或 Apache-2.0 双许可证模式，为使用者提供了灵活的选择。您可以在以下两种许可证中选择一种来遵守：
|
||||
|
||||
- **MIT 许可证**: 允许在任何项目中自由使用、复制、修改、合并、发布、分发、再许可和销售软件的副本，只需在软件和衍生作品中包含原始版权声明和许可声明。
|
||||
- **Apache-2.0 许可证**: 提供了更全面的条款，包括明确的专利授权、商标使用限制和贡献者责任豁免。它还要求在分发源代码或二进制文件时包含 NOTICE 文件。
|
||||
|
||||
这种双许可证策略旨在平衡开源社区的开放性与企业用户的法律确定性。详细的许可证文本可以在项目根目录下的 `LICENSE` 文件中找到。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L595-L597)
|
||||
- [Cargo.toml](file://Cargo.toml#L31)
|
||||
|
||||
## 变更日志
|
||||
|
||||
### v0.1.0 (当前版本)
|
||||
|
||||
#### 新增功能
|
||||
- ✅ 初始版本发布
|
||||
- ✅ 基于 ACP 协议的 AI 代理统一管理
|
||||
- ✅ HTTP API 接口支持
|
||||
- ✅ Claude Code 和 OpenAI Codex 代理集成
|
||||
- ✅ YAML 配置文件支持
|
||||
- ✅ 命令行参数支持
|
||||
- ✅ 多层配置系统（命令行 > 环境变量 > 配置文件 > 默认）
|
||||
- ✅ OpenTelemetry 集成和分布式追踪
|
||||
- ✅ Swagger UI API 文档
|
||||
- ✅ 项目文件解析器 (Nuwax Parser)
|
||||
|
||||
#### 技术特性
|
||||
- ✅ 基于 Rust 2024 Edition
|
||||
- ✅ 异步架构 (Tokio)
|
||||
- ✅ 模块化设计 (Workspace Crates)
|
||||
- ✅ 实时通信 (SSE)
|
||||
- ✅ 结构化日志 (Tracing)
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L627-L649)
|
||||
|
||||
## FAQ
|
||||
|
||||
### 如何配置 AI 代理？
|
||||
|
||||
AI 代理的配置主要通过环境变量完成。对于 Claude Code 代理，需要设置 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_MODEL` 环境变量。例如：
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
|
||||
```
|
||||
对于 OpenAI Codex 代理，需要参考其官方文档进行相应的设置。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L107-L129)
|
||||
|
||||
### 如何解决端口被占用的问题？
|
||||
|
||||
如果遇到端口被占用的情况，可以通过命令行参数 `--port` 指定一个不同的端口。例如：
|
||||
```bash
|
||||
cargo run --bin rcoder -- --port 8087
|
||||
```
|
||||
此外，也可以通过环境变量 `RCODER_PORT` 或在 `config.yml` 配置文件中修改 `port` 字段来更改端口。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L622-L623)
|
||||
- [config.yml](file://config.yml#L11)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L18)
|
||||
|
||||
### 配置系统的优先级是怎样的？
|
||||
|
||||
RCoder 的配置系统遵循一个明确的优先级顺序，从高到低依次为：
|
||||
1. **命令行参数**：最高优先级，直接在启动命令中指定。
|
||||
2. **环境变量**：中等优先级，可以在系统或 shell 中设置。
|
||||
3. **配置文件**：较低优先级，存储在 `config.yml` 文件中。
|
||||
4. **默认配置**：最低优先级，由代码中的默认值提供。
|
||||
|
||||
例如，如果同时在命令行指定了 `--port 8080`，在环境变量中设置了 `RCODER_PORT=9000`，并且在 `config.yml` 中配置了 `port: 3000`，最终生效的端口将是 8080。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L388-L393)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L109-L113)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L274-L294)
|
||||
|
||||
### 如何启用和配置 Pingora 反向代理？
|
||||
|
||||
要启用 Pingora 反向代理，需要在启动命令中添加 `--enable-proxy` 参数，并通过 `--proxy-port` 指定监听端口。例如：
|
||||
```bash
|
||||
cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
|
||||
```
|
||||
您也可以在 `config.yml` 文件中配置 `proxy_config` 部分，包括 `listen_port`、`default_backend_port` 等选项。代理请求应直接发送到 Pingora 的监听端口，路径格式为 `/proxy/{port}/{path}`。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L70-L77)
|
||||
- [config.yml](file://config.yml#L14-L22)
|
||||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs#L9)
|
||||
|
||||
### Docker 容器是如何管理的？
|
||||
|
||||
RCoder 使用 DockerManager 和 ContainerManager 组件来动态创建和管理每个项目的独立 Docker 容器。容器的镜像选择策略支持多镜像配置，可以根据系统架构（ARM64/AMD64）自动选择合适的镜像。相关的配置在 `config.yml` 的 `docker_config` 部分定义，包括镜像仓库、资源限制和网络模式等。
|
||||
|
||||
**Section sources**
|
||||
- [CLAUDE.md](file://CLAUDE.md#L102-L107)
|
||||
- [config.yml](file://config.yml#L31-L161)
|
||||
- [crates/shared_types/src/service_type.rs](file://crates/shared_types/src/service_type.rs#L9)
|
||||
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L12)
|
||||
|
||||
### 如何进行故障排查？
|
||||
|
||||
当遇到问题时，建议按照以下步骤进行排查：
|
||||
1. 查看 `RUST_LOG=debug` 启用的详细日志输出。
|
||||
2. 检查 `README.md` 和 `CLAUDE.md` 中的相关说明。
|
||||
3. 搜索已有的 Issues 看是否已有解决方案。
|
||||
4. 使用 `cargo clippy` 和 `cargo fmt` 检查代码质量和格式。
|
||||
5. 如果问题依然存在，可以创建一个新的 Issue 并提供详细的错误信息和复现步骤。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L611-L626)
|
||||
- [CLAUDE.md](file://CLAUDE.md#L193-L203)
|
||||
497
qiming-rcoder/.qoder/repowiki/zh/content/项目概述.md
Normal file
497
qiming-rcoder/.qoder/repowiki/zh/content/项目概述.md
Normal file
@@ -0,0 +1,497 @@
|
||||
# 项目概述
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [Cargo.toml](file://Cargo.toml)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||||
- [crates/rcoder/src/lib.rs](file://crates/rcoder/src/lib.rs)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs)
|
||||
- [crates/acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs)
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs)
|
||||
- [crates/shared_types/src/model/agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [配置系统](#配置系统)
|
||||
8. [API接口](#api接口)
|
||||
9. [使用示例](#使用示例)
|
||||
10. [故障排除](#故障排除)
|
||||
|
||||
## 简介
|
||||
|
||||
RCoder 是一个基于 Rust 构建的现代化 AI 驱动开发平台，通过 ACP (Agent Client Protocol) 协议实现与多种 AI 代理的统一交互。平台提供简洁的 HTTP API 接口，让开发者能够轻松集成和管理 AI 辅助开发功能。
|
||||
|
||||
RCoder 采用模块化设计，通过 Rust 的 Workspace 特性组织多个功能组件，包括主应用、代理运行器、Docker 管理器、Pingora 反向代理等。平台支持多种 AI 代理，如 Codex 和 Claude Code，并通过反向代理机制实现高性能的端口路由。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L1-L652)
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 项目结构
|
||||
|
||||
RCoder 项目采用 Rust Workspace 结构，将不同功能模块分离到独立的 crate 中，实现高内聚低耦合的设计。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[crates/] --> B[rcoder]
|
||||
A --> C[agent_runner]
|
||||
A --> D[shared_types]
|
||||
A --> E[acp_adapter]
|
||||
A --> F[pingora-proxy]
|
||||
A --> G[docker_manager]
|
||||
A --> H[claude-code-agent]
|
||||
A --> I[codex-acp-agent]
|
||||
B --> J[src/]
|
||||
C --> K[src/]
|
||||
D --> L[src/]
|
||||
E --> M[src/]
|
||||
F --> N[src/]
|
||||
G --> O[src/]
|
||||
J --> P[main.rs]
|
||||
J --> Q[router.rs]
|
||||
J --> R[config.rs]
|
||||
J --> S[handler/]
|
||||
J --> T[service/]
|
||||
K --> U[proxy_agent/]
|
||||
K --> V[service/]
|
||||
L --> W[model/]
|
||||
M --> X[types.rs]
|
||||
N --> Y[server.rs]
|
||||
O --> Z[manager.rs]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [README.md](file://README.md#L269-L377)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L269-L377)
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
|
||||
## 核心组件
|
||||
|
||||
RCoder 的核心组件包括主应用、代理适配器、反向代理和 Docker 管理器。这些组件协同工作，提供完整的 AI 代理管理功能。
|
||||
|
||||
主应用（rcoder）负责处理 HTTP 请求、管理会话状态和协调各个组件。代理适配器（acp_adapter）提供与 ACP 协议兼容的通信功能。反向代理（pingora-proxy）基于 Cloudflare Pingora 实现高性能的端口路由。Docker 管理器（docker_manager）负责容器的生命周期管理。
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L1-L451)
|
||||
- [crates/acp_adapter/src/lib.rs](file://crates/acp_adapter/src/lib.rs#L1-L13)
|
||||
- [crates/pingora-proxy/src/lib.rs](file://crates/pingora-proxy/src/lib.rs#L1-L250)
|
||||
- [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs#L1-L211)
|
||||
|
||||
## 架构概览
|
||||
|
||||
RCoder 采用分层架构设计，各组件职责明确，通过清晰的接口进行通信。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Client] --> B[Axum HTTP Server]
|
||||
A --> C[Pingora Proxy]
|
||||
B --> D[API Routes]
|
||||
B --> E[Agent Worker (LocalSet)]
|
||||
C --> F[Backends: 127.0.0.1:{port}]
|
||||
D --> G[Handler Modules]
|
||||
G --> H[Container Manager]
|
||||
H --> I[Docker Manager]
|
||||
I --> J[Docker Engine]
|
||||
G --> K[Session Cache]
|
||||
G --> L[Config Manager]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [README.md](file://README.md#L18-L25)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L16-L25)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 主应用分析
|
||||
|
||||
主应用是 RCoder 的核心，负责启动服务、处理请求和协调各个组件。
|
||||
|
||||
#### 主函数分析
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([启动 RCoder]) --> InitTelemetry["初始化遥测系统"]
|
||||
InitTelemetry --> ParseArgs["解析命令行参数"]
|
||||
ParseArgs --> LoadConfig["加载配置文件"]
|
||||
LoadConfig --> CreateDir["创建项目目录"]
|
||||
CreateDir --> InitPathResolver["初始化路径解析器"]
|
||||
InitPathResolver --> InitDockerManager["初始化 Docker Manager"]
|
||||
InitDockerManager --> CleanupContainers["清理遗留容器"]
|
||||
CleanupContainers --> StartProxy["启动 Pingora 代理"]
|
||||
StartProxy --> SetupSignal["设置信号处理器"]
|
||||
SetupSignal --> CreateState["创建应用状态"]
|
||||
CreateState --> StartCleanup["启动清理任务"]
|
||||
CreateState --> CreateRouter["创建路由"]
|
||||
CreateRouter --> StartServer["启动 HTTP 服务器"]
|
||||
StartServer --> WaitShutdown["等待关闭信号"]
|
||||
WaitShutdown --> CleanupAll["清理所有容器"]
|
||||
CleanupAll --> End([服务关闭])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L31-L451)
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
|
||||
#### 配置系统分析
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AppConfig {
|
||||
+default_agent : AgentType
|
||||
+projects_dir : PathBuf
|
||||
+port : u16
|
||||
+proxy_config : Option<ProxyConfig>
|
||||
+docker_config : Option<DockerConfig>
|
||||
}
|
||||
class CliArgs {
|
||||
+port : Option<u16>
|
||||
+projects_dir : Option<String>
|
||||
+enable_proxy : bool
|
||||
+proxy_port : Option<u16>
|
||||
+default_backend_port : Option<u16>
|
||||
}
|
||||
class ProxyConfig {
|
||||
+listen_port : u16
|
||||
+default_backend_port : u16
|
||||
+backend_host : String
|
||||
+port_param : String
|
||||
+health_check : HealthCheckConfig
|
||||
}
|
||||
class DockerConfig {
|
||||
+multi_image_config : Option<MultiImageConfig>
|
||||
+network_mode : Option<String>
|
||||
+work_dir : Option<String>
|
||||
+auto_cleanup : Option<bool>
|
||||
+container_ttl_seconds : Option<u64>
|
||||
}
|
||||
class HealthCheckConfig {
|
||||
+enabled : bool
|
||||
+interval_seconds : u64
|
||||
+timeout_seconds : u64
|
||||
+healthy_threshold : u32
|
||||
+unhealthy_threshold : u32
|
||||
}
|
||||
AppConfig --> ProxyConfig : "包含"
|
||||
AppConfig --> DockerConfig : "包含"
|
||||
DockerConfig --> MultiImageConfig : "包含"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L38-L109)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L1-L513)
|
||||
|
||||
### 聊天处理器分析
|
||||
|
||||
聊天处理器负责处理用户发送的聊天消息，并将其转发到相应的 AI 代理。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as "客户端"
|
||||
participant Handler as "ChatHandler"
|
||||
participant Container as "ContainerManager"
|
||||
participant Docker as "DockerManager"
|
||||
participant Agent as "AgentRunner"
|
||||
Client->>Handler : POST /chat
|
||||
Handler->>Container : get_or_create_container()
|
||||
Container->>Docker : create_container()
|
||||
Docker-->>Container : ContainerInfo
|
||||
Container-->>Handler : ContainerInfo
|
||||
Handler->>Agent : 转发聊天请求
|
||||
Agent-->>Handler : 返回响应
|
||||
Handler->>Client : 返回响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L1-L431)
|
||||
- [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs)
|
||||
|
||||
### SSE 通知处理器分析
|
||||
|
||||
SSE 通知处理器负责处理 Server-Sent Events (SSE) 连接，实现实时进度流。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[收到SSE连接请求] --> B{找到对应容器?}
|
||||
B --> |是| C[获取容器SSE端点URL]
|
||||
B --> |否| D[返回404错误]
|
||||
C --> E[建立SSE代理连接]
|
||||
E --> F[转发SSE事件]
|
||||
F --> G[客户端接收实时消息]
|
||||
D --> H[客户端收到错误]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/handler/agent_session_notification.rs](file://crates/rcoder/src/handler/agent_session_notification.rs#L1-L378)
|
||||
- [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
RCoder 项目采用依赖注入和模块化设计，各组件之间的依赖关系清晰。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[rcoder] --> B[shared_types]
|
||||
A --> C[acp_adapter]
|
||||
A --> D[pingora-proxy]
|
||||
A --> E[docker_manager]
|
||||
A --> F[claude-code-agent]
|
||||
B --> G[agent-client-protocol]
|
||||
C --> G
|
||||
D --> H[pingora]
|
||||
E --> I[bollard]
|
||||
F --> J[serde]
|
||||
F --> K[reqwest]
|
||||
A --> L[axum]
|
||||
A --> M[tokio]
|
||||
A --> N[tracing]
|
||||
L --> O[tower]
|
||||
M --> P[futures]
|
||||
N --> Q[tracing-subscriber]
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
|
||||
**本文档引用的文件**
|
||||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L1-L91)
|
||||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml#L1-L79)
|
||||
|
||||
## 配置系统
|
||||
|
||||
RCoder 提供灵活的配置系统，支持多种配置方式，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。
|
||||
|
||||
### 配置优先级
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[命令行参数] --> B[环境变量]
|
||||
B --> C[配置文件]
|
||||
C --> D[默认配置]
|
||||
D --> E[最终配置]
|
||||
```
|
||||
|
||||
### 配置文件结构
|
||||
```yaml
|
||||
# rcoder 配置文件
|
||||
|
||||
# 默认使用的 AI 代理类型
|
||||
# 可选值: "Codex", "Claude"
|
||||
default_agent: Codex
|
||||
|
||||
# 项目工作的根目录
|
||||
projects_dir: "./project_workspace"
|
||||
|
||||
# 服务端口
|
||||
port: 3000
|
||||
|
||||
# 反向代理配置
|
||||
proxy_config:
|
||||
listen_port: 8088
|
||||
default_backend_port: 8086
|
||||
backend_host: "127.0.0.1"
|
||||
port_param: "port"
|
||||
health_check:
|
||||
enabled: true
|
||||
interval_seconds: 5
|
||||
timeout_seconds: 1
|
||||
healthy_threshold: 2
|
||||
unhealthy_threshold: 3
|
||||
|
||||
# Docker 配置
|
||||
docker_config:
|
||||
multi_image_config:
|
||||
services:
|
||||
rcoder:
|
||||
image: null
|
||||
arm64_image: "registry.yichamao.com/rcoder:latest-arm64"
|
||||
amd64_image: "registry.yichamao.com/rcoder:latest-amd64"
|
||||
default_image: "registry.yichamao.com/rcoder:latest"
|
||||
image_tag_prefix: "rcoder"
|
||||
enabled: true
|
||||
environment:
|
||||
RUST_LOG: "info"
|
||||
SERVICE_MODE: "full"
|
||||
API_PORT: "8086"
|
||||
mounts: []
|
||||
command:
|
||||
- "/app/bin/agent_runner"
|
||||
- "--port"
|
||||
- "8086"
|
||||
entrypoint: null
|
||||
resource_limits:
|
||||
memory_limit: 2147483648
|
||||
cpu_limit: 2
|
||||
swap_limit: 4294967296
|
||||
disk_limit: null
|
||||
process_limit: null
|
||||
work_dir: "/app"
|
||||
network_mode: "bridge"
|
||||
container_path_template: "/app/project_workspace/{project_id}"
|
||||
agent-runner:
|
||||
image: null
|
||||
arm64_image: "registry.yichamao.com/rcoder-agent-runner:latest-arm64"
|
||||
amd64_image: "registry.yichamao.com/rcoder-agent-runner:latest-amd64"
|
||||
default_image: "registry.yichamao.com/rcoder-agent-runner:latest"
|
||||
image_tag_prefix: "rcoder-agent-runner"
|
||||
enabled: false
|
||||
environment:
|
||||
RUST_LOG: "debug"
|
||||
SERVICE_MODE: "agent-only"
|
||||
AGENT_PORT: "8086"
|
||||
mounts: []
|
||||
command:
|
||||
- "/app/bin/agent_runner"
|
||||
- "--port"
|
||||
- "8086"
|
||||
entrypoint: null
|
||||
resource_limits:
|
||||
memory_limit: 4294967296
|
||||
cpu_limit: 3
|
||||
swap_limit: 8589934592
|
||||
disk_limit: null
|
||||
process_limit: null
|
||||
work_dir: "/app"
|
||||
network_mode: "bridge"
|
||||
container_path_template: "/app/project_workspace/{project_id}"
|
||||
global_defaults:
|
||||
image: null
|
||||
arm64_image: null
|
||||
amd64_image: null
|
||||
default_image: null
|
||||
registry_prefix: null
|
||||
selection_strategy: ServiceOnly
|
||||
cache_config:
|
||||
enabled: true
|
||||
ttl_seconds: 3600
|
||||
max_entries: 100
|
||||
network_mode: "bridge"
|
||||
work_dir: "/app"
|
||||
auto_cleanup: true
|
||||
container_ttl_seconds: 3600
|
||||
```
|
||||
|
||||
**本文档引用的文件**
|
||||
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L1-L403)
|
||||
- [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml)
|
||||
|
||||
## API接口
|
||||
|
||||
RCoder 提供 RESTful API 接口，支持健康检查、聊天交互、进度流等功能。
|
||||
|
||||
### 核心端点
|
||||
| 端点 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/health` | GET | 健康检查 |
|
||||
| `/chat` | POST | 发送聊天消息给 AI 代理 |
|
||||
| `/agent/progress/{session_id}` | GET (SSE) | 获取统一实时进度流 |
|
||||
| `/agent/session/cancel` | POST | 取消正在执行的任务 |
|
||||
| `/agent/stop` | POST | 停止当前 Agent |
|
||||
| `/agent/status/{project_id}` | GET | 查询 Agent 状态 |
|
||||
| `/api/docs` | GET | Swagger UI API 文档 |
|
||||
|
||||
### Pingora 代理相关端点
|
||||
| 端点 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/proxy/status` | GET | 查看代理服务状态 |
|
||||
| `/proxy/config` | GET | 查看代理配置 |
|
||||
| `/proxy/stats` | GET | 查看代理统计信息 |
|
||||
| `/proxy/{port}/{path}` | GET | 代理到指定端口的服务 |
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L209-L227)
|
||||
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 启动服务
|
||||
```bash
|
||||
# 使用默认端口 3000
|
||||
cargo run --bin rcoder
|
||||
|
||||
# 指定端口和项目目录
|
||||
cargo run --bin rcoder -- --port 8087 --projects-dir ./my-projects
|
||||
|
||||
# 启用并运行 Pingora 反向代理
|
||||
cargo run --bin rcoder -- --enable-proxy --proxy-port 8080
|
||||
|
||||
# 指定默认后端端口
|
||||
cargo run --bin rcoder -- --enable-proxy --proxy-port 8080 --default-backend-port 3000
|
||||
```
|
||||
|
||||
### API 调用示例
|
||||
```bash
|
||||
# 健康检查
|
||||
curl -X GET http://localhost:3000/health
|
||||
|
||||
# 发送聊天消息
|
||||
curl -X POST http://localhost:3000/chat \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"prompt": "你好，请帮我创建一个 Rust Web API 项目",
|
||||
"project_id": "my-rust-project"
|
||||
}'
|
||||
|
||||
# 获取实时进度流
|
||||
curl -X GET http://localhost:3000/agent/progress/your-session-id \
|
||||
-H "Accept: text/event-stream"
|
||||
|
||||
# 代理请求示例
|
||||
curl "http://127.0.0.1:8080/proxy/5173/page/1977625137029189632/prod/"
|
||||
```
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L61-L198)
|
||||
- [http_test.rest](file://http_test.rest)
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
- **端口被占用**: 使用 `--port` 参数指定其他端口
|
||||
- **AI 代理连接失败**: 检查 API 密钥和网络连接
|
||||
- **配置文件错误**: 检查 YAML 格式和字段名称
|
||||
- **容器自检测失败**: 检查 Docker socket 路径和权限
|
||||
|
||||
### Docker 配置帮助
|
||||
```bash
|
||||
# 确保 docker-compose.yml 包含以下配置
|
||||
services:
|
||||
rcoder:
|
||||
environment:
|
||||
- DOCKER_SOCKET_PATH=/var/run/docker.sock
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
- ./data/rcoder/project_workspace:/app/project_workspace
|
||||
```
|
||||
|
||||
**本文档引用的文件**
|
||||
- [README.md](file://README.md#L611-L626)
|
||||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L350)
|
||||
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user