模板管理 - 函数计算

本文介绍如何删除、获取和列出模板，以及如何排查模板构建问题。以下示例均使用模板 ID。

准备工作

配置云沙箱的 API Key、API URL 和域名。<region> 必须与模板所在地域一致。

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"
export TEMPLATE_ID="<template-id>"

Python 示例使用 requests 库：

pip install requests

删除模板

删除操作不可恢复。执行前先确认模板 ID，避免误删仍在使用的模板。

curl

curl --request DELETE \
  --url "${E2B_API_URL}/templates/${TEMPLATE_ID}" \
  --header "X-API-Key: ${E2B_API_KEY}"

Python requests

import os

import requests

api_url = os.environ["E2B_API_URL"].rstrip("/")
template_id = os.environ["TEMPLATE_ID"]

response = requests.delete(
    f"{api_url}/templates/{template_id}",
    headers={"X-API-Key": os.environ["E2B_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(f"已删除模板：{template_id}")

E2B CLI

下面的命令会要求确认后再删除模板：

e2b template delete "${TEMPLATE_ID}"

自动化脚本可以增加 --yes 跳过确认。使用该参数前，应确保 TEMPLATE_ID 已通过程序校验。

获取模板

获取接口根据模板 ID 返回模板详情及其构建记录。

curl

curl --request GET \
  --url "${E2B_API_URL}/templates/${TEMPLATE_ID}" \
  --header "X-API-Key: ${E2B_API_KEY}"

Python requests

import json
import os

import requests

api_url = os.environ["E2B_API_URL"].rstrip("/")
template_id = os.environ["TEMPLATE_ID"]

response = requests.get(
    f"{api_url}/templates/{template_id}",
    headers={"X-API-Key": os.environ["E2B_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))

E2B CLI

E2B CLI 当前没有单独的 template get 命令。可以输出 JSON 格式的模板列表，再使用 jq 按模板 ID 获取对应的列表项：

e2b template list --format json \
  | jq --arg template_id "${TEMPLATE_ID}" \
      '.[] | select(.templateID == $template_id)'

该方式返回模板的列表摘要。如果需要查看模板详情和构建记录，请使用 curl 或 Python requests 调用获取接口。

列出模板

列表接口返回当前账号在目标地域可见的模板。

curl

curl --request GET \
  --url "${E2B_API_URL}/templates" \
  --header "X-API-Key: ${E2B_API_KEY}"

Python requests

import json
import os

import requests

api_url = os.environ["E2B_API_URL"].rstrip("/")

response = requests.get(
    f"{api_url}/templates",
    headers={"X-API-Key": os.environ["E2B_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))

E2B CLI

以表格形式列出模板：

e2b template list

需要在脚本中处理结果时，可以输出 JSON：

e2b template list --format json

模板构建

不支持通过 E2B Template 内联传入 steps 或 Dockerfile，如何构建依赖？

当前 Template Build API 不支持在 E2B Template 定义中内联传入 steps（安装步骤）或 Dockerfile。传入 steps 会返回 400 steps are not supported，因此不要试图用构建步骤在线安装依赖。

这里不支持的只是「通过 E2B Template 定义内联传入 steps 或 Dockerfile」这种用法；Dockerfile 本身仍然可用：你可以照常在外部用 Dockerfile 构建出成品镜像，再通过 from_image 从镜像仓库构建模板。

因此，依赖应在 Dockerfile 或外部镜像构建阶段装好，再把成品镜像推送到镜像仓库，模板只负责从该镜像构建。这样可以避免在模板构建或每次创建 Sandbox 后重复下载和安装依赖。

精简的 Dockerfile 示例：

FROM python:3.12-slim

# 安装 Python 依赖
RUN pip install --no-cache-dir pandas numpy

# 安装系统依赖并清理 apt 索引
RUN apt-get update \
    && apt-get install -y --no-install-recommends git \
    && rm -rf /var/lib/apt/lists/*

排查失败时先看错误摘要；如果摘要不足以定位，再查看完整构建日志中的失败阶段、RequestId、镜像地址和构建配置。

模板构建与自定义镜像的完整流程，参见构建自定义镜像模板。

私有镜像拉取或构建失败，怎么排查？

先在完整构建日志中确认失败阶段，再按下表处理常见的源镜像拉取和镜像格式问题。

失败阶段	典型错误	处理动作
拉取源镜像	`unauthorized`、`denied`、`manifest unknown` 或 `not found`	核对镜像地址、tag 或 digest 是否真实存在。使用 ACR EE 时，确认实例与云沙箱属于同一 UID、同一地域，已绑定构建链路可访问的 VPC，并检查用户名、密码或 token。
转换/构建	`invalid image, platform of image is unknown/unknown`，或 manifest、provenance 相关错误	检查镜像 manifest。使用 `linux/amd64` 单一平台构建，关闭 provenance 和 SBOM，推送新 tag 后重试；不要复用内容可能已变化的旧 tag。

自定义镜像模板的完整构建流程参见构建自定义镜像模板；从私有仓库拉取镜像的端到端示例参见使用 GHCR 自定义镜像构建 Sandbox 模板。