构建 Template

Template 是创建 Sandbox 所依据的蓝图——它定义了基础镜像、安装的软件包、文件、环境变量,以及启动时运行的命令。每个 Sandbox 都由某个 Template 生成,因此构建 Template 就是产出可复用、开箱即用环境的方式。 Template 在概念上与容器镜像非常接近: 它可以始于一个 Docker 镜像、Dockerfile 或已有 Template。构建 Template 的体验类似于编写 Dockerfile。你通常可以使用 SDK 构建器(fromImage、runCmd、copy、setEnvs 等)以代码形式描述步骤，也可以直接复用已有的 Dockerfile，或在其他 Template 之上派生。产出是一个 templateId，PPIO 用它来快速启动 Sandbox。

构建

Template 定义就绪后,使用 ppio.template.build(...) 进行构建。根据 Template 定义的来源,构建方式分为三种:从现有的 Docker Image 构建、从 Dockerfile 构建，以及基于已有的其他 Template 构建。

从 Docker Image 构建

使用 fromImage / from_image 以一个现有的 Docker 镜像作为基础构建 Template，构建完成后即可用返回的 template ID 创建 Sandbox。

from ppio_sandbox import PPIO

ppio = PPIO()

template = ppio.template.new().from_image("python:3.12")

build = ppio.template.build(
    template,
    "my-python-template",
    cpu_count=2,
    memory_mb=1024,
)

sandbox = ppio.sandbox.create(build.template_id)
print(sandbox.sandbox_id)

sandbox.kill()

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const template = ppio.template.new().fromImage('python:3.12')

const build = await ppio.template.build(template, 'my-python-template', {
  cpuCount: 2,
  memoryMB: 1024,
})

const sandbox = await ppio.sandbox.create(build.templateId)
console.log(sandbox.sandboxId)

await sandbox.kill()

从 Dockerfile 构建

使用 fromDockerfile / from_dockerfile 直接从 Dockerfile 构建 Template,适合已有 Dockerfile 的项目;也可以通过 CLI 完成同样的构建。

from ppio_sandbox import PPIO

ppio = PPIO()

template = ppio.template.new().from_dockerfile("ppio.Dockerfile")

build = ppio.template.build(
    template,
    "my-dockerfile-template",
    cpu_count=2,
    memory_mb=1024,
)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const template = ppio.template.new().fromDockerfile('ppio.Dockerfile')

const build = await ppio.template.build(template, 'my-dockerfile-template', {
  cpuCount: 2,
  memoryMB: 1024,
})

# 将 Dockerfile 构建为 Sandbox Template（别名：template ct）
# 默认读取根目录下的 ./ppio.Dockerfile（或 Dockerfile）
ppio template create my-python-template

# 指定 Dockerfile、资源和启动命令
ppio template create my-python-template \
  --dockerfile ./ppio.Dockerfile \
  --cpu-count 2 \
  --memory-mb 1024 \
  --cmd "python app.py"

基于其他 Template 构建

使用 fromTemplate / from_template 以一个已构建的 Template(ID 或别名)作为基础,在其之上叠加额外的构建步骤(如运行命令、设置启动/就绪命令),适合从通用基础 Template 派生出多个变体。

from ppio_sandbox import PPIO

ppio = PPIO()

# 使用已有的 Template ID 或别名作为基础 Template
template = (
    ppio.template.new().from_template("my-python-template")
    .run_cmd('echo "hello from from_template" > /home/user/from-template.txt')
    .set_start_cmd("python3 -m http.server 8080")
)

build = ppio.template.build(
    template,
    "from-template-demo:v1",
)

print(build.template_id)
print(build.build_id)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// 使用已有的 Template ID 或别名作为基础 Template
const template = ppio.template.new().fromTemplate('my-python-template')
  .runCmd('echo "hello from from_template" > /home/user/from-template.txt')
  .setStartCmd('python3 -m http.server 8080')

const build = await ppio.template.build(template, 'from-template-demo:v1')

console.log(build.templateId)
console.log(build.buildId)

名称

