CubeSandbox沙箱生命周期状态机全解：从create到destroy的完整旅程-平芜编程栈

CubeSandbox沙箱生命周期状态机全解：从create到destroy的完整旅程

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

CubeSandbox 是一个专为 AI Agent 打造的即时、并发、安全且轻量的沙箱平台。理解 CubeSandbox 沙箱生命周期状态机，是掌握它从create到destroy完整旅程的第一步：每个沙箱始终处于running、pausing、paused、resuming、terminated这 5 种状态之一，由timeout、on_timeout、auto_resume三个开关驱动流转。本文带你一次看懂这套状态机。

状态机全览：5个状态一次看懂

CubeSandbox 中，沙箱是核心运行时单元，任意时刻只处于以下 5 个状态之一：

状态	含义	是否消耗 CPU/内存
`running`	活跃运行中，可接受请求、执行代码	✅ 是
`pausing`	平台正在对 VM 打快照（瞬时过渡态）	正在释放
`paused`	快照已落盘，零CPU/内存成本，完整状态保留	❌ 否
`resuming`	平台正在从快照恢复（瞬时过渡态）	正在重建
`terminated`	被`kill()`或超时回收，不可恢复	❌ 否

其中pausing和resuming只是短暂过渡，你几乎看不到它们；真正需要理解的是三条主干路径：

活跃路径：running↔paused（由 connect / 自动恢复触发）
终结路径：任意状态 →terminated（kill()永远优先）
时间路径：空闲超时 → 根据on_timeout走向paused或terminated

💡 直觉记忆：pause 是"存档"，kill 是"删档"。

第一步：Create —— 从模板到 running

沙箱由模板启动。调用Sandbox.create()后，平台完成调度、资源分配与 VM 启动，状态进入running。创建时你只需关心几个关键参数：

参数	作用
`template`	启动所用模板 ID
`timeout`	空闲多少秒后触发超时（省略则由集群默认值决定）
`lifecycle`	生命周期策略（`on_timeout`/`auto_resume`）
`metadata`/`env_vars`	自定义键值对 / 注入的环境变量

timeout的取值有讲究：-1（NEVER_TIMEOUT）表示永不超时；0表示首次空闲扫描即回收；正整数 N 表示空闲 N 秒后触发。创建成功后，get_info()会返回startedAt与endAt——后者就是按当前timeout预测的下次超时时刻，每次有请求到达都会刷新。

第二步：Pause —— 把运行态"存档"到零成本

调用pause()（或空闲超时且on_timeout="pause"）后，沙箱进入pausing：平台将 VM 的 CPU 寄存器、进程内存、TCP 状态与文件系统变更全部冻结进快照，完成后状态变为paused，CPU 和内存被物理回收，成本归零，而进程状态完整保留。

快照存储在底层走的是 CoW（写时复制）+ reflink 的极速路径——paused状态不占计算资源，只占存储。

⚠️ 注意：手动pause()不会取消空闲回收。默认on_timeout="kill"下，已暂停的沙箱若空闲超过timeout仍会被销毁。想让暂停的沙箱长期存活，请传timeout=NEVER_TIMEOUT。

第三步：Resume —— 无感唤醒回 running

从paused回到running有两条路：

显式恢复：调用sandbox.connect()，快照被还原，继续执行时"如同从未暂停过"；
自动恢复：创建时设置lifecycle={"on_timeout": "pause", "auto_resume": True}，之后任何请求（HTTP、run_code、文件 I/O）到达一个paused沙箱时，平台会在请求落地前先把它唤醒——调用方完全无感，典型恢复延迟在亚秒到数秒级。

每次自动恢复都会重置空闲时钟（超时时长不变），因此"恢复 → 短用 → 空闲 → 再暂停"的循环可以无限重复。这正是 Agent 工作负载的理想形态：用户输入 → 模型思考 → 沙箱执行 → 空闲时被自动暂停省资源。

另有两个细节值得了解：

恢复会重建 guest 网卡与主机端口并重写代理路由，CubeProxy 的本地缓存会被同步清理，避免流量仍指向暂停前的旧 IP；
若节点资源不足，resume 可能被准入检查拒绝（HTTP 409，可重试）——这由节点级配置paused_resource_release_ratio控制，0表示暂停沙箱始终保留配额（恢复永不失败），1表示配额完全释放（最大化密度）。

第四步：Terminate —— kill 与 destroy 的终局

terminated是唯一的终点，不可逆：

显式kill()：无论沙箱处于running还是paused，无论是否配置了on_timeout="pause"，kill()都优先生效并丢弃快照；
超时回收：on_timeout="kill"（默认）时，空闲超过timeout即被销毁，下一个请求会得到410 Gone，SDK 客户端应停止重试；
删除 paused 沙箱：DELETE接口会直接移除暂停墓碑、删除暂停快照并清理控制面元数据——它不会先恢复 MicroVM，也无需节点容量准入，清理完成后同步返回204 No Content。

幕后机制：CubeMaster 与 CLM 如何协同

状态机的"手脚"由两个组件分工完成，源码可查：

组件	职责
CubeMaster	控制面单写者：成功 pause/resume 后向 Redis Stream 广播`state`事件（只广播`paused`/`running`两个终态），元数据快照存于`lifecycle:meta`
cube-lifecycle-manager（CLM）	自动暂停/恢复协调者：消费事件流，持有每沙箱状态键（`running`/`pausing`/`paused`/`resuming`/`killing`/`killed`），负责空闲扫描（sweeper）与自动唤醒（resumer）

协调上有几个精巧设计：

事件流 + 快照双通道：CLM 多副本各自消费 append-only 事件流，启动时从元数据快照引导，保证每个热备副本都持有完整注册表；
过渡锁语义：pausing/resuming等过渡标记只存在于 CLM 的 per-sandbox 状态键中，通过SETNX过渡锁保证同一沙箱的 pause/resume 串行执行，多副本不会打架；
领导选举：Kubernetes 部署默认 2 个热备副本，Redis 租约选出唯一执行者做空闲扫描与清理，副本故障切换后最多多做一次 pause/resume，下个请求照常自动恢复。

关键源码位置：

事件与状态定义：CubeMaster/pkg/lifecycle/schema.go
Redis 写入实现：CubeMaster/pkg/lifecycle/store.go
状态键协调（CLM 侧镜像）：cube-lifecycle-manager/internal/lifecycle/schema.go

一条完整的旅程串起来

把上面所有内容连成一条 Agent 沙箱的典型旅程：

create(timeout=300, lifecycle={on_timeout:"pause", auto_resume:True})→ 沙箱进入running；
执行完一段代码后空闲 5 分钟 → CLM 空闲扫描触发自动暂停，running → pausing → paused，CPU/内存归零；
用户下一轮对话的请求到来 → CubeProxy 回调 CLM 的/internal/resume，paused → resuming → running，请求无感落地，空闲时钟重置；
如此循环 N 轮……用户最终kill()或会话结束 →terminated，快照与资源全部释放。