qiming/qiming-rcoder/.qoder/repowiki/zh/content/故障排除/常见问题.md

常见问题

**本文档中引用的文件** - [README.md](file://README.md) - [config.yml](file://config.yml) - [docker-compose.yml](file://docker/docker-compose.yml) - [main.rs](file://crates/rcoder/src/main.rs) - [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs) - [port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs) - [server.rs](file://crates/pingora-proxy/src/server.rs) - [config.rs](file://crates/pingora-proxy/src/config.rs) - [CLAUDE.md](file://CLAUDE.md) - [install.md](file://install.md)

目录

1. 代理启动失败
2. 端口冲突问题
3. Docker权限错误
4. SSE流中断
5. Claude Code代理集成限制

代理启动失败

代理启动失败通常由配置错误或依赖服务未就绪导致。根据crates/pingora-proxy/src/server.rs中的实现，代理服务在启动时会进行配置验证。

根本原因分析：

• 配置文件config.yml中proxy_config.listen_port设置为0或无效值
• 环境变量RCODER_PORT与代理端口冲突
• Docker socket未正确挂载，导致容器无法通信

调试步骤：

1. 检查日志中是否出现"配置验证失败"错误
2. 验证config.yml中proxy_config.listen_port是否为有效端口
3. 确认Docker socket路径是否正确挂载

解决方案：

# config.yml
proxy_config:
  listen_port: 8088           # 确保端口大于0
  default_backend_port: 8087  # 与主服务端口一致

Section sources

• server.rs
• config.rs
• config.yml

端口冲突问题

端口冲突主要发生在多个服务尝试绑定同一端口时。系统通过port_manager.rs管理端口分配。

根本原因分析：

• 多个RCoder实例同时运行
• 端口范围(8000-9999)内所有端口已被占用
• 容器未正确清理，遗留端口映射

调试步骤：

1. 检查netstat -an | grep <port>确认端口占用情况
2. 查看日志中"端口范围内无可用端口"错误
3. 使用docker ps检查是否有遗留容器

解决方案：

# 修改端口范围
cargo run --bin rcoder -- --port 9000 --proxy-port 9001

或在代码中调整端口管理器范围：

// port_manager.rs
impl PortManager {
    pub fn new() -> Self {
        Self::with_range(10000, 11999) // 扩大端口范围
    }
}

Section sources

• port_manager.rs
• main.rs

Docker权限错误

Docker权限错误通常与socket访问权限或挂载配置有关。

根本原因分析：

• Docker socket未挂载到容器
• 用户不在docker组中
• 路径解析器初始化失败

调试步骤：

1. 检查docker-compose.yml中socket挂载配置
2. 验证用户权限：groups $USER | grep docker
3. 测试Docker API连通性：curl --unix-socket /var/run/docker.sock http://localhost/info

解决方案： 确保docker-compose.yml包含正确配置：

services:
  rcoder:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./project_workspace:/app/project_workspace

并添加用户到docker组：

sudo usermod -aG docker $USER

Section sources

• main.rs
• docker-compose.yml

SSE流中断

SSE（Server-Sent Events）流中断会影响实时进度更新功能。

根本原因分析：

• 客户端连接超时设置过短
• 代理配置未正确转发SSE连接
• 服务器资源不足导致连接被重置

调试步骤：

1. 检查客户端是否设置Connection: keep-alive
2. 验证Nginx等反向代理的超时配置
3. 监控服务器资源使用情况

解决方案： 在客户端增加重连机制：

const eventSource = new EventSource('/agent/progress/session123');
eventSource.onmessage = (event) => {
    console.log(event.data);
};
eventSource.onerror = () => {
    setTimeout(() => {
        // 重新连接
        eventSource.close();
    }, 5000);
};

Section sources

• README.md

Claude Code代理集成限制

Claude Code代理集成存在特定限制和配置要求。

根本原因分析：

• CLI工具未正确安装
• API密钥未配置
• 环境变量未正确传递

调试步骤：

1. 验证Claude CLI安装：claude --version
2. 检查环境变量：echo $ANTHROPIC_API_KEY
3. 查看日志中代理初始化错误

解决方案：

1. 安装CLI工具：

npm install -g @anthropic-ai/claude-code

2. 配置环境变量：

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"

3. 在config.yml中确保代理配置正确：

default_agent: "Claude"

规避方法：

• 使用环境变量而非配置文件存储API密钥
• 实现密钥轮换机制
• 添加代理健康检查

Section sources

• CLAUDE.md
• install.md
• config.yml