挂载 AgenticFS Volume

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

已有符合要求的模板，可直接进入步骤二：安装 SDK。

如果使用第二代运行时（MicroVM）的自定义模板，必须在构建模板前，在源镜像中预装 AgenticFS 客户端。当前 AgenticFS 安装包仅支持 linux/amd64。以下 Dockerfile 默认使用 Ubuntu 22.04，也可通过构建参数切换到 Debian 12：

ARG BASE_IMAGE=ubuntu:22.04
FROM ${BASE_IMAGE}

ARG DEBIAN_FRONTEND=noninteractive
ARG ALINAS_DEB_URL=https://aliyun-alinas-eac-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-alinas-utils_2.4-0.20260908115139.ac23e3.amd64.deb
ARG ALINAS_DEB_SHA256=e0866d4a4a8b9fa7dbb3b0dea8ee086e7c8bfe3e79160a5e415935a86ec3367d

RUN set -eux; \
    test -n "${ALINAS_DEB_URL}"; \
    test -n "${ALINAS_DEB_SHA256}"; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        nfs-common; \
    curl -fL --retry 3 \
        "${ALINAS_DEB_URL}" \
        -o /tmp/aliyun-alinas-utils.deb; \
    echo "${ALINAS_DEB_SHA256}  /tmp/aliyun-alinas-utils.deb" \
        | sha256sum -c -; \
    apt-get install -y --no-install-recommends \
        /tmp/aliyun-alinas-utils.deb; \
    rm -f /tmp/aliyun-alinas-utils.deb; \
    rm -rf /var/lib/apt/lists/*; \
    command -v mount.alinas; \
    command -v mount.nfs; \
    mkdir -p /mnt/agenticfs

WORKDIR /root

# 不设置 USER、ENTRYPOINT 或 CMD，由 MicroVM 管控链路接管。

AgenticFS 基于 NFS（Network File System，网络文件系统）挂载，不需要安装 fuse3，也不依赖 /dev/fuse。请勿将 AccessKey、Token 等凭证写入 Dockerfile 或镜像层，必须在运行时安全注入。安装包升级时，必须同时更新 ALINAS_DEB_URL 和 ALINAS_DEB_SHA256，不要跳过 SHA-256 校验。

在 Dockerfile 所在目录构建 Ubuntu 22.04 镜像：

docker buildx build \
  --platform linux/amd64 \
  --load \
  -t microsandbox-agenticfs:ubuntu22.04-alinas-utils-2.4 \
  .

构建 Debian 12 镜像：

docker buildx build \
  --platform linux/amd64 \
  --build-arg BASE_IMAGE=debian:12-slim \
  --load \
  -t microsandbox-agenticfs:debian12-alinas-utils-2.4 \
  .

--load 会将构建结果加载到本地 Docker。如果需要直接推送到镜像仓库，请先登录仓库，将 --load 替换为 --push，并将 -t 后的名称改为完整镜像地址。

构建完成后，分别验证镜像中的客户端和挂载目录：

Ubuntu 22.04

docker run --rm --platform linux/amd64 \
  microsandbox-agenticfs:ubuntu22.04-alinas-utils-2.4 \
  sh -euxc '
    command -v mount.alinas
    command -v mount.nfs
    dpkg-query -W aliyun-alinas-utils nfs-common
    test -d /mnt/agenticfs
  '

Debian 12

docker run --rm --platform linux/amd64 \
  microsandbox-agenticfs:debian12-alinas-utils-2.4 \
  sh -euxc '
    command -v mount.alinas
    command -v mount.nfs
    dpkg-query -W aliyun-alinas-utils nfs-common
    test -d /mnt/agenticfs
  '

以上命令全部成功，表示镜像中已正确安装 AgenticFS 客户端，但不代表 VPC、权限或真实挂载链路已经可用。

使用上述镜像创建第二代运行时（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"

步骤三：挂载并验证

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="code-interpreter-v1"

export AGENTICFS_VOLUME_NAME="agent-workspace"

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/agenticfs"
marker_path = f"{mount_dir}/hello-agenticfs-{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("AGENTICFS_VOLUME_NAME")},
    )

    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

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

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

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

创建 Sandbox 提示缺少 RAM 角色

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

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

已配置 VPC，为什么仍提示配置不完整

错误消息包含 mount requires complete VPC config 时，表示本次创建使用的 VPC 配置缺少必填项。

未在 metadata 中指定 VPC 时，检查 Volume 的 mountConfig.vpcConfig；已指定时，检查 fc.sandbox.network.vpc。实际使用的配置必须包含 vpcId、securityGroupId 和非空的 vSwitchIds。metadata 配置优先，不会用 Volume 的字段补齐不完整的 metadata。

Sandbox 创建超时或挂载失败

如果错误消息未指出具体参数问题，可按以下顺序排查实际挂载条件：

1. 确认 Access Point 处于 active 状态，地址和远端目录填写正确。

2. 检查 Sandbox 所用 VPC 的路由、安全组及与 Access Point 的连通性。

3. 检查实际使用的 RAM 角色，确认信任策略允许函数计算服务扮演，且具备目标存储所需的访问权限。

4. 使用第二代运行时自定义模板时，按本文步骤一：准备第二代运行时镜像验证 AgenticFS 客户端。

Volume 已挂载，但文件读写失败

先确认应用访问的是本次指定的本地挂载目录，再根据文件操作的错误检查目录权限、UID/GID 和实际使用的 RAM 角色是否具备相应的读写权限。Access Point 的访问状态也需正常。

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