SPACE沙箱生命周期完全指南:Running/Paused/Suspended三种状态如何选?附pause/suspend/wake实战
SPACE沙箱生命周期完全指南:Running/Paused/Suspended三种状态如何选?附pause/suspend/wake实战
SPACE 是一款面向 AI Agent 的沙箱代码执行平台(Sandboxed Platform for Agentic Code Execution),用 Firecracker 微虚机把 agent 与用户代码隔离运行。理解 SPACE 沙箱生命周期,核心就是搞清 running(运行)、paused(暂停)、suspended(休眠) 三种状态的区别,以及 pause、suspend、wake 三个操作分别适用什么场景。本文结合官方文档与协议定义,带你快速做出正确选择。
🧭 三种状态,一句话讲清
在 SPACE 的 API 层面,沙箱对外呈现三种主要状态:
| 状态 | VM 是否驻留节点 | 内存/文件系统 | 恢复速度 | 资源成本 |
|---|---|---|---|---|
| Running | ✅ 驻留 | 实时 | 无需恢复 | 持续占用 |
| Paused | ✅ 驻留 | 冻结但保留 | ⚡ 极快(解冻 vCPU) | 仍占内存 |
| Suspended | ❌ 已释放 | 持久化到磁盘/对象存储 | 中等(从快照恢复) | ≈ 0 |
💡 简单记法:paused 是"屏保",suspended 是"关机前存档"。
图:SPACE 参考部署架构 —— 沙箱由 sandbox-manager 编排、node-manager 在节点上真正拉起 Firecracker 微虚机
🔬 状态背后:内部状态机
你在 API 里看到的 running / paused / suspended,背后对应一套更细的内部状态机。沙箱管理服务用一组 SandboxState 表示完整生命周期,包括 Starting、Started、Pausing、Paused、Resuming、Suspending、Suspended、Restoring 等(定义见 state.rs)。
对外协议里三个关键 RPC 的语义写得很直白(见 manager.proto):
| RPC | 官方注释语义 |
|---|---|
Pause |
冻结 vCPU,进程保持存活(Pause a running sandbox, freeze vCPUs, process stays alive) |
Suspend |
FC vmstate + 完整内存快照 + 停止,释放资源 |
Wake |
从任意休眠状态唤醒,恢复面向 guest 的访问 |
也就是说:暂停只是"按了暂停键",休眠才是"存档并关闭虚拟机"。
⚡ Running:随时可跑的状态
沙箱创建成功后进入 running。此时你可以随时创建命令会话并执行代码,命令输出通过事件流实时返回。官方 Python 示例 first_sandbox.py 演示了完整的"创建 → 等待 running → 执行命令 → 查看进程 → 删除"流程(见 docs/first-sandbox.md)。
⚠️ 注意:running 不等于你的应用已就绪。命令执行要求进程端点就绪;wake 之后同样需要重新检查 running 状态与进程就绪后再发命令。
😴 Paused:驻留内存的"屏保"
调用 pause 后:
- vCPU 被冻结,guest 内所有进程暂停在"现场";
- VM 仍然驻留在原节点,内存内容原封不动;
- 恢复(resume/wake)只是解冻 vCPU,几乎无感。
适用场景:用户暂时离开但马上回来(几十秒到几分钟)、需要保持网络连接或会话上下文的短中断。
💾 Suspended:完整存档 + 释放资源
调用 suspend 后:
- 保存 VM 状态(vmstate)、完整内存快照和文件系统变更;
- 停止并释放该沙箱的活跃 VM 资源(节点内存、CPU 立即归还);
- 恢复时从持久化快照重建沙箱,甚至可以跨节点恢复(快照存于对象存储),因此不受单机容量限制。
适用场景:长时间空闲(小时到天级)、多租户集群需要回收高密度资源。这也是成本敏感场景的首选。
⚖️ 如何选择?决策速查
| 你的场景 | 推荐操作 |
|---|---|
| 用户切到别的标签页,几秒后回来 | 保持 Running(或依赖自动空闲策略) |
| 中断几分钟,需秒级恢复、保持会话 | pause → wake |
| 闲置数小时以上、想释放节点资源 | suspend → wake |
| 沙箱不再需要 | 直接删除(DELETE),勿用休眠"养"着 |
两个补充事实:
- ECW(E2B 兼容接口)只映射 suspend 路径:
pause对应 SPACE 的suspend,resume对应restore;它不暴露驻留内存的 pause/resume(见 docs/ecw.md)。 - 自动生命周期策略支持按空闲自动执行暂停或休眠(协议中
AUTO_LIFECYCLE_IDLE_ACTION_PAUSE/_SUSPEND),可以让平台替你选择。
🛠️ pause / suspend / wake 实战(Native API)
三个生命周期接口如下(摘自 docs/first-sandbox.md):
| 生命周期请求 | 效果 |
|---|---|
POST /v1/sandboxes/{id}:pause |
保持 VM 驻留、暂停执行 |
POST /v1/sandboxes/{id}:suspend |
保存 VM 状态与文件系统,释放活跃 VM 资源 |
POST /v1/sandboxes/{id}:wake |
恢复或还原沙箱 |
实战要点:
- 每个变更请求都带
Idempotency-Key头,避免超时重试造成重复操作; - 请求成功后返回一个 operation,轮询它直到成功,不要只凭 HTTP 200 下结论;
wake完成后,重复执行 running 状态与进程就绪检查,再执行下一条命令;- 对 suspended 的沙箱直接发命令是不行的——先
wake,再操作。
图:沙箱 Pod 视图缓存机制 —— 各组件通过 watcher 与缓存读取沙箱身份、就绪与槽位状态,理解 wake 后"何时算真正可用"的关键
✅ 避坑清单
- ❌ 把"状态已变更"当成"立即可用":wake 后必须再查 ready;
- ❌ 忘记
Idempotency-Key:超时后无法安全重试; - ❌ 用 ECW 的
pause期待"驻留内存暂停":它实际执行的是suspend; - ❌ 用 suspended 沙箱长期替代删除:快照同样占存储,无用沙箱请删除。
📚 延伸阅读
- 第一个沙箱完整流程:docs/first-sandbox.md
- 暖池(让创建更快):docs/warm-pools.md
- ECW 兼容层行为:docs/ecw.md
- 生命周期协议定义:proto/sandbox/manager/v1/manager.proto
- 内部状态机源码:crates/libs/sbx/mgr/server/src/state.rs

