企业官网建设流程全解析

CubeSandbox 全链路追踪指南：Sandbox.create() 如何快速穿越 8 层组件

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox

🚀CubeSandbox是一个面向 AI Agent 的即时、并发、安全、轻量级沙箱服务，基于 RustVMM 和 KVM 构建，兼容 E2B SDK，能在 60ms 内创建一个硬件隔离的沙箱。本文带你做一次「请求全链路追踪」：一行Sandbox.create()调用，是如何穿越SDK → CubeAPI → CubeMaster → Cubelet → CubeShim → CubeHypervisor → CubeVS → Redis/CubeProxy这 8 层组件，最终变为一台毫秒级就绪的 MicroVM 的。无论你是刚接触 AI Agent 沙箱的新手，还是想深入理解其架构的开发者，这篇文章都是一份完整地图 🗺️

一、先看全局：一次调用的 8 层旅程

在深入每一层之前，先整体认识 CubeSandbox 的架构。系统分为控制面（无状态，任意实例可服务任意请求）与数据面（节点本地，管理该节点上的沙箱）：

整个链路的时序如下（摘自 docs/architecture/overview.md）：

Client/SDK ──POST /sandboxes──▶ CubeAPI ──gRPC──▶ CubeMaster ──选节点──▶ Cubelet ◀──201 {sandbox_id}──────────────────────────────┘ │ ▼ CubeShim ──launch_vmm()──▶ CubeHypervisor ──▶ MicroVM 就绪 Cubelet ──AddTAPDevice──▶ CubeVS CubeMaster ──▶ Redis 发布生命周期事件

二、第 1 层：SDK —— 一切从 Sandbox.create() 开始

你只需一行代码（完整参数说明见 sandbox.py）：

sb = Sandbox.create(template="base", timeout=600)

SDK 内部把template、timeout、env_vars、network（出网策略）、lifecycle（自动暂停/恢复）等参数序列化后，发出一个POST /sandboxes的 E2B 兼容 REST 请求。得益于 E2B 兼容设计，从 E2B Cloud 迁移过来通常只需替换 API 地址等环境变量。

三、第 2 层：CubeAPI —— E2B 协议到内部协议的翻译官

CubeAPI 是 Rust（Axum）编写的 REST 网关。请求先命中路由 routes.rs，再由 create_sandbox handler 接收。

真正的工作在 services/sandboxes.rs：

• 参数校验：环境变量合法性、卷挂载名唯一性等，危险配置在这里就被拦截 ❌
• 协议翻译：把 E2B 风格请求转成内部 gRPCCreateSandboxRequest（含模板注解、网络配置、生命周期标志）
• gRPC 转发：通过 cubemaster/mod.rs 中的create_sandbox()调用 CubeMaster

接口契约定义在 pkgs/proto/services/cubebox/v1/cubebox.proto。CubeAPI不保存任何本地状态，因此可以水平扩展。

四、第 3 层：CubeMaster —— 决定沙箱住在哪里

CubeMaster 是 Go 编写的集群调度器，入口在 CreateSandbox。它做三件关键的事：

1. 资源匹配：基于节点资源水位，从候选节点中选出目标节点（支持distribution_scope指定节点）
2. 任务派发：通过 gRPCRunCubeSandbox把任务下发给目标节点的 Cubelet，失败可自动换节点重试
3. 事件发布：成功后向Redis发布生命周期事件——这是 CubeProxy 路由表和 cube-lifecycle-manager（负责空闲自动暂停/唤醒）的数据源

由于所有协调都走 Redis，CubeMaster 自身也无状态，任意副本都能接管请求。

五、第 4 层：Cubelet —— 节点上的「总管家」

Cubelet 是节点本地调度 Agent（Go），负责本节点上所有沙箱实例的完整生命周期：create → run → pause → resume → snapshot → destroy。创建时的核心动作（见 Cubelet/services/cubebox/service.go）：

• 📦存储准备：调用 CubeCoW 引擎，用内核FICLONE（reflink）从模板 O(1) 克隆出 rootfs 卷和内存卷——零数据拷贝，这是毫秒级启动的关键
• 🖼️镜像就绪：与 containerd 集成，确保模板镜像已拉取
• 🚪下发启动：以 containerd Shim v2 方式把创建任务交给 CubeShim

六、第 5 层：CubeShim —— 容器世界与 MicroVM 的桥

CubeShim（Rust，见 CubeShim/shim/src）实现了containerd Shim v2接口，是「容器抽象」与「真实 MicroVM」之间的桥：

• 准备 VM 资源：rootfs 设备、内存文件、内核
• 调用launch_vmm() → create_vm() → restore_vm()启动虚拟机
• 管理 vsock 通信通道（沙箱内 envd 与宿主机的对话管道）
• 支持原地快照，为 AutoPause 提供基础

七、第 6 层：CubeHypervisor —— 硬件隔离的真正执行者

CubeHypervisor 是基于RustVMM + KVM的轻量 VMM（见 hypervisor/vmm），负责 MicroVM 的 vCPU、内存区域和 virtio 设备（块设备、网络、vsock、文件系统）。

✨性能核心在这里：沙箱不是「冷启动」，而是从预快照模板恢复。每个沙箱运行在独立内核、独立 MicroVM 中，没有共享内核的攻击面，同时获得亚 100ms 的启动速度。

八、第 7 层：CubeVS —— 纯 eBPF 的内核态网络

VM 就绪后，Cubelet 调用 CubeVS 完成AddTAPDevice + AttachFilter。CubeVS 是 eBPF 网络数据面（CubeNet/cubevs），每个沙箱拥有独立 TAP 设备，但没有 iptables 规则爆炸、没有 Linux Bridge：

• 逐沙箱 SNAT/DNAT：BPF Map 替代防火墙规则
• 有状态连接跟踪：TCP 11 态状态机、UDP、ICMP
• LPM-trie 网络策略：按 CIDR/域名做 L3/L4/L7 过滤，线速执行
• 默认拒绝私网/链路本地段，出网流量还可被 TPROXY 到 CubeEgress 做 L7 审查

九、第 8 层：Redis + CubeProxy —— 状态协调与业务流量入口

最后一层让沙箱真正「可用」：

• Redis：沙箱元数据、生命周期事件流、分布式锁的单一事实来源（cube-lifecycle-manager 据此实现空闲自动暂停、请求到达自动唤醒）
• CubeProxy（OpenResty）：解析<port>-<sandbox_id>.<domain>形式的 Host 头，把外部 HTTP 请求路由到对应沙箱的对应端口

至此，Sandbox.create()的响应（201 { sandbox_id, ... }）已经回到 SDK 手中，沙箱同时可以对外提供网络服务 🎉

十、为什么这条链路能快到 60ms？

总结：一次调用，八层协作

回顾这次全链路追踪：SDK发出请求 →CubeAPI翻译协议 →CubeMaster调度选点 →Cubelet准备存储 →CubeShim拉起 VM →CubeHypervisor快照恢复 →CubeVS接通网络 →Redis/CubeProxy完成状态与路由。每一层都单一职责、可独立水平扩展，共同构成了这个「比眨眼更快」的 AI Agent 沙箱。

📚 延伸阅读：

• 架构总览：docs/architecture/overview.md
• 网络模型深潜：docs/architecture/network.md
• 生命周期（自动暂停/恢复）：docs/guide/lifecycle.md
• 性能基准：docs/guide/performance-benchmark.md
• 快照/克隆/回滚：docs/guide/snapshot-rollback-clone.md

【免费下载链接】CubeSandboxInstant, Concurrent, Secure & Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox