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 研发与沙箱化运营的得力基础设施。