添加qiming-rcoder模块

2026-06-01 13:54:52 +08:00
parent 8092c4b1f8
commit 4b1a580132
539 changed files with 151650 additions and 0 deletions
--- a/qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/清理任务.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/核心模块架构/代理运行器架构/清理任务.md
@@ -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)