compose-anything/builds/cube-sandbox/README.zh.md

CubeSandbox

在单个特权 Docker 容器内完整运行 腾讯云 CubeSandbox——一个基于 KVM、兼容 E2B SDK 的 MicroVM 沙箱——无需修改宿主系统。

为什么这个栈与众不同

CubeSandbox 上游并不是一个容器化项目。它的核心组件（Cubelet、network-agent、cube-shim、cube-runtime、CubeAPI、CubeMaster）以宿主机二进制形式分发，官方 install.sh 会把它们写入 /usr/local/services/cubetoolbox，然后作为本机进程启动并与宿主 containerd 集成。

本栈把整个安装器塞进一个特权容器：

1. 容器内自起一个 dockerd（Docker-in-Docker），用于运行 MySQL / Redis / CubeProxy / CoreDNS 等依赖。
2. 在 /data/cubelet 创建一个 XFS 格式的 loop 卷（install.sh 强制要求 XFS）。
3. 首次启动时执行上游的 online-install.sh。
4. 通过 tail 日志保持容器存活。

最终得到一个单节点 CubeSandbox 一体化容器，方便在不改动宿主的前提下评估 CubeSandbox。

特性

• 基于 Ubuntu 22.04（项目主要测试环境）
• 自包含：不安装宿主机软件包，不挂载宿主路径
• 通过 /dev/kvm 透传 KVM
• 三个持久化命名卷分别保存安装产物、沙箱数据和 DinD 存储
• 健康检查覆盖 CubeAPI、CubeMaster、network-agent
• 默认使用国内镜像 (MIRROR=cn)
• 内置冒烟测试脚本（smoke-test.sh）

环境要求

• Linux 宿主（或开启 KVM 透传的 WSL2），/dev/kvm 对 Docker 可见
• 已开启嵌套虚拟化（暴露 Intel VT-x / AMD-V）
• cgroup v2（现代内核——Debian 12+、Ubuntu 22.04+、kernel 5.10+）
• 推荐 ≥ 16 GiB 内存、≥ 8 vCPU（上游最低 8 GiB）
• 至少 60 GiB 空闲磁盘，用于 XFS loop 文件 + Docker 镜像层
• 可访问外网，用于下载安装包（数百 MB）和 Docker 镜像

WSL2 用户：先确认 /dev/kvm 存在（ls -l /dev/kvm），并且当前用户在宿主发行版的 kvm 组中。

快速开始

1. 复制示例环境文件（可选，默认值即可使用）：

   cp .env.example .env
   

2. 构建并启动（首次运行会下载 CubeSandbox 安装包和若干 Docker 镜像，预计 5-20 分钟）：

   docker compose up -d --build
   

3. 观察启动日志：

   docker compose logs -f cube-sandbox
   

   等待出现 ==================== CubeSandbox is up ==================== 横幅。

4. 验证所有服务健康：

   curl -fsS http://127.0.0.1:3000/health        && echo  # CubeAPI
   curl -fsS http://127.0.0.1:8089/notify/health && echo  # CubeMaster
   curl -fsS http://127.0.0.1:19090/healthz      && echo  # network-agent
   

5. （可选）运行冒烟测试：

   bash smoke-test.sh                            # 仅做健康检查
   SKIP_TEMPLATE_BUILD=1 bash smoke-test.sh      # 跳过较慢的模板构建步骤
   

服务端点

由于容器使用 network_mode: host，CubeSandbox 的所有 HTTP 端点都直接暴露在宿主回环地址上：

服务	URL
CubeAPI	http://127.0.0.1:3000
CubeMaster	http://127.0.0.1:8089
network-agent	http://127.0.0.1:19090

CubeAPI 暴露兼容 E2B 的 REST 接口；将 e2b Python SDK 指向 http://127.0.0.1:3000 即可创建沙箱。

配置项

主要环境变量（完整列表见 .env.example）：

变量	描述	默认值
GLOBAL_REGISTRY	推送到私有仓库时使用的镜像前缀	（空）
CUBE_SANDBOX_VERSION	本地构建的封装镜像 tag	0.1.7
UBUNTU_IMAGE	基础 Ubuntu 版本	22.04
TZ	容器时区	Asia/Shanghai
CUBE_MIRROR	安装器镜像源——cn（国内 CDN）或 gh（GitHub）	cn
CUBE_XFS_SIZE	/data/cubelet 背后 XFS loop 文件大小	50G
CUBE_FORCE_REINSTALL	设为 1 时下次启动会重跑 install.sh	0
CUBE_CPU_LIMIT	CPU 上限	8
CUBE_MEMORY_LIMIT	内存上限	16G
CUBE_CPU_RESERVATION	CPU 预留	2
CUBE_MEMORY_RESERVATION	内存预留	8G

存储

三个命名卷保存所有持久化状态——docker compose down && up 不会丢失安装：

卷	容器内路径	用途
cube_dind_data	/var/lib/docker	DinD 守护进程的镜像 / 容器 / 卷
cube_data	/data	XFS loop 文件、/data/cubelet、沙箱磁盘、日志
cube_toolbox	/usr/local/services/cubetoolbox	已安装的 CubeSandbox 二进制和脚本

完全清空并从头重装：

docker compose down -v
docker compose up -d --build

安全说明

⚠️ 本栈按设计是高特权的，仅在受信环境中使用。

• privileged: true——挂载 XFS loop 卷、管理 TAP 接口、运行 KVM 所必需
• network_mode: host——Cubelet 注册节点 IP、管理宿主 TAP 接口所必需
• cgroup: host——容器内的 dockerd 共享宿主 cgroup v2 层级所必需
• 透传 /dev/kvm 和 /dev/net/tun

这些权限等同于直接在宿主上运行 online-install.sh 所需的权限。容器封装的好处在于：所有安装副作用都被限制在上述三个命名卷内，删除本栈不会在宿主上留下任何残留。

故障排查

• /dev/kvm not found：宿主未对 Docker 暴露 KVM。WSL2 用户请确认嵌套虚拟化已启用且内核暴露 /dev/kvm；裸金属用户请在 BIOS 中启用 VT-x / AMD-V。

• 首次启动卡在 "Running CubeSandbox one-click installer"：安装器正在下载安装包（数百 MB）并拉取若干 Docker 镜像。用 docker compose logs -f cube-sandbox 查看进度。

• quickcheck.sh reported issues：进入容器查看日志：

  docker compose exec cube-sandbox bash
  ls /data/log/
  tail -f /data/log/CubeAPI/*.log
  

• 干净重跑安装：在 .env 中设置 CUBE_FORCE_REINSTALL=1，然后 docker compose up -d --force-recreate。

项目信息

• 上游项目：https://github.com/TencentCloud/CubeSandbox
• 许可证：上游项目采用 Apache-2.0；本配置以 as-is 形式提供给 Compose Anything 项目使用。