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

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

服务器: 腾讯云 CVM（沐曦算力） |OS: OpenCloudOS 9.4 |CubeSandbox: v0.5.0
GitHub: TencentCloud/CubeSandbox

一、CubeSandbox 是什么

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

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

二、环境概览

2.1 服务器规格

2.2 CubeSandbox 架构一览

┌──────────────────────────────────────┐ │ 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 安装内核包

dnfinstall-ykernel-6.6.69-1.1.cubesandbox.oc9

实际执行输出：

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 设置默认启动内核

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

实际输出：

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 内核启动参数

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

实际输出：

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 重启进入新内核

reboot

重启后验证：

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

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

3.5 加载 KVM 模块

modprobe kvm_pvm lsmod|grepkvm_pvm

实际输出：

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

设置开机自启动：

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 执行安装脚本

curl-sLhttps://cnb.cool/CubeSandbox/CubeSandbox/-/git/raw/master/deploy/one-click/online-install.sh\|CUBE_PVM_ENABLE=1MIRROR=cnbash

环境变量说明：

4.2 安装过程记录

[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 服务：

4.4 安装的 CLI 工具

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

5.1 创建第一个沙箱模板

cubemastercli tpl create-from-image\--imagecube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest\--writable-layer-size 1G\--expose-port49999\--expose-port49983\--probe49999

参数解释：

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

[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% ← 就绪 ✅

实际输出：

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 确认模板状态

cubemastercli tpl list

实际输出：

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：

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

WebUI 首页可看到：

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

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

7.1 配置 LLM 服务

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

安全机制：选择「凭证托管」后，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 秒），创建数字助手实例：

创建后实例卡：

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

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

Unknown model: deepseek/deepseek-v4-flash

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

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

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

cubemastercli list

实际输出：

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

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

cubemastercli snapshot create\--sandbox-id 0bfae8c116174a64a9523f1d6a2a5bcd\--display-name snap-test-001\--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}}

关键字段解读：

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

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

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

实际输出：

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

验证结果：

cubemastercli list

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）存储的优势。

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

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

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

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

实际输出：

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%

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

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

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

八、部署踩坑备忘录

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

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

# 旧内核中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。云服务器安全组需放行该端口，否则外网无法访问。

九、总结

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

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

CubeSandbox 的核心价值：

实操产物清单

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

CubeSandbox GitHub: github.com/TencentCloud/CubeSandbox
如果觉得项目不错，记得给仓库点个 Star ⭐

本文基于 CubeSandbox v0.5.0 实战部署编写 | 环境：腾讯云 CVM + OpenCloudOS 9.4 + 沐曦算力