构建自定义镜像模板

ACREE 准备

1. 在与云沙箱相同 UID、相同地域下，创建 ACR EE 实例（经济版暂不支持）。

2. 为 ACR EE 实例添加专有网络，确保云沙箱可以通过 VPC 拉取镜像。

镜像要求

推荐基础镜像：Ubuntu 20.04、Debian 12 (bookworm) 及以上（仅作推荐，不强制发行版）。自定义镜像需满足下表要求，按“硬性 / 条件 / 推荐”分级：

镜像推送

将镜像推送到该 ACR EE 仓库，得到支持 VPC 访问的内网镜像地址，例如 test-registry-vpc.cn-beijing.cr.aliyuncs.com/runtime/python:3.12-v1。

不要向同一个 tag 推送内容不同的镜像。每个不同的镜像都必须使用新的唯一 tag，例如使用版本号、日期或提交 ID，并让模板固定引用对应 tag。

构建 template

安装依赖：

python3 -m venv .venv
source .venv/bin/activate
pip install e2b==2.31.0 e2b-code-interpreter==2.8.1 python-dotenv

创建 .env 文件：

# 使用前请替换为自己的 API_KEY 和镜像地址
E2B_API_KEY=e2b_xxx
FROM_IMAGE="test-registry-vpc.cn-beijing.cr.aliyuncs.com/runtime/python:3.12-v1"

# 北京生产环境地址示例值
E2B_API_URL=https://api.cn-beijing.e2b.fc.aliyuncs.com
E2B_DOMAIN=cn-beijing.e2b.fc.aliyuncs.com

运行脚本，将 image 构建为 template，并创建 sandbox 验证：

#!/usr/bin/env python3

import os
import time

from dotenv import load_dotenv
from e2b import Template, default_build_logger
from e2b_code_interpreter import Sandbox


load_dotenv()

FROM_IMAGE = os.getenv("FROM_IMAGE", "").strip()
RUN_CODE = "print('hello')"

# SDK 自动读取 E2B_API_KEY / E2B_API_URL / E2B_DOMAIN 环境变量。
build = Template.build(
    Template().from_image(FROM_IMAGE),
    name=f"template-{int(time.time())}",
    cpu_count=2,
    memory_mb=2048,
    skip_cache=False,
    on_build_logs=default_build_logger(),
)
sandbox = Sandbox.create(template=build.template_id, timeout=900)

try:
    print(f"template_id: {build.template_id}")
    print(f"build_id: {build.build_id}")
    print(f"sandbox_id: {sandbox.sandbox_id}")
    print(f"sandbox_domain: {sandbox.sandbox_domain}")
    print(f"envd_api_url: {sandbox.envd_api_url}")

    execution = sandbox.run_code(RUN_CODE, timeout=60, request_timeout=120)
    stdout = "".join(execution.logs.stdout or [])
    stderr = "".join(execution.logs.stderr or [])

    print(f"run_code code: {RUN_CODE}")
    print(f"run_code stdout: {stdout.strip()}")
    print(f"run_code stderr: {stderr.strip()}")
    print(f"run_code error: {execution.error}")

    if execution.error is not None:
        raise RuntimeError(f"run_code 执行失败: {execution.error}")
    if stdout.strip() != "hello":
        raise RuntimeError(f"run_code stdout 不符合预期: {stdout!r}")
finally:
    print(f"killing sandbox: {sandbox.sandbox_id}")
    sandbox.kill()
    print("sandbox killed")

TypeScript 示例：

import { Sandbox, Template, defaultBuildLogger } from "@e2b/code-interpreter";

// SDK 自动读取 E2B_API_KEY / E2B_API_URL / E2B_DOMAIN 环境变量。
const build = await Template.build(
  Template().fromImage(process.env.FROM_IMAGE),
  `template-${Date.now()}`,
  {
    cpuCount: 2,
    memoryMB: 2048,
    skipCache: false,
    onBuildLogs: defaultBuildLogger(),
  },
);

const sandbox = await Sandbox.create(build.templateId, {
  timeoutMs: 900_000,
});

try {
  console.log(`template_id: ${build.templateId}`);
  console.log(`build_id: ${build.buildId}`);
  console.log(`sandbox_id: ${sandbox.sandboxId}`);

  const execution = await sandbox.runCode("print('hello')", {
    timeoutMs: 60_000,
    requestTimeoutMs: 120_000,
  });

  console.log(`run_code stdout: ${execution.logs.stdout.join("").trim()}`);
  console.log(`run_code stderr: ${execution.logs.stderr.join("").trim()}`);
  console.log("run_code error:", execution.error);

  if (execution.error) {
    throw new Error(`run_code failed: ${execution.error.value}`);
  }
} finally {
  await sandbox.kill();
}

使用 FC E2B 官方镜像

FC E2B 提供了官方镜像，不需要您提供 ACREE，即可直接构建模板并创建沙箱验证：

复用快速开始的 Python 脚本，直接使用以下镜像地址：

FROM_IMAGE="fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/code-interpreter-v1:v0.0.31"

目前北京地域的 FC E2B 官方镜像地址列表为

fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/base:v0.0.31
fc-e2b-registry.cn-beijing.cr.aliyuncs.com/runtime/code-interpreter-v1:v0.0.31

使用 CLI 查看模板并创建沙箱

如果已经安装 E2B CLI，可以通过模板列表确认构建状态：

