CubeSandbox 模板创建与 OCI 镜像全流程指南

这篇文章从架构视角解释：为什么 cubemastercli tpl create-from-image 这条命令，最终会变成 TemplateDefinition、RootFS Artifact、节点副本与 LocalRunTemplate。内容以当前 CLI 与控制面实现为准。

如果你想直接照着命令行操作，请优先阅读：从 OCI 镜像制作模板。

1. 先看结论：命令行创建模板，本质上是在触发一条异步供应链

当你执行：

cubemastercli tpl create-from-image \
  --image ccr.ccs.tencentyun.com/ags-image/sandbox-browser:latest \
  --writable-layer-size 1G \
  --expose-port 9000 \
  --probe 9000 \
  --probe-path /

控制面并不是“立即生成一个可运行沙箱”，而是在后台启动一条模板构建流水线：

1. 记录模板构建任务
2. 拉取 OCI 镜像
3. 导出 rootfs 并制作 artifact
4. 启动探针验证模板是否 ready
5. 将产物分发到节点并形成可用副本

2. 这条命令真实支持哪些参数

截至当前源码，create-from-image 支持这些核心参数：

• --image
• --template-id
• --writable-layer-size
• --expose-port（可重复）
• --probe
• --probe-path
• --env（可重复）
• --allow-internet-access
• --allow-out-cidr（可重复）
• --deny-out-cidr（可重复）
• --registry-username
• --registry-password

另外还支持通用参数：

• --server
• --timeout
• --json

这条命令当前并不直接接受 --cpu、--memory、--disk、--label、--annotation、--command、--args、--volume 等参数。那些字段可能存在于 CubeAPI 或模板请求模型里，但不是当前 CLI 的原生 flags。

3. probe 与 expose-port 为什么这么关键

模板创建成功与否，不只取决于“镜像能不能拉下来”，还取决于镜像启动后是否能通过 HTTP 探针。

因此至少要同时想清楚三件事：

• 服务实际监听哪个端口
• Cube 要探测哪个端口
• Cube 要请求哪个路径

源码里的真实行为是：

• --probe 如果省略，CLI 会自动取第一个 --expose-port
• 如果最终 probe 端口仍为空，CLI 会直接报错
• --probe-path 默认值是 /health
• 如果传入的路径不以 / 开头，CLI 会自动补 /

这也是为什么很多模板失败，根因其实不是镜像本身，而是探针配置和服务监听不一致。

4. writable layer 到底是什么

--writable-layer-size 指定的是模板运行时默认可写层大小，比如：

• 512M
• 1G
• 2G

这个参数控制的是基于模板启动出的沙箱，在 rootfs 之上可写入的数据空间预算。太小会导致安装依赖、写临时文件、浏览器缓存等场景失败；太大则会增加存储成本。

5. 出网控制参数会被写进模板请求

--allow-internet-access、--allow-out-cidr、--deny-out-cidr 不只是 CLI 表层参数，它们会进入生成后的模板请求，最终影响 cubevs_context：

• --allow-internet-access：控制是否允许公网访问
• --allow-out-cidr：向允许列表追加 CIDR
• --deny-out-cidr：向拒绝列表追加 CIDR

这意味着模板不仅定义“文件系统长什么样”，还会定义“默认网络策略长什么样”。

6. RootFS Artifact 生成与缓存机制

• CubeMaster 会根据镜像及构建规格生成 artifact 相关身份信息
• 若已有可复用产物，则可以复用
• 否则会重新拉取镜像、导出 rootfs、制作 ext4 镜像
• 产物会带摘要信息，便于校验与追踪

7. 节点副本与 AppSnapshot 机制

• 模板创建后，控制面会在节点上形成副本（Replica）
• 副本包含 snapshot 路径、状态、phase、错误信息等
• 只有副本 ready，模板才真正可用于后续沙箱创建

所以“数据库里有模板记录”不等于“模板已经可运行”。

8. 为什么 CLI 没有 --cpu / --memory

很多用户会自然地问：为什么没有 --cpu、--memory、--disk？

原因是：create-from-image 的职责是“把镜像做成模板”，而不是“直接定义某次沙箱启动规格”。

这条命令主要关心的是：

• 镜像从哪里来
• 可写层多大
• 应用能否通过探针
• 需要注入哪些环境变量
• 默认出网策略是什么

而运行时资源规格，通常属于后续“基于模板创建沙箱”的请求层语义，不是当前 CLI 入口的直接 flags。

9. CLI 与 Python SDK 的差异要分开看

如果你使用 Python SDK 的 Template.build()，会看到它还能传：

• cpu_count
• memory_mb
• allow_internet_access
• instance_type

这是 CubeAPI 模板接口 暴露的能力，不等于 cubemastercli tpl create-from-image 这条命令已经原生支持同名 flags。写文档时必须把“CLI 能力”和“SDK/API 能力”分开。

10. 建议搭配阅读

• 从 OCI 镜像制作模板
• 模板如何变成可运行沙箱
• 模板检查与请求预览