CubeSandbox 是一个基于 RustVMM 和 KVM 的开源沙箱服务，专为 AI Agent 设计

CubeSandbox 高性能安全沙箱详细部署教程

CubeSandbox 是一个基于 RustVMM 和 KVM 的开源沙箱服务，专为 AI Agent 设计。它能在 60ms 内创建一个硬件隔离、内存开销低于 5MB 的 MicroVM，提供极致的安全性和并发性能。本教程将指导您在 x86_64 Linux 环境（支持 KVM）上完成部署。

---

📋 目录

1. CubeSandbox 是什么
2. 部署架构与准备
3. 部署路径概览
4. 路径一：PVM 云服务器部署（推荐）
5. 路径二：裸金属服务器部署
6. 路径三：开发测试环境部署
7. 首次使用与验证
8. 高级配置与管理
9. 更新与卸载
10. 常见问题排查

---

CubeSandbox 是什么

CubeSandbox 是一个为 AI Agent 提供安全、轻量、极速执行环境的沙箱服务。它利用硬件虚拟化技术，为每个沙箱提供独立的操作系统内核，并通过 eBPF 实现网络隔离。

核心优势：

• ⚡ 极速启动：平均启动时间 < 60ms，即使在 50 并发下 P99 延迟也仅为 137ms。
• 🔒 硬件隔离：每个沙箱运行在独立的 MicroVM 中，拥有专用内核，安全性极高。
• 📦 高密度部署：每个沙箱内存开销 < 5MB，单台服务器可运行数千实例。
• 🔌 E2B SDK 兼容：无需修改代码，仅需更改环境变量即可从 E2B 迁移。

---

部署架构与准备

核心组件

组件	职责
CubeAPI	高并发 REST API 网关（兼容 E2B SDK）
CubeMaster	集群编排器，接收 API 请求并调度给 Cubelet
CubeProxy	反向代理，将请求路由至具体沙箱实例
Cubelet	计算节点代理，管理本机所有沙箱生命周期
CubeVS	基于 eBPF 的虚拟交换机，提供网络隔离
CubeEgress	七层安全网关，进行域名过滤与凭证注入

硬件与系统要求

• 操作系统：x86_64 Linux（推荐 OpenCloudOS 9、Ubuntu 22.04/24.04）
• 虚拟化支持：CPU 必须支持 KVM 并已启用
• 内存：根据并发沙箱数量而定，建议 ≥ 16GB
• 磁盘：≥ 100GB（用于存储镜像和模板）
• 网络：良好的内网连通性（多节点部署）

检查 KVM 支持：

egrep -c '(vmx|svm)' /proc/cpuinfo  # 输出 > 0 表示支持
kvm-ok                                # 若命令不存在，安装 cpu-checker

---

部署路径概览

路径	目标	适用场景
PVM 云服务器（推荐）	在普通云虚拟机上部署（无需嵌套虚拟化）	生产环境、快速试用
裸金属服务器	在物理机上部署，性能最佳	高吞吐、低延迟生产环境
开发测试环境	在 QEMU 虚拟机内体验（性能较差）	功能验证、学习探索

---

路径一：PVM 云服务器部署（推荐）

这是官方推荐的部署方式，通过自动化脚本在普通云虚拟机上完成安装。

1. 登录您的 Linux 服务器，确保 KVM 支持。

2. 执行一键部署脚本

# 下载并执行安装脚本（会自动检测环境并安装依赖）
curl -fsSL https://raw.githubusercontent.com/TencentCloud/CubeSandbox/main/scripts/install.sh | bash

此脚本会安装 CubeSandbox 所需的全部组件，包括 KVM 加速包、网络配置等。

3. 启动服务

# 启动所有服务（CubeAPI, CubeMaster, CubeProxy, Cubelet 等）
systemctl start cubesandbox

4. 设置开机自启

systemctl enable cubesandbox

5. 验证安装

# 查看所有服务状态
systemctl status cubesandbox

---

路径二：裸金属服务器部署

在物理机上部署以获得最佳性能。此路径与 PVM 类似，但能直接利用硬件特性。

1. 准备环境

# 确保系统为 x86_64 Linux，并更新内核
sudo apt update && sudo apt upgrade -y  # Ubuntu/Debian
sudo yum update -y                      # RHEL/CentOS

2. 安装 Docker 和必要工具

# 以 Ubuntu 为例
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

3. 使用 Terraform 一键部署
CubeSandbox 提供了 Terraform 模板，可快速在裸金属上创建集群。

git clone https://github.com/TencentCloud/CubeSandbox.git
cd CubeSandbox/deploy/terraform/bare-metal
terraform init
terraform apply -var="node_ip=<您的节点IP>" -var="ssh_key_path=~/.ssh/id_rsa"

