使用代码构建和管理自定义模板

选择镜像来源

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-demo-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                # 构建与运行日志投递到同地域 SLS。
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
                    generation=2,  # 必填：2 表示二代模板。
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-acree-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="<instance>-registry-vpc.cn-hangzhou.cr.aliyuncs.com/<namespace>/<image>:<tag>",
                    generation=2,
                    acr_instance_id="cri-xxxxxx",
                    registry_config=models.CreateTemplateRegistryConfig(
                        auth_config=models.CreateTemplateRegistryAuthConfig(
                            user_name="<username>",
                            password="<password>",
                        ),
                        network_config=models.CreateTemplateRegistryNetworkConfig(
                            vpc_id="<vpc-id>",
                            v_switch_id="<vsw-id>",
                            security_group_id="<sg-id>",
                        ),
                    ),
                ),
            ),
        )
    )
)

配置启动命令和就绪命令

以一个预置 HTTP 服务的场景说明两个命令的配合方式：构建期平台以后台进程执行 start_command 启动服务，然后反复执行 ready_command，退出码为 0 一次即判定服务就绪，随后对仍在运行的沙箱制作模板快照。基于该模板创建的沙箱在创建时服务已在运行，创建即可访问，不会再次执行启动命令。

• 执行时机：两个命令仅在模板构建期执行，结果固化进快照；创建沙箱时不重放。

• 填写格式：均为字符串形式的 Shell 命令；两个参数均为可选，不配置 start_command 则不执行额外的启动命令。

• 失败处理：start_command 提前退出、ready_command 持续失败或等待超过 5 分钟，模板构建失败；ready_command 写错的典型表现是构建超时而非参数报错。

• 日志排查：命令输出与失败原因通过 log_config 投递到 SLS，在对应 Logstore 中查看。

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen2-service-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                disk_size=15360,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
                    generation=2,
                    # 构建期以后台进程执行。
                    start_command="python3 -m http.server 8000",
                    # 反复执行，退出码为 0 一次即判定就绪。
                    ready_command="curl -sf http://localhost:8000/ > /dev/null",
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

构建就绪后，使用 E2B SDK 创建沙箱并直接访问服务：

from e2b import Sandbox

sandbox = Sandbox.create(
    template=template_id,
    timeout=600,
    # SDK 自动读取 E2B_API_KEY / E2B_API_URL / E2B_DOMAIN 环境变量。
    api_url=f"https://api.{REGION}.e2b.fc.aliyuncs.com",
    domain=f"{REGION}.e2b.fc.aliyuncs.com",
)
try:
    host = sandbox.get_host(8000)
    print(f"https://{host}")
finally:
    sandbox.kill()

选择镜像来源

• 官方公共镜像：一代模板地址格式为 fc-e2b-registry.<地域>.cr.aliyuncs.com/runtime/<镜像名>:<tag>（与二代的 runtime-v2 前缀不同），无需凭证与网络配置，平台直接使用，不再执行构建注入。

• ACR EE 镜像：实例准备、网络约束与拉取方式同二代ACR EE 镜像；镜像地址使用 -vpc 域名。同账号镜像可免凭证，由平台使用实例临时授权拉取。

• OCI 镜像仓库：任意标准 OCI 仓库（公网可达或 VPC 内私有）。通过 registry_config.auth_config 提供仓库凭证（user_name/password，需同时具备拉取和推送权限）；VPC 内私有仓库还需通过 registry_config.network_config 提供拉取网络三件套（vpc_id/v_switch_id/security_group_id）。

选择构建方式

构建非官方镜像时，一代模板通过 build_config 控制两个构建动作：copy（把构建产物推送为目标镜像）和 envd_inject（注入沙箱运行依赖）。

build_config 缺省时按源镜像自动推导：官方公共镜像直接使用，不执行构建；其他镜像执行注入构建。注意 copy 和 envd_inject 需同时开启或同时关闭，只开启其中一个会返回 400。

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-direct-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime/code-interpreter-v1:v0.0.53",
                    generation=1,
                ),
            ),
        )
    )
)

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-builder-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="<instance>-registry-vpc.cn-hangzhou.cr.aliyuncs.com/<namespace>/<image>:<tag>",
                    generation=1,  # 必填：1 表示一代模板。
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

