在部署 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需额外执行（在管理员PowerShell中运行）：
wsl --shutdown
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网络配置
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
# 若服务异常，可重启所有Cube组件
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
