添加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,353 @@
+# 常见问题解答
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [CLAUDE.md](file://CLAUDE.md)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+- [config.yml](file://config.yml)
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs)
+- [service.rs](file://crates/pingora-proxy/src/service.rs)
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs)
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs)
+- [app_error.rs](file://crates/shared_types/src/model/app_error.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本FAQ面向初学者与专家用户，围绕安装配置、AI代理集成、反向代理路由、SSE进度流中断等高频问题，结合代码库中的实际实现，提供现象、根因、解决方案与预防措施，并给出可复现的排查步骤与日志分析技巧。文档同时整合跨组件问题（如配置优先级冲突导致的行为异常），帮助快速定位与修复。
+
+## 项目结构
+- 主应用（Axum）负责业务API、会话管理与SSE进度流
+- Pingora代理独立监听端口，按路径前缀“/proxy/{port}/{path}”转发到指定后端
+- 两者并行运行，互不阻塞；Axum中的“/proxy/...”路由仅作文档与重定向到Pingora
+
+```mermaid
+graph TB
+A["客户端"] --> B["Axum 主服务"]
+A --> C["Pingora 反向代理"]
+B --> D["API 路由"]
+B --> E["Agent 工作者(LocalSet)"]
+C --> F["后端: 127.0.0.1:{port}"]
+```
+
+图表来源
+- [README.md](file://README.md#L16-L30)
+
+章节来源
+- [README.md](file://README.md#L16-L30)
+
+## 核心组件
+- 配置系统：命令行 > 环境变量 > 配置文件 > 默认值，优先级明确
+- 反向代理：Pingora提供端口路由、路径重写、指标统计与健康检查
+- 观测性：Tracing + OpenTelemetry，统一注入trace_id，便于跨服务串联
+- 容器化：DockerManager动态创建容器，内部网络通信，自动路径解析与挂载
+- SSE：统一的实时进度流接口，便于前端消费
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [config.yml](file://config.yml#L1-L30)
+
+## 架构总览
+- 主服务与代理并行：Axum提供REST API与SSE；Pingora独立监听代理端口
+- 代理请求必须发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
+- 代理模式下不支持查询参数提取端口（遵循“代理端口提取规则”）
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Axum as "Axum 主服务"
+participant Proxy as "Pingora 代理"
+participant Backend as "后端服务(127.0.0.1 : {port})"
+Client->>Axum : "GET /proxy/status" (文档/状态)
+Axum-->>Client : "307 重定向到 Pingora 端口"
+Client->>Proxy : "GET /proxy/{port}/{path}" (直接请求代理端口)
+Proxy->>Proxy : "提取端口/重写路径"
+Proxy->>Backend : "转发请求"
+Backend-->>Proxy : "响应"
+Proxy-->>Client : "返回响应"
+```
+
+图表来源
+- [README.md](file://README.md#L133-L206)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L253-L354)
+
+章节来源
+- [README.md](file://README.md#L133-L206)
+
+## 详细组件分析
+
+### 反向代理路由失败
+- 现象
+  - 请求误发到Axum主服务端口的“/proxy/...”路由，收到307重定向
+  - 收到JSON演示响应而非真实转发
+  - 端口提取失败（路径非“/proxy/{port}/{path}”或端口非法）
+- 根因
+  - 代理模式仅支持路径前缀提取端口，不解析查询参数
+  - 未指定目标后端端口或端口不可达
+- 解决方案
+  - 直接请求Pingora监听端口，路径格式为“/proxy/{port}/{path}”
+  - 确认目标后端服务已在本机启动且端口有效
+- 预防措施
+  - 在客户端或网关层统一走Pingora端口
+  - 使用代理状态/配置/统计接口辅助排障
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> CheckPort["检查路径是否为 /proxy/{port}/{path}"]
+CheckPort --> ValidPort{"端口是否为有效数字?"}
+ValidPort --> |否| FixPath["修正路径格式为 /proxy/{port}/{path}"]
+ValidPort --> |是| BackendUp{"目标后端(127.0.0.1:{port}) 是否启动?"}
+BackendUp --> |否| StartBackend["启动后端服务"]
+BackendUp --> |是| Forward["转发到后端"]
+FixPath --> End(["结束"])
+StartBackend --> End
+Forward --> End
+```
+
+图表来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+
+章节来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+
+### SSE进度流中断
+- 现象
+  - 客户端SSE连接断开，无法持续接收进度事件
+- 根因
+  - 代理层或上游服务超时、连接中断、NAT/防火墙丢弃空闲连接
+  - 客户端未正确处理长连接或网络波动
+- 解决方案
+  - 保持客户端长连接，合理设置心跳与重连策略
+  - 在代理层开启健康检查与负载均衡，避免后端不稳定导致中断
+- 预防措施
+  - 使用代理统计接口观察活跃连接数与失败率
+  - 在主服务侧确保SSE通道稳定，避免阻塞
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+### Docker权限问题
+- 现象
+  - 容器创建失败、镜像拉取失败、无法获取容器日志
+- 根因
+  - Docker socket权限不足或未挂载
+  - 容器内无法访问宿主机路径映射
+- 解决方案
+  - 确保Docker socket挂载到容器并具备读写权限
+  - 在compose中设置正确的环境变量（如DOCKER_SOCKET_PATH）
+  - 使用容器自检测器进行socket连通性与容器ID解析验证
+- 预防措施
+  - 启动时先验证Docker连接，再执行容器操作
+  - 在CI/本地开发环境统一挂载策略
+
+```mermaid
+sequenceDiagram
+participant Dev as "开发者"
+participant Compose as "Docker Compose"
+participant RC as "RCoder 容器"
+participant Inspect as "ContainerSelfInspector"
+Dev->>Compose : "启动服务"
+Compose->>RC : "挂载 /var/run/docker.sock"
+RC->>Inspect : "初始化并验证Docker连接"
+Inspect-->>RC : "连接成功/失败"
+RC-->>Dev : "日志输出(成功/失败)"
+```
+
+图表来源
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+
+章节来源
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+
+### AI代理集成（Claude Code代理无法启动）
+- 现象
+  - Claude Code代理启动失败或无法连接
+- 根因
+  - Claude Code CLI未安装或环境变量未配置
+  - 容器内网络隔离导致外部服务不可达
+  - 容器内路径解析失败，挂载映射不正确
+- 解决方案
+  - 安装并配置Claude Code CLI，设置API密钥与模型
+  - 使用内部网络通信，避免宿主机端口映射带来的复杂性
+  - 通过容器自检测器校验挂载点与宿主机路径映射
+- 预防措施
+  - 在配置文件中明确镜像与资源限制
+  - 启动后检查容器健康状态与日志
+
+章节来源
+- [CLAUDE.md](file://CLAUDE.md#L116-L133)
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L132-L242)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
+
+### 配置优先级冲突导致的行为异常
+- 现象
+  - 端口、代理监听端口、默认后端端口与期望不一致
+  - 环境变量覆盖配置文件但被命令行参数再次覆盖
+- 根因
+  - 配置来源优先级顺序：命令行 > 环境变量 > 配置文件 > 默认值
+- 解决方案
+  - 明确各层配置来源，必要时显式指定命令行参数
+  - 在启动脚本中统一设置环境变量，避免遗漏
+- 预防措施
+  - 在CI/本地开发环境固化配置来源，减少歧义
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+- [config.yml](file://config.yml#L1-L30)
+
+## 依赖关系分析
+- 配置来源与优先级
+  - 命令行参数最高优先级，环境变量次之，配置文件再次之，最后为默认值
+- 代理与后端
+  - Pingora代理负责端口提取与路径重写，后端映射动态维护
+- 观测性
+  - Tracing中间件统一注入trace_id，便于跨服务日志关联
+
+```mermaid
+graph LR
+CLI["命令行参数"] --> Prio["配置优先级"]
+ENV["环境变量"] --> Prio
+CFG["配置文件"] --> Prio
+DEF["默认值"] --> Prio
+Prio --> AX["Axum 主服务"]
+Prio --> PRX["Pingora 代理"]
+```
+
+图表来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+
+章节来源
+- [README.md](file://README.md#L386-L439)
+- [CLAUDE.md](file://CLAUDE.md#L108-L114)
+
+## 性能考量
+- 代理层指标
+  - 总请求数、成功率、平均响应时间、按端口统计、活跃连接数
+- 负载均衡
+  - 支持轮询与健康检查，定期探测后端可达性
+- 容器化
+  - 内部网络通信，避免端口映射带来的额外开销
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+## 故障排查指南
+
+### 通过tracing_middleware日志定位请求失败原因
+- 步骤
+  - 启用详细日志：设置RUST_LOG为debug或指定模块
+  - 观察请求进入与退出日志，定位trace_id
+  - 在Axum中间件层记录请求开始/结束与状态码
+- 建议
+  - 在客户端携带trace_id或x-request-id，便于跨服务串联
+  - 使用代理统计接口查看失败率与平均响应时间
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Axum as "Axum 中间件"
+participant Handler as "业务处理器"
+Client->>Axum : "请求(携带trace_id)"
+Axum->>Axum : "记录请求开始"
+Axum->>Handler : "处理请求"
+Handler-->>Axum : "返回响应"
+Axum->>Axum : "记录响应状态"
+Axum-->>Client : "响应"
+```
+
+图表来源
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
+
+章节来源
+- [tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs#L71-L130)
+
+### 通过container_self_inspector诊断容器状态
+- 步骤
+  - 初始化ContainerSelfInspector，验证Docker socket连接
+  - 获取当前容器ID与挂载信息，核对容器内路径到宿主机路径映射
+  - 若未找到挂载信息，列出所有挂载点辅助定位
+- 建议
+  - 在容器启动脚本中先验证Docker连接与挂载权限
+  - 使用compose挂载/var/run/docker.sock并设置环境变量
+
+章节来源
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L258-L269)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L63-L136)
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+
+### 代理端口提取失败排查
+- 步骤
+  - 确认请求路径为“/proxy/{port}/{path}”，端口为有效数字
+  - 如未指定端口，确认默认后端端口配置
+  - 使用代理状态/配置/统计接口查看后端映射与健康状态
+- 建议
+  - 在客户端统一走Pingora端口，避免误发到Axum主服务端口
+
+章节来源
+- [README.md](file://README.md#L168-L198)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L357-L399)
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L63-L118)
+
+### SSE进度流中断排查
+- 步骤
+  - 检查代理统计接口，关注活跃连接数与失败率
+  - 确认上游服务健康状态与响应时间
+  - 在客户端侧增加重连与心跳机制
+- 建议
+  - 使用代理健康检查循环，定期探测后端可达性
+
+章节来源
+- [proxy_api.rs](file://crates/rcoder/src/handler/proxy_api.rs#L119-L156)
+- [service.rs](file://crates/pingora-proxy/src/service.rs#L582-L596)
+
+### 容器内路径解析失败
+- 步骤
+  - 使用容器自检测器检测容器ID与挂载点
+  - 核对容器内路径到宿主机路径映射是否正确
+  - 在配置文件中明确挂载路径并进行变量替换
+- 建议
+  - 在启动脚本中统一挂载策略，避免相对路径与容器内绝对路径混淆
+
+章节来源
+- [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs#L244-L295)
+- [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs#L138-L166)
+
+## 结论
+- 代理请求必须直接发送到Pingora监听端口，路径前缀“/proxy/{port}/{path}”
+- 配置优先级清晰，命令行最高，环境变量次之，配置文件再次之
+- 观测性与容器化能力完善，建议结合Tracing与代理统计进行问题定位
+- Docker权限与路径解析是容器化部署的关键，务必在启动阶段验证
+
+## 附录
+- 常用命令与接口
+  - 健康检查：/health
+  - 代理状态：/proxy/status
+  - 代理配置：/proxy/config
+  - 代理统计：/proxy/stats
+  - 实时进度流：/agent/progress/{session_id}
+
+章节来源
+- [README.md](file://README.md#L209-L268)