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需额外执行（在管理员PowerShell中运行）：

wsl --shutdown

2. 报错：/dev/kvm not found（常见于WSL或云VM）

• 原因：未开启CPU虚拟化、WSL嵌套虚拟化未启用、云VM不支持嵌套

• 解决

1. BIOS/UEFI中开启 Intel VT-x 或 AMD-V
2. WSL 2开启嵌套（需Windows 11 22H2及以上）：
   # 管理员PowerShell中执行
wsl --shutdown
Set-VMProcessor -VMName -ExposeVirtualizationExtensions $true
3. 云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/

六、部署前快速自检清单

1. ✅ 操作系统：x86_64 架构，CentOS 7 / Ubuntu 20.04 / OpenCloudOS 9
2. ✅ 内核版本：uname -r 结果 ≥ 5.4
3. ✅ KVM 设备：ls -l /dev/kvm 存在且当前用户属于 kvm 组
4. ✅ 可用内存：≥ 4GB（推荐8GB以上）
5. ✅ 网络配置：关闭防火墙、开启 IP 转发
6. ✅ 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