动态挂载 JuiceFS

功能介绍

创建 Sandbox 时，可以通过 metadata 将 JuiceFS 文件系统或其子目录挂载到 Sandbox 内，无需预先创建 Volume。挂载后，应用通过本地挂载目录访问数据。

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

适用范围

• 已在 JuiceFS 企业版控制台创建文件系统，并获取文件系统名称、访问 Token 和服务地址。操作方法参见 JuiceFS 企业版快速上手。

• 已准备与 JuiceFS 服务网络连通的 VPC（Virtual Private Cloud，专有网络）、交换机和安全组。

• 已准备智能体沙箱 API Key 和第二代运行时（MicroVM）自定义模板。

JuiceFS 通过 Token 访问文件系统，挂载 JuiceFS 本身不要求配置 RAM（Resource Access Management，访问控制）角色。

安装 SDK

创建并激活 Python 虚拟环境，然后安装 E2B SDK：

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

挂载配置

创建 Sandbox 时，在 metadata 中提供以下配置：

创建时直接挂载，需同时通过 fc.sandbox.network.vpc 提供完整 VPC 配置，值为 JSON 字符串。模板或同一请求中 Volume 的 VPC 配置不能替代该 metadata。

fc.sandbox.storage.juicefs 的 JSON 结构如下。提交时需将其序列化为字符串，不能直接传入 Python 字典或 JavaScript 对象：

{
  "mountPoints": [
    {
      "volumeName": "<JUICEFS-FILE-SYSTEM-NAME>",
      "remoteDir": "/",
      "mountDir": "/mnt/juicefs",
      "token": "<JUICEFS-TOKEN>",
      "args": []
    }
  ],
  "envs": {
    "BASE_URL": "https://<JUICEFS-SERVICE-ADDRESS>"
  }
}

动态挂载通过 envs.BASE_URL 指定 JuiceFS 服务地址，无需在创建请求中填写 Volume 的 baseURL 字段；与已有 JuiceFS Volume 组合挂载时，两者取值仍须一致。

args 是传递给 JuiceFS 客户端的额外挂载参数。本文示例使用环境变量 JUICEFS_ARGS_JSON 传入该数组；不需要额外参数时设置为 []，不能设置为空字符串或 JSON null，也不能覆盖平台管理的 --token 和 --subdir 参数。

不要在日志中打印完整 metadata、JuiceFS Token 或其他凭证。

环境变量说明

挂载并验证

先设置环境变量，替换示例中的占位符；API 地址、模板和存储需使用匹配的地域及网络配置：

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 SANDBOX_VPC_ID="vpc-xxxxxxxx"
export SANDBOX_SECURITY_GROUP_ID="sg-xxxxxxxx"
export SANDBOX_VSWITCH_ID="vsw-xxxxxxxx"

export JUICEFS_BASE_URL="https://<JUICEFS-SERVICE-ADDRESS>"
export JUICEFS_VOLUME_NAME="<JUICEFS-FILE-SYSTEM-NAME>"
export JUICEFS_TOKEN="<JUICEFS-TOKEN>"
export JUICEFS_REMOTE_DIR="/"
export JUICEFS_MOUNT_DIR="/mnt/juicefs"

export JUICEFS_ARGS_JSON="[]"

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

将以下代码保存为 14_sandbox_juicefs.py：

import json
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


def juicefs_args() -> list[str]:
    value = json.loads(require_env("JUICEFS_ARGS_JSON"))
    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
        raise RuntimeError("JUICEFS_ARGS_JSON 必须是字符串数组")

    managed_options = ("--token", "--subdir")
    for item in value:
        if any(item == option or item.startswith(f"{option}=") for option in managed_options):
            raise RuntimeError(f"JUICEFS_ARGS_JSON 不能覆盖平台托管参数: {item}")
    return value


mount_dir = require_env("JUICEFS_MOUNT_DIR")
marker_path = f"{mount_dir}/hello-juicefs-{uuid4().hex}.txt"

vpc_config = {
    "vpcId": require_env("SANDBOX_VPC_ID"),
    "securityGroupId": require_env("SANDBOX_SECURITY_GROUP_ID"),
    "vSwitchIds": [require_env("SANDBOX_VSWITCH_ID")],
}

juicefs_config = {
    "mountPoints": [
        {
            "volumeName": require_env("JUICEFS_VOLUME_NAME"),
            "remoteDir": require_env("JUICEFS_REMOTE_DIR"),
            "mountDir": mount_dir,
            "token": require_env("JUICEFS_TOKEN"),
            "args": juicefs_args(),
        }
    ],
    "envs": {
        "BASE_URL": require_env("JUICEFS_BASE_URL"),
    },
}

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"),
        metadata={
            "fc.sandbox.network.vpc": json.dumps(vpc_config),
            "fc.sandbox.storage.juicefs": json.dumps(juicefs_config),
        },
    )

    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 动态挂载读写验证成功")

在已激活的 Python 虚拟环境中运行示例：

python 14_sandbox_juicefs.py

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

行为说明

• Sandbox 暂停后再恢复时会恢复 JuiceFS 挂载。

• 释放 Sandbox 不会删除底层存储数据。测试文件由示例主动删除，其他数据的保留和清理需通过存储服务或挂载目录单独处理。

使用限制

• 本地挂载目录必须是规范化的绝对 Unix 路径，不能为 /，不能包含前后空格、.、.. 或重复的路径分隔符。

• 本地挂载目录不能使用 /bin、/opt、/var、/dev 等系统目录及其子目录，也不能包含 .cache 等隐藏目录。如需通过隐藏目录访问数据，可先挂载到符合要求的目录，再在隐藏目录路径下创建指向该挂载目录的符号链接。

• 同一个 Sandbox 中的本地挂载目录不能重复，包括不同存储类型的挂载目录。

• 同一个 Sandbox 最多包含 5 个 JuiceFS 挂载点，按创建时的挂载点与后续追加的挂载点累计计算，包括直接配置和引用 Volume 的挂载。

• 多个 JuiceFS 挂载点必须使用相同的服务地址；与已有 JuiceFS Volume 组合挂载时，envs.BASE_URL 必须与 Volume 的 baseURL 一致。

常见问题