挂载 JuiceFS Volume

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

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

JuiceFS Volume 挂载必须使用第二代运行时（MicroVM）。构建自定义模板前，必须在源镜像中预装 JuiceFS 企业版客户端、RADOS 运行库和 FUSE 2。第二代运行时直接使用源镜像，不会在模板构建时注入 JuiceFS 客户端。

JuiceFS Volume 挂载当前仅支持 JuiceFS 企业版。JuiceFS 官方在 Docker Hub 的 juicedata/mount 仓库提供企业版 Mount 镜像，镜像标签以 ee- 开头。镜像中的 /usr/bin/juicefs 是客户端启动器，固定版本的客户端可执行文件位于 /usr/local/juicefs/mount/jfsmount。

以下示例使用 juicedata/mount:ee-5.3.7-58af72b。其中，5.3.7 是客户端版本，58af72b 是对应的构建 commit。版本信息可通过 JuiceFS 命令参考核对。镜像和容器的使用方法参见 在 Docker 中使用 JuiceFS。

先确认镜像可以拉取，并检查其中的企业版客户端：

docker pull --platform linux/amd64 \
  juicedata/mount:ee-5.3.7-58af72b

docker run --rm --platform linux/amd64 \
  --entrypoint /usr/bin/juicefs \
  juicedata/mount:ee-5.3.7-58af72b \
  version

输出的客户端版本应为 5.3.7，构建 commit 应为 58af72b。不要使用 latest 或 ee-nightly 等浮动标签，以免重新构建模板后客户端版本发生变化。如果构建环境不能访问 Docker Hub，请先将该镜像同步到可访问的私有镜像仓库，再替换以下 Dockerfile 中 juicedata/mount 的镜像地址。

以下 Dockerfile 默认使用 Ubuntu 22.04。基于已有的 Sandbox 基础镜像构建时，通过 BASE_IMAGE 构建参数传入该镜像地址：

ARG BASE_IMAGE=ubuntu:22.04

FROM juicedata/mount:ee-5.3.7-58af72b AS juicefs-ee

FROM ${BASE_IMAGE}

ARG DEBIAN_FRONTEND=noninteractive

RUN set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends \
        ca-certificates \
        fuse \
        librados2; \
    rm -rf /var/lib/apt/lists/*

COPY --from=juicefs-ee /usr/local/juicefs/mount/jfsmount /usr/bin/juicefs

RUN set -eux; \
    chmod 0755 /usr/bin/juicefs; \
    command -v juicefs; \
    command -v fusermount; \
    mkdir -p /mnt/juicefs

WORKDIR /root

# 不设置自定义 USER、ENTRYPOINT 或 CMD，由 Sandbox 管控链路接管。

不要将 JuiceFS Token 或挂载配置写入 Dockerfile 或镜像层。

构建并推送 linux/amd64 镜像前，先将占位符替换为实际值：

docker buildx build \
  --platform linux/amd64 \
  --build-arg BASE_IMAGE="<YOUR-SANDBOX-BASE-IMAGE>" \
  --push \
  -t "<REGISTRY>/<NAMESPACE>/microsandbox-juicefs-ee:<VERSION>" \
  .

构建完成后，检查镜像中的客户端、RADOS 运行库和 FUSE 2：

docker run --rm --platform linux/amd64 \
  --entrypoint /bin/sh \
  <REGISTRY>/<NAMESPACE>/microsandbox-juicefs-ee:<VERSION> \
  -euxc '
    command -v juicefs
    command -v fusermount
    ldconfig -p | grep "librados\.so\.2"
    juicefs version
  '

该检查只验证镜像内容，不代表 VPC、Token 或真实挂载链路已经可用。请使用该镜像重新构建 MicroVM 模板，再运行后续示例。

步骤二：安装 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="<MICROVM-TEMPLATE-ID>"

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

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

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

python 04_mount_juicefs_volume.py

提示找不到 Volume

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

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

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

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

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

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

Volume 创建成功，但 Sandbox 创建超时或挂载失败

创建 Volume 只保存配置，不执行真实挂载。根据错误消息检查对应配置；消息未明确指出原因时，可按以下顺序排查：

1. 按本文步骤一：准备第二代运行时镜像验证 JuiceFS 企业版客户端、RADOS 运行库和 FUSE 2。

2. 检查实际使用的 VPC 路由、安全组和服务地址，确认 Sandbox 能访问 JuiceFS 服务。

3. 核对 Token、文件系统名称及远端目录，确认 Token 允许访问目标目录。

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