Windows WSL 安装 CubeSandbox 沙箱完整指南

第一部分：环境准备

1.1 启用 WSL 2 和虚拟化功能

以管理员身份打开 PowerShell，执行：

# 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑
Restart-Computer

1.2 设置 WSL 2 为默认版本

重启后，以管理员身份打开 PowerShell：

wsl --set-default-version 2

1.3 安装 Ubuntu 20.04 LTS

# 查看可用的 Linux 发行版
wsl --list --online

# 安装 Ubuntu 20.04 LTS（推荐，稳定性好）
wsl --install -d Ubuntu-20.04

安装过程中会提示创建用户名和密码。记好这个用户名和密码。

1.4 将 Ubuntu 20.04 设为默认发行版

# 查看当前所有发行版
wsl --list --verbose

# 设置 Ubuntu-20.04 为默认
wsl --set-default Ubuntu-20.04

之后直接输入 wsl 就会进入 Ubuntu 20.04 环境。

1.5 进入 WSL 并更新系统

# 进入 WSL
wsl

# 更新软件包
sudo apt update && sudo apt upgrade -y

第二部分：安装 CubeSandbox 依赖

2.1 安装基础工具

sudo apt install -y wget curl qemu-utils qemu-system-x86 ripgrep

2.2 克隆 CubeSandbox 仓库

cd ~
git clone https://github.com/CubeSandbox/CubeSandbox.git
cd CubeSandbox/dev-env

注意：如果因为网络问题无法克隆，可以直接从 Windows 下载后复制到 WSL。

2.3 修复脚本换行符问题

从 Windows 复制过来的脚本可能包含 CRLF 换行符，需要转换：

# 安装 dos2unix
sudo apt install dos2unix -y

# 转换所有 .sh 脚本
dos2unix *.sh

# 赋予执行权限
chmod +x *.sh

2.4 准备虚拟机镜像

# 运行镜像准备脚本（会自动下载约 400MB 的 OpenCloudOS 镜像）
bash prepare_image.sh

成功后会显示：

[prepare_image][OK] Image preparation finished
[prepare_image][INFO]   Image path: /home/用户名/CubeSandbox/dev-env/.workdir/OpenCloudOS-GenericCloud-9.4-20251120.0.x86_64.qcow2

第三部分：修复 KVM 权限问题

3.1 问题描述

启动虚拟机时出现：

Could not access KVM kernel module: Permission denied
qemu-system-x86_64: failed to initialize KVM: Permission denied

3.2 解决方案

# 将当前用户加入 kvm 组
sudo usermod -aG kvm $USER

# 验证加入成功
groups $USER

然后完全退出 WSL，在 PowerShell 中执行：

wsl --shutdown

重新进入 WSL：

wsl -d Ubuntu-20.04

3.3 验证 KVM 权限

ls -l /dev/kvm
# 应显示类似：crw-rw---- 1 root kvm 10, 232 ...

第四部分：启动虚拟机

4.1 检查宿主机可用内存

在 PowerShell 中执行：

# 查看总内存（字节）
wmic computersystem get TotalPhysicalMemory

# 查看可用内存（KB）
wmic OS get FreePhysicalMemory

参考：总内存 32GB，可用约 14.6GB，可以安全分配 8GB 给虚拟机。

4.2 启动虚拟机（指定 8GB 内存）

cd ~/CubeSandbox/dev-env
VM_MEMORY_MB=8192 bash run_vm.sh

说明：脚本默认内存为 8GB（8192 MB），通过环境变量 VM_MEMORY_MB 可以调整。如果宿主机内存较小，可以改为 4096。

4.3 登录虚拟机

虚拟机启动后，另开一个 WSL 终端：

cd ~/CubeSandbox/dev-env
./login.sh

成功后会进入虚拟机的 root 终端：

[root@localhost ~]#

第五部分：在虚拟机内部署 CubeSandbox

5.1 运行官方安装脚本

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash

5.2 遇到问题：MySQL 容器启动失败

错误信息：

[one-click-runtime] ERROR: mysql container did not become healthy
docker logs cube-sandbox-mysql
# 显示：ls: cannot open directory '/docker-entrypoint-initdb.d/': Permission denied

原因：SELinux 阻止了容器访问挂载的目录。

5.3 解决方案：修改 Docker Compose 配置

安装脚本会在 MySQL 失败后退出。此时不要重新运行安装脚本，而是手动修改配置文件。

cd /usr/local/services/cubetoolbox/support

# 1. 添加 privileged: true
sed -i '/container_name: cube-sandbox-mysql/a\    privileged: true' docker-compose.yaml

# 2. 为数据卷添加 :Z 标签（SELinux 上下文）
sed -i 's|- cube-sandbox-mysql-data:/var/lib/mysql|- cube-sandbox-mysql-data:/var/lib/mysql:Z|g' docker-compose.yaml

# 3. 注释掉 initdb 挂载（避免权限干扰）
sed -i 's|- /usr/local/services/cubetoolbox/sql:/docker-entrypoint-initdb.d:ro|# - /usr/local/services/cubetoolbox/sql:/docker-entrypoint-initdb.d:ro|g' docker-compose.yaml

# 验证修改
grep -A 2 "container_name: cube-sandbox-mysql" docker-compose.yaml
grep "mysql-data" docker-compose.yaml