resp = pop_client.create_template(
    models.CreateTemplateRequest(
        body=models.CreateTemplateInput(
            name=f"template-gen1-oci-{int(time.time())}",
            team_id=TEAM_ID,
            runtime_config=models.CreateTemplateRuntimeConfig(
                cpu=2,
                memory_size=2048,
                log_config=models.CreateTemplateLogConfig(
                    project="<sls-project>",
                    logstore="<sls-logstore>",
                ),
                sandbox_config=models.CreateTemplateSandboxConfig(
                    image="registry.internal.example.com/<namespace>/<image>:<tag>",
                    generation=1,
                    registry_config=models.CreateTemplateRegistryConfig(
                        auth_config=models.CreateTemplateRegistryAuthConfig(
                            user_name="<username>",
                            password="<password>",
                        ),
                        network_config=models.CreateTemplateRegistryNetworkConfig(
                            vpc_id="<vpc-id>",
                            v_switch_id="<vsw-id>",
                            security_group_id="<sg-id>",
                        ),
                        cert_config=models.CreateTemplateRegistryCertConfig(
                            insecure=True,  # 自签证书时传入
                        ),
                    ),
                ),
            ),
        )
    )
)
template_id = resp.body.template_id
state = wait_ready(template_id)
assert state == "ready"

查询模板信息和构建状态

通过 ListTemplates 分页查询 Team 下的模板列表，通过 GetTemplate 查询单个模板的配置与构建状态。status.state 取值：pending（等待构建）、building（构建中）、updating（更新配置后重建中）、ready（可用于创建沙箱）、error（构建失败，status.reason.message 给出原因）。建议按 5~10 秒间隔轮询。

完整示例（循环翻页列出全部模板）：

import os

from alibabacloud_sandbox20260820 import models
from alibabacloud_sandbox20260820.client import Client as SandboxClient
from alibabacloud_tea_openapi import models as open_api_models

REGION = "cn-hangzhou"
TEAM_ID = "<your-team-id>"

config = open_api_models.Config(
    access_key_id=os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
    access_key_secret=os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
    region_id=REGION,
    endpoint=f"sandbox.{REGION}.aliyuncs.com",
)
pop_client = SandboxClient(config)

next_token = None
while True:
    request = models.ListTemplatesRequest(team_id=TEAM_ID)
    if next_token:
        request.next_token = next_token
    response = pop_client.list_templates(request)
    for template in response.body.templates:
        print(template.template_id, template.name, template.status.state)
    next_token = response.body.next_token
    if not next_token:
        break

使用已构建的模板创建沙箱

模板进入 ready 状态后，使用 E2B SDK 创建沙箱并验证运行结果：

from e2b import Sandbox

sandbox = Sandbox.create(
    template=template_id,
    timeout=600,
    api_url=f"https://api.{REGION}.e2b.fc.aliyuncs.com",
    domain=f"{REGION}.e2b.fc.aliyuncs.com",
)
try:
    result = sandbox.commands.run("printf hello")
    print(result.stdout)
finally:
    sandbox.kill()

修改配置并重新构建

使用 UpdateTemplate 原地修改模板配置，可更新镜像、规格、网络等配置项。提交后平台自动重新构建，模板回到 updating 状态，构建完成后恢复 ready：

pop_client.update_template(
    template_id,
    models.UpdateTemplateRequest(
        team_id=TEAM_ID,
        body=models.PublicUpdateTemplateInput(
            runtime_config=models.PublicUpdateTemplateRuntimeConfig(
                cpu=4,
                memory_size=4096,
            ),
        ),
    ),
)
state = wait_ready(template_id)
assert state == "ready"

• 只需传入要修改的配置项，未传入的配置项保持原有取值。

清理不再使用的模板

pop_client.delete_template(
    template_id, models.DeleteTemplateRequest(team_id=TEAM_ID))

• 模板处于任意状态（含构建中）都可删除，删除会终止进行中的构建。

场景选择

注意：VPC 网段需使用 RFC 1918 私有地址段（10.0.0.0/8、172.16.0.0/12、192.168.0.0/16）；vSwitch 需位于函数计算支持的可用区。

场景一：访问 VPC 和公网，出口 IP 不固定

配置 vpc_config，并保持 internet_access 开启（缺省即开启）：

runtime_config=models.CreateTemplateRuntimeConfig(
    cpu=2,
    memory_size=2048,
    disk_size=15360,
    internet_access=True,
    vpc_config=models.CreateTemplateVPCConfig(
        vpc_id="<vpc-id>",
        v_switch_ids=["<vsw-id>"],
        security_group_id="<sg-id>",
    ),
    log_config=models.CreateTemplateLogConfig(
        project="<sls-project>",
        logstore="<sls-logstore>",
    ),
    sandbox_config=models.CreateTemplateSandboxConfig(
        image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
        generation=2,
    ),
)

