模板体系

模板是 CubeSandbox 的启动加速核心。没有模板，每次创建沙箱都要像普通虚拟机一样完整启动系统；有了模板，平台可以从预热状态快速恢复一个新的 MicroVM。

模板解决什么问题

AI Agent 常见运行环境往往很重：

• Python、Node.js、浏览器、Jupyter kernel。
• 数据分析包、编译工具链、调试工具。
• 需要监听端口的 envd、浏览器 CDP 服务或自定义应用。

如果每次沙箱创建都重新安装这些依赖，启动时间会不可接受。CubeSandbox 的做法是把这些依赖预先固化到模板中，并在服务 ready 后保存快照。

三阶段工作流

阶段	发生了什么	关键问题
Init	从 OCI 镜像构建 rootfs	镜像是否可拉取，依赖是否齐全。
Boot & Snapshot	冷启动一次 MicroVM 并等待服务 ready	探针端口是否正确，CA 是否注入。
Deploy	注册模板并分发到节点	模板是否 READY，跨节点是否可用。

从镜像创建模板

最常见的命令：

cubemastercli tpl create-from-image \
  --image cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \
  --writable-layer-size 1G \
  --expose-port 49999 \
  --expose-port 49983 \
  --probe 49999

参数理解：

参数	作用
--image	OCI 镜像地址。
--writable-layer-size	每个沙箱运行时可写层大小。
--expose-port	模板声明的沙箱服务端口。
--probe	制作模板时等待哪个端口 ready。

创建后用 watch 命令观察：

cubemastercli tpl watch --job-id <job_id>

什么应该放进模板

适合放进模板：

• 语言运行时、系统依赖、常用 Python/Node 包。
• 浏览器、Jupyter、envd、长期服务的启动脚本。
• CubeEgress 根 CA、证书配置、代理基础配置。
• 只读或低频变化的数据集。

不适合放进模板：

• 每个用户不同的 API Key。
• 会频繁变化的临时文件。
• 需要按请求动态注入的任务数据。
• 需要严格隔离的用户私有数据。

密钥应该通过 CubeEgress 凭证注入或控制面能力托管，避免进入模板和沙箱文件系统。

端口、探针和服务 ready

模板制作里最容易踩坑的是端口：

场景	建议
沙箱内服务需要被 SDK 调用	用 --expose-port 声明端口。
服务启动需要时间	用 --probe 等待实际 ready 端口。
多个服务端口	多次传 --expose-port。
不需要 HTTP 服务	仍可只用命令执行能力，但要确认基础 agent 服务端口就绪。

如果模板构建成功但运行时访问失败，优先检查服务是否监听了正确地址。很多应用默认只监听 127.0.0.1，而你可能需要它监听沙箱网络接口。

模板商店与 WebUI

WebUI 的 Template Store 可以安装官方预置模板。学习阶段建议先使用官方预置环境，确认集群基础能力没问题，再制作自定义模板。

在 WebUI 中重点看：

• Template Store：安装官方模板。
• Templates：查看状态、节点分布、构建进度。
• Template Inspection：检查最终请求和模板健康。

相关文档：WebUI 控制台、模板检查与请求预览。

模板与网络策略

模板可以带默认网络配置，创建沙箱时也可以追加或覆盖。合并后的网络配置会下发到 CubeVS 和 CubeEgress。

学习时先记住：

• 模板提供“默认安全姿态”。
• 创建请求提供“本次任务例外”。
• 同名 L7 rule 通常由请求侧覆盖，列表项会按规则合并。

如果你要给某类 Agent 固定出网范围，把基础网络规则放在模板层会更容易治理。

常见故障

现象	排查方向
模板构建卡住	镜像拉取、探针端口、服务启动脚本。
模板 READY 但创建沙箱失败	节点本地 artifact 缺失、XFS、磁盘空间、版本不一致。
HTTPS 出网报证书错误	模板是否烘入 CubeEgress CA。
沙箱内服务无法访问	--expose-port、服务监听地址、CubeProxy 域名/TLS。

深入排障见 模板相关排障。

下一步

继续阅读 生命周期与状态管理，理解模板启动后的沙箱如何暂停、恢复、快照、克隆和回滚。