追加挂载 JuiceFS

JuiceFS 挂载参数

以下字段位于 inlineVolumeMounts.juiceFS 中；选择直接提供配置时，按表中要求填写：

不要在日志中打印 Token 或完整请求体。

本地挂载目录

mountDir 和 namedVolumeMounts[].path 都表示 Sandbox 内的本地挂载目录。建议使用 /home、/mnt、/tmp 或 /data 的子目录，目录限制参见使用限制。

直接提供挂载配置

以下示例将 JuiceFS 文件系统中的远端目录追加到 /mnt/juicefs，并验证读写。请确保 Token 和目录权限允许读写；已有 JuiceFS 挂载时，BASE_URL 必须与当前地址一致。

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="/datasets/project-a"

将以下代码保存为 append_juicefs.py，确认 mount_dir 未被已有挂载占用：

import os
from uuid import uuid4

import httpx
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 verify_read_write(sandbox: Sandbox, mount_dir: str) -> None:
    marker_path = f"{mount_dir}/mount-check-{uuid4().hex}.txt"
    expected = f"append mount check {uuid4().hex}\n"
    sandbox.files.write(marker_path, expected)
    try:
        content = sandbox.files.read(marker_path)
        if content != expected:
            raise RuntimeError(f"文件内容校验失败: {marker_path}")
    finally:
        sandbox.files.remove(marker_path)
    print(f"读写校验通过，测试文件已删除: {mount_dir}")


api_key = require_env("E2B_API_KEY")
api_url = require_env("E2B_API_URL").rstrip("/")
domain = require_env("E2B_DOMAIN")
sandbox_id = require_env("SANDBOX_ID")
mount_dir = "/mnt/juicefs"

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

response = httpx.post(
    f"{api_url}/sandboxes/{sandbox_id}/fc-volume-mounts",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120.0,
)
if response.status_code != 204:
    raise RuntimeError(f"追加挂载失败: HTTP {response.status_code}, {response.text}")

sandbox = Sandbox.connect(
    sandbox_id,
    timeout=300,
    api_key=api_key,
    api_url=api_url,
    domain=domain,
)

verify_read_write(sandbox, mount_dir)

python append_juicefs.py

remoteDir 是 JuiceFS 中的远端目录，mountDir 是 Sandbox 内的本地目录。平台会将 remoteDir 转换为客户端的 --subdir 参数；远端目录的使用方法参见动态挂载 JuiceFS。

引用已有 Volume

已有智能体沙箱 Volume 时，首次运行前将上述脚本中的 payload 定义替换为以下内容，其他代码保持不变。请将 name 替换为同一 Team 中的 Volume 名称，读写校验要求该 Volume 允许读写。

payload = {
    "namedVolumeMounts": [{
        "name": "juicefs-workspace",
        "path": mount_dir,
    }],
}

name 使用智能体沙箱 Volume 名称，不使用 JuiceFS 文件系统名称。组合挂载时，envs.BASE_URL 必须与所引用 Volume 的 baseURL 以及已有 JuiceFS 挂载的服务地址一致。

以上两个示例分别演示一种挂载方式，单次运行时选择其一。同一个挂载目录不能重复追加；挂载已成功但校验失败时，只需重新执行连接和验证代码，不要再次提交追加请求。

直接配置与引用 Volume 组合使用时，将两种配置放入同一个请求体，并为每个挂载点指定不同的本地挂载目录。引用 Volume 的完整操作和多卷示例参见追加挂载 Volume。

请求被 API Key 策略拒绝

错误消息为 request is not allowed by API key policy 时，检查 API Key 策略是否允许本次挂载方式和存储类型，参见API Key 管理。这类拒绝发生在接口授权阶段，调整存储 RAM 角色不能解决。

按名称挂载时提示找不到 Volume

核对请求中的 Volume 名称、API Key 所属 Team 和 API 地址的地域，确认使用同一 Team 中的 Volume 名称，而非 Volume ID。详细说明参见追加挂载 Volume。

按名称挂载时提示 Volume 不可用

通过 GetVolume 查询 Volume 的状态和状态原因，确认处于可用状态后再挂载；存在失败原因时，先处理该原因。详细说明参见追加挂载 Volume。

追加挂载提示 Sandbox 未运行

错误消息为 sandbox must be running 时，确认目标 Sandbox 已进入 running 状态。已暂停的 Sandbox 需先恢复运行；已释放的 Sandbox 需重新创建。

追加挂载提示 Sandbox 的 VPC 配置不完整

错误消息包含 FC Function complete VPC configuration is required 时，缺少配置的是当前 Sandbox。追加请求或新增 Volume 的 mountConfig.vpcConfig 不会补齐它。

需要在重新创建 Sandbox 时配置完整的 vpcId、securityGroupId 和非空 vSwitchIds。创建时可直接通过 metadata 提供，或在引用 Volume 时使用该 Volume 保存的 VPC 配置。

追加挂载提示 JuiceFS 服务地址冲突

核对本次 inlineVolumeMounts.juiceFS.envs.BASE_URL、所引用 Volume 的 baseURL，以及 Sandbox 已有 JuiceFS 挂载使用的服务地址。所有 JuiceFS 挂载必须使用同一服务地址。

例如，错误消息包含 JuiceFS Volume baseUrl conflicts with inline JuiceFS envs.BASE_URL，表示本次直接配置与引用 Volume 的服务地址不一致。填写一致的地址或选择相应 Volume；需要接入另一个 JuiceFS 服务时，应使用另一个 Sandbox。

追加挂载提示目录重复

错误消息包含 duplicate mount path 或 duplicate mount dir 时，检查本次请求内是否有重复的本地挂载目录，以及目录是否已被 Sandbox 中的其他挂载占用。不同存储类型也不能共用同一个本地挂载目录。

已有挂载无需再次提交；新增挂载应使用未占用的目录。追加接口不能覆盖或替换已有挂载。

本次只追加一个挂载点，为什么仍提示数量超限

挂载数量按 Sandbox 中已有和本次新增的挂载累计计算，直接配置和引用 Volume 的挂载都需计入。不能只检查本次请求的数量。

按本文使用限制核对相应存储类型的挂载数量。达到上限时，可将新增存储挂载到另一个 Sandbox；更换本地挂载目录不会减少已有挂载数量。

若问题仍未解决，或接口提示服务暂时不可用，请保留完整错误信息和请求 ID，联系产品支持。