创建Sandbox时挂载OSS Volume-智能体沙箱(Agent Sandbox)-阿里云帮助中心

创建 Sandbox 时，可通过volume_mounts将已有 OSS Volume 挂载到指定目录。

功能介绍

挂载后，Sandbox 可以通过文件路径访问 OSS，数据不随 Sandbox 释放而删除。

如需向运行中的 Sandbox 追加挂载，请参见追加挂载 Volume。

适用范围

已为目标 Team 创建 OSS Volume，并获取 Volume 名称。
已准备绑定同一 Team 的智能体沙箱 API Key。Volume 和 API Key 不能跨 Team 使用。具体操作，请参见创建 API Key。
已准备 RAM（Resource Access Management，访问控制）角色。该角色具备目标 OSS 路径的访问权限，且信任策略允许函数计算服务扮演。具体操作，请参见配置 RAM 角色。
已准备智能体沙箱 API URL、Domain 和可用模板。

使用第二代运行时（MicroVM，微型虚拟机）自定义模板时，源镜像必须预装 ossfs2 2.0.10 或以上版本。

操作步骤

步骤一：准备第二代运行时镜像

本步骤仅适用于使用第二代运行时（MicroVM）自定义模板的场景。已有符合要求的模板时，跳过本步骤，直接进入步骤二：安装 SDK。

如果使用第二代运行时（MicroVM）的自定义模板，必须在构建模板前，在源镜像中预装 ossfs2 2.0.10 或以上版本。第二代运行时直接使用源镜像，不会在模板构建时注入 ossfs2。当前 ossfs2 安装包仅支持 linux/amd64。以下 Dockerfile 以 Ubuntu 22.04 和 ossfs2 2.0.10 为例：

FROM ubuntu:22.04

