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

cpyaxjq

60人浏览 · 2026-07-04 17:01:03

cpyaxjq · 2026-07-04 17:01:03 发布

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

服务器: 腾讯云 CVM（沐曦算力） | OS: OpenCloudOS 9.4 | CubeSandbox: v0.5.0
GitHub: TencentCloud/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 架构一览

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

dnf install -y kernel-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 -sL https://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 | grep kvm_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 -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 安装过程记录

[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 创建第一个沙箱模板

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 步流水线）

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

字段	值
地址	`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。首次对话会报错：
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
    }
}

关键字段解读：

字段	值	说明
`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 创建克隆（分身）实例：

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

实际输出：

{
    "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 的核心价值：

能力	场景	实现方式	实测耗时
快照	保存沙箱完整状态	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 研发与沙箱化运营的得力基础设施。

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

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

openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

Linux操作系统-服务管理

openEuler 社区

【Qt】系统相关（1）——事件

openEuler 社区

Cherry Studio下载和安装教程

访问 Cherry Studio 官网或 GitHub 仓库，选择对应操作系统的安装包（支持 Windows/macOS/Linux），如果下载不下来可以尝试国内镜像gitee.com/FIRC/fircfiles/blob/master/cherrystudio。点击下一步，选择自己需要安装目录注意不要有空格和中文路径。双击安装包运行，按向导选择安装路径和语言（默认中文）。完成安装后，启动客