---
url: https://cubesandbox.com/zh/guide/templates.md
---
# 模板概览 (Templates)

模板是 CubeSandbox 创建沙箱时使用的可复用运行环境。它不仅包含来自 OCI 镜像的根文件系统，还包含沙箱启动所需的配置和预热后的 MicroVM 快照。基于同一个模板可以反复创建相互隔离、环境一致的沙箱，并通过恢复快照缩短启动时间。

## 核心概念

### OCI 镜像

OCI（Open Container Initiative）定义了容器镜像的开放标准。日常使用的 Docker 镜像通常就是 OCI 镜像：它由一组只读文件系统层和镜像配置组成，记录了操作系统文件、应用及依赖，以及 `ENTRYPOINT`、`CMD`、环境变量等启动信息。镜像一般以 `仓库/名称:标签` 引用，例如 `docker.io/library/python:3.11`，也可以用 digest 锁定具体内容。

CubeSandbox 不会把 OCI 镜像直接当作沙箱运行。它会拉取并展开镜像，将其转换为适合 MicroVM 使用的 rootfs，按镜像中的启动配置运行服务，然后生成可快速恢复的模板快照。因此，OCI 镜像是模板的输入，模板才是创建沙箱时使用的产物。

### 什么时候制作模板快照

CubeSandbox 拉取 OCI 镜像后，会用它启动一个临时 MicroVM。镜像中的入口程序、系统服务和应用会像正常启动沙箱一样运行。Cube 不会在进程刚启动时立刻制作模板，而是**等待指定的 HTTP 探针返回 2xx**；这个响应表示环境已经到达适合保存的时刻。随后 Cube 冻结此时的文件系统和内存状态并生成模板快照。

选择探针，本质上是在定义“什么时候算启动完成”。探针返回得太早，快照可能生成在应用仍在初始化或依赖尚未预热时；探针始终不成功，模板构建则会超时。理想的探针端点应在模板中需要预热的服务都准备完成后才返回 2xx。

### 用端口和探针定义就绪时机

Cube 平台在制作模板时，会启动容器并通过 HTTP 探测容器是否已就绪。因此：

1. 你的容器镜像**必须**在某个固定端口上启动一个 HTTP 服务器，并提供返回 2xx 的就绪端点；它可以来自 `envd`，也可以来自你的应用。
2. 创建模板时**必须**指定以下参数：
   * `--expose-port <port>` — 声明 HTTP 服务监听的端口
   * `--probe <port>` — 告诉 Cube 要探测哪个端口
   * `--probe-path <path>` — Cube 将 `GET` 的 HTTP 路径（如 `/` 或 `/health`）
3. 被选择的探针端点应在**需要预热的服务完全准备好之后**才返回 HTTP 2xx。Cube 会以此为信号制作快照；如果探测的是 `envd`，该信号只表示 `envd` 本身已经就绪。

一次模板构建选择一个探针端口和路径，Cube 会持续请求 `http://<sandbox>:<probe-port><probe-path>`，直到收到 HTTP 2xx 响应后制作快照。

`envd` 是预装在 CubeSandbox 基础镜像中的一个后台服务：沙箱创建后，SDK 的“执行命令”“读写文件”和“打开终端”等操作，实际都会请求沙箱内的 `envd`。`envd` 默认监听 `49983`，其 `/health` 接口会在 `envd` 可以接收这些请求时返回 204。

下面的参数配置是一个最常见的例子，表示开放 `envd` 的 49983 端口，监听探测 49983 端口，并在 `/health` 返回成功后制作模板快照：

```bash
--expose-port 49983 --probe 49983 --probe-path /health
```

但 `envd` 就绪只代表 SDK 数据面已经就绪，不一定代表业务应用也已完成启动。如果模板需要预热 Web 应用、Jupyter 等其他服务，应把探针指向能够反映该应用就绪状态的端口和路径，详见[预热模板服务](./tutorials/prewarm-template-service.md)。

> `envd` 不是制作模板的必需组件。只提供自有 Web 服务且不使用命令、文件或终端等 SDK 能力的镜像，可以不安装 `envd`，直接探测应用自己的健康检查端点。需要这些 SDK 能力时，则应使用包含 `envd` 的基础镜像，或在构建模板时注入 `envd`。具体接入方式见[自定义模板镜像](./tutorials/bring-your-own-image.md)。

### 沙箱就绪语义

被探测的端口同时也是沙箱的就绪契约：由于模板只有在探针返回 HTTP 2xx 后才会被标记为就绪，因此由该模板创建的**运行中**沙箱，其被探测端口在创建返回时即可提供服务。客户端无需在 `create` 创建沙箱后额外等待或重试；通过 resume / 自动恢复重新运行起来的沙箱同样适用。

有两点需要注意：

* **该保证只覆盖被探测的端口。** 仅用 `--expose-port` 暴露而未被探测的端口，其上的服务在沙箱开始接收流量时可能仍在启动中；如果需要同样的就绪保证，请改为探测该端口。
* **服务自身必须健康。** 该保证针对的是平台侧的端口可达性——运行中的沙箱里若服务崩溃或停止监听，在其恢复之前仍然不可访问。

## 如何制作模板

CubeSandbox 支持两种制作方式：

* **从 OCI 镜像制作**：准备包含系统、工具和应用依赖的 OCI 镜像，再由 CubeSandbox 将其转换为模板。这是创建可复现模板的常用方式，详见[从 OCI 镜像制作模板](./tutorials/template-from-image.md)。
* **从运行中的沙箱制作**：先在沙箱内安装软件或调整环境，再将其当前文件系统和内存状态提交为新模板。适合交互式调试和快速固化环境，详见[将运行中的沙箱提交为模板](./tutorials/template-from-sandbox.md)。

无论采用哪种方式，模板制作过程都可以概括为：准备根文件系统，启动 MicroVM 并等待环境就绪，生成快照，最后注册并发布模板。模板就绪后，CubeSandbox 可以用它快速创建新的沙箱。

## 模板与镜像的关系

OCI 镜像是制作模板的一种输入，而不是可直接启动的 CubeSandbox 模板。两者的主要区别如下：

| | OCI 镜像 | CubeSandbox 模板 |
| --- | --- | --- |
| 包含内容 | 根文件系统和容器元数据 | 根文件系统、MicroVM 快照及沙箱运行配置 |
| 主要用途 | 分发和复现软件环境 | 快速创建 CubeSandbox 沙箱 |
| 使用方式 | 需要先转换为模板 | 可以直接用于创建沙箱 |

因此，同一个 OCI 镜像可以根据 CPU、内存、网络、启动命令等配置制作出不同的模板；从运行中沙箱提交的模板，则会保留该沙箱提交时的文件系统和内存状态。

## 下一步

* [从 OCI 镜像制作模板](./tutorials/template-from-image.md) — 完整的 CLI 指南，包括探针配置、进度监控和故障排查。
* [将运行中的沙箱提交为模板](./tutorials/template-from-sandbox.md) — 固化沙箱当前环境，并按需覆盖创建请求。
* [模板检查与请求预览](./template-inspection-and-preview.md) — 查看模板状态并预览最终生效的请求。