从 OCI 镜像制作模板
本文介绍如何使用 cubemastercli 命令行工具，从标准 OCI 容器镜像出发，完成模板的创建、进度监控和删除操作。本文以 CLI 实际源码行为 为准。
概述
模板（Template） 是一份预构建的不可变 rootfs 快照，沙箱运行时用它来冷启动（或热启动）新的沙箱实例。从 OCI 镜像制作模板是一个在集群上异步执行的三阶段流水线：
OCI 镜像 ──拉取──► ext4 rootfs ──启动──► 快照 ──注册──► 模板 READY模板进入 READY 状态后，即可通过其 template_id 创建沙箱实例。
前置条件
- 已安装
cubemastercli并加入$PATH - 设置环境变量
CUBEMASTER_ADDR，或在每条命令中加--server <host> - OCI 镜像须可被 CubeMaster 节点访问（公开仓库或已配置认证的私有仓库）
⚠️ 镜像必须提供 HTTP 服务
Cube 平台在制作模板时，会启动容器并通过 HTTP 探测容器是否已就绪。因此：
- 你的容器镜像必须在某个固定端口上启动一个 HTTP 服务器。
- 你至少要提供一个
--expose-port，或者显式指定--probe。 --probe如果省略，CLI 会默认取第一个--expose-port。--probe-path如果留空，CLI 默认使用/health。- 你的容器入口程序应在应用完全准备好对外提供服务之后，再启动 HTTP 服务——Cube 在探针返回 HTTP 2xx 时即将模板标记为就绪。
如果容器未暴露 HTTP 服务，或探针参数配置错误，模板制作将因超时而失败。如果既没有 --probe，也没有任何 --expose-port，CLI 会直接报错。
第一步 — 创建模板
使用 tpl create-from-image 子命令发起构建任务：
cubemastercli tpl create-from-image \
--image cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-browser:latest \
--writable-layer-size 1G \
--expose-port 9000 \
--probe 9000 \
--probe-path /镜像仓库说明： 国内优先使用
cube-sandbox-cn.tencentcloudcr.com/cube-sandbox/sandbox-browser:latest；境外访问推荐使用cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-browser:latest。
命令成功后立即返回 job_id 和自动生成的 template_id 并退出，构建任务在集群后台继续执行：
job_id: 0042cd3a-c1d6-45fd-8757-2595ba0027e8
template_id: tpl-4ff5adc5eea44c14b1c8dbb3
attempt_no: 1
artifact_id:
status: PENDING
phase: PULLING
progress: 0%常用参数
| 参数 | 是否必填 | 说明 |
|---|---|---|
--image | 是 | OCI 镜像地址 |
--template-id | 否 | 指定模板 ID，不传则由后端生成 |
--expose-port | 否 | 暴露端口，可重复 |
--probe | 否 | HTTP 探针端口；省略时取第一个 --expose-port |
--probe-path | 否 | HTTP 探针路径，默认 /health |
--writable-layer-size | 否 | 可写层大小，默认 1G |
--env | 否 | 环境变量，格式 KEY=VALUE，可重复 |
--allow-internet-access | 否 | 为生成的模板请求设置 allowInternetAccess=true |
--allow-out-cidr | 否 | 追加允许出网 CIDR，可重复 |
--deny-out-cidr | 否 | 追加拒绝出网 CIDR，可重复 |
--registry-username / --registry-password | 否 | 私有仓库认证 |
--server | 否 | 指定 CubeMaster 地址 |
--timeout | 否 | 请求超时，默认 5m |
--json | 否 | 输出原始 JSON |
示例 — 多端口 + 自定义探针路径 + 环境变量
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 \
--probe-path /health \
--env MY_ENV=production示例 — 私有仓库 + 出网控制
cubemastercli tpl create-from-image \
--server 127.0.0.1:8080 \
--image harbor.example.com/team/browser:2026-06-01 \
--registry-username robot$builder \
--registry-password '<token>' \
--writable-layer-size 2G \
--expose-port 9000 \
--probe 9000 \
--probe-path /healthz \
--allow-internet-access \
--allow-out-cidr 0.0.0.0/0 \
--deny-out-cidr 169.254.0.0/16 \
--env ENV=prod第二步 — 监控进度
有两种方式跟踪构建任务。
Watch（阻塞，推荐）
tpl watch 循环轮询任务，直到任务到达终态（READY 或 FAILED）才退出：
cubemastercli tpl watch --job-id <job_id>任务完成时的示例输出：
job_id: 2e71b561-153e-4c08-ac37-5270d94f5f15
template_id: tpl-748094d2f2374b0a8a37e6ec
attempt_no: 1
artifact_id: rfs-1e8e07c90e9bb8eff94ecde2
status: READY
phase: READY
progress: 100%
distribution: 1/1 ready, 0 failed
template_spec_fingerprint: 1e8e07c90e9bb8eff94ecde20396002c411f6b812612a2a05086b85fe245b858
artifact_status: READY
artifact_sha256: 5d413bc735062d49d36ef9c0e62cd0c3a915853be5ec0c7fba90e13d9fd33f79
template_status: READYStatus（单次查询）
cubemastercli tpl status --job-id <job_id>主要字段说明：
| 字段 | 说明 |
|---|---|
status / template_status | 任务和模板整体状态，READY 表示模板可用 |
phase | 当前流水线阶段，如 PULLING / BUILDING / DISTRIBUTING / READY |
progress | 当前阶段完成百分比 |
distribution | N/M ready，表示副本分发进度 |
artifact_id | rootfs artifact 稳定 ID |
artifact_sha256 | artifact 的 SHA-256 摘要 |
template_spec_fingerprint | 规格指纹，用于判断相同输入是否复用构建产物 |
第三步 — 使用模板
template_status: READY 后，通过 template_id 创建沙箱：
export CUBE_TEMPLATE_ID=tpl-748094d2f2374b0a8a37e6ec
python CubeAPI/examples/create.py如果你使用 Python SDK，也可以通过 Template.build() 调 CubeAPI 的模板接口。需要注意：Python SDK 支持的字段比 CLI 更宽，比如 cpu_count、memory_mb、allow_internet_access，这属于 CubeAPI 层能力，不等于 CLI 的 flags 集合。
查询模板
列出所有模板
cubemastercli tpl list如果需要同时查看 VERSION 和 LAST_ERROR，使用宽格式输出：
cubemastercli tpl list -o wide加 --json 输出完整 JSON，便于脚本处理：
cubemastercli tpl list --json | jq '.data[].template_id'查看单个模板详情
cubemastercli tpl info --template-id tpl-748094d2f2374b0a8a37e6eccubemastercli tpl info --template-id tpl-748094d2f2374b0a8a37e6ec --jsoncubemastercli tpl info --template-id tpl-748094d2f2374b0a8a37e6ec --json --include-request如果想预览创建沙箱时最终生效的请求，可使用：
cubemastercli tpl render --template-id tpl-748094d2f2374b0a8a37e6ec --json删除模板
cubemastercli tpl delete --template-id tpl-748094d2f2374b0a8a37e6ec⚠️ 删除操作会同时移除模板元数据和所有节点上的 artifact 副本。已基于该模板运行的沙箱不受影响，但此后无法再用该模板创建新沙箱。
常见问题
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
CLI 报错 probe port is required | 未传 --probe，且也没有任何 --expose-port | 至少补一个 --expose-port，或显式指定 --probe |
phase: PULLING 长时间卡住 | 镜像拉取慢或集群节点无法访问镜像仓库 | 检查网络/防火墙；私有仓库需添加 --registry-username / --registry-password |
status: FAILED（BUILDING 阶段） | 构建错误（磁盘满、镜像入口问题、探针配置错误等） | 执行 tpl status --job-id <id> --json 查看 last_error |
distribution: 0/N ready（状态已 READY） | artifact 分发仍在进行 | 等待后重新执行 tpl info；若长时间未恢复检查目标节点 Cubelet 日志 |
| 沙箱启动后就绪探针一直失败 | 容器内服务未在预期端口/路径监听，或服务尚未完全就绪时 HTTP server 已提前启动 | 确认 HTTP server 在应用完全就绪后再启动；检查 --probe-path、--probe 与端口监听是否一致 |
| 模板后续沙箱不能访问外网 | 模板请求中的 CubeVS 出网策略限制了流量 | 检查 --allow-internet-access、--allow-out-cidr、--deny-out-cidr |