CubeSandbox 实战：从零部署到快照/克隆/回滚全体验

一、CubeSandbox 是什么

CubeSandbox 是腾讯云开源的一款安全沙箱运行时（Sandbox Runtime），基于轻量级虚拟机（microVM）技术，为 AI Agent / 代码执行 / 多租户隔离等场景提供毫秒级启动、快照-克隆-回滚三大能力的沙箱化基础设施。

本文将在腾讯云 CVM 上完成 从零部署到体验三大核心能力 的完整流程。

---

二、环境概览

2.1 服务器规格

项目	信息
实例 ID	ins-8zxst9gs
主机名	VM-0-29-opencloudos
公网 IP	43.138.197.216
内网 IP	10.101.0.29
CPU	8 核
内存	15 GiB
磁盘	100 GB vda1
操作系统	OpenCloudOS 9.4
SSH 端口	9888

2.2 CubeSandbox 架构一览

javascript

代码解读

复制代码

┌──────────────────────────────────────┐ │ CubeSandbox WebUI │ │ http://<IP>:12088 │ └──────────────┬───────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ │ │ ┌───────────▼───────────┐ ┌────────▼────────┐ ┌─────────▼──────────┐ │ CubeMaster │ │ CubeEgress │ │ CubeProxy │ │ (Template & Sandbox │ │ (MITM Proxy / │ │ (Gateway Routing) │ │ Lifecycle Mgmt) │ │ API Key 托管) │ │ │ └───────────┬───────────┘ └────────┬────────┘ └─────────┬──────────┘ │ │ │ ┌───────────▼───────────────────────▼───────────────────────▼──────────┐ │ Cubelet │ │ (Node Agent --- microVM 创建/销毁/快照/克隆/回滚) │ └───────────┬─────────────────────────────────────────────────────────┘ │ ┌───────────▼───────────┐ ┌──────────────┐ ┌────────────────────┐ │ kvm_pvm │ │ CoreDNS │ │ MySQL + Redis │ │ (PVM 虚拟化内核模块) │ │ (沙箱 DNS) │ │ (元数据 & 缓存) │ └───────────────────────┘ └──────────────┘ └────────────────────┘

---

三、第一步：安装 PVM 内核

CubeSandbox 的 microVM 依赖 PVM（轻量级虚拟化）内核模块。需要先安装专用的 Linux 内核。

3.1 安装内核包

bash

代码解读

复制代码

dnf install -y kernel-6.6.69-1.1.cubesandbox.oc9

实际执行输出：

vbnet

代码解读

复制代码

Package kernel-6.6.69-1.1.cubesandbox.oc9.x86_64 is already installed. Dependencies resolved. Nothing to do. Complete!

说明：腾讯云 CVM 已预装 CubeSandbox 内核，生产环境首次部署时需要下载安装（约 80MB）。

3.2 设置默认启动内核

bash

代码解读

复制代码

grubby --set-default /boot/vmlinuz-6.6.69-1.1.cubesandbox.oc9.x86_64

实际输出：

csharp

代码解读

复制代码

The default is /boot/loader/entries/98823c2f3f5b4b35875d9c96c3e2537b-6.6.69-1.1.cubesandbox.oc9.x86_64.conf with index 1 and kernel /boot/vmlinuz-6.6.69-1.1.cubesandbox.oc9.x86_64

参数解释：

• grubby --set-default 修改 GRUB2 默认启动项
• 回显 The default is ... 不是报错，是正常确认信息

3.3 配置 PVM 内核启动参数

bash

代码解读

复制代码

curl -sL https://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/pvm/grub/host_grub_config.sh | bash

实际输出：

erlang

代码解读

复制代码

Generating grub configuration file ... Warning: os-prober will not be executed to detect other bootable partitions. Systems on them will not be added to the GRUB boot configuration. Check GRUB_DISABLE_OS_PROBER documentation entry. Adding boot menu entry for UEFI Firmware Settings ... done

3.4 重启进入新内核

bash

代码解读

复制代码

reboot

重启后验证：

bash

