添加qiming-rcoder模块

qiming-rcoder/docker/rcoder-agent-runner/TROUBLESHOOTING.md

@@ -0,0 +1,208 @@
+# RCoder Agent Runner 故障排查指南
+
+## 常见问题
+
+### 1. VNC 虚拟桌面文件权限问题
+
+#### 问题描述
+
+在 VNC 虚拟桌面中尝试打开文件时，提示：
+```
+Could not open the file "/home/user/xxx/file.xxx".
+You do not have the permissions necessary to open the file.
+```
+
+#### 根本原因
+
+这是 Docker 容器用户 UID 不匹配导致的权限问题：
+
+1. **宿主机目录挂载**：当宿主机目录挂载到容器的 `/home/user` 时，宿主机文件的 UID 可能与容器内 `user` 用户的 UID（默认 1000）不同
+2. **权限检查失败**：容器内的 `user` 用户无法读取其他 UID 所有者的文件
+3. **VNC 用户权限**：VNC 桌面环境以 `user` 用户身份运行，继承了权限限制
+
+#### 解决方案
+
+##### 方案 A：自动修复（推荐）
+
+从 **v1.x.x** 版本开始，容器启动脚本会自动修复挂载目录的权限问题。
+
+**修复逻辑**（在 `start-up.sh` 中自动执行）：
+```bash
+# 修复整个 /home/user 的所有者
+chown -R user:user /home/user
+
+# 修复目录权限：确保 user 可以读取、写入、执行目录
+find /home/user -type d -exec chmod u+rwx {} \;
+
+# 修复文件权限：确保 user 可以读取和写入文件
+find /home/user -type f -exec chmod u+rw {} \;
+```
+
+**使用新版本镜像**：
+```bash
+# 重新构建镜像
+make dev-build
+
+# 停止旧容器
+make dev-down
+
+# 启动新容器（自动修复权限）
+make dev-up
+```
+
+##### 方案 B：手动修复（临时方案）
+
+如果使用旧版本镜像，可以手动在容器内修复权限：
+
+```bash
+# 1. 查找容器名称
+docker ps | grep rcoder
+
+# 2. 进入容器
+docker exec -it <container_name> bash
+
+# 3. 修复整个 /home/user 目录权限
+chown -R user:user /home/user
+find /home/user -type d -exec chmod u+rwx {} \;
+find /home/user -type f -exec chmod u+rw {} \;
+
+# 4. 退出容器
+exit
+```
+
+**注意**：手动修复后，在 VNC 桌面中需要重新打开文件管理器或应用程序才能生效。
+
+##### 方案 C：宿主机侧修复（不推荐）
+
+在宿主机上修改文件所有者（需要 sudo 权限）：
+
+```bash
+# 查看容器内 user 用户的 UID
+docker exec <container_name> id -u user
+# 输出：1000
+
+# 在宿主机上修改文件所有者为容器内的 UID
+sudo chown -R 1000:1000 /path/to/host/directory
+```
+
+**缺点**：
+- 需要 root 权限
+- 会影响宿主机文件系统
+- 不适合多用户环境
+
+#### 预防措施
+
+**推荐做法**：
+
+1. **使用最新版本镜像**：确保使用包含自动权限修复逻辑的镜像版本
+2. **避免混合 UID**：尽量让宿主机用户的 UID 与容器内 `user` 用户的 UID（1000）保持一致
+3. **使用 Docker Volume**：对于需要持久化的数据，使用 Docker Volume 而不是直接挂载宿主机目录
+
+**Docker Compose 配置示例**：
+```yaml
+services:
+  agent-runner:
+    image: rcoder-agent-runner:latest
+    volumes:
+      # 推荐：使用 Docker Volume
+      - user_home_volume:/home/user
+      
+      # 或者：挂载宿主机目录（会自动修复权限）
+      - ./host-directory:/home/user
+
+volumes:
+  user_home_volume:
+```
+
+#### 技术细节
+
+**为什么会出现 UID 不匹配？**
+
+Docker 容器使用 Linux 内核的命名空间（namespace）隔离，但文件系统的 UID/GID 是全局的：
+
+- **容器内 `user` 用户**：UID = 1000, GID = 1000
+- **宿主机用户**：UID 可能是 1001, 1002, ... 或任意值
+- **挂载目录**：保留宿主机文件的原始 UID/GID
+
+当容器内的进程尝试访问宿主机文件时，Linux 内核检查进程的 UID（1000）是否匹配文件的 UID（如 1001），不匹配则拒绝访问。
+
+**权限位说明**：
+- `u+rwx`：所有者可读（r）、可写（w）、可执行（x）目录
+- `u+rw`：所有者可读（r）、可写（w）文件
+
+### 2. Chromium 浏览器无法打开
+
+#### 问题描述
+VNC 桌面中 Chromium 浏览器无法启动或显示空白页面。
+
+#### 解决方案
+检查 Chromium 数据目录权限（已在启动脚本中自动处理）：
+```bash
+# 容器内执行
+ls -la /home/user/.config/chromium
+```
+
+如果权限不正确，容器会在启动时自动修复。
+
+### 3. 中文输入法无法使用
+
+#### 问题描述
+在 VNC 桌面中无法使用中文输入法（fcitx5）。
+
+#### 解决方案
+1. 检查 fcitx5 进程是否运行：
+   ```bash
+   docker exec <container_name> pgrep fcitx5
+   ```
+
+2. 如果未运行，手动启动：
+   ```bash
+   docker exec -u user <container_name> bash -c "DISPLAY=:0 fcitx5 -d"
+   ```
+
+3. 在 VNC 桌面中使用 `Ctrl+Space` 切换输入法
+
+## 日志和调试
+
+### 查看容器启动日志
+```bash
+# 查看最新日志
+docker logs <container_name>
+
+# 实时查看日志
+docker logs -f <container_name>
+```
+
+### 进入容器调试
+```bash
+# 以 root 用户进入
+docker exec -it <container_name> bash
+
+# 以 user 用户进入
+docker exec -it -u user <container_name> bash
+```
+
+### 检查 VNC 服务状态
+```bash
+# 检查 x11vnc 进程
+docker exec <container_name> pgrep x11vnc
+
+# 检查 noVNC 端口
+docker exec <container_name> netstat -tuln | grep 6080
+```
+
+## 联系支持
+
+如果以上方案无法解决问题，请：
+
+1. 收集以下信息：
+   - 容器版本：`docker inspect <container_name> | grep Image`
+   - 错误日志：`docker logs <container_name>`
+   - 宿主机操作系统和版本
+   
+2. 提交 Issue 到 GitHub 仓库
+
+## 更新记录
+
+- **v1.x.x** (2025-12-19): 添加自动权限修复逻辑
+- **v1.0.0** (初始版本): 基础容器镜像