SPACE沙箱生命周期完全指南:Running/Paused/Suspended三种状态如何选?附pause/suspend/wake实战

原创2026-10-18 12:34:521,286 阅读

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沙箱集群部署架构

图: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),勿用休眠"养"着

两个补充事实:

  1. ECW(E2B 兼容接口)只映射 suspend 路径:pause 对应 SPACE 的 suspend,resume 对应 restore;它不暴露驻留内存的 pause/resume(见 docs/ecw.md)。
  2. 自动生命周期策略支持按空闲自动执行暂停或休眠(协议中 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 恢复或还原沙箱

实战要点:

  1. 每个变更请求都带 Idempotency-Key 头,避免超时重试造成重复操作;
  2. 请求成功后返回一个 operation,轮询它直到成功,不要只凭 HTTP 200 下结论;
  3. wake 完成后,重复执行 running 状态与进程就绪检查,再执行下一条命令;
  4. 对 suspended 的沙箱直接发命令是不行的——先 wake,再操作。

SPACE沙箱Pod视图与就绪状态

图:沙箱 Pod 视图缓存机制 —— 各组件通过 watcher 与缓存读取沙箱身份、就绪与槽位状态,理解 wake 后"何时算真正可用"的关键

✅ 避坑清单

  • ❌ 把"状态已变更"当成"立即可用":wake 后必须再查 ready;
  • ❌ 忘记 Idempotency-Key:超时后无法安全重试;
  • ❌ 用 ECW 的 pause 期待"驻留内存暂停":它实际执行的是 suspend;
  • ❌ 用 suspended 沙箱长期替代删除:快照同样占存储,无用沙箱请删除。

📚 延伸阅读

登录后查看全文
SPACE