ARG DEBIAN_FRONTEND=noninteractive
ARG OSSFS2_DEB_URL=https://gosspublic.alicdn.com/ossfs/ossfs2_2.0.10_linux_x86_64.deb
ARG OSSFS2_DEB_SHA256=72e864b8087d6f889c5017339c625154619f626bbc13c9afcb70403544ad9b70

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends ca-certificates curl fuse3; \
    curl --fail --location --retry 3 \
        "${OSSFS2_DEB_URL}" \
        --output /tmp/ossfs2.deb; \
    echo "${OSSFS2_DEB_SHA256}  /tmp/ossfs2.deb" | sha256sum -c -; \
    apt-get install -y --no-install-recommends /tmp/ossfs2.deb; \
    rm -f /tmp/ossfs2.deb; \
    rm -rf /var/lib/apt/lists/*

WORKDIR /root

安装包升级时，必须同时更新 OSSFS2_DEB_URL 和 OSSFS2_DEB_SHA256。不要跳过 SHA-256 校验，也不要在镜像中加入存储凭证或挂载配置。

构建并推送 linux/amd64 镜像。执行前请将占位符替换为实际值：

docker buildx build \
  --platform linux/amd64 \
  --push \
  -t <REGISTRY>/<NAMESPACE>/microsandbox-ossfs2:2.0.10 \
  .

构建完成后，验证镜像中的 ossfs2 不低于 2.0.10：

docker run --rm --platform linux/amd64 \
  <REGISTRY>/<NAMESPACE>/microsandbox-ossfs2:2.0.10 \
  sh -euxc '
    test -x /usr/local/bin/ossfs2
    installed_version="$(dpkg-query -W ossfs2 | cut -f2)"
    dpkg --compare-versions "${installed_version}" ge "2.0.10"
  '

该检查只验证镜像内容，不代表权限、Endpoint 或真实挂载链路已经可用。

使用步骤一的镜像创建第二代运行时（MicroVM）自定义模板后，在步骤三的挂载示例中将 E2B_TEMPLATE 设置为该模板的 ID 或别名。具体操作，请参见控制台管理自定义模板。

步骤二：安装 SDK

本文使用 E2B Python SDK 演示。volume_mounts 需要 E2B Python SDK 2.31.0 版本。

python3 -m venv .venv
source .venv/bin/activate
pip install "e2b==2.31.0"

步骤三：挂载并验证

环境变量说明

环境变量	用途	取值来源或填写方式
`E2B_API_KEY`	访问智能体沙箱的 API Key。	从智能体沙箱控制台获取，必须绑定 Volume 所属的 Team。
`E2B_API_URL`	E2B API 请求地址。	填写 `https://api.<REGION>.sandbox.aliyuncs.com`，地域与目标 Volume 一致。
`E2B_DOMAIN`	SDK 使用的服务域名。	填写 `<REGION>.sandbox.aliyuncs.com`，与 API 地址使用同一地域，不带协议前缀。
`E2B_TEMPLATE`	创建 Sandbox 使用的模板，可以是官方模板或自定义模板。	填写满足本文适用范围要求的可用模板 ID 或别名；可从智能体沙箱控制台获取。
`OSS_VOLUME_NAME`	要挂载的 OSS Volume 名称。	使用本文创建 OSS Volume中设置的名称，或从 Volume 列表查询；不使用 Volume ID。

挂载示例

在终端中设置以下参数，并将所有占位符替换为实际值。各变量的取值参见本文环境变量说明。

export E2B_API_KEY="<YOUR-E2B-API-KEY>"
export E2B_API_URL="https://api.<REGION>.sandbox.aliyuncs.com"
export E2B_DOMAIN="<REGION>.sandbox.aliyuncs.com"
export E2B_TEMPLATE="<TEMPLATE-ID-OR-ALIAS>"

export OSS_VOLUME_NAME="<YOUR-VOLUME-NAME>"

挂载目录位于 Sandbox 内，对应 volume_mounts 的键。建议使用 /home、/mnt、/tmp 或 /data 的子目录，本文使用 /mnt/oss。

以下示例复用 Volume 的 mountConfig.role，将 OSS Volume 挂载到 /mnt/oss。请确保 Volume 已保存有效的 RAM 角色。需要通过 metadata 指定角色时，参见配置 RAM 角色。

示例会在挂载目录中创建带随机标识的独立测试文件，写入并读取校验后删除该文件，再释放本次创建的 Sandbox。请使用具备读写权限的挂载配置。

将以下代码保存为 01_mount_oss_volume.py：

import os
from uuid import uuid4

from e2b import Sandbox


def require_env(name: str) -> str:
    value = os.environ.get(name, "").strip()
    if not value:
        raise RuntimeError(f"缺少环境变量: {name}")
    return value


mount_dir = "/mnt/oss"
marker_path = f"{mount_dir}/hello-oss-{uuid4().hex}.txt"
sandbox = None
marker_written = False

try:
    sandbox = Sandbox.create(
        template=require_env("E2B_TEMPLATE"),
        timeout=300,
        api_key=require_env("E2B_API_KEY"),
        api_url=require_env("E2B_API_URL"),
        domain=require_env("E2B_DOMAIN"),
        volume_mounts={mount_dir: require_env("OSS_VOLUME_NAME")},
    )

    info = sandbox.get_info()
    print(f"volume_mounts={info.volume_mounts}")

    sandbox.files.write(marker_path, "hello oss\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello oss\n":
        raise RuntimeError(f"文件内容不一致: {content!r}")
finally:
    try:
        if sandbox is not None and marker_written:
            sandbox.files.remove(marker_path)
    finally:
        if sandbox is not None:
            sandbox.kill()

print("OSS Volume 挂载读写验证成功")

运行示例：

python 01_mount_oss_volume.py

输出 OSS Volume 挂载读写验证成功 表示本次读写、测试文件清理和 Sandbox 释放已完成。

行为说明

volume_mounts 使用 {挂载目录: Volume 名称} 格式，不使用 Volume ID。
Sandbox 暂停后再恢复时会恢复 Volume 挂载。
释放 Sandbox 不会删除 OSS 中的数据。测试文件由示例主动删除，其他数据的保留和清理需单独处理。
挂载只读 Volume 时，Sandbox 只能读取挂载目录内的文件。

使用限制

由于安全问题，OSS 挂载暂不支持 KMS（Key Management Service，密钥管理服务）服务端加密（SSE-KMS）。
同一 Sandbox 中，OSS 最多 5 个挂载点。数量包含创建时和后续追加的挂载，也包含直接提供存储配置的挂载。
挂载目录必须是规范化的绝对 Unix 路径，不能为 /，不能包含前后空格、重复分隔符、. 或 .. 路径段。
挂载目录不能使用 /bin、/opt、/var、/dev 等系统目录及其子目录，也不能包含 .cache 等以 . 开头的隐藏目录。
同一 Sandbox 中的挂载目录不能重复。

常见问题

提示找不到 Volume

错误消息为 volume not found 时，核对请求中的 Volume 名称、API Key 所属 Team 和 API 地址的地域。按名称挂载需使用同一 Team 中已有的 Volume，不能填写 Volume ID。

Volume 已存在，为什么仍提示不可用

错误消息包含 is not available 时，表示 Volume 存在，但状态尚不满足挂载要求。通过 GetVolume 查询其状态和状态原因，确认处于可用状态后再挂载；存在失败原因时，应先处理该原因。重复提交挂载请求不会使 Volume 变为可用。

创建 Sandbox 提示缺少 RAM 角色

错误消息包含 OSS mount requires Function role 时，表示本次创建未获得挂载所需的 RAM 角色。

本文示例从 Volume 的 mountConfig.role 获取角色；如果创建请求的 metadata 显式设置了 fc.sandbox.auth.role，则以该值为准。核对实际使用的角色配置，补齐有效的角色 ARN（Aliyun Resource Name，阿里云资源名称）后重新提交创建请求。角色配置方法参见配置 RAM 角色。

Sandbox 创建时挂载失败

根据错误消息核对 Volume 保存的 Bucket 名称、对象前缀和 Endpoint。如果消息提示存储访问被拒绝，检查 Sandbox 实际使用的 RAM 角色及 Bucket Policy；角色选择规则参见配置 RAM 角色。

使用第二代运行时自定义模板时，还需按本文步骤一：准备第二代运行时镜像确认已安装 ossfs2。

Volume 已挂载，但无法写入

先检查 Volume 是否设置了 readOnly: true。如果配置为可读写，继续检查 Sandbox 实际使用的 RAM 角色是否具备写入权限，以及 Bucket Policy 是否允许相应操作。

如需进一步排查，请保留完整错误信息和请求 ID。