代码解读

复制代码

uname -r # 输出: 6.6.69-1.1.cubesandbox.oc9.x86_64

踩坑提示：重启前确保 grub 默认项已正确设置。若进入旧内核，需进 grub 菜单手动选择。

3.5 加载 KVM 模块

bash

代码解读

复制代码

modprobe kvm_pvm lsmod | grep kvm_pvm

实际输出：

代码解读

复制代码

kvm_pvm 49152 0 kvm 1163264 1 kvm_pvm kmem_cache 16384 2 kvm,kvm_pvm

设置开机自启动：

bash

代码解读

复制代码

echo 'kvm_pvm' > /etc/modules-load.d/kvm-pvm.conf

参数解释：

• kvm_pvm：PVM 核心驱动模块，49152 = modprobe 默认 48KB 内存占用（实际运行时约 50MB）
• kvm：Linux KVM 基础模块，被 kvm_pvm 依赖（Used by=1）
• kmem_cache：跨模块共享的内核内存缓存

---

四、第二步：一键安装 CubeSandbox

4.1 执行安装脚本

bash

代码解读

复制代码

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

环境变量说明：

变量	值	含义
CUBE_PVM_ENABLE	1	启用 PVM 虚拟化（必选，否则不加载 kvm_pvm）
MIRROR	cn	使用中国大陆镜像源加速下载

4.2 安装过程记录

sql

代码解读

复制代码

[one-click] glibc version 2.38 OK (>= 2.31) [one-click] auto-detected node IP from eth0: 10.101.0.29 [one-click] using node IP: 10.101.0.29 [one-click] using primary network interface: eth0 [one-click] default CubeSandbox network CIDR preflight OK: 192.168.0.0/18 [one-click] checking and installing dependencies... [one-click] installing docker via yum... [one-click] release manifest contract OK [one-click] CUBE_PVM_ENABLE=1, selected PVM guest kernel: vmlinux-pvm

4.3 安装的服务清单

安装完成后，/etc/systemd/system 下自动注册了 10 个 systemd 服务：

服务名	类型	用途
cube-sandbox-coredns	容器	沙箱内部 DNS 解析
cube-sandbox-cube-api	守护进程	CubeSandbox REST API
cube-sandbox-cube-egress	守护进程	透明 MITM 代理（API Key 托管）
cube-sandbox-cube-proxy	容器	网关路由 / Gateway 代理
cube-sandbox-cubelet	守护进程	节点 Agent（microVM 生命周期）
cube-sandbox-cubemaster	守护进程	模板 & 实例编排
cube-sandbox-mysql	容器	元数据存储
cube-sandbox-network-agent	守护进程	沙箱网络管理
cube-sandbox-redis	容器	缓存 & 状态存储
cube-sandbox-webui	容器	Web 管理界面

4.4 安装的 CLI 工具

命令	路径	用途
cubemastercli	/usr/local/bin/	模板 & 实例管理客户端
cubecli	/usr/local/bin/	通用沙箱操作 CLI
cube-runtime	/usr/local/bin/	沙箱运行时
containerd-shim-cube-rs	/usr/local/bin/	containerd Cube shim

---

五、第三步：创建模板，验证功能

5.1 创建第一个沙箱模板

bash

代码解读

复制代码

cubemastercli tpl create-from-image \ --image cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \ --writable-layer-size 1G \ --expose-port 49999 \ --expose-port 49983 \ --probe 49999

参数解释：

参数	值	含义
--image	sandbox-code:latest	基础沙箱镜像（内置 Python/Node.js 等运行时）
--writable-layer-size	1G	沙箱可写层大小，上限取决于磁盘
--expose-port	49999	暴露 Code Server 端口（Web IDE）
--expose-port	49983	暴露附加服务端口
--probe	49999	健康检查端口（探活）

5.2 模板创建过程（7 步流水线）

ini

代码解读

复制代码

