CubeSandbox持久化存储完全指南跨沙箱保留数据的三种姿势【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandboxCubeSandbox 是一个专为 AI Agent 设计的即时、并发、安全且轻量的沙箱平台。但很多新手都会遇到同一个痛点沙箱销毁后里面的数据也一起没了。沙箱运行在轻量 MicroVM 中默认所有写入数据都是临时的。本指南带你彻底搞懂 CubeSandbox 持久化存储的三种姿势——Host Mount 主机目录挂载、S3 Volume 持久卷、Volume 插件自定义后端一篇讲透怎么选、怎么配、怎么避坑。先看懂为什么沙箱默认失忆CubeSandbox 的核心理念是沙箱即弃——用 KVM MicroVM 提供强隔离创建并发极高销毁也极快。代价就是默认没有磁盘持久化。你写的文件、训练出的模型、生成的报告沙箱一关就清零。要解决数据要活过沙箱CubeSandbox 提供了三层方案从简单到灵活依次是方案一句话定位适用场景Host Mount 主机挂载把宿主机目录直接绑进沙箱数据已经在节点上、追求零拷贝零延迟S3 Volume 持久卷对象存储上的用户级网盘跨沙箱、跨节点保留独立数据最省心Volume 插件COS/NFS 等按 CSI 模型接入任意后端企业级多云存储、私有化定制上图展示了 CubeSandbox 的存储共享机制多个沙箱可共享同一份只读镜像与 rootfs配合全局共享 pagecache避免重复占内存。这层共享是只读的——想让写入的数据留下来就要用下面三种姿势。姿势一Host Mount 主机目录挂载最快上手Host Mount 是 Cube 的专属扩展把沙箱宿主机节点上的一个绝对路径绑定挂载到沙箱内部的某个目录。读写即时可见没有同步、没有上传、没有延迟。一键挂载步骤在宿主机上准备好目录例如/data/shared/output创建沙箱时在metadata中传入host-mount键JSON 数组每项包含三个字段hostPath宿主机上的绝对路径默认只允许/data/shared/前缀mountPath沙箱内的目标路径readOnlytrue只读 /false读写沙箱销毁后宿主机目录里的文件原封不动。最小示例with Sandbox.create(templateTEMPLATE_ID, metadata{ host-mount: json.dumps([ {hostPath: /data/shared/output, mountPath: /mnt/out, readOnly: False}, ]) }) as sb: sb.commands.run(echo persist data /mnt/out/output.txt)沙箱关闭后执行cat /data/shared/output/output.txt数据还在 ✅典型用法共享模型权重/数据集只读挂载大目录多个沙箱复用不用拷贝持久化任务输出读写挂载输出目录日志和构建产物跨沙箱存活Agent 团队协作嵌套挂载实现共享区只读 每人目录可写各 Agent 互不干扰。三个必知限制 ⚠️路径白名单hostPath默认必须在/data/shared/下越界路径如/etc/passwd、/data/shared/../etc会在创建沙箱时被拒绝节点本地目录只存在于调度到该沙箱的那台节点上跨节点迁移不跟过去多节点集群建议配 NFS让所有节点在相同路径看到同一份数据不进快照对含 Host Mount 的沙箱做快照/回滚时挂载目录不随快照回退始终保留最新状态删除沙箱也不会删掉宿主目录。 完整文档docs/guide/persistent-storage.md示例代码examples/host-mount/姿势二S3 Volume 持久卷最省心如果说 Host Mount 是借宿主的硬盘S3 Volume 就是给每个用户/任务发一块自己的云盘创建 Volume → 挂进沙箱读写 → 销毁沙箱数据仍在 → 下次再挂回来继续用。后端是任意 S3 兼容对象存储AWS S3、腾讯云 COS、R2、MinIO默认安装自带 MinIO——也就是说 one-click 或 Helm 默认装完就能用无需任何额外配置。最快配置方法pip install cubesandbox0.6.0然后三行代码完成写入 → 销毁 → 再挂的完整验证vol Volume.create(my-data, drivers3) with Sandbox.create(volume_mounts{/workspace: vol}) as sb: sb.files.write(/workspace/hello.txt, from S3 volume) # 沙箱已销毁数据还在再开一个沙箱挂上去文件依旧 with Sandbox.create(volume_mounts{/workspace: vol}) as sb: print(sb.files.read(/workspace/hello.txt))它凭什么省心能力说明生命周期解耦销毁沙箱不会删数据只有显式Volume.destroy()才擦除不可逆多沙箱共享一个 Volume 可同时挂给多个沙箱挂载由引用计数自动管理只读挂载VolumeMount(vol, read_onlyTrue)共享模型/数据集的最佳实践密钥不出宿主机S3 凭证只存在 CubeMaster/Cubelet 上沙箱内只看到普通文件系统支持跨节点快照沙箱在别的节点恢复时Volume 可以重新挂载详见docs/guide/cross-node-snapshot.md 想切换外部 S3one-click 部署只需在.one-click.env关闭捆绑 MinIO 并填入CUBE_S3_*连接信息重跑安装脚本即可插件配置由安装器自动生成。 完整文档docs/guide/s3-volume.md插件操作手册examples/volume/s3/README.zh.md姿势三Volume 插件——接入任意存储后端CubeSandbox 的 Volume 机制借鉴了 Kubernetes CSI 模型把插件分成两个角色ControllerCubeMaster 侧负责Create/Destroy在后端分配/删除存储资源NodeCubelet 侧负责Attach/Detach在宿主机上真正挂载产出一个hostPath交给 microVM 使用。这意味着你可以把任何后端接进来对象存储、NFS、分布式文件系统……官方就提供了两个参考实现S3 插件任意 S3 兼容 Endpoints3fs 同时支持 amd64/arm64COS 插件腾讯云 COS 专用另有 binary 直连和 RPC 两种形态可参考 examples/volume/cos/。上图展示了从 SDK 到 microVM 的完整分层底层由 CubeCow 负责磁盘快照reflink/CoWVolume 插件则通过 Cubelet 把后端存储挂进来——两者协作既有状态快照也有数据持久化。自研插件的协议细节、Hook 定义和部署流程详见docs/guide/volume-plugin.md⚠️ 版本要求Volume 能力需要 Cube 平台 ≥ 0.6.0CubeMaster / CubeAPI / Cubelet 全部升级Python SDKcubesandbox≥ 0.6.0Go SDKsdk/go同等支持。三种姿势怎么选一张表说清维度Host MountS3 VolumeVolume 插件自定义上手难度⭐ 最简单⭐⭐ 默认即开即用⭐⭐⭐ 需开发/部署插件数据位置宿主机节点本地对象存储默认捆绑 MinIO任意后端跨沙箱共享同节点天然共享同集群天然共享取决于后端跨节点/跨集群需自行配 NFS/对象存储挂载✅ 天然支持取决于后端快照回滚联动挂载数据不回滚数据不回滚恢复时可重挂同左多租户隔离靠目录规划 权限加固用户级独立 Volume天然隔离可自定义选择建议数据本来就在节点上 → Host Mount要每个 Agent/任务一块独立持久盘 → S3 Volume90% 场景的正确答案有企业私有存储需求 → Volume 插件。最佳实践与避坑清单输入数据优先只读挂载模型、数据集、配置都建议readOnly: true防止沙箱意外写坏源头尽早检查权限沙箱用户的 UID 要和宿主机目录属主一致否则写入报Permission denied白名单要窄allowed_host_mount_prefixes只加/data/shared/这类深层路径绝不加/或/data/输出目录定期清理挂载目录不像沙箱本体那样会自动清理会持续积累文件别用Volume.destroy()试错它清空整个后端前缀不可恢复且有沙箱仍挂载时会返回 409并发写要自己协调多沙箱挂同一可写目录时Cube 不提供锁和版本控制应用层自行处理对象存储挂载适合读模型权重、数据集这类只读负载用 S3/COS 没问题高频小文件写入优先选 NFS 或块存储。常见问题速查挂载路径被拒、Permission denied、s3fs 挂载失败等已整理在 docs/guide/persistent-storage.md 的 Troubleshooting 章节。写在最后三种姿势覆盖从单机快速共享到企业级多后端的全部诉求Host Mount—— 快、零拷贝适合节点内数据共享S3 Volume—— 生命周期解耦默认安装开箱即用跨沙箱保留数据的主力Volume 插件—— CSI 风格的可扩展框架NFS、分布式文件系统通通能接。把数据从沙箱里的一次性草稿变成可复用资产你的 AI Agent 才算真正有了长期记忆 延伸阅读持久化存储Host Mountdocs/guide/persistent-storage.mdS3 持久卷docs/guide/s3-volume.mdVolume 插件开发框架docs/guide/volume-plugin.md跨节点快照配合持久卷docs/guide/cross-node-snapshot.md快照/克隆/回滚总览docs/guide/snapshot-rollback-clone.md【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
