# 常见问题

<cite>
**本文档中引用的文件**  
- [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)
</cite>

## 目录
1. [代理启动失败](#代理启动失败)
2. [端口冲突问题](#端口冲突问题)
3. [Docker权限错误](#docker权限错误)
4. [SSE流中断](#sse流中断)
5. [Claude Code代理集成限制](#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路径是否正确挂载

**解决方案**：
```yaml
# config.yml
proxy_config:
  listen_port: 8088           # 确保端口大于0
  default_backend_port: 8087  # 与主服务端口一致
```

**Section sources**
- [server.rs](file://crates/pingora-proxy/src/server.rs#L27-L54)
- [config.rs](file://crates/pingora-proxy/src/config.rs#L50-L68)
- [config.yml](file://config.yml#L16)

## 端口冲突问题

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

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

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

**解决方案**：
```bash
# 修改端口范围
cargo run --bin rcoder -- --port 9000 --proxy-port 9001
```

或在代码中调整端口管理器范围：
```rust
// port_manager.rs
impl PortManager {
    pub fn new() -> Self {
        Self::with_range(10000, 11999) // 扩大端口范围
    }
}
```

**Section sources**
- [port_manager.rs](file://crates/rcoder/src/proxy_agent/port_manager.rs#L32-L49)
- [main.rs](file://crates/rcoder/src/main.rs#L223-L225)

## 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`包含正确配置：
```yaml
services:
  rcoder:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./project_workspace:/app/project_workspace
```

并添加用户到docker组：
```bash
sudo usermod -aG docker $USER
```

**Section sources**
- [main.rs](file://crates/rcoder/src/main.rs#L49-L82)
- [docker-compose.yml](file://docker/docker-compose.yml#L11-L15)

## SSE流中断

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

**根本原因分析**：
- 客户端连接超时设置过短
- 代理配置未正确转发SSE连接
- 服务器资源不足导致连接被重置

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

**解决方案**：
在客户端增加重连机制：
```javascript
const eventSource = new EventSource('/agent/progress/session123');
eventSource.onmessage = (event) => {
    console.log(event.data);
};
eventSource.onerror = () => {
    setTimeout(() => {
        // 重新连接
        eventSource.close();
    }, 5000);
};
```

**Section sources**
- [README.md](file://README.md#L254-L266)

## Claude Code代理集成限制

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

**根本原因分析**：
- CLI工具未正确安装
- API密钥未配置
- 环境变量未正确传递

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

**解决方案**：
1. 安装CLI工具：
```bash
npm install -g @anthropic-ai/claude-code
```

2. 配置环境变量：
```bash
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="claude-3-sonnet-20240229"
```

3. 在`config.yml`中确保代理配置正确：
```yaml
default_agent: "Claude"
```

**规避方法**：
- 使用环境变量而非配置文件存储API密钥
- 实现密钥轮换机制
- 添加代理健康检查

**Section sources**
- [CLAUDE.md](file://CLAUDE.md#L109-L132)
- [install.md](file://install.md#L5-L8)
- [config.yml](file://config.yml#L5)