452 lines
7.0 KiB
Markdown
452 lines
7.0 KiB
Markdown
# 沙箱故障排查指南
|
||
|
||
> **版本**: 1.0.0
|
||
> **更新**: 2026-03-22
|
||
|
||
---
|
||
|
||
## 1. Docker 相关问题
|
||
|
||
### 1.1 Docker 不可用
|
||
|
||
**症状：** `SandboxError: SANDBOX_UNAVAILABLE`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 1. 检查 Docker 是否安装
|
||
docker --version
|
||
|
||
# 2. 检查 Docker 服务状态
|
||
# macOS
|
||
docker status
|
||
# Linux
|
||
sudo systemctl status docker
|
||
|
||
# 3. 检查 Docker 权限
|
||
docker ps
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
| 平台 | 命令 |
|
||
|------|------|
|
||
| macOS | 安装 Docker Desktop 并启动 |
|
||
| Linux | `sudo systemctl start docker` |
|
||
| Windows | 安装 Docker Desktop 并启用 WSL2 |
|
||
|
||
---
|
||
|
||
### 1.2 容器启动失败
|
||
|
||
**症状：** `SandboxError: WORKSPACE_EXISTS` 或容器无法创建
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 1. 检查容器列表
|
||
docker ps -a
|
||
|
||
# 2. 检查 Docker 日志
|
||
docker logs <container-id>
|
||
|
||
# 3. 检查磁盘空间
|
||
docker system df
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 清理未使用的容器和镜像
|
||
docker system prune -a
|
||
|
||
# 增加 Docker 磁盘配额（Docker Desktop -> Settings -> Disk）
|
||
```
|
||
|
||
---
|
||
|
||
### 1.3 容器内命令执行失败
|
||
|
||
**症状：** `SandboxError: EXECUTION_FAILED`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 1. 检查容器是否运行
|
||
docker ps | grep <container-id>
|
||
|
||
# 2. 进入容器调试
|
||
docker exec -it <container-id> /bin/sh
|
||
|
||
# 3. 检查容器资源
|
||
docker stats <container-id>
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Windows WSL 相关问题
|
||
|
||
### 2.1 WSL 未安装
|
||
|
||
**症状：** `SandboxError: SANDBOX_UNAVAILABLE` (Windows)
|
||
|
||
**排查步骤：**
|
||
|
||
```powershell
|
||
# 检查 WSL 状态
|
||
wsl --status
|
||
|
||
# 列出已安装的发行版
|
||
wsl --list --verbose
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```powershell
|
||
# 安装 WSL
|
||
wsl --install -d Ubuntu-22.04
|
||
|
||
# 重启后检查
|
||
wsl --set-default Ubuntu-22.04
|
||
```
|
||
|
||
---
|
||
|
||
### 2.2 WSL 发行版启动失败
|
||
|
||
**症状：** `SandboxError: WORKSPACE_EXISTS`
|
||
|
||
**排查步骤：**
|
||
|
||
```powershell
|
||
# 关闭所有 WSL 实例
|
||
wsl --shutdown
|
||
|
||
# 检查发行版状态
|
||
wsl --list --verbose
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Linux Firejail 相关问题
|
||
|
||
### 3.1 Firejail 未安装
|
||
|
||
**症状：** `SandboxError: SANDBOX_UNAVAILABLE` (Linux)
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查 Firejail
|
||
firejail --version
|
||
|
||
# 安装 Firejail
|
||
# Ubuntu/Debian
|
||
sudo apt install firejail
|
||
|
||
# Fedora
|
||
sudo dnf install firejail
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 Firejail 配置文件错误
|
||
|
||
**症状：** `SandboxError: EXECUTION_FAILED`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查 profile 语法
|
||
firejail --debug-profile=/path/to/profile 2>&1
|
||
|
||
# 测试 profile
|
||
firejail --profile=/path/to/profile /bin/ls
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 权限相关问题
|
||
|
||
### 4.1 权限被拒绝
|
||
|
||
**症状：** `SandboxError: PERMISSION_DENIED`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查工作区目录权限
|
||
ls -la ~/.qimingclaw/workspaces/
|
||
|
||
# 检查用户组
|
||
groups $USER
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 修复目录权限
|
||
chmod -R 755 ~/.qimingclaw/workspaces/
|
||
|
||
# 将用户加入 docker 组
|
||
sudo usermod -aG docker $USER
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 权限请求无响应
|
||
|
||
**症状：** 命令挂起等待权限确认
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查待处理的权限请求
|
||
# 在渲染进程中查看 PendingPermissions 状态
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
- 检查用户是否看到了权限确认弹窗
|
||
- 增加权限请求超时时间
|
||
- 设置自动批准常见操作
|
||
|
||
---
|
||
|
||
## 5. 工作区问题
|
||
|
||
### 5.1 工作区创建失败
|
||
|
||
**症状：** `SandboxError: WORKSPACE_EXISTS`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查工作区目录
|
||
ls -la ~/.qimingclaw/workspaces/
|
||
|
||
# 检查是否有残留进程
|
||
ps aux | grep qimingclaw
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 删除残留目录
|
||
rm -rf ~/.qimingclaw/workspaces/<session-id>
|
||
|
||
# 重启应用
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 工作区磁盘空间不足
|
||
|
||
**症状：** `SandboxError: EXECUTION_FAILED` (disk full)
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查磁盘空间
|
||
df -h ~/.qimingclaw/
|
||
|
||
# 检查工作区大小
|
||
du -sh ~/.qimingclaw/workspaces/*
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 清理临时文件
|
||
rm -rf ~/.qimingclaw/workspaces/*/tmp/*
|
||
|
||
# 增加磁盘限额配置
|
||
# 在 sandbox.json 中设置 maxDiskUsage
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 工作区清理失败
|
||
|
||
**症状：** 退出应用后工作区仍然存在
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查保留策略配置
|
||
cat ~/.qimingclaw/workspaces/<session-id>/sandbox.json
|
||
|
||
# 检查是否有进程占用
|
||
lsof +D ~/.qimingclaw/workspaces/<session-id>
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 性能问题
|
||
|
||
### 6.1 沙箱启动慢
|
||
|
||
**症状：** 首次创建沙箱需要很长时间
|
||
|
||
**原因：** Docker 镜像下载、WSL 初始化等
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 预热：提前拉取镜像
|
||
docker pull node:20-slim
|
||
|
||
# WSL 预初始化
|
||
wsl -d Ubuntu-22.04
|
||
```
|
||
|
||
---
|
||
|
||
### 6.2 命令执行超时
|
||
|
||
**症状：** `SandboxError: EXECUTION_TIMEOUT`
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查命令复杂度
|
||
# 增加超时时间
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```typescript
|
||
// 增加默认超时
|
||
const executeOptions: ExecuteOptions = {
|
||
timeout: 600000, // 10 分钟
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 网络问题
|
||
|
||
### 7.1 沙箱内无法访问网络
|
||
|
||
**症状：** `npm install` 失败
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查 Docker 网络
|
||
docker network ls
|
||
|
||
# 测试网络连通性
|
||
docker exec <container-id> ping 8.8.8.8
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```typescript
|
||
// 在配置中启用网络
|
||
const config: SandboxConfig = {
|
||
networkEnabled: true,
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 跨平台路径问题
|
||
|
||
### 8.1 Windows 路径错误
|
||
|
||
**症状：** 文件找不到
|
||
|
||
**排查步骤：**
|
||
|
||
```bash
|
||
# 检查路径格式
|
||
echo $PATH
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```typescript
|
||
// 使用 path 模块
|
||
import path from 'path';
|
||
|
||
const sandboxPath = path.join(workspacePath, 'projects');
|
||
// 避免手动拼接字符串
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 日志获取
|
||
|
||
### 9.1 主进程日志
|
||
|
||
```bash
|
||
# 查看主进程日志
|
||
tail -f ~/.qimingclaw/logs/main.$(date +%Y-%m-%d).log
|
||
```
|
||
|
||
### 9.2 Docker 容器日志
|
||
|
||
```bash
|
||
# 查看容器日志
|
||
docker logs <container-id>
|
||
|
||
# 实时跟踪
|
||
docker logs -f <container-id>
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 常见错误代码
|
||
|
||
| 错误代码 | 说明 | 解决方案 |
|
||
|---------|------|---------|
|
||
| `SANDBOX_UNAVAILABLE` | 沙箱不可用 | 检查 Docker/WSL/Firejail 安装 |
|
||
| `WORKSPACE_NOT_FOUND` | 工作区不存在 | 创建工作区或检查 ID |
|
||
| `WORKSPACE_EXISTS` | 工作区已存在 | 销毁现有工作区 |
|
||
| `PERMISSION_DENIED` | 权限不足 | 检查权限配置或用户确认 |
|
||
| `EXECUTION_FAILED` | 执行失败 | 查看详细日志 |
|
||
| `EXECUTION_TIMEOUT` | 执行超时 | 增加超时或优化命令 |
|
||
| `FILE_NOT_FOUND` | 文件不存在 | 检查路径 |
|
||
| `FILE_WRITE_FAILED` | 文件写入失败 | 检查磁盘空间和权限 |
|
||
| `CLEANUP_FAILED` | 清理失败 | 手动清理或检查进程 |
|
||
| `CONFIG_INVALID` | 配置无效 | 检查配置参数 |
|
||
|
||
---
|
||
|
||
## 11. 获取帮助
|
||
|
||
### 11.1 收集诊断信息
|
||
|
||
```bash
|
||
# 1. 系统信息
|
||
uname -a
|
||
|
||
# 2. Docker 信息
|
||
docker version
|
||
docker info
|
||
|
||
# 3. 应用日志
|
||
tar -czf diagnostics.tar.gz ~/.qimingclaw/logs/
|
||
|
||
# 4. 配置文件
|
||
cat ~/.qimingclaw/config.json
|
||
```
|
||
|
||
### 11.2 报告问题
|
||
|
||
报告问题时请包含：
|
||
- 操作系统版本
|
||
- Docker/WSL/Firejail 版本
|
||
- 错误日志
|
||
- 复现步骤
|
||
- 预期行为
|
||
|
||
---
|
||
|
||
## 12. 变更记录
|
||
|
||
| 日期 | 版本 | 变更 |
|
||
|------|------|------|
|
||
| 2026-03-22 | 1.0.0 | 初始版本 |
|