追加挂载 Volume

接口与参数

POST /sandboxes/{sandboxID}/fc-volume-mounts

请求使用 X-API-Key 鉴权，Content-Type 为 application/json。通过 namedVolumeMounts 追加已有 Volume 时，请求参数如下。

接口成功时返回 204 No Content，响应体为空。

环境变量说明

追加一个 Volume

在本地终端设置连接信息，将占位符替换为实际值。各变量的取值参见本文环境变量说明。

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 SANDBOX_ID="<SANDBOX-ID>"

以下代码在本地运行，通过 SDK 访问 Sandbox 内的文件。示例会为每个新增挂载创建带随机标识的独立测试文件，写入并读取校验后删除该文件，保留当前 Sandbox。请使用允许读写的 Volume；只读 Volume 的验证方式参见本文步骤三：验证挂载。

Sandbox.connect() 会更新 Sandbox 的超时时间。示例通过 timeout=300 将连接后的超时时间设为 300 秒，可按任务需要调整。

以下示例将已有的 oss-workspace Volume 挂载到 /mnt/oss。请替换为实际的 Volume 名称和未被占用的挂载目录，将代码保存为 append_volume.py：

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")

mounts = [
    {"name": "oss-workspace", "path": "/mnt/oss"},
]
payload = {"namedVolumeMounts": mounts}

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,
)

for mount in mounts:
    verify_read_write(sandbox, mount["path"])

运行示例：

python append_volume.py

追加多个 Volume

首次运行前，将上述脚本的 mounts 定义替换为以下内容，可一次追加两个已有 Volume。请替换为实际的 Volume 名称，并确保两者均允许读写。脚本会逐一验证各挂载目录。

mounts = [
    {"name": "project-data", "path": "/mnt/project"},
    {"name": "project-results", "path": "/mnt/results"},
]

同一次请求可以引用不同存储类型的 Volume，但 Sandbox 必须同时满足这些存储的访问条件。各 Volume 中配置的 RAM 角色不会合并生效，也不会替换 Sandbox 已有的角色。

请求中只列出本次新增的挂载。已有挂载会保留，重复提交相同挂载会返回 400。挂载已成功但校验失败时，只需重新执行连接和验证代码，不要再次提交追加请求。