[1/7] PULLING progress=0% ← 拉取镜像 [2/7] UNPACKING progress=20% artifact_id=rfs-eaa... ← 解包镜像层 [5/7] DISTRIBUTING progress=70% ← 分发到节点 [6/7] CREATING progress=85% distribution=1/1 ready ← 创建模板元数据 [7/7] READY progress=100% ← 就绪 ✅

实际输出：

ini

代码解读

复制代码

template image job succeeded template_id=tpl-4abeef4448bc41d2820b93a8 job_id=7b5fe777-d35c-4540-afc4-aa7aa01be5ae artifact_id=rfs-eaaad36d9aa650524205b058 distribution=1/1 ready, 0 failed

5.3 确认模板状态

bash

代码解读

复制代码

cubemastercli tpl list

实际输出：

java

代码解读

复制代码

TEMPLATE_ID STATUS CREATED_AT IMAGE_INFO tpl-4abeef4448bc41d2820b93a8 READY 2026-07-04T08:31:37Z sandbox-code:latest@sha256:5ad58...

状态为 READY 即表示 CubeSandbox 完整部署成功，可以正常创建沙箱实例。

---

六、第四步：登录 WebUI

浏览器访问 http://43.138.197.216:12088：

字段	值
地址	http://43.138.197.216:12088
默认账号	admin
默认密码	admin

踩坑提示 ：如果无法访问，检查云服务器安全组是否放行了 12088 端口（TCP 入方向）。

WebUI 首页可看到：

• 运行中的沙箱实例卡片
• 已创建的沙箱模板列表
• 数字助手入口

---

七、第五步：配置数字助手（WebUI）

7.1 配置 LLM 服务

在 WebUI 登录后，进入「数字助手」页面，配置 LLM 模型服务：

字段	值
Provider	OpenAI Compatible
LLM Base URL	https://newapi-2607.cubesandbox.com/v1
模型 ID	hy3-preview
API Key	sk-JhXt...（托管后只显示掩码 ••••9Qww）
凭证交付方式	凭证托管（推荐）

安全机制 ：选择「凭证托管」后，API Key 由 CubeEgress（透明 MITM 代理）托管，沙箱内部无法直接获取真实密钥。OpenClaw 配置中只保存托管占位 Key。

保存后 WebUI 确认：已配置 openai-compatible / hy3-preview（Key：••••9Qww，来源：数据库，方式：凭证托管（推荐））

7.2 安装数字助手模板

在「模板市场」→「AI · LLM」中选择 轻量版 OpenClaw （lightweight-openclaw-deepseek-wecom:latest，约 2.5 GB），点击「安装并启用到数字助手」。

模板创建完成后（约 40 秒），创建数字助手实例：

配置项	值
实例名称	openclaw-test
助手模板	龙虾助手 · 轻量版 · tpl-4fe74ef5f3c54ee1a49cde05
状态管理模式	完整快照型
模型	hy3-preview

创建后实例卡：

• 状态：运行中 ✅
• Sandbox ID：0bfae8c116174a64a9523f1d6a2a5bcd
• 版本：2026.4.5-t.27

踩坑记录 ：轻量版 OpenClaw 模板默认使用 deepseek/deepseek-v4-flash 模型，但实际 API endpoint 是兼容 OpenAI 格式的 hy3-preview。首次对话会报错：

bash

代码解读

复制代码
Unknown model: deepseek/deepseek-v4-flash

需在 OpenClaw 聊天界面底部模型选择器手动切换到 hy3-preview 模型才能正常响应。切换后模型状态变为 hy3-preview · Medium。

7.3 核心能力一：快照（Snapshot）

切换到 CLI 操作。首先确认当前运行的沙箱：

bash

代码解读

复制代码

cubemastercli list

实际输出：

lua

代码解读

复制代码

NODE_SCOPE 1-1 NODES_SCANNED 1/1 SANDBOX_COUNT 1 sandbox_id status host_id create_at 0bfae8c116174a64a9523f1d6a2a5bcd running 10.101.0.29 2026-07-04 16:50:43

为这个沙箱创建一份快照：

bash

代码解读

复制代码

