209 lines
5.4 KiB
Markdown
209 lines
5.4 KiB
Markdown
# 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** (初始版本): 基础容器镜像
|