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

CubeSandbox 全链路追踪指南Sandbox.create() 如何快速穿越 8 层组件【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox是一个面向 AI Agent 的即时、并发、安全、轻量级沙箱服务基于 RustVMM 和 KVM 构建兼容 E2B SDK能在 60ms 内创建一个硬件隔离的沙箱。本文带你做一次「请求全链路追踪」一行Sandbox.create()调用是如何穿越SDK → CubeAPI → CubeMaster → Cubelet → CubeShim → CubeHypervisor → CubeVS → Redis/CubeProxy这 8 层组件最终变为一台毫秒级就绪的 MicroVM 的。无论你是刚接触 AI Agent 沙箱的新手还是想深入理解其架构的开发者这篇文章都是一份完整地图 ️一、先看全局一次调用的 8 层旅程在深入每一层之前先整体认识 CubeSandbox 的架构。系统分为控制面无状态任意实例可服务任意请求与数据面节点本地管理该节点上的沙箱层级组件语言职责1️⃣Python SDKSandbox.create()Python构造 E2B 兼容的 REST 请求2️⃣CubeAPIRustAPI 网关鉴权、参数校验、协议翻译3️⃣CubeMasterGo集群调度选节点、派发任务、发布事件4️⃣CubeletGo节点 Agent准备 rootfs、管理沙箱生命周期5️⃣CubeShimRustcontainerd Shim v2桥接容器运行时与 MicroVM6️⃣CubeHypervisorRustRustVMM KVMVM 的创建与快照恢复7️⃣CubeVSeBPF内核态网络数据面SNAT/DNAT、策略过滤8️⃣Redis CubeProxyGo/Lua状态协调 请求路由业务流量入口整个链路的时序如下摘自 docs/architecture/overview.mdClient/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.pysb Sandbox.create(templatebase, timeout600)SDK 内部把template、timeout、env_vars、network出网策略、lifecycle自动暂停/恢复等参数序列化后发出一个POST /sandboxes的 E2B 兼容 REST 请求。得益于 E2B 兼容设计从 E2B Cloud 迁移过来通常只需替换 API 地址等环境变量。三、第 2 层CubeAPI —— E2B 协议到内部协议的翻译官CubeAPI 是 RustAxum编写的 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。它做三件关键的事资源匹配基于节点资源水位从候选节点中选出目标节点支持distribution_scope指定节点任务派发通过 gRPCRunCubeSandbox把任务下发给目标节点的 Cubelet失败可自动换节点重试事件发布成功后向Redis发布生命周期事件——这是 CubeProxy 路由表和 cube-lifecycle-manager负责空闲自动暂停/唤醒的数据源由于所有协调都走 RedisCubeMaster 自身也无状态任意副本都能接管请求。五、第 4 层Cubelet —— 节点上的「总管家」Cubelet 是节点本地调度 AgentGo负责本节点上所有沙箱实例的完整生命周期create → run → pause → resume → snapshot → destroy。创建时的核心动作见 Cubelet/services/cubebox/service.go存储准备调用 CubeCoW 引擎用内核FICLONEreflink从模板 O(1) 克隆出 rootfs 卷和内存卷——零数据拷贝这是毫秒级启动的关键️镜像就绪与 containerd 集成确保模板镜像已拉取下发启动以 containerd Shim v2 方式把创建任务交给 CubeShim六、第 5 层CubeShim —— 容器世界与 MicroVM 的桥CubeShimRust见 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/DNATBPF Map 替代防火墙规则有状态连接跟踪TCP 11 态状态机、UDP、ICMPLPM-trie 网络策略按 CIDR/域名做 L3/L4/L7 过滤线速执行默认拒绝私网/链路本地段出网流量还可被 TPROXY 到 CubeEgress 做 L7 审查九、第 8 层Redis CubeProxy —— 状态协调与业务流量入口最后一层让沙箱真正「可用」Redis沙箱元数据、生命周期事件流、分布式锁的单一事实来源cube-lifecycle-manager 据此实现空闲自动暂停、请求到达自动唤醒CubeProxyOpenResty解析port-sandbox_id.domain形式的 Host 头把外部 HTTP 请求路由到对应沙箱的对应端口至此Sandbox.create()的响应201 { sandbox_id, ... }已经回到 SDK 手中沙箱同时可以对外提供网络服务 十、为什么这条链路能快到 60ms优化点所在层效果快照恢复代替冷启动CubeHypervisor跳过内核/系统启动流程FICLONEreflink 克隆Cubelet CubeCoWrootfs/内存卷 O(1) 复制零拷贝无状态控制面 Redis 协调CubeAPI/CubeMaster任意副本服务天然高并发纯 eBPF 网络数据面CubeVS无 iptables 规则开销线速策略执行总结一次调用八层协作回顾这次全链路追踪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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考