构建 Template 模板 - PPIO 派欧云文档中心

ppio template create 将 Dockerfile 直接构建成可重用的沙箱模板。它读取 Dockerfile、构建镜像、应用沙箱设置（启动/就绪命令、CPU、内存），并以模板名称注册结果 —— 然后您可以将该名称传递给 sandbox.create(...)。

ppio template create <template-name> [options]

# 别名
ppio ct <template-name> [options]

参数

参数	必填	说明
`<template-name>`	是	要创建或重建的模板名称。必须是小写，并且只能包含字母、数字、短横线和下划线（`^[a-z0-9-_]+$`）。

选项

选项	默认值	说明
`-p, --path <path>`	当前目录	更改执行命令的根目录。Dockerfile 查找和构建文件上下文相对于它解析。
`-d, --dockerfile <file>`	`ppio.Dockerfile`，然后是 `Dockerfile`	Dockerfile 的路径，相对于根目录。如果没有此选项，CLI 首先查找 `ppio.Dockerfile`，然后回退到 `Dockerfile`。
`-c, --cmd <start-command>`	—	沙箱启动时执行的命令。必须与 `--ready-cmd` 一起使用。
`--ready-cmd <ready-command>`	—	必须以退出代码 0 退出才能将模板视为就绪的命令。可以单独使用。
`--cpu-count <cpu-count>`	`2`	用于运行沙箱的 CPU 数量。
`--memory-mb <memory-mb>`	`512`	用于运行沙箱的内存（单位为兆字节）。必须是偶数。
`--no-cache`	关闭	构建模板时跳过构建缓存。有关构建缓存的工作原理，请参阅缓存。
`--patch-cmd <cmd>`	—	在配置阶段结束时修补不兼容的基础镜像的命令。

行为和验证

需要身份验证：使用 ppio auth login 登录或在环境中设置 PPIO_API_KEY。
提供 --cmd 而不提供 --ready-cmd 将失败并显示 Both start and ready commands must be provided.；单独使用 --ready-cmd 是允许的。
无效的模板名称或奇数的 --memory-mb 值会在向服务器发送任何内容之前中止构建。
构建日志流式传输到终端。成功后，CLI 打印 Python / JS 代码片段，显示如何从新模板创建沙箱。

示例

# 最简：读取当前目录中的 ./ppio.Dockerfile（或 ./Dockerfile）
ppio template create my-python-template

# 显式指定 Dockerfile
ppio template create my-python-template --dockerfile ./Dockerfile

# 完整：自定义根目录、资源、启动/就绪命令、无缓存
ppio template create my-python-template \
  --path ./app \
  --dockerfile ./docker/ppio.Dockerfile \
  --cpu-count 4 \
  --memory-mb 2048 \
  --cmd "python app.py" \
  --ready-cmd "curl -sf http://localhost:8080/health" \
  --no-cache

上述命令使用的示例 Dockerfile：

FROM python:3.12

WORKDIR /home/user/app

RUN pip install --no-cache-dir flask requests

COPY app.py .

ENV PORT=8080

CMD ["python", "app.py"]

构建完成后，按名称从模板创建沙箱：

const sandbox = await ppio.sandbox.create('my-python-template')

最后修改于 2026年9月1日