验证方式：创建沙箱后分别访问 VPC 内资源（如内网域名或私网 IP）和公网地址（如 curl https://www.aliyun.com），两者均可访问。该方式不提供固定公网出口 IP。

场景二：仅访问 VPC，不访问公网

配置 vpc_config，并关闭 internet_access；同时确认 VPC 本身未配置公网出口：

runtime_config=models.CreateTemplateRuntimeConfig(
    cpu=2,
    memory_size=2048,
    disk_size=15360,
    internet_access=False,
    vpc_config=models.CreateTemplateVPCConfig(
        vpc_id="<vpc-id>",
        v_switch_ids=["<vsw-id>"],
        security_group_id="<sg-id>",
    ),
    log_config=models.CreateTemplateLogConfig(
        project="<sls-project>",
        logstore="<sls-logstore>",
    ),
    sandbox_config=models.CreateTemplateSandboxConfig(
        image=f"fc-e2b-registry.{REGION}.cr.aliyuncs.com/runtime-v2/base:v0.0.53",
        generation=2,
    ),
)

验证方式：沙箱内访问 VPC 内资源正常；访问公网地址超时或被拒绝。

场景三：访问 VPC 和公网，使用固定出口 IP

配置 vpc_config，并关闭 internet_access。在 VPC 侧配置公网 NAT 网关和 EIP，以及相应的路由与 SNAT 规则，使公网流量通过指定出口访问。详细操作，请参考沙箱实例出公网访问（固定 IP）。

1. VPC 侧准备：为 VPC 配置公网 NAT 网关并绑定 EIP，为相关 vSwitch 配置指向 NAT 网关的路由与 SNAT 规则，确认沙箱所在 vSwitch 的流量能够通过该出口访问公网。

2. 模板侧配置：参数与场景二相同（internet_access=False + vpc_config）。

验证方式：在沙箱内查询出口 IP（如 curl ifconfig.me），返回的应为配置的 EIP。

场景二和场景三的模板构建参数相同，区别在于 VPC 是否具备公网出口。因此，关闭 internet_access 后，仍需结合 VPC 的网络配置判断沙箱是否能够访问公网。

一代模板能否配置启动命令和就绪命令？

不能。一代模板设置 start_command 或 ready_command 会返回 400 InvalidParameter。需要把常驻进程固化到模板时，请使用二代模板。

为什么所有构建示例都包含日志配置？

log_config 将模板构建期和沙箱运行期的日志投递到账号下的 SLS，便于在构建和运行验证过程中定位问题：构建期可查看启动命令、就绪命令的输出和构建失败原因；运行期可查看沙箱内进程日志。日志入口为 SLS 控制台中配置的 Project 和 Logstore，需与云沙箱位于同一地域。

为什么关闭 internet_access 后仍可能访问公网？

internet_access 只控制平台侧公网出口。如果模板接入的 VPC 已配置公网出口（NAT 网关 + EIP + SNAT），沙箱仍可通过该出口访问公网。需要彻底隔离公网时，同时检查模板参数和 VPC 网络配置。

如何获得固定公网出口 IP？

按场景三配置：模板侧关闭 internet_access 并配置 vpc_config；VPC 侧配置公网 NAT 网关和 EIP，并配置相应路由与 SNAT 规则。验证沙箱内出口 IP 是否为配置的 EIP。

镜像拉取失败、构建失败或启动失败时如何排查？

1. 通过 GetTemplate 查看 status.reason.message 获取失败阶段与原因。

2. 在 log_config 配置的 SLS Logstore 中查看详细日志。

3. 按失败阶段分别排查：

   • 镜像拉取失败：确认镜像地址与 tag 正确、凭证具备拉取权限、拉取网络可达（ACR EE 实例 VPC 绑定已生效、安全组出方向放行 443/TCP）。

   • 构建失败：确认镜像满足镜像要求（linux/amd64 架构、存在 /bin/bash、/etc/passwd 可写等）；一代模板确认目标仓库凭证具备推送权限。

   • 启动命令或就绪检查失败（二代）：确认 start_command 不会提前退出，ready_command 探测的是真实就绪条件且能在 5 分钟内通过。