添加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,189 @@
+# 常见问题
+
+<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)