cubemastercli snapshot create \ --sandbox-id 0bfae8c116174a64a9523f1d6a2a5bcd \ --display-name snap-test-001 \ --json

实际输出：

json

代码解读

复制代码

{ "requestID": "a3dcece6-5e21-4f7a-94d0-419928abd0cf", "ret": { "ret_code": 200, "ret_msg": "success" }, "snapshot": { "snapshot_id": "snap-daf46ef7c84a41e98fd3eb6b", "instance_type": "cubebox", "version": "v2", "status": "READY", "display_name": "snap-test-001", "origin_sandbox_id": "0bfae8c116174a64a9523f1d6a2a5bcd", "origin_node_id": "10.101.0.29", "storage_backend": "cubecow", "rootfs_size_bytes_at_snapshot": 2000000000, "created_at": "2026-07-04T08:56:22Z", "replicas": [ { "node_id": "10.101.0.29", "node_ip": "10.101.0.29", "status": "READY", "phase": "READY", "spec": "cpu=2000m,mem=2000Mi" } ] }, "operation": { "operation_id": "db651a55-2854-4388-9823-afb92a595fb0", "snapshot_id": "snap-daf46ef7c84a41e98fd3eb6b", "sandbox_id": "0bfae8c116174a64a9523f1d6a2a5bcd", "operation": "SNAPSHOT_CREATE", "status": "READY", "phase": "REGISTERING", "progress": 100 } }

关键字段解读：

字段	值	说明
snapshot_id	snap-daf46...	快照唯一 ID，后续克隆和回滚都依赖它
status	READY	快照已就绪
rootfs_size_bytes_at_snapshot	2000000000	快照时 rootfs 大小 = 2 GB
storage_backend	cubecow	Copy-on-Write 存储，克隆和回滚秒级的关键
replicas[0].spec	cpu=2000m,mem=2000Mi	该快照副本的资源规格 = 2 vCPU + 2G 内存

7.4 核心能力二：克隆（Clone）

基于快照通过 REST API 创建克隆（分身）实例：

bash

代码解读

复制代码

curl -s -X POST \ -H "Content-Type: application/json" \ -d '{"templateID":"tpl-4fe74ef5f3c54ee1a49cde05", "snapshotID":"snap-daf46ef7c84a41e98fd3eb6b"}' \ http://127.0.0.1:3000/cubeapi/v1/sandboxes

实际输出：

json

代码解读

复制代码

{ "templateID": "tpl-4fe74ef5f3c54ee1a49cde05", "sandboxID": "102bb34fb167434685556f079ffa8130", "clientID": "558664fe-53ab-4627-b935-c1510cf27745", "envdVersion": "0.5.11", "domain": "cube.app" }

验证结果：

bash

代码解读

复制代码

cubemastercli list

lua

代码解读

复制代码

NODE_SCOPE 1-1 NODES_SCANNED 1/1 SANDBOX_COUNT 2 ← 已有 2 个沙箱 sandbox_id status host_id create_at 0bfae8c116174a64a9523f1d6a2a5bcd running 10.101.0.29 2026-07-04 16:50:43 ← 原始实例 102bb34fb167434685556f079ffa8130 running 10.101.0.29 2026-07-04 17:00:01 ← 克隆分身

两个沙箱同时运行在同一个节点上，完全独立、互不影响。克隆耗时不到 10 秒，这就是 CubeSandbox CoW（Copy-on-Write）存储的优势。

scss

代码解读

复制代码

快照 snap-daf46ef7c84a41e98fd3eb6b │ ┌─────────┼─────────┐ ▼ │ ▼ 原始实例 │ 克隆分身 0bfae8... │ 102bb3... (OpenClaw) │ (OpenClaw 副本) │ CoW 共享基础层 + 独立可写层 完全隔离，互不影响

7.5 核心能力三：回滚（Rollback）

通过 CLI 将原始沙箱回滚到之前创建的快照：

bash

代码解读

复制代码

cubemastercli sandbox rollback \ --sandbox-id 0bfae8c116174a64a9523f1d6a2a5bcd \ --snapshot-id snap-daf46ef7c84a41e98fd3eb6b

