353 lines
13 KiB
Markdown
353 lines
13 KiB
Markdown
# 常见问题解答
|
||
|
||
<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) |