CubeSandbox 沙箱生命周期完全指南：创建、暂停恢复、自动回收与资源配额的实战与原理

CubeSandbox 沙箱生命周期完全指南创建、暂停恢复、自动回收与资源配额的实战与原理【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox沙箱Sandbox是 CubeSandbox 的核心运行单元理解其生命周期——从创建、运行、暂停/恢复到销毁——是使用与运维这套 AI Agent 沙箱平台的基础。本文以官方生命周期文档为主体结合 CubeMaster、Cubelet、CubeProxy 等仓库源码与端到端示例系统讲解状态模型、timeout/on_timeout/lifecycle配置语义、显式与自动的暂停/恢复/销毁操作以及集群级默认空闲超时和节点级暂停资源配额等运维要点帮助你为 Agent 工作负载设计自动暂停、按需唤醒、成本可控的运行策略。沙箱状态模型一个沙箱在它的生命周期里会处于以下几种状态之一状态含义running正在运行CPU/内存被实际占用可以接收请求与执行代码pausing平台正在暂停沙箱保存 VM 快照中瞬时态paused沙箱已暂停VM 内存已落盘为快照不消耗CPU 与内存状态完整保留resuming平台正在从快照恢复沙箱瞬时态terminated沙箱被显式销毁kill或因on_timeoutkill超时被回收无法恢复其中pausing与resuming是瞬时态正常流程下应快速过渡到paused或runningpaused是冷藏态资源不占用但数据完整terminated是终态不可逆。两个核心驱动参数timeout 与 on_timeout状态转换主要由两个参数驱动timeout可选沙箱空闲多久后触发超时单位为秒注意与 e2b 的timeoutMs是毫秒不同。不传时由服务端决定SDK 不再自带 300 秒之类的默认值。on_timeout超时后怎么办——kill默认销毁或pause暂停可之后恢复。timeout 取值语义timeout的取值语义对齐 e2b取值行为不传使用服务端配置的默认空闲超时服务端未配置或设为 ≤ 0 时永不超时NEVER_TIMEOUT-1永不超时——不会因空闲被自动回收0立刻超时——空闲后首次扫描即回收正整数N空闲N 秒后触发超时语言层面的常量Go 为cubesandbox.NeverTimeoutPython 为from cubesandbox import NEVER_TIMEOUT。在 Python SDK 中该常量定义于 sdk/python/cubesandbox/sandbox.pyNEVER_TIMEOUT -1并在 sdk/python/cubesandbox/init.py 中导出SDK 测试 sdk/python/tests/test_sandbox.py 明确验证了NEVER_TIMEOUT必须以-1原样透传给后端。状态转换图┌──────────────────────────────────────┐ │ │ create() ┌────▼────┐ timeout on_timeoutpause ┌─────────┐ ───────────────►│ running │ ──────────────────────────────►│ paused │ │ │◄──────── connect() 或 │ │ └──┬────┬─┘ auto_resume 触发的请求 └──┬────┬─┘ │ │ │ │ │ │ timeout on_timeoutkill │ │ timeout on_timeoutkill │ └────────────────┐ │ └──────────────┐ │ ▼ │ ▼ │ ┌────────────┐◄────────────┘ │ │ terminated │ │ └──────▲─────┘ │ │ │ kill() │ kill() └──────────────────────┘简单归纳create()进入running空闲超时后按on_timeout分流到paused或terminatedpaused可以通过connect()或auto_resume触发的请求回到runningkill()从任意状态直接进入terminated。创建沙箱最小创建示例from cubesandbox import Sandbox # 创建沙箱空闲 60 秒后自动销毁默认 on_timeoutkill sandbox Sandbox.create( templateyour-template-id, timeout60, # 单位秒 ) print(sandbox.sandbox_id)Sandbox.create()关键参数参数说明template模板 ID沙箱基于它启动缺省读环境变量CUBE_TEMPLATE_IDtimeout可选空闲超时秒见上文取值说明lifecycle生命周期策略详见下文平台自动暂停 / 自动恢复metadata任意键值对写入沙箱元数据可在列表 / 详情接口中读出env_vars注入沙箱进程的环境变量allow_internet_access是否允许出公网network提供更细粒度的出站策略Cube 不像托管 e2b 那样有严格的 24h/1h 单次运行上限。省略timeout时实际空闲 TTL 由集群运维在服务端配置见下文设计与运维要点。值得说明的是timeout的单位是秒这是 Cube SDK 与 e2b 刻意拉开的一个差异点e2b 的timeoutMs以毫秒为单位迁移时务必换算。查询与列出沙箱查询沙箱信息info sandbox.get_info() print(info) # { # sandboxID: iiny0783cype8gmoawzmx-ce30bc46, # templateID: rki5dems9wqfm4r03t7g, # state: running, # startedAt: 2026-06-17T12:34:56Z, # endAt: 2026-06-17T12:39:56Z, # metadata: {...} # }endAt表示按当前timeout估算的下一次超时时间。每次接收到新请求或调用set_timeout若有endAt会被刷新。对于永不超时的沙箱没有截止时间因此响应中会省略endAt而不是把它渲染成等于startedAt——这是调用方判断该沙箱是否设置了无限空闲窗口的一个可靠信号。列出运行中的沙箱for sb in Sandbox.list(): print(sb[sandboxID], sb[state])Sandbox.list()默认过滤掉已终止terminated的沙箱因此沙箱从列表消失本身就是自动销毁已落地的一个强信号下文 auto-kill 演示正是利用了这一契约。显式销毁与删除暂停状态的沙箱显式销毁sandbox.kill()kill()是不可逆的与暂停不同被 kill 的沙箱不能恢复。即便lifecycle.on_timeoutpause调用kill()仍然立即终止并丢弃快照。删除暂停状态的沙箱kill()和DELETE /sandboxes/{sandboxID}均可用于删除处于running或paused状态的沙箱。删除paused沙箱时CubeSandbox不会先 Resume唤醒 MicroVM。控制面直接删除 paused tombstone、清理 pause 快照catalogCoW并清除 pause 元数据。Plugin volume 的 refcount 已在 Pause 时调整删除路径无需为销毁再挂载一遍。接口仍保持同步语义只有清理完成后才返回204 No Content。该路径不是一次 Resume不会触发sandbox.resumed生命周期事件不会重置空闲超时不需要节点容量准入不再有删除前恢复。删除暂停状态的沙箱时通常会遇到以下几类情况删除成功时返回204 No Content表示沙箱、pause 快照及相关资源已经完成清理。如果沙箱正在进入暂停状态或其他生命周期操作pauseresumedelete尚未完成并持有沙箱锁会返回503 Service Unavailable并携带Retry-After: 2。客户端应等待至少两秒后重试。Retry-After的单位为秒仅用于提示客户端等待后重试。它不表示 CubeSandbox 会在后台继续删除也不会启动后台重试任务——重试时机完全由客户端自行掌握。404 Not Found、408 Request Timeout以及running沙箱的删除行为保持不变。显式暂停 / 恢复pause / connect 基础用法sandbox.pause() # 主动保存快照释放 CPU/内存 # ... 一段时间过去 ... sandbox.connect() # 从快照恢复 sandbox.run_code(print(back!)) # 像没暂停过一样继续用pause()不会取消空闲回收。默认on_timeoutkill时之后被暂停的沙箱空闲仍超过timeout一样会被销毁。若要保住暂停中的沙箱请传timeoutNEVER_TIMEOUT、省略timeout且服务端未设正数默认、或把timeout设得足够大——见下文行为说明。connect()不会改变沙箱的空闲超时——创建时设置的值或之后用set_timeout改的值在暂停/恢复过程中保持不变。若要在恢复时改超时用已弃用的resume(timeout...)resume(timeout...)效果不传 /None保持当前超时与connect()相同0保持当前超时立刻到期请用set_timeout(0)NEVER_TIMEOUT-1恢复后永不超时N 0从恢复时刻起重新开 N 秒窗口可参考示例 examples/code-sandbox-quickstart/pause.py该演示用显式pause()/connect()走完创建 → 计算 → 写 checkpoint → 暂停 → 空闲 → 恢复 → 校验状态五步最后对比内核内存 文件系统两层状态是否完全保留。跨机 ResumeS3 后端且remote_statusready见 跨机快照。Resume 后的 CubeProxy 缓存Resume 会重建 guest NIC主机端口并重写 Redis 沙箱代理路由。CubeMaster 随后 best-effort 调用 CubeProxyPOST /admin/backend_cache/delete清理local_cache避免流量仍打到 pause 前的旧 IP同机 504。要使该清理成功CubeMaster 与 CubeProxy 必须配置相同的 admin tokenCubeMastercubeproxy.admin_token请求头X-Cube-Admin-TokenCubeProxynginx.conf中的$cube_admin_token见 CubeProxy/lua/admin_phase.lua若只配一侧或两端不一致清理会返回403Redis 路由已正确但 CubeProxy 可能继续使用过期缓存直至条目过期。使用 Resume 时请在部署Helm 中对齐该 token。这一细节在实践中经常被忽略一旦遗漏暂停后首次恢复的请求可能命中旧 IP 而出现偶发 504。平台自动暂停 / 自动恢复很多 Agent 工作负载并不持续繁忙用户敲一段代码 → 模型推理 → 沙箱执行 → 等待下一轮交互。在等待期间让沙箱自动暂停下次请求来时再自动恢复可以显著降低资源占用。Cube 提供与 e2blifecycle完全一致的配置形态sandbox Sandbox.create( templateyour-template-id, timeout300, # 5 分钟空闲后触发 on_timeout lifecycle{ on_timeout: pause, # 空闲超时后 → 暂停而不是销毁 auto_resume: True, # 暂停后下一次请求 → 透明恢复 }, )行为说明on_timeoutpause沙箱空闲timeout秒后平台调度暂停流程state变为pausedVM 内存被冷藏到快照存储。auto_resumeTrue当再有任何请求路由到这个paused沙箱HTTP 请求、run_code、文件读写等平台自动唤醒它调用方无需显式connect()典型恢复时间在亚秒级到秒级。如果auto_resumeFalse或省略沙箱暂停后必须显式Sandbox.connect(sandbox_id...)才能再用 —— 适合等用户决定的场景。自动恢复后的 timeout 重置每次自动恢复成功后空闲计时重置但超时时长不变。所以恢复 → 短暂使用 → 再次空闲超时 → 再次暂停的循环可以无缝持续这正是 Agent 多轮交互场景的理想行为。何时算活跃下列动作都会重置 idle 计时通过 SDK 调用sandbox.run_code(...)、sandbox.commands.run(...)、sandbox.files.read(...)/write(...)。通过 HTTP 直连沙箱内的服务例如getHost()返回的 URL。未配置auto_pause/ 不传lifecycle的沙箱默认行为是on_timeoutkill空闲超过timeout秒后平台会主动销毁该沙箱。这与 e2blifecycle.on_timeoutkill语义一致。手动pause()不会取消auto-kill之后被暂停的沙箱空闲仍超过timeout时一样会被销毁。若要保住暂停中的沙箱请传timeoutNEVER_TIMEOUT、省略timeout且服务端未设正数默认、把timeout设得足够大或通过定期活动刷新空闲计时。端到端示例平台提供两个互为镜像的端到端演示对应on_timeout的两种取值examples/code-sandbox-quickstart/auto-resume.py ——on_timeoutpauseauto_resumeTrue。创建沙箱、空闲触发自动暂停、再发请求触发自动恢复最终对比内核内存 文件系统两层状态验证全状态保留。examples/code-sandbox-quickstart/auto-kill.py ——on_timeoutkill默认行为。创建沙箱、空闲触发自动销毁、验证后续请求以 410 Gone 快速失败、Sandbox.list()不再返回该沙箱并通过创建一个对照沙箱排除集群整体故障。运行方式export CUBE_TEMPLATE_IDyour-template # 自动暂停 自动恢复 python examples/code-sandbox-quickstart/auto-resume.py # 自动销毁不可恢复 python examples/code-sandbox-quickstart/auto-kill.py两个脚本都支持--idle-timeout参数调整演示用的空闲窗口默认 30 秒与--dark深色终端配色。从源码实现看auto-resume 演示的校验逻辑是暂停前先写入/tmp/checkpoint.txt并记录进程内变量hash_val/pi_approx恢复后再次读取变量与文件逐层比对kernel memory 两层 filesystem 一层是否完全一致auto-kill 演示则额外用请求抛出异常、从Sandbox.list()消失、新建对照沙箱可正常 create-then-info三个审计项确认销毁已真正落地而非网络故障见 auto-kill.py 中的is_alive与审计表逻辑。设计与运维要点集群默认空闲超时default_timeout_insec客户端不传timeout时由 CubeMaster 读取 CubeMaster/conf.yaml 中的cubelet_conf.default_timeout_insecone-click 安装路径/usr/local/services/cubetoolbox/CubeMaster/conf.yaml。该配置项在 CubeMaster/pkg/base/config/config.go 中定义属于cubelet_conf配置段。配置值客户端省略timeout时的效果未配置或 0不设集群级空闲 TTL—— 沙箱不会因空闲被自动回收正整数N默认空闲N 秒后触发超时仓库默认不配置集群级空闲超时default_timeout_insec: -1。若希望集群自动回收未显式传timeout的沙箱可改为正数例如300。修改后需重启cube-sandbox-cubemaster.service。create_timeout_insec 与空闲 TTL 无关同一段里的create_timeout_insec与空闲 TTL 无关仅限制创建/调度 RPC 的截止时间。仓库默认值为600秒见 CubeMaster/conf.yaml并在 CubeMaster/pkg/service/sandbox/sandbox_run.go 中作为创建路径 RPC deadline 使用源码注释明确说明Create RPC deadline uses create_timeout_insec, not idle TTL。也就是说创建耗时受create_timeout_insec约束创建完成后的空闲寿命受timeout/default_timeout_insec约束二者是两条独立的控制维度。更多 CubeMaster 配置项见 服务管理 — CubeMaster 配置项。暂停的状态保真度与集群一致性暂停的状态保真度CPU 寄存器、进程内存、TCP 连接无外部对端、文件系统改动都会随快照保留面向外部的连接如 sandbox 主动建立的 outbound socket会在暂停时断开恢复后由应用层自行重连。集群一致性自动暂停由cube-lifecycle-manager协调。Helm chart 与 Terraform 一键部署默认都是两个温备副本。两个副本都消费生命周期事件、发现 CubeProxy 并处理恢复回调由 Redis 租约选出一个副本执行空闲扫描、销毁和过期注册清理。leader 故障切换后沙箱可能多一次 pause/resume下次请求会照常 auto-resume见 Kubernetes FAQ。每沙箱 Redis 状态转换与 CubeMaster lifecycle lock 共同串行化跨副本的有效暂停/恢复操作。失败回退自动恢复 RPC 失败时CubeProxy 直接对客户端返回 503 Retry-After不会让用户卡在长超时上当沙箱已经被销毁killing/killed则返回 410 Gone 让客户端立即停止重试。故障排查控制节点上执行docker logs cube-lifecycle-manager查看运行日志关键事件包括create event applied、auto-paused sandbox、auto-resumed sandbox、timeout-killed sandbox。每个 CubeProxy 副本额外提供GET http://node-ip:8082/admin/healthz其中heartbeat_last_pushed_ms表示该副本最近一次向 manager 上报心跳的时间戳。管理端口默认为8082由于 CubeProxy 使用主机网络当该端口已被占用时可通过CUBE_PROXY_ADMIN_PORT覆盖。暂停资源释放与节点调度配额沙箱暂停后其 CPU 和内存在物理上已被回收——但在默认情况下节点资源计账仍然将暂停中paused/pausing的沙箱视为已占用调度配额。这意味着即使大量闲置沙箱被暂停宿主机上仍然没有空位来创建新沙箱。为了解决这个问题Cube 提供了一个节点级调节旋钮host.quota.paused_resource_release_ratio在 Cubelet/config/config.toml 中配置值域[0, 1]默认0该配置项在 Cubelet/pkg/config/config.go 中定义Cubelet/dynamicconf/conf.yaml 中默认值为0.0值行为适用场景0.0暂停沙箱保留完整配额与旧版本行为一致。恢复始终有保障不会因资源不足被拒绝。对可用性要求极高、不希望恢复失败的场景1.0暂停沙箱的 CPU/内存配额全部释放给调度器。恢复变为尽力而为——节点资源不足时恢复会被拒绝。追求最大化部署密度、允许恢复偶尔失败的场景0 r 1释放r比例保留(1-r)作为余量。保留的配额仍会计入调度器的 CPU/内存使用量因此暂停密集的节点会被自然降权调度器不会在已有大量暂停沙箱的节点上继续堆积新沙箱。需要在可用性和高利用率之间做折中的场景配置示例# Cubelet/config/config.toml [host.quota] paused_resource_release_ratio 0.5 # 释放一半保留一半恢复准入检查当ratio 0时恢复操作会触发本地实时准入检查——如果节点当前无法容纳该沙箱释放出去的资源量恢复会被拒绝resume rejected by paused_resource_release_ratio policy: need 1024MB quota 512MB该准入逻辑在 Cubelet/services/cubebox/update.go 的admitResume中实现ratio 0时策略关闭、恢复零检查保持旧行为ratio 0时按当前已分配资源 恢复需补回的释放份额实时计算刻意不缓存保证准入反映当下分配不足则以ErrorCode_Conflict拒绝。拒绝信息通过以下链路透传给客户端Cubelet (130409 Conflict)→CubeAPI (HTTP 409)→WebUI显示容量诊断。409 是可重试的状态码——当其他沙箱被销毁或暂停、节点资源释放后恢复可以重新尝试。注意事项磁盘和 MvmNum不受 ratio 影响——暂停快照始终占用存储空间沙箱对象始终存在。ratio0是零值安全的默认值如果从未配置过此项行为与旧版本完全一致升级不会产生意外。此项为节点级配置不同节点可以设置不同的比值灵活应对异构硬件或分池部署的需求。当节点上一大批沙箱同时被唤醒、单节点无法承载时控制面会返回 409 并给出具体配额数字。对使用 S3 后端的沙箱调度器可以回退到其它兼容节点恢复——跨机条件与调度规则见 跨机快照。下一步模板概览 —— 沙箱基于模板启动模板的构建过程也会影响首次冷启动开销。快速开始 —— 完整跑通创建沙箱 → 执行代码 → 销毁的最短路径。上游参考e2b · Sandbox lifecycle、e2b · Auto-resumee2b 用户可将既有代码按本页语义直接迁移。【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考