Cube Sandbox

English

简体中文

English

简体中文

Appearance

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

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

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

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

当你执行：

bash
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. 建议搭配阅读 ​

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

12. 常见问题解答 ​

  • 如何自定义规格？
    • 直接在模板创建请求中填写 cpu、memory、disk 字段。
  • 如何挂载数据盘/卷？
    • 使用 volumes 字段，指定 host/container 路径映射。
  • 如何调试模板失败？
    • 检查镜像可用性、规格是否超出节点资源、端口暴露是否正确。
  • 如何批量分发副本？
    • 可通过 API 指定副本分发节点。

参考阅读：