沙箱模板及快照管理
沙箱模板是沙箱实例的规格定义,描述了实例创建时的运行环境配置,包括镜像、资源规格、网络配置、存储挂载和环境变量等参数。通过模板可以将环境配置标准化和复用,避免每次创建实例时重复配置。
模板定义完成后您可以对其进行构建,构建过程中系统会运行沙箱镜像并执行配置好的启动命令,待环境就绪后,将整个沙箱的文件系统、内存和进程状态保存为构建产物,即模板快照。
前提条件
以下示例均基于E2B SDK,请确保已完成配置本地E2B SDK执行环境。
创建沙箱模板
您可以使用Template.build_in_background方法异步创建沙箱模板和快照。
from e2b import Template, wait_for_port
template = (
Template()
.from_image("<your_image>")
.set_start_cmd(
"python3 -m http.server 8081",
wait_for_port(8081),
)
)
build = Template.build_in_background(
template,
name="template-test",
arch="x86_64",
description="test",
api_headers={
"X-User-Project-ID":"user-project-id-02",
"X-Project-ID":"project-id-02",
},
memory_mb=4096,
gateway_id="gateway-id-02",
network_configuration={
"networkMode": "networkModePrivate",
"targetProjectId": "targetProjectId-02",
"targetVpcId": "targetVpcId-02",
"targetSubnetId": "targetSubnetId-02",
},
invoke={
"protocol": "HTTP",
"port": 49984,
},
env_vars={"FOO_1": "bar-1"},
first_invoke_cmd=["/bin/sh", "-c", "echo build-ready-1"],
agencies={
"runtimeAgency": "my-agency-1",
},
liveness_probe={
"probeHandler": {
"httpGet": {
"path": "/health-1",
"protocol": "HTTP",
"port": 49983,
},
},
"probeConfig": {
"initialDelaySeconds": 3,
"timeoutSeconds": 6,
"periodSeconds": 4,
"failureThreshold": 12,
"enabled": True,
},
},
observability={
"logs": {
"enableStdLogs": True,
},
},
session_storage_config={
"mountDir": "mountDir-1",
},
storage_config={
"obsMounts": [
{
"bucket": "bucket-1",
"bucketPath": "bucketPath-1",
"mountDir": "mountDir-1",
"readOnly": True,
}
],
"sfsTurboMounts": [
{
"sfsTurboId": "sfsTurboId-1",
"shareRoot": "shareRoot-1",
"sharePath": "sharePath-1",
"mountDir": "mountDir-1",
"readOnly": False,
"withSessionCredential": True,
}
],
},
)
print(f"template build started: {build}")
status= Template.get_build_status(build)
print(f"get build status: {status}") | 参数 | 是否必选 | 说明 |
|---|---|---|
| template | 必选 | 沙箱模板对象,用于定义沙箱实例的基础配置(基础镜像、构建步骤、启动命令等)。通过Template().from_image(...)创建。 |
| name | 必选 | 模板名称,构建成功后以该名称标识模板。 |
| arch | 必选 | 沙箱运行架构,如x86_64。需与基础镜像架构匹配,影响构建产物和运行时兼容性。 |
| description | 可选 | 模板描述信息,用于说明该模板的用途、环境内容等,便于管理和检索。 |
| api_headers | 可选 | 自定义API请求头,以字典传递。示例中的X-User-Project-ID、X-Project-ID用于华为云多租户/项目隔离场景,标明沙箱归属的用户项目与项目ID,确保资源创建在正确的项目空间下。 |
| timeout | 可选 | 沙箱实例的超时时间(秒)。超时后沙箱自动终止,防止资源长期占用。 |
| api_key | 必选 | 访问AgentSphere服务的API Key,用于身份认证与权限控制。 |
| memory_mb | 必选 | 沙箱分配的内存量(MB)。例如4096表示4GB内存。 |
| gateway_id | 必选 | 华为云AgentSphere网关实例ID,指定沙箱网络流量经过的网关实例,用于网络隔离与访问控制。 |
| network_configuration | 必选 | 沙箱网络配置,控制沙箱连接的网络模式与所属网络资源。 networkModePrivate表示私有网络模式;targetProjectId/targetVpcId/targetSubnetId 指定沙箱接入的目标项目、VPC 与子网,实现跨项目组网或按需网络接入。 |
| invoke | 可选 | 沙箱被调用(invoke)时的协议与端口配置。 protocol: HTTP表示通过HTTP协议访问;port为对外暴露的服务端口(如49984),供外部/EnvD调用沙箱内服务。 |
| env_vars | 可选 | 沙箱环境变量,以字典形式传入(如FOO_1: bar-1),沙箱内进程启动后可直接读取,用于注入配置、密钥或运行参数。 |
| first_invoke_cmd | 可选 | 首次调用(invoke)时在沙箱内执行的命令。示例/bin/sh -c "echo build-ready-1"用于沙箱就绪后执行一次初始化/验证命令,返回执行结果确认环境可用。 |
| agencies | 可选 | 沙箱运行时使用的委托/代理(Agency)配置。runtimeAgency指定华为云IAM委托名称,使沙箱内进程可通过该委托获得临时凭证访问其他云服务(如OBS、SFS等)。 |
| liveness_probe | 可选 | 沙箱存活探针,用于检测沙箱内主服务是否健康可用,不健康时触发重启/重建。
|
| observability | 可选 | 沙箱可观测性配置,控制日志/监控采集。logs.enableStdLogs为true时收集沙箱标准输出日志(stdout/stderr),便于排查沙箱内运行问题。 |
| session_storage_config | 可选 | 会话级存储配置。mountDir指定会话存储挂载到沙箱内的目录路径,用于在会话期间保存临时/中间数据,会话结束可回收。 |
| storage_config | 可选 | 沙箱持久化存储配置,挂载外部存储到沙箱。
|
| cpu_count | 可选 | 沙箱分配的CPU核数,默认2。 |
| tags | 可选 | 为模板构建附加其他标签,便于多版本管理。 |
| skip_cache | 可选 | 为True时强制全量重建,忽略构建缓存,用于排查缓存导致的构建问题。 |
删除沙箱模板
您可以使用Template.delete_build删除沙箱模板。
Template.delete_build(build.template_id, build.build_id)
print("template build deleted") | 参数 | 说明 |
|---|---|
| template_id | 沙箱模板ID,可在控制台页面查看。 |
| build_id | 模板构建后的快照ID,可在控制台页面查看。 |