Terraform 将自动配置所有组件。

---

路径三：开发测试环境部署

如果您的环境不支持 KVM（如普通云虚拟机、WSL），可以使用此方式在 QEMU 虚拟机内体验，但性能会显著下降。

1. 准备一台 安装有 QEMU 的 Linux 主机（建议 16GB 内存以上）。

2. 下载预配置的 OpenCloudOS 9 镜像

wget https://github.com/TencentCloud/CubeSandbox/releases/download/v0.7.0/opencloudos9-cubesandbox.qcow2

3. 启动 QEMU 虚拟机

qemu-system-x86_64 \
  -enable-kvm \
  -m 8192 \
  -smp 4 \
  -drive file=opencloudos9-cubesandbox.qcow2,format=qcow2 \
  -netdev user,id=net0,hostfwd=tcp::5555-:22 \
  -device virtio-net-pci,netdev=net0 \
  -vnc :1

虚拟机内部已预装 CubeSandbox，您可通过 VNC 或 SSH（映射到主机 5555 端口）访问。

---

首次使用与验证

部署完成后，可以通过 Web 控制台或 SDK 来管理沙箱。

访问 Web 控制台

在浏览器中打开：http://<您服务器的公网IP>:12088
您可以在此：

• 概览：查看节点状态与容量。
• 模板商店：安装官方预置模板（如 Python、Node.js 环境）。
• 沙箱：创建并管理沙箱实例，查看实时日志。

使用 Python SDK 测试

安装 Python SDK：

pip install cubesandbox

编写测试脚本 (test_sandbox.py)：

from cubesandbox import Sandbox

# 连接到您的 CubeSandbox 服务
sandbox = Sandbox(
    api_url="http://<您的服务器IP>:12080",  # CubeAPI 默认端口
    template="python:3.11"                 # 使用模板名称或别名
)

# 执行代码
execution = sandbox.run_code("print('Hello from CubeSandbox!')")
print(execution.text)

# 关闭沙箱
sandbox.close()

运行脚本：

python test_sandbox.py

若输出 “Hello from CubeSandbox!”，则部署成功！

---

高级配置与管理

使用 Terraform 部署生产集群（Tencent Cloud）

CubeSandbox 提供官方 Terraform 模块，可在腾讯云上快速创建生产级集群。

cd CubeSandbox/deploy/terraform/tencent-cloud
cp terraform.tfvars.example terraform.tfvars
# 编辑 terraform.tfvars，填入您的 Secret ID、Key、VPC 等信息
terraform init
terraform apply -auto-approve

在 Kubernetes 上部署

参考 K8s 部署文档，通过 Helm Chart 将控制平面和计算节点部署到 K8s 集群。

配置安全代理与凭证保险库

CubeSandbox 支持 L7 安全代理 (CubeEgress)，可精细控制沙箱的对外访问域名和路径，并自动注入凭证，密钥不会进入沙箱内部。

# 配置 egress 规则（示例）
curl -X PUT http://localhost:12080/api/v1/egress/rules \
  -d '{"domain": "api.openai.com", "methods": ["POST"], "inject_credential": "OPENAI_API_KEY"}'

---

更新与卸载

更新 CubeSandbox

1. 拉取最新代码或安装脚本。
2. 重新执行部署命令（脚本会处理版本升级）。

卸载 CubeSandbox

1. 停止服务：

   systemctl stop cubesandbox
   systemctl disable cubesandbox

2. 删除相关文件（根据安装路径，通常为 /opt/cubesandbox）：

   rm -rf /opt/cubesandbox

3. （可选）移除 Docker 镜像和网络配置。

---

常见问题排查

问题：安装脚本提示 KVM 不可用。

• 解决：确保 CPU 支持虚拟化且在 BIOS 中开启。如在云虚拟机中，需确认机型支持嵌套虚拟化（如腾讯云 PVM 实例）。

问题：无法访问 Web 控制台（端口 12088）。

• 解决：检查服务器防火墙是否放行了 12088 端口。尝试 curl http://localhost:12088 确认服务是否正常运行。

问题：Python SDK 连接超时。

• 解决：确认 api_url 中的 IP 和端口（默认 12080）正确，且服务器防火墙已放行该端口。

问题：创建沙箱失败，提示 “No ready template”。

• 解决：请先通过 Web 控制台的“模板商店”安装一个官方模板，或使用 API 创建一个自定义模板。

通过以上步骤，您应能成功部署并运行 CubeSandbox。对于生产环境，建议仔细阅读官方文档中的安全指南和性能调优章节。如需更多帮助，可加入其 Discord 社区 或提交 GitHub Issue。