添加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,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)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/反向代理服务.md
@@ -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)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/启用与启动.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/启用与启动.md
@@ -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 服务绑定，代理服务负责端口路由、路径重写、负载均衡与健康检查。遵循本文的配置要点、启动流程与故障排查建议，可稳定启用并维护代理服务。
--- a/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/请求处理与路由.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/请求处理与路由.md
@@ -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)
--- a/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/配置选项.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/反向代理服务/配置选项.md
@@ -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)
+
+[本节为参考性内容，无需列出具体文件来源]