实际输出：

yaml

代码解读

复制代码

2026/07/04 17:00:10 operation_id: 3be70c78-87a2-4281-b982-e923c0dadf13 2026/07/04 17:00:10 snapshot_id: snap-daf46ef7c84a41e98fd3eb6b 2026/07/04 17:00:10 sandbox_id: 0bfae8c116174a64a9523f1d6a2a5bcd 2026/07/04 17:00:10 operation: SNAPSHOT_ROLLBACK 2026/07/04 17:00:10 status: READY 2026/07/04 17:00:10 phase: READY 2026/07/04 17:00:10 progress: 100%

回滚操作瞬间完成（同一秒内），沙箱恢复到打快照时的完整状态。

scss

代码解读

复制代码

时间线： ────────────────────────────────────────────────────► 快照 回滚! 验证 snap-daf4... ──────────► 状态恢复 ✅ │ 100% └──── 环境回退到此处 ────┘ (CoW 写时复制, 秒级回滚)

核心原理：cubecow（Cube Copy-on-Write）存储后端在回滚时，不搬运数据，只重置文件的 COW 引用链，将当前可写层指向快照时的根节点。因此无论原始数据多大，回滚都在秒级完成。

---

八、部署踩坑备忘录

以下是在实操中需要特别注意的几个点。

8.1 PVM 模块只能在 CubeSandbox 内核中加载

bash

代码解读

复制代码

# 旧内核中 modprobe kvm_pvm # FATAL: Module kvm_pvm not found in directory /lib/modules/6.6.119-49.22.oc9.x86_64

原因 ：kvm_pvm 是 CubeSandbox 定制内核 6.6.69-1.1 编译的模块，与标准内核的 /lib/modules 不兼容。必须重启进入 CubeSandbox 内核后才能加载。

8.2 网络 CIDR 不能与宿主机冲突

安装脚本自动探测宿主机网段（eth0 = 10.101.0.0/24），默认沙箱网络 CIDR 为 192.168.0.0/18。如果宿主机恰好也使用 192.168.x.x，安装时会提示 CIDR preflight FAIL，需通过 CUBE_SANDBOX_NETWORK_CIDR 环境变量指定其他网段。

8.3 Docker 安装依赖

安装脚本会自动检查 Docker 是否已安装，未安装则通过 yum 自动安装。实际环境中安装了 Docker 29.3.1。

8.4 端口 12088 安全组放行

WebUI 默认监听 0.0.0.0:12088。云服务器安全组需放行该端口，否则外网无法访问。

---

九、总结

通过本次实操，完整走通了以下链路：

sql

代码解读

复制代码

安装 PVM 内核 → 重启切换 → 加载 kvm_pvm → 一键安装 CubeSandbox → 创建沙箱模板 → WebUI 配置数字助手 → CLI 验证三大能力 → 快照 snapshot create → 克隆 REST API → 回滚 sandbox rollback

CubeSandbox 的核心价值：

能力	场景	实现方式	实测耗时
快照	保存沙箱完整状态	CoW 快照（cubecow 存储后端）	~1 秒
克隆	并行实验 / 多租户隔离	基于快照 CoW 引用的秒级复制	~10 秒
回滚	安全试错 / 误操作恢复	重置 CoW 引用链	<1 秒

实操产物清单

资源	ID	说明
模板（code）	tpl-4abeef4448bc41d2820b93a8	sandbox-code 基础镜像
模板（openclaw）	tpl-4fe74ef5f3c54ee1a49cde05	轻量版 OpenClaw
原始实例	0bfae8c116174a64a9523f1d6a2a5bcd	openclaw-test 数字助手
快照	snap-daf46ef7c84a41e98fd3eb6b	2GB rootfs, CoW 存储
克隆分身	102bb34fb167434685556f079ffa8130	基于快照的独立副本

CubeSandbox 将「安全试错、瞬时回退、并行实验」凝练为一键操作，是 AI Agent 研发与沙箱化运营的得力基础设施。