# 沙箱模板及快照管理 沙箱模板是沙箱实例的规格定义，描述了实例创建时的运行环境配置，包括镜像、资源规格、网络配置、存储挂载和环境变量等参数。通过模板可以将环境配置标准化和复用，避免每次创建实例时重复配置。 模板定义完成后您可以对其进行构建，构建过程中系统会运行沙箱镜像并执行配置好的启动命令，待环境就绪后，将整个沙箱的文件系统、内存和进程状态保存为构建产物，即模板快照。 #### 前提条件 以下示例均基于E2B SDK，请确保已完成[配置本地E2B SDK执行环境](https://support.huaweicloud.com/sdkreference-agentsphere/agentsphere_05_0001.html)。 #### 创建沙箱模板 您可以使用Template.build_in_background方法异步创建沙箱模板和快照。 ``` from e2b import Template, wait_for_port template = ( Template() .from_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** | 可选 | 沙箱存活探针，用于检测沙箱内主服务是否健康可用，不健康时触发重启/重建。 - probeHandler.httpGet：定义HTTP探测方式 - path：探测路径 - protocol：HTTP协议 - port：探测端口 - probeConfig：定义探测策略 - initialDelaySeconds：启动后延迟探测秒数 - timeoutSeconds：单次探测超时 - periodSeconds：探测周期 - failureThreshold：连续失败多少次判定不健康 - enabled：是否启用探针 | | **observability** | 可选 | 沙箱可观测性配置，控制日志/监控采集。logs.enableStdLogs为true时收集沙箱标准输出日志（stdout/stderr），便于排查沙箱内运行问题。 | | **session_storage_config** | 可选 | 会话级存储配置。mountDir指定会话存储挂载到沙箱内的目录路径，用于在会话期间保存临时/中间数据，会话结束可回收。 | | **storage_config** | 可选 | 沙箱持久化存储配置，挂载外部存储到沙箱。 - obsMounts：OBS对象存储挂载数组 - bucket：桶名 - bucketPath：桶内路径 - mountDir：挂载到沙箱内路径 - readOnly：是否只读 - sfsTurboMounts：SFS Turbo文件系统挂载数组 - sfsTurboId：文件系统 ID - shareRoot/sharePath：共享根/共享路径 - mountDir：挂载目录 - readOnly：是否只读 - withSessionCredential：是否注入会话临时凭证访问该文件系统 | | **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，可在控制台页面查看。 |