Cube Sandbox部署问题全解析与高效解决方案
在部署 Cube Sandbox 时，环境差异引发的故障集中在 KVM 虚拟化、网络配置、镜像源、权限、WSL 嵌套以及组件崩溃六大领域。以下直接列出典型报错与实战解法，按需检索即可，无需反复查阅文档。
一、环境与KVM虚拟化问题（高频故障）
1. 报错：Could not access KVM kernel module: Permission denied
• 原因：当前用户缺少 /dev/kvm 设备访问权限
• 修复方案
# 将用户加入kvm组
sudo usermod -aG kvm $USER
# 重启WSL或系统后生效
groups $USER
# 确认输出中包含kvm
WSL环境需额外执行：
wsl --shutdown
# 在管理员PowerShell中运行
2. 报错：/dev/kvm not found（WSL/云VM）
• 原因：CPU虚拟化未开启、WSL嵌套虚拟化未启用、云VM不支持嵌套虚拟化
• 修复方案
- BIOS/UEFI中启用 Intel VT-x 或 AMD-V
- WSL 2 开启嵌套（Windows 11 22H2 及以上）：
# 管理员PowerShell
wsl --shutdown
Set-VMProcessor -VMName-ExposeVirtualizationExtensions $true - 云VM：更换支持嵌套虚拟化的实例类型（如裸金属、PVM内核）
3. 报错：ERROR: Unsupported distribution 'opencloudos'
• 原因：部署脚本未识别当前操作系统
• 修复方案（临时伪装为CentOS）
sudo cp /etc/os-release /etc/os-release.bak
sudo tee /etc/os-release <<'EOF'
NAME="CentOS Linux"
VERSION="7 (Core)"
ID="centos"
ID_LIKE="rhel fedora"
VERSION_ID="7"
PRETTY_NAME="CentOS Linux 7 (Core)"
EOF
# 安装完成后恢复原始文件
二、安装/镜像源/网络问题
1. 报错：Alpine 3.17 EOL / 404 Not Found
• 原因：Alpine 3.17 已停止维护，镜像源不可用
• 修复方案
# 修改prepare_image.sh，升级至Alpine 3.19
sed -i 's/ALPINE_VERSION=3.17/ALPINE_VERSION=3.19/g' prepare_image.sh
# 或指定国内镜像源
export ALPINE_MIRROR_URL=https://mirrors.aliyun.com/alpine/
2. 在线安装缓慢或失败（国内环境）
• 修复方案：强制使用国内镜像源
curl -sL https://cnb.cool/cube-sandbox/online-install.sh | MIRROR=cn bash
3. 网络组件崩溃：network-agent panic: nil pointer dereference
• 日志位置：/var/log/cube-sandbox-one-click/network-agent.log
• 修复方案
# 重启网络组件
sudo systemctl restart cube-network-agent
# 或重新安装
sudo /usr/local/services/cubetoolbox/scripts/one-click/up.sh
三、沙箱创建/启动失败
1. 报错：template not ready 或 create-from-image 超时
• 原因：镜像拉取失败、磁盘空间不足、端口被占用
• 修复方案
# 检查磁盘剩余空间（至少10GB）
df -h
# 清理无用镜像
cubemastercli image prune
# 重新创建模板
cubemastercli tpl create-from-image --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest --writable-layer-size 1G --expose-port 49999 --probe 49999
2. 沙箱启动后无法访问或端口不通
• 修复方案
# 关闭防火墙并清空iptables规则
sudo systemctl stop firewalld
sudo iptables -F
# 启用IP转发
sudo sysctl -w net.ipv4.ip_forward=1
四、WSL专属问题
1. WSL内存或CPU资源不足
• 修复方案：调整 .wslconfig 配置文件
[wsl2]
memory=8GB
processors=4
swap=8GB
文件路径：C:\Users\<你的用户名>\.wslconfig
2. WSL与Windows网络冲突
• 修复方案
# 重置WSL DNS配置
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
五、服务与日志排查（通用方法）
1. 核心服务状态检查
sudo systemctl status cube-master cube-node cube-network-agent
# 重启所有相关服务
sudo systemctl restart cube-*
2. 关键日志存放路径
- 主服务日志：
/var/log/cube-sandbox-one-click/*.log - 网络组件日志：
/var/log/cube-sandbox-one-click/network-agent.log - 沙箱运行日志：
/var/lib/cube-sandbox/logs/
六、快速自检清单（部署前务必执行）
- ✅ 系统架构：x86_64、CentOS 7 /Ubuntu 20.04 /OpenCloudOS 9
- ✅ 内核版本：
uname -r≥ 5.4 - ✅ KVM设备：
ls -l /dev/kvm存在且用户属于kvm组 - ✅ 可用内存：≥ 4GB（推荐8GB）
- ✅ 网络配置：关闭防火墙，开启IP转发
- ✅ WSL环境：Windows 11 22H2 以上，嵌套虚拟化已启用
七、依然失败？尝试升级或重装
# 卸载旧版本
sudo /usr/local/services/cubetoolbox/scripts/one-click/uninstall.sh
# 重新安装（使用国内源）
curl -sL https://cnb.cool/cube-sandbox/online-install.sh | MIRROR=cn bash