企业官网建设流程全解析

如何读懂 CubeSandbox 的 Cubelet：节点本地调度代理如何管理沙箱全生命周期（完整指南）

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

CubeSandbox 是一款为 AI Agent 打造的即时、并发、安全且轻量的沙箱平台，而它最关键的“节点级执行者”就是Cubelet——一个用 Go 编写的节点本地调度代理，负责管理单台计算节点上所有沙箱实例的完整生命周期：创建、运行、暂停、恢复、快照与销毁。如果你想在自建集群中理解“一次Sandbox.create()请求落到节点后到底发生了什么”，这篇文章就是你要的 Cubelet 深度解析。

为什么需要 Cubelet：控制面与数据面的分工

CubeSandbox 采用无状态控制面 + 节点本地数据面的架构（详见 docs/architecture/overview.md）：

CubeMaster 只负责“选哪台机器”，真正的“怎么把沙箱跑起来”全部交给节点上的 Cubelet。这种分离带来两个好处：控制面可随意水平扩展，节点故障时只需重新调度，无需迁移本地状态。

Cubelet 的创建全流程：从 gRPC 请求到 MicroVM 就绪

当一个创建请求经过 CubeMaster 选点后，会以gRPC RunCubeSandbox的形式发送到目标节点的 Cubelet，随后 Cubelet 按顺序完成以下工作：

1. 准备 rootfs：调用 cubecow（XFS reflink 引擎）从模板以 O(1) 成本克隆出根文件系统卷，零数据拷贝；
2. 拉起运行时：通过 containerd Shim v2 接口调用 CubeShim，执行Create + Start；
3. 启动虚拟机能：CubeShim 调用 CubeHypervisor（RustVMM + KVM）完成create_vm()→restore_vm()，毫秒级恢复预快照；
4. 接入网络：调用 CubeVS 的AddTAPDevice + AttachFilter，为该沙箱挂载 eBPF 网络策略；
5. 回报状态：向 CubeMaster 返回 running，事件写入 Redis 供 CubeProxy 路由。

对应的时序细节可以阅读 docs/architecture/overview.md 中的 Request Lifecycle 小节，服务主体实现位于 service.go。

沙箱状态模型：Cubelet 如何守护五种状态

每个沙箱在任何时刻都处于且仅处于一种状态（完整说明见 docs/guide/lifecycle.md）：

Cubelet 内部用一系列“卡住阈值”守护这些瞬时态，例如 service.go 中定义了createStuckThreshold = 2 × 创建截止时间：只有当沙箱在CONTAINER_CREATED中间态停留超过 2 倍创建超时，DeadGC 才会将其判定为真正卡死并回收——既避免误杀正常创建，又保证故障不累积。

暂停与恢复：快照是 Cubelet 的看家本领

Cubelet 的暂停/恢复能力由多个专门模块协作完成（位于 Cubelet/services/cubebox/）：

• pause_cow.go：暂停时通过 CubeCoW 只持久化脏内存页，未变化页继续以 reflink 共享，快照体积与写放大都最小化；
• pause_package.go：将快照打包，为跨节点恢复做准备；
• cross_node_restore.go：支持把暂停的沙箱恢复到集群中另一台节点，实现“快照跟随调度”；
• rollback.go：支持回滚到历史快照版本。

配合 CubeProxy 侧的 cube-lifecycle-manager，空闲沙箱会被自动暂停，收到请求时再透明恢复——用户几乎无感，成本却降到接近零。

节点级支撑能力：网络、存储与镜像

Cubelet 并不孤立，它把节点上的所有资源抽象成插件化模块：

• 网络：Cubelet/network/ 实现 TAP 设备创建、策略下发等插件，与 eBPF 数据面 CubeNet 协作，为每个沙箱提供 per-VM 的 SNAT/连接跟踪而不会导致 iptables 规则爆炸；
• 存储：Cubelet/storage/ 封装卷池、reflink 池与 S3 持久化（s3_pause_memory_src_test.go等文件可见暂停内存上传 S3 的完整链路）；
• 镜像：Cubelet/plugins/cube/images/ 对接 containerd 完成镜像拉取与加速分发，API 定义见 hostimage.proto 生成的文档 cubelet-api.md。

这些能力共同保证了高并发下“百毫秒级冷启动 + 零拷贝克隆”的承诺。

如何观察与排查 Cubelet：从 CLI 到日志

• 命令行：Cubelet/cmd/cubecli/ 提供节点级运维 CLI，可查询沙箱列表、状态与指标；集群侧工具见 docs/guide/cli-tools.md；
• 日志定位：各组件日志位置汇总在 docs/guide/troubleshooting/component-log-locations.md；
• 节点运维：节点上下线、扩缩容操作参见 docs/guide/node-operations.md；
• 配置：单机部署的 Cubelet 配置样例位于 configs/single-node/cubelet.yaml。

写在最后：Cubelet 在 CubeSandbox 中的角色小结

🎯一句话总结：Cubelet 是 CubeSandbox 数据面的“大管家”——它把控制面的一条 gRPC 指令，翻译成 rootfs 克隆、Shim 启动、MicroVM 恢复、eBPF 网络挂载这一整套节点本地动作，并用阈值守护与事件上报保证沙箱状态永远可追踪。

理解了 Cubelet，你就理解了 CubeSandbox“毫秒级启动、并发可扩展、暂停零成本”这三项核心卖点的实现根基。接下来推荐阅读：

• 整体架构：docs/architecture/overview.md
• 网络模型深度解析：docs/architecture/network.md
• 沙箱生命周期指南：docs/guide/lifecycle.md

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