每次构建都需要一个 Template 名称。同一逻辑 Template 系列应保持名称稳定。返回的 Template ID 是不可变的构建产物，供运行时使用。

基础镜像

Template 定义总是以选择一个基础镜像(或已有 Template)开始，使用某个 from* 方法。

from ppio_sandbox import PPIO

ppio = PPIO()

# PPIO 默认基础镜像
base = ppio.template.new().from_base_image()

# 特定语言的镜像
python = ppio.template.new().from_python_image("3.12")
ubuntu = ppio.template.new().from_ubuntu_image("24.04")

# 自定义镜像（可选携带私有镜像仓库凭证）
custom = ppio.template.new().from_image(
    "myregistry.com/myimage:latest",
    credentials={"username": "user", "password": "pass"},
)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// PPIO 默认基础镜像
const base = ppio.template.new().fromBaseImage()

// 特定语言的镜像
const python = ppio.template.new().fromPythonImage('3.12')
const ubuntu = ppio.template.new().fromUbuntuImage('24.04')

// 自定义镜像（可选携带私有镜像仓库凭证）
const custom = Template
  .fromImage('myregistry.com/myimage:latest', {
    username: 'user',
    password: 'pass',
  })

用户与工作目录

选定基础镜像后,你可以控制后续构建步骤以哪个用户身份运行，以及在哪个目录中执行。

from ppio_sandbox import PPIO

ppio = PPIO()

template = (
    ppio.template.new()
    .from_ubuntu_image("24.04")
    .set_user("root")
    .apt_install(["git"])
    .set_user("user")
    .set_workdir("/home/user/app")
)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const template = ppio.template.new()
  .fromUbuntuImage('24.04')
  .setUser('root')
  .aptInstall(['git'])
  .setUser('user')
  .setWorkdir('/home/user/app')

标签与版本管理

标签(tag)让你为构建打上标记以便发布管理,而无需更改底层的 Template 名称。

from ppio_sandbox import PPIO

ppio = PPIO()

template = ppio.template.new().from_python_image("3.12")

build = ppio.template.build(
    template,
    "agent-runtime-base",
    tags=["v1.0.0", "latest"],
)

ppio.template.assign_tags("agent-runtime-base:v1.0.0", "production")

tags = ppio.template.get_tags(build.template_id)
print(tags)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const template = ppio.template.new().fromPythonImage('3.12')

const build = await ppio.template.build(template, 'agent-runtime-base', {
  tags: ['v1.0.0', 'latest'],
})

await ppio.template.assignTags('agent-runtime-base:v1.0.0', 'production')

const tags = await ppio.template.getTags(build.templateId)
console.log(tags)

日志

构建日志可帮助你查看配置进度并诊断失败原因。

from ppio_sandbox import PPIO

ppio = PPIO()

template = ppio.template.new().from_python_image("3.12")

build = ppio.template.build(template, "my-logged-template")
print(build.build_id)

import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

const template = ppio.template.new().fromPythonImage('3.12')

const build = await ppio.template.build(template, 'my-logged-template')
console.log(build.buildId)

错误处理

Template 构建可能因以下几种常见原因失败:

私有镜像仓库的凭据无效
runCmd(...) / run_cmd(...) 中的软件包安装失败
启动命令意外退出
就绪命令始终未成功
CPU 和内存设置不满足平台限制

产品简介

快速开始

最佳实践

Sandbox

Template

Snapshot

文件系统

Secret

Volume

工具集成

CLI 功能

旧版归档

构建

从 Docker Image 构建

从 Dockerfile 构建

基于其他 Template 构建

名称

基础镜像

用户与工作目录

标签与版本管理

日志

错误处理

​构建

​从 Docker Image 构建

​从 Dockerfile 构建

​基于其他 Template 构建

​名称

​基础镜像

​用户与工作目录

​标签与版本管理

​日志

​错误处理

构建

从 Docker Image 构建

从 Dockerfile 构建

基于其他 Template 构建

名称

基础镜像

用户与工作目录

标签与版本管理

日志

错误处理