Skip to main content

休眠与唤醒

OpenKruise Agents 允许将运行中的沙箱 休眠（pause），使其停止消耗 CPU / 内存；之后再 唤醒（resume），回到运行态。整个过程中沙箱身份保持不变（同一个 sandboxID、同一个 Pod）。

⚠️ 该能力仍在持续演进。底层的捕获机制（是否保留内存状态、是否对文件系统做检查点等）依赖集群环境（例如内存态保留目前仅在阿里云 ACS 支持）。本文只介绍如何使用 API；关于状态保留的具体保证请参考平台运维手册。

概述​

提供两种并列的接入方式，底层操作的都是同一个 Sandbox 资源：

接入方式面向的使用者典型场景
E2B SDK（pause / connect）基于 E2B Python / JavaScript SDK 的应用代码在空闲时编程式休眠、按需唤醒
Kubernetes CRD集群运维、声明式 GitOps、kubectl 或自定义控制器切换 spec.paused 或配置 spec.pauseTime

休眠 / 唤醒是 一对一 的：整个 pause → resume 过程中，沙箱 ID 保持不变。若需要「快照后克隆多个新沙箱」这种一对多的工作流，请参考 快照管理。

工作原理（简述）​

  1. 休眠（Pause）：冻结沙箱 Pod。所有活动的 WebSocket / PTY / 命令流连接都会断开，客户端需要在唤醒后重连。
  2. 唤醒（Resume）：将 Pod 恢复为运行态。沙箱 ID 保持不变。
  3. 捕获的具体范围（内存 / 文件系统）取决于运行时平台以及其背后 SandboxSpec 的配置。

休眠沙箱​

E2B SDK 在沙箱句柄上暴露了 pause() 方法，底层调用 POST /sandboxes/{sandboxID}/pause。

from e2b_code_interpreter import Sandbox

with Sandbox.create(template="code-interpreter", timeout=300) as sbx:
    sbx.run_code("a = 1")
    sbx.pause()  # 沙箱进入 paused 状态；sandboxID 保持不变
import { Sandbox } from 'e2b'

const sbx = await Sandbox.create({ template: 'code-interpreter', timeoutMs: 300_000 })
await sbx.betaPause()

注意事项：

  • 对非 running 状态的沙箱执行 pause 会返回 409 Conflict。
  • 休眠期间沙箱 不会 被自动删除——空闲超时计时会在休眠期间被关闭。

自动休眠（Auto Pause）​

除了显式调用 pause，还可以在创建沙箱时声明 到期自动进入 paused——到时间后沙箱不会被销毁，而是转为 paused 状态，保留身份等待后续唤醒。

参考 E2B 官方文档 - Auto-pause：创建沙箱时将 lifecycle.on_timeout 设为 "pause"。

from e2b_code_interpreter import Sandbox

sbx = Sandbox.create(
    template="demo",
    timeout=600,  # 10 分钟；到期后进入 paused，而不是被删除
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": False,  # 见下方说明
    },
)
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create({
  template: 'demo',
  timeoutMs: 10 * 60 * 1000, // 10 分钟；到期后进入 paused
  lifecycle: {
    onTimeout: 'pause',
    autoResume: false, // 见下方说明
  },
})

⚠️ 当前 OpenKruise Agents 尚未实现 auto_resume。 即使将其显式设为 true，休眠中的沙箱也 不会 被自动唤醒；客户端仍需在需要时显式调用 Sandbox.connect(sandbox_id, ...)（见下一节）。建议显式写为 false 以表明语义。

唤醒沙箱​

E2B SDK 侧 推荐 使用 Sandbox.connect(...)——它会隐式地唤醒一个休眠中的沙箱，同时刷新其 timeout。遗留的 resume 端点仅出于向后兼容而保留，新代码不应再使用。

from e2b_code_interpreter import Sandbox

sbx = Sandbox.connect(sandbox_id, timeout=300)  # 如果休眠则唤醒，并刷新 timeout
sbx.run_code("print(a)")
import { Sandbox } from 'e2b'

const sbx = await Sandbox.connect(sandboxId, { timeoutMs: 300_000 })

注意事项：

  • 若沙箱已经在运行，connect 只会刷新 timeout，并且是 只延长（extend-only） 策略：永远不会缩短剩余时间。（例外：paused → running 的唤醒会直接采用请求的 timeout。）
  • 对不存在或不属于当前 API-key 用户的沙箱调用 connect 会返回 404 Not Found。

能力矩阵​

能力E2B SDKKubernetes CRD
休眠运行中的沙箱✅ sbx.beta_pause()✅ spec.paused: true
唤醒休眠中的沙箱✅ Sandbox.connect(id, ...)✅ spec.paused: false
到 timeout 时自动触发 pause✅ lifecycle.on_timeout='pause'❌
在绝对时间点自动触发 pause❌✅ spec.pauseTime
自动唤醒（auto-resume）❌ 暂不支持❌ 暂不支持
唤醒的同时设置 / 刷新 timeout✅ Sandbox.connect(id, timeout=...)✅ 同一次 patch 中写 spec.shutdownTime / spec.pauseTime
运行态下对 timeout 的只延长（extend-only）保护✅❌ 用户写入值可缩短
观察 paused / running 状态通过 SDK 响应status.phase（Paused / Running）

如果你需要「只延长、永不缩短」的 timeout 刷新语义，请走 E2B SDK；CRD 路径更适合声明式 / GitOps 批量管控「暂停 / 运行 + 绝对时间」的场景。

注意事项​

  • 连接会断开。 休眠时 Pod 被冻结，所有活动连接（WebSocket / PTY / 命令流）都会断开，客户端需要在唤醒后重连。
  • 休眠期间的生命周期。 休眠中的沙箱不会因为空闲超时而被自动删除，自动删除由 spec.shutdownTime 独立控制。
  • 旧版 SDK。 遗留的 POST /sandboxes/{sandboxID}/resume 端点仅为旧版 SDK 兼容保留。新代码一律使用 Sandbox.connect(...)。
  • 状态保留取决于平台。 跨休眠/唤醒是否保留内存状态依赖具体的运行时平台。如果你需要显式的内存 + 文件系统快照、并且希望能克隆出全新沙箱，请使用 快照管理。