189 lines
5.2 KiB
Markdown
189 lines
5.2 KiB
Markdown
# 常见问题
|
||
|
||
<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) |