export E2B_API_KEY=e2b_xxx
export E2B_ACCESS_TOKEN=$E2B_API_KEY
export E2B_API_URL=https://api.cn-beijing.e2b.fc.aliyuncs.com
export E2B_DOMAIN=cn-beijing.e2b.fc.aliyuncs.com

e2b template list

当模板状态为 ready 后，可以使用模板名称或 template_id 创建沙箱：

e2b sandbox create my-code-interpreter-v1

进入沙箱后建议先验证关键依赖：

env | sort | head
python3 --version
which python3

ACR EE 网络要求

使用自己的 ACR EE 镜像前，请先确认以下条件：

• ACR EE 实例已至少绑定一个专有网络 VPC。

• 该 VPC 下至少有一个 vSwitch 位于函数计算支持的可用区。

• ACR EE 镜像仓库、VPC、vSwitch 与云沙箱需位于同一地域，例如本文默认使用北京地域。

• ACR EE 访问控制与 VPC 配置已允许对应网络访问。

• VPC 网段需使用 RFC 1918 规定的私有地址段，即 10.0.0.0/8、172.16.0.0/12 或 192.168.0.0/16。不支持公网私用，详情请参见VPC 常见问题。

• VPC 下需至少配置一个非云服务托管的安全组，且该安全组规则需允许访问对应的 ACR EE 实例。

函数计算支持的可用区会随地域和产品能力调整，最新列表请参考配置网络。

模板名称最佳实践

建议在模板名称中包含业务名、基础镜像、关键依赖版本或日期，例如 agent-python313-20260531。生产环境避免覆盖正在使用的模板，先创建新模板并灰度验证。

高级配置：通过 Header 调整模板构建

sandbox-gateway 支持通过 Template.build(..., headers={...}) 传入 X-E2B-Template-* 扩展 Header。只有需要显式指定构建模式、目标镜像、私有仓库凭证或 ACR EE 网络时，才需要配置这些 Header。

其中 builder 用于把普通业务镜像处理成可用于云沙箱模板的镜像。构建时，平台会临时启动一个 FC 函数，由这个 builder 函数拉取源镜像、加入云沙箱运行所需的依赖，并推送为目标镜像；模板最终使用这个目标镜像创建沙箱运行环境。

示例：

headers = {
    "X-E2B-Template-Build-Mode": "builder",
    "X-E2B-Template-Source-Registry-Type": "acree",
    "X-E2B-Template-Dest-Image-Ref": "example-registry.cn-beijing.cr.aliyuncs.com/example/app:e2b",
    "X-E2B-Template-Source-Username": "source-user",
    "X-E2B-Template-Source-Password": "source-password",
    "X-E2B-Template-Dest-Username": "dest-user",
    "X-E2B-Template-Dest-Password": "dest-password",
    "X-E2B-Template-Source-ACREE-Instance-ID": "cri-example",
    "X-E2B-Template-Source-VPC-ID": "vpc-example",
    "X-E2B-Template-Source-VSwitch-IDs": "vsw-example-a,vsw-example-b",
    "X-E2B-Template-Source-Security-Group-ID": "sg-example",
}

build = Template.build(
    Template().from_image(image),
    name=name,
    cpu_count=2,
    memory_mb=2048,
    skip_cache=False,
    on_build_logs=default_build_logger(),
    headers=headers,
)

支持的 Header：

builder 模式还可以配置以下 Header：

构建模式说明：

• builder：使用临时 FC 函数处理源镜像，加入云沙箱运行依赖，并生成适配云沙箱的目标镜像，适合普通业务镜像。

• direct：不执行镜像转换，直接把源镜像作为 custom-container 模板函数镜像。源镜像需要已经具备 E2B 运行依赖。

注意事项：

• 密码、token 等敏感信息建议只从 .env 或环境变量读取，不要写入代码仓库，也不要打印到日志。

• VPC、vSwitch、安全组 Header 只用于 builder 访问源镜像仓库，不影响最终模板和沙箱的网络配置。

1. 模板构建慢

优先检查自己的 ACR EE 镜像体积、网络链路、镜像层缓存和 ACR EE 私网访问配置。基础镜像越大，首次构建通常越慢。

如果只是排查模板构建链路是否正常，可以临时使用已有 E2B 兼容镜像做对照验证。这类镜像已经注入 envd 等运行依赖，通常更容易排除镜像适配问题。

2. ACR EE 镜像拉取失败

检查镜像地址、地域、命名空间、仓库权限、VPC 绑定和访问控制配置。使用私有 ACR EE 镜像时，网络配置错误比 SDK 参数错误更常见。

3. vSwitch 所在可用区不支持

如果构建或运行过程中遇到 vSwitch is in unsupported zone，说明当前选择的 vSwitch 所在可用区不被函数计算支持。

处理方式：

1. 根据错误信息确认当前 vSwitch 所在可用区。

2. 在函数计算支持的可用区中选择一个 Zone。

3. 在同一个 VPC 中新建该 Zone 下的 vSwitch。

4. 使用这个新的 vSwitch 配置函数计算或相关网络配置。

5. 重新构建模板并创建沙箱验证。

同一个 VPC 内不同可用区的交换机默认内网互通。因此，即使业务资源在其他可用区，也可以在同一个 VPC 中新增一个函数计算支持可用区下的 vSwitch，用于完成函数计算侧网络接入。

4. 沙箱创建成功但 run_code 失败

run_code 会调用镜像的 python3 命令执行代码，如果镜像不包含 python3 或相关依赖，可能会导致执行失败。建议先确认镜像是否包含代码解释器所需依赖。可以在沙箱中运行：

python3 --version
which python3
env | sort | head -50