CubeSandbox

简体中文

English

简体中文

English

Appearance

Agent 平台集成：手动 freeze / resume ​

面向在 CubeSandbox 之上暴露 sandbox_freeze、sandbox_connect_by_id 等工具的 Agent 编排层（不是终端用户 SDK 示例）。

心智模型：三层 S3 能力彼此独立 ​

层含义保留什么
Volume（cube-volume-s3 + MinIO）用户盘挂载，如 /home/user/persistentkill 后新建实例仍保留的文件
s3lvol（ONE_CLICK_ENABLE_S3LVOL）集群 snapshot 后端跨节点 pause/snapshot
模板 --backend s3注册模板时指定跨节点 pause/snapshot（xfs 模板也可同节点 pause；S3 用于跨节点，见 跨机快照）

Volume 不能替代实例 freeze。Freeze 保留同一 sandboxId 的内存+磁盘态； Volume 在实例销毁后通过新实例保留文件。

关键：pause() 不会停止 idle 计时 ​

默认 on_timeout="kill" 时，沙箱在创建时获得的 idle deadline 在 pause 后仍然有效。 paused 沙箱仍可能在 deadline 到期时被 销毁。

典型现象： POST /pause 成功、CubeMaster 有 action=pause 日志，但一小时后 connect / GET /sandboxes/{id} 返回 404。

缓解（可组合）：

  1. 用 POST /sandboxes/{id}/timeout 延长保留，请求体为 {"timeout": <秒>}（如 {"timeout": 86400}）。running 时应在 pause 之前调用，或在 pause 返回后立即调用——idle sweeper 每隔数秒运行，两步之间的间隙仍按 pause 前的 deadline 计时。
  2. 创建时使用 lifecycle.on_timeout="pause" 并配合较长 timeout，或策略允许时使用 NEVER_TIMEOUT。
  3. 恢复 paused 沙箱时，先走管控面 POST /sandboxes/{id}/connect，再连 envd 数据面（见下）。

推荐管控面流程 ​

Freeze（Agent 工具） ​

text
1. POST /sandboxes/{id}/timeout  {"timeout": 86400}   # 仍在 running 时
2. POST /sandboxes/{id}/pause          # 等到 state=paused
3. 释放进程内句柄；在用户绑定存储中保留 sandboxId

第 3 步之前确认 pause 已落地：GET /sandboxes/{id} 应显示 state="paused"。无论直接调 REST 还是通过受支持的 SDK（含 E2B 兼容的 sandbox.pause()）均适用。

Resume（connect_by_id） ​

text
1. GET  /sandboxes/{id}                # 可选：检查 state
2. POST /sandboxes/{id}/connect        # paused 会自动 resume
3. POST /sandboxes/{id}/timeout {"timeout": 300}   # 可选：设置交互 idle 窗口
4. 连接 envd 数据面（命令、文件、VNC）

第 3 步在需要更短 idle 窗口时必不可少：connect(timeout=…) 只会延长已有 deadline（例如 freeze 时设了 24h，connect(timeout=300) 仍约剩 24h）。在 connect 之后调用 POST /timeout 才能把交互窗口改为你想要的值。

对 paused 实例直接走 envd 或数据面常在管控面 resume 之前失败——常见为 stale 代理后端的同节点 504、pause 进行中的 503 + Retry-After，或沙箱已被销毁的 410 Gone；必须先经 POST /sandboxes/{id}/connect（见 生命周期）。

Volume 权限（s3fs） ​

S3 volume 插件不会设置 s3fs 的 uid/gid/umask，guest 内可见的权限取决于 s3fs 默认值。 请使用官方支持的配置入口——安装器会生成并在升级时重写 volume-s3.conf，不要手动编辑该文件（见 S3 Volume）：

bash
# one-click（.one-click.env）
# install.sh 仅在变量为空时补上 -ouse_path_request_style；使用内置 MinIO 时需保留该 token。
CUBE_S3_S3FS_EXTRA_OPTS='-ouse_path_request_style -ouid=1000 -ogid=1000 -oumask=022'
yaml
# Helm（values.yaml）——仅当 minio.enabled=false 且配置了 volumeS3.endpoint / existingSecret 时生效
volumeS3:
  extraOpts: "-ouse_path_request_style -ouid=1000 -ogid=1000 -oumask=022"

使用 chart 内置 MinIO 时，volumeS3.extraOpts 不会生效（选项由 chart 硬编码）。 自托管 MinIO 作为外部后端时同样需要 -ouse_path_request_style。

仅 从零手动部署 场景才在 volume-s3.conf 中设置 S3FS_EXTRA_OPTS。 也可在 Agent 启动流程或模板 entrypoint 中做挂载后 chown/chmod。 另见 宿主机挂载权限 中类似的属主排查思路。

运维检查清单 ​

  • [ ] 所有计算节点 s3lvol 就绪后再 tpl create-from-image --backend s3 （Kubernetes 上启用 s3lvol 会重建 Big Pod，并在 Pod 网络（cubeNode.hostNetwork: false）下中断该节点上的沙箱；见 Kubernetes 升级）
  • [ ] 所有计算节点上 S3 模板均为 READY （单节点 FAILED 时用 cubemastercli tpl redo --template-id <id> --failed-only --node <node-ip>）
  • [ ] 用户 Volume 桶与 s3lvol 快照桶分离
  • [ ] Agent 绑定 TTL ≤ paused 保留 timeout（避免绑定到已销毁 ID）

延伸阅读 ​