挂载 AgenticFS Volume

前提条件

• 已为目标 Team 创建 AgenticFS Volume，并获取 Volume 名称。

• 已准备绑定同一 Team 的云沙箱 API Key。Volume 和 API Key 不能跨 Team 使用。

• 已准备与 AgenticFS Access Point 网络连通的 VPC、vSwitch 和安全组。

• 已准备函数执行 RAM Role。该 Role 具备 AgenticFS 挂载和读写权限，且信任策略允许函数计算服务扮演。

• 已准备云沙箱 API URL、Domain 和可用模板。

注意：创建 Sandbox 前，必须确保对应的 AgenticFS Access Point 处于 active 状态，否则 createSandbox 调用可能超时或失败。您可以登录 AgenticFS 控制台，找到对应的 FileSystem，进入 FileSystem 详情页面，然后单击挂载使用查看挂载点状态。

配置权限

请将以下权限策略授予函数执行 RAM Role：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "nas:ClientMount",
        "nas:ClientWrite",
        "nas:ClientRootAccess"
      ],
      "Resource": "*"
    }
  ]
}

该 Role 的信任策略还必须允许函数计算服务扮演。相关配置参见权限策略及示例。

安装 SDK

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

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

运行示例前设置以下环境变量：

export E2B_API_KEY="<your-e2b-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"
export E2B_TEMPLATE="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"
export FCSANDBOX_VPC_ID="vpc-xxxxxxxx"
export FCSANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export FCSANDBOX_VSWITCH_ID="vsw-xxxxxxxx"
export FCSANDBOX_ROLE_ARN="acs:ram::<account-id>:role/<execution-role>"

挂载并验证

以下示例将 AgenticFS Volume 挂载到 /mnt/agenticfs，并验证文件读写。将代码保存为 02_mount_agenticfs_volume.py：

import json
import os

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


vpc_config = {
    "vpcId": require_env("FCSANDBOX_VPC_ID"),
    "securityGroupId": require_env("FCSANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("FCSANDBOX_VSWITCH_ID")],
}

mount_dir = "/mnt/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs.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("AGENTICFS_VOLUME_NAME")},
        metadata={
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.auth.role": require_env("FCSANDBOX_ROLE_ARN"),
        },
    )

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

    sandbox.files.write(marker_path, "hello agenticfs\n")
    marker_written = True
    content = sandbox.files.read(marker_path)
    if content != "hello agenticfs\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("AgenticFS Volume 挂载读写验证成功")

运行示例：

python 02_mount_agenticfs_volume.py

行为说明

• volume_mounts 使用 {挂载目录: Volume 名称} 格式，不使用 Volume ID。

• Sandbox 暂停后再恢复时会恢复 Volume 挂载，AgenticFS 数据不依赖 Sandbox 生命周期。

使用限制

• 创建 Sandbox 时，fc.sandbox.network.vpc 必须包含 vpcId、securityGroupId 和非空的 vSwitchIds。模板中的 VPC 配置不能替代该 metadata。

• 同一个 Sandbox 最多挂载 5 个 AgenticFS Volume。

• 同一个 Sandbox 挂载多个 AgenticFS Volume 时，各 Volume 的 user_id 和 group_id 必须完全一致。

• 挂载目录最大长度为 128 个字符，必须是规范化的绝对 Unix 路径，不能为 /，不能包含前后空格或 ..。

• 同一个 Sandbox 中的挂载目录不能重复。建议使用 /mnt/agenticfs 或其子目录，避免覆盖模板内已有目录。

常见问题