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不支持嵌套
• 解决

  1. BIOS/UEFI开启 Intel VT-x / AMD-V

  2. WSL 2开启嵌套（Windows 11 22H2+）：

     # 管理员PowerShell
     wsl --shutdown
     Set-VMProcessor -VMName <WSL分发版名> -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 超时

• 原因：镜像拉取失败、磁盘空间不足、端口冲突

• 解决

  # 检查磁盘（至少10G）
  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. 沙箱启动后无法访问/端口不通

• 解决

  # 关闭防火墙/放行端口
  sudo systemctl stop firewalld
  sudo iptables -F
  # 检查NAT与转发
  sudo sysctl -w net.ipv4.ip_forward=1

---

四、WSL专属问题

1. WSL内存/资源不足

• 解决 ：调整 .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
# 重启所有服务
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