添加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,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 一致性，又提供了可操作的健康检查与代理监控接口。建议在生产环境中结合日志滚动策略、代理指标与清理任务配置，持续优化性能与稳定性。