5.4 手动启动 MySQL

cd /usr/local/services/cubetoolbox
docker compose -f support/docker-compose.yaml up -d

验证 MySQL 状态：

docker ps -a | grep mysql
# 应显示 (healthy)

5.5 继续运行安装脚本

MySQL 修复后，重新运行安装脚本完成剩余部署：

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh | MIRROR=cn bash

第六部分：修复 cube-proxy 容器

6.1 问题描述

安装脚本运行后，cube-proxy 容器不断重启：

docker ps -a | grep cube-proxy
# 显示 Restarting

docker logs cube-proxy
# 显示：open() "/usr/local/openresty/nginx/conf/global/global.conf" failed (13: Permission denied)

6.2 解决方案

找到 cube-proxy 的 compose 文件并添加特权模式：

# 查找配置文件
find /usr/local/services/cubetoolbox -name "*.yaml" | xargs grep -l "cube-proxy"
# 输出：/usr/local/services/cubetoolbox/cubeproxy/docker-compose.yaml

cd /usr/local/services/cubetoolbox/cubeproxy

# 添加 privileged: true
sed -i '/container_name: cube-proxy/a\    privileged: true' docker-compose.yaml

# 重启容器
docker compose up -d cube-proxy

6.3 验证

docker ps -a | grep cube-proxy
# 应显示 Up

第七部分：修复 cube-proxy-coredns 容器

7.1 问题描述

cube-proxy-coredns 容器也陷入重启循环。

7.2 解决方案

# 查找配置文件
find /usr/local/services/cubetoolbox -name "*.yaml" | xargs grep -l "cube-proxy-coredns"
# 输出：/usr/local/services/cubetoolbox/coredns/docker-compose.yaml

cd /usr/local/services/cubetoolbox/coredns

# 添加 privileged: true
sed -i '/container_name: cube-proxy-coredns/a\    privileged: true' docker-compose.yaml

# 注意：服务名是 coredns，不是容器名
docker compose up -d coredns

7.3 验证

docker ps -a | grep coredns
# 应显示 Up

第八部分：验证部署成功

8.1 检查所有容器

docker ps -a

预期输出四个运行中的容器：

cube-sandbox-mysql (healthy)
cube-sandbox-redis (healthy)
cube-proxy (Up)
cube-proxy-coredns (Up)

8.2 检查核心进程

ps aux | grep -E "cubemaster|cubelet|cube-api|network-agent" | grep -v grep

应有多个进程输出。

8.3 测试 Cube API

在虚拟机内部：

curl http://127.0.0.1:3000/health

在 Windows 宿主机（浏览器或 PowerShell）：

http://127.0.0.1:13000/health

成功响应：

{"status":"ok","sandboxes":0}

第九部分：创建第一个沙箱模板

9.1 创建模板

cubemastercli tpl create-from-image \
  --image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest \
  --writable-layer-size 1G \
  --expose-port 49999 \
  --expose-port 49983 \
  --probe 49999

输出示例：

job_id: 9ba1e2ee-dc8e-44f7-9950-b5e34ac44e1f
template_id: tpl-0a37e549367a41248263a9e4
status: PENDING
phase: PULLING

9.2 监视模板创建进度

# 使用正确的 job_id
cubemastercli tpl watch --job-id 9ba1e2ee-dc8e-44f7-9950-b5e34ac44e1f

# 或者查看状态
cubemastercli tpl status --template-id tpl-0a37e549367a41248263a9e4

等待 status 变为 SUCCESS。

9.3 创建沙箱实例（模板成功后）

cubemastercli sandbox create --template-id tpl-0a37e549367a41248263a9e4

第十部分：日常使用

10.1 启动虚拟机

cd ~/CubeSandbox/dev-env
VM_MEMORY_MB=8192 bash run_vm.sh

10.2 登录虚拟机

cd ~/CubeSandbox/dev-env
./login.sh

10.3 检查服务状态

docker ps -a
ps aux | grep cube

10.4 如果容器没有自动启动

cd /usr/local/services/cubetoolbox
docker compose -f support/docker-compose.yaml up -d
cd cubeproxy && docker compose up -d
cd ../coredns && docker compose up -d coredns

10.5 关闭虚拟机

在虚拟机终端中执行：

poweroff

不要直接关闭终端窗口，否则可能损坏虚拟磁盘。

附录：问题速查表

问题	原因	解决方案
`wsl: command not found`	WSL 未安装	以管理员身份运行 `wsl --install`
`KVM: Permission denied`	用户不在 kvm 组	`sudo usermod -aG kvm $USER` 后重启 WSL
脚本报 `\r` 错误	Windows 换行符问题	`dos2unix *.sh`
MySQL 容器权限错误	SELinux 阻止	添加 `privileged: true` 和 `:Z` 标签
cubelet 被 Killed	内存不足	`VM_MEMORY_MB=8192` 增加虚拟机内存
compose 文件被覆盖	安装脚本重置配置	备份修改后的文件，脚本运行后恢复
`no such service: cube-proxy-coredns`	服务名与容器名不同	使用 `coredns` 作为服务名
API 端口 13000 不通	端口转发问题	虚拟机内用 `3000`，宿主机用 `13000`

posted @ 2026-04-24 15:53 树下黑猫阅读(232) 评论(0) 收藏举报

刷新页面返回顶部

树下黑猫