关键词：AI 沙箱、微虚拟机、KVM 隔离、RustVMM、E2B 兼容
当你让大模型生成一段 Python 脚本并按下“执行”的那一刻，一个根本性的安全问题就已浮现——这段未经审计的代码，将在哪里运行？
Docker 容器是多数团队的第一直觉，但共享内核的 Namespace 隔离早已被证明存在风险：容器逃逸漏洞时有发生，一旦 AI Agent 被诱导执行恶意代码，整台宿主机都可能面临威胁。
- CubeSandbox 是基于 RustVMM 与 KVM 构建的高性能、开箱即用的安全沙箱服务。它既支持单节点部署，也可轻松扩展至多节点集群。该服务兼容 E2B SDK，能够在 60 毫秒内创建具备完整服务能力的硬件隔离沙箱环境，同时将内存开销控制在 5MB 以下。
- 项目地址：https://github.com/TencentCloud/CubeSandbox
传统虚拟机虽然能提供强隔离，但分钟级的启动速度和动辄数百兆的内存开销，使其在“每次对话创建一个新环境”的 AI 应用场景中难以胜任。
是否存在一种方案，能同时兼顾虚拟机的内核级安全隔离与容器的轻量敏捷？腾讯云开源的 CubeSandbox，正是对这道难题的工程化解答。
本文目录
- 零、快速上手：从零运行你的第一个安全沙箱
- 0.1 环境要求
- 0.2 第一步：一键安装服务
- 0.3 第二步：创建沙箱模板
- 0.4 第三步：使用 E2B SDK 执行代码
- 一、架构总览与设计哲学
- 1.1 请求的完整生命周期
- 二、CubeAPI：用 Rust 重写的 API 网关
- 2.1 路由注册与中间件栈
- 2.2 异步运行时的精细控制
- 三、CubeShim：Rust 实现的 containerd Shim v2
- 3.1 启动时的文件描述符预扩展技巧
- 3.2 核心模块划分
- 四、CubeProxy：基于 OpenResty 的智能路由
- 五、Hypervisor 层：基于 Cloud Hypervisor 的深度定制
- 六、CubeVS 与网络安全模型
- 七、一键部署与生产实践
- 总结与展望
零、快速上手：从零运行你的第一个安全沙箱
本节旨在让读者在 5 分钟内跑通完整链路。如需了解多节点集群部署、自定义模板、TLS 证书管理等进阶内容，请参阅完整的 Quick Start 指南。
0.1 环境要求
- x86_64 架构的物理 Linux 服务器，需已开启 KVM（确认
/dev/kvm设备存在）。 - Docker 已安装并正在运行。
- 服务器需具备外网访问能力（用于拉取镜像和安装包）。
💡 提示：虚拟机（嵌套虚拟化）环境理论上可用，但不建议用于生产；云服务器需确认实例类型支持 KVM 透传。详见多节点部署文档。
0.2 第一步：一键安装服务
bash
curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/cube-sandbox/deploy/one-click/online-install.sh | bash
安装脚本会自动完成以下工作：启动 CubeAPI（监听端口 3000）、CubeMaster、Cubelet、CubeShim、CubeProxy（含 mkcert TLS 证书）、CoreDNS，以及 MySQL / Redis 等依赖容器。
⚠️ 注意：如果服务器主网卡名称不是
eth0，需手动指定节点 IP 后再执行安装：bash
CUBE_SANDBOX_NODE_IP=<your-ip> bash <(curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/cube-sandbox/deploy/one-click/online-install.sh)
安装完成后，将 CLI 工具加入系统 PATH：bash
echo 'export PATH=/usr/local/services/cubetoolbox/CubeMaster/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
0.3 第二步：创建沙箱模板
bash
cubemastercli tpl create-from-image
--image ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest
--writable-layer-size 1G
--expose-port 49999
--expose-port 49983
--probe 49999
等待模板构建完成（可通过 cubemastercli tpl watch --job-id <job_id> 命令跟踪进度），并记录输出中的 Template ID。
关于自定义镜像构建模板的完整工作流，请参考 Template Concepts 文档。
0.4 第三步：使用 E2B SDK 执行代码
首先安装 E2B SDK：bash
pip install e2b-code-interpreter
设置必要的环境变量：bash
export E2B_API_URL="http://127.0.0.1:3000"
export E2B_API_KEY="dummy" # 本地部署时，任意非空字符串即可
export CUBE_TEMPLATE_ID="<第二步获得的模板ID>"
export SSL_CERT_FILE="$(mkcert -CAROOT)/rootCA.pem"
| 变量 | 说明 |
| :— | :— |
| E2B_API_URL | 将 E2B SDK 指向本地部署的 CubeAPI，而非其官方云服务。 |
| E2B_API_KEY | SDK 内部有非空校验，本地部署可填写任意值。 |
| CUBE_TEMPLATE_ID | 沙箱模板 ID，决定了虚拟机内运行的具体环境。 |
| SSL_CERT_FILE | mkcert 根证书路径，用于 SDK 访问沙箱的 HTTPS 连接。 |
运行你的第一段在硬件隔离环境中的代码：
“`python
import os
from e2b_code_interpreter import Sandbox # 直接使用 E2B 官方 SDK
with Sandbox.create(template=os.environ[“CUBE_TEMPLATE_ID”]) as sandbox:
# 以下代码运行在一个拥有独立内核的 KVM 微虚拟机中
result = sandbox.run_code(“print(‘Hello from Cube Sandbox!’)”)
print(result)
# 也可以执行 Shell 命令
cmd = sandbox.commands.run("uname -a")
print(cmd.stdout) # 输出将显示这是一个独立的 Guest 内核
“`
更多使用场景（如 Shell 命令执行、文件读写、浏览器自动化、沙箱暂停/恢复、网络策略配置等）的详细示例，请参考项目 examples/ 目录及示例教程。
一、架构总览与设计哲学
CubeSandbox 的核心设计思想可概括为：分层解耦、极致裁剪。
整个系统自上而下分为六大组件，构成一条从 HTTP 请求到 MicroVM 内进程执行的完整处理链路：
| 组件 | 语言 | 职责 |
| :— | :— | :— |
| CubeAPI | Rust (Axum) | 提供与 E2B 兼容的 REST API 网关 |
| CubeMaster | Go | 集群编排调度器，负责资源与状态管理 |
| CubeProxy | OpenResty/Lua | 反向代理，将请求路由至目标沙箱 |
| Cubelet | Go | 单节点沙箱生命周期管理器 |
| CubeVS | eBPF/C | 内核态虚拟交换机，实现网络隔离 |
| CubeRuntime | Rust | 集成 Shim、Hypervisor 与 Agent 的运行时 |
该架构有意借鉴了 Kubernetes 的 Master-Node 范式（CubeMaster 对应 kube-apiserver 与 scheduler，Cubelet 对应 kubelet），但其不依赖 Kubernetes，支持单机一键部署运行。
这是一个关键的产品决策：在 AI Agent 开发场景中，开发者通常不希望维护完整的 K8s 集群，而更倾向于获得一个开箱即用的安全沙箱环境。
1.1 请求的完整生命周期
一个典型的沙箱创建流程如下：
- 用户通过 E2B SDK 发送
POST /sandboxes请求。 - CubeAPI 接收请求，并将其转发至 CubeMaster。
- CubeMaster 将任务调度到合适的 Cubelet 节点。
- Cubelet 通过 containerd 调用 CubeShim（遵循 Shim v2 协议）。
- CubeShim 请求 Hypervisor 启动基于 KVM 的 MicroVM。
- MicroVM 内的 cube-agent 就绪，沙箱进入可用状态。
得益于资源池预置和快照克隆技术，整个链路端到端耗时可控制在 60 毫秒以内，跳过了传统虚拟机冗长的引导加载流程。
二、CubeAPI：基于 Rust 的 API 网关
CubeAPI 作为系统的入口，承担着一项特殊使命：使用户无需修改任何业务代码，即可从 E2B 云服务无缝迁移至自托管的沙箱环境。仅需更改环境变量 E2B_API_URL，所有通过 E2B 官方 Python SDK 发起的调用都将被 CubeAPI 透明接管。
2.1 路由注册与中间件栈
CubeAPI 基于 Axum 框架构建，其路由层设计清晰：
“`rust
// 来源：CubeAPI/src/routes.rs
pub fn build_router(state: AppState) -> Router {
let sandbox_routes = Router::new()
.route(“/sandboxes”, get(sandboxes::list_sandboxes))
.route(“/sandboxes”, post(sandboxes::create_sandbox))
.route(“/v2/sandboxes”, get(sandboxes::list_sandboxes_v2))
.route(“/sandboxes/:sandboxID”, get(sandboxes::get_sandbox))
.route(“/sandboxes/:sandboxID”, delete(sandboxes::kill_sandbox))
.route(“/sandboxes/:sandboxID/pause”, post(sandboxes::pause_sandbox))
.route(“/sandboxes/:sandboxID/resume”, post(sandboxes::resume_sandbox))
.route(“/sandboxes/:sandboxID/connect”, post(sandboxes::connect_sandbox));
// 全局中间件：请求ID、链路追踪、超时、压缩、跨域
Router::new()
.route("/health", get(health::health))
.merge(sandbox_routes)
.with_state(state)
.layer(
ServiceBuilder::new()
.layer(SetRequestIdLayer::x_request_id(MakeRequestUuid))
.layer(TraceLayer::new_for_http())
.layer(TimeoutLayer::new(Duration::from_secs(30)))
.layer(CompressionLayer::new())
.layer(CorsLayer::permissive()),
)
}
“`
其中几个关键设计决策包括：
- 认证可选化：仅当配置了
auth_callback_url时，才会启用认证和限流中间件。在本地开发场景下，设置E2B_API_KEY=dummy即可通过。 - V1/V2 双版本路由并存：同时暴露
/sandboxes和/v2/sandboxes路由，以兼容不同版本的 E2B SDK。 - 30 秒全局超时：通过
tower_http::TimeoutLayer设置统一超时，防止下游阻塞导致网关被拖垮。
2.2 异步运行时的精细控制
在 main.rs 中，CubeAPI 并未使用 Tokio 的 #[tokio::main] 宏，而是选择手动构建运行时：
rust
// 来源：CubeAPI/src/main.rs
let mut builder = tokio::runtime::Builder::new_multi_thread();
if cfg.worker_threads > 0 {
builder.worker_threads(cfg.worker_threads);
}
let rt = builder
.enable_all()
.thread_name("cube-api-worker")
.build()?;
rt.block_on(async_main(cfg, cli.debug))
这看似微小的选择实际上至关重要——在高并发沙箱创建场景下（例如同时处理50个请求），Tokio worker线程数直接决定了请求调度的并行度。通过 --worker-threads 参数或环境变量进行手动配置，允许运维人员在生产环境中进行精确的性能调优。
三、CubeShim：Rust 实现的 containerd Shim v2
CubeShim 是连接容器编排世界与 MicroVM 世界的“翻译官”。
它完整实现了 containerd Shim v2 协议，使得 containerd 能够像管理普通容器一样进行操作，而实际上，底层每一个“容器”都是一个拥有独立内核的 KVM 虚拟机。
containerd
│ (Shim v2 API)
▼
containerd-shim-cube-rs ← CubeShim
│ (ttrpc / vsock)
▼
cube-agent ← 虚拟机内的 guest agent
│
▼
container workload ← 运行在 MicroVM 内部
3.1 启动时的文件描述符预扩展技巧
CubeShim 的
main.rs中包含一段精妙的底层优化代码：
rust
// 来源：CubeShim/shim/src/main.rs
unsafe {
// Create dummy socket and dup it to large fd, so that we could trigger
// expand_files in kernel. And this tricky work will avoid later multi
// thread try to invoke expand_files at same time, there will be lock
// contention in expand_files.
let dummy = libc::socket(libc::AF_UNIX, libc::SOCK_STREAM | libc::SOCK_CLOEXEC, 0);
if dummy > 0 {
libc::dup2(dummy, 512);
}
}
这段代码在进程启动时创建一个 Unix socket，然后使用 dup2 系统调用将其复制到文件描述符（fd）512。其目的是什么？
Linux 内核维护的文件描述符表（fdtable）在首次访问一个高编号的文件描述符时，会触发 expand_files 函数进行动态扩容，而这个操作需要持有锁。如果在多线程运行时（例如 Tokio 的 worker 线程）才首次触发此扩容，就会产生锁竞争。通过在单线程的启动阶段提前触发并完成扩容，可以彻底规避运行时的锁争用问题。
这是一个典型的“以空间换时间、以启动时间换运行时性能”的系统级编程技巧。
3.2 核心模块划分
CubeShim 的代码结构清晰地映射了其职责边界：
rust
// 来源：CubeShim/shim/src/lib.rs
pub mod common; // 版本信息、公共常量
pub mod container; // 容器生命周期管理（Create/Start/Kill/Delete）
pub mod cube; // Cube 运行时特有逻辑
pub mod hypervisor; // Hypervisor 交互层（VM 创建/销毁）
pub mod log; // 日志基础设施
pub mod sandbox; // 沙箱抽象（一个沙箱 = 一个 VM + N 个容器）
pub mod service; // Shim v2 gRPC 服务实现
pub mod snapshot; // 快照相关功能（暂停/恢复/克隆）
其中，sandbox（沙箱）与 container（容器）模块的分离体现了一个重要的架构设计：
- 在 Kata Containers 等安全容器方案中，一个虚拟机（即一个 sandbox）可以承载多个容器。
- CubeShim 继承了这一模型，但在 AI Agent 场景下，通常采用一个沙箱对应一个容器的“一对一”使用模式。
四、CubeProxy：基于 OpenResty 的智能路由
CubeProxy 解决了关键的“最后一公里”问题：用户的应用或 SDK 如何访问到具体沙箱内的服务端口？
其答案是通过域名编码的路由机制。CubeProxy 会解析 HTTP 请求中 Host 头的特定格式：<端口号>-<沙箱ID>.<域名>，并将其路由到对应虚拟机的对应端口。
“`
来源：CubeProxy/nginx.conf
server {
listen 8080 ssl reuseport;
server_name _;
ssl_certificate /usr/local/openresty/nginx/certs/cube.app+3.pem;
ssl_certificate_key /usr/local/openresty/nginx/certs/cube.app+3-key.pem;
location / {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection “upgrade”;
proxy_send_timeout 7206s;
proxy_read_timeout 7206s;
rewrite_by_lua_file lua/rewrite_phase.lua;
proxy_pass http://backend;
}
}
“`
配置中的几个关键点值得解读：
reuseport：启用SO_REUSEPORT套接字选项，允许多个 Nginx worker 进程各自拥有独立的监听队列，避免了传统的“惊群效应”，在高并发场景下能显著提升连接处理吞吐量。- WebSocket 支持：通过设置
Upgrade和Connection "upgrade"头部，代理能够正确转发 WebSocket 等长连接协议——这对于依赖 Chrome DevTools Protocol (CDP) 的浏览器沙箱等场景至关重要。 - 7206 秒超时：约2小时的超时设置，足以覆盖长时间运行的 AI Agent 任务，同时避免了无限期等待。
- Lua 阶段注入：
rewrite_phase.lua脚本负责从Host头中解析出沙箱 ID 和端口号；balancer_phase.lua脚本则通过lua_shared_dict共享内存查找后端虚拟机的实际 IP 地址。整个路由决策在高效的 Lua 层完成，无需为每个请求都查询中心化的 CubeMaster 服务。
五、Hypervisor 层：基于 Cloud Hypervisor 的深度定制
hypervisor/ 目录是项目中体量最大的 Rust 代码区域，它基于 Cloud Hypervisor 项目进行 fork，并针对 AI 沙箱场景进行了定制。其子模块结构体现了功能的完整性：
vmm/：虚拟机管理器核心，负责虚拟机的创建、配置和运行循环。hypervisor/：KVM 接口抽象层。virtio-devices/：virtio 设备模拟（如网卡、块设备、控制台等）。vm-migration/：虚拟机状态的序列化与反序列化，是快照恢复功能的基础。block_util/、qcow/、vhdx/：提供对多种磁盘格式的支持。arch/：包含 x86_64 架构特定的代码（如 CPUID、MSR 配置等）。
CubeSandbox 能够实现低于 5MB 的单实例内存开销，其核心优化在于以下两点：
- 极致裁剪的客户机操作系统：客户机镜像通过专用 Dockerfile 生成，仅包含最小化的 init 进程（cube-agent）和必要的文件系统。
- 写时复制内存复用：基于快照克隆技术，多个沙箱实例共享同一份客户机内核和根文件系统的物理内存页，仅在被修改的页面产生新的内存分配。
六、CubeVS 与网络安全模型
CubeVS（Cube Virtual Switch）是基于 eBPF 实现的内核态虚拟交换机，位于 CubeNet/cubevs/ 目录。它在数据平面实现了三个核心能力：
- 沙箱间严格网络隔离：确保不同沙箱的网络命名空间彼此不可达，即使它们运行在同一台物理主机上。
- 细粒度出站流量过滤：可根据策略限制沙箱访问外部网络的范围，防止 Agent 被利用后对内网发起攻击。
- 内核态数据包转发：转发过程不经过用户态协议栈，减少了上下文切换的开销。
相较于传统的 iptables/nftables 方案，eBPF 程序直接附加到网络设备的 TC（流量控制）钩子上，在数据包进入协议栈之前即可完成过滤和转发决策，性能损耗极低。
七、一键部署与生产实践
CubeSandbox 的部署流程设计简洁。deploy/one-click/ 目录实现了一个自包含的发布包构建和安装流程：
“`bash
在支持 KVM 的机器上，可通过三步启动
curl -sL …/online-install.sh | bash # 安装服务
cubemastercli tpl create-from-image # 创建模板
–image sandbox-code:latest
–writable-layer-size 1G –expose-port 49999
export E2B_API_URL=”http://127.0.0.1:3000″ # 配置 SDK
“`
安装脚本会自动处理 MySQL/Redis 等依赖的部署、TLS 证书生成（通过内置的 mkcert）、CoreDNS 的 split-DNS 配置，以及所有组件的编排启动。对于多节点场景，计算节点只需设置环境变量 ONE_CLICK_DEPLOY_ROLE=compute 并指定控制平面 IP 地址即可加入集群。
总结与展望
CubeSandbox 代表了 AI 基础设施领域的一个重要趋势：将虚拟化技术下沉为一种透明的安全原语。开发者无需深入理解 KVM、virtio、eBPF 等底层技术，只需像使用 Docker 一样调用兼容的 SDK，即可获得硬件级的隔离保障。
从技术实现角度看，其几个关键选择值得借鉴：
- 使用 Rust 重写关键路径：在 CubeAPI、CubeShim、Hypervisor 等组件中利用 Rust 的内存安全与零成本抽象特性，兼顾了系统编程场景下的性能与可靠性。
- 协议兼容而非重新发明：100% 兼容现有 SDK 接口，将迁移成本降至趋近于零。
- 利用 eBPF 实现网络安全平面：在内核态执行策略，避免了引入额外用户态组件及其带来的性能损耗。
- 通过快照克隆实现亚百毫秒启动：将虚拟机的启动问题转化为内存页的写时复制问题。
根据项目路线图，“事件级快照回滚”是一个值得期待的特性。该功能将允许 Agent 在探索过程中于任意时间点轻量地 fork 出分支环境，类似于 Git 的分支操作，这将为 AI Agent 的树搜索、强化学习训练等场景开辟新的可能性。
CubeSandbox 已在生产环境中经过大规模验证。对于任何正在为 AI Agent 寻找安全执行环境的团队而言，该项目都值得深入评估。
关注“鲸栖”小程序，掌握最新AI资讯
本文来自网络搜集，不代表鲸林向海立场，如有侵权，联系删除。转载请注明出处：http://www.itsolotime.com/archives/30791
