动态挂载 OSS - 函数计算

动态挂载 OSS 用于在创建 Sandbox 时，将指定 OSS Bucket 或 Bucket 子目录挂载到 Sandbox 内的本地目录。挂载完成后，Sandbox 可以像访问本地文件系统一样读取或写入挂载目录，适合读取输入数据、保存任务产物、跨任务沉淀文件。

OSS 动态挂载通过 Sandbox metadata 配置，不需要把挂载配置固化到模板中。创建 Sandbox 时传入：

fc.sandbox.storage.oss：OSS 挂载配置，值为 JSON 字符串。
fc.sandbox.auth.role：用于访问 OSS 的 RAM Role ARN。

前提条件

使用前需要准备：

OSS Bucket 名称。
OSS Endpoint，例如 https://oss-cn-hangzhou.aliyuncs.com。
RAM Role ARN。该角色需要授予函数计算服务可扮演权限，并具备访问目标 Bucket 或 Bucket 子目录的 OSS 权限。
Sandbox 内挂载目录，例如 /mnt/oss。

建议只授权任务所需的 Bucket 子目录，不要将整个 Bucket 以可写方式暴露给不可信代码。

挂载配置

fc.sandbox.storage.oss 的值是 JSON 字符串，结构如下：

{
  "mountPoints": [
    {
      "bucketName": "example-bucket",
      "mountDir": "/mnt/oss",
      "bucketPath": "/e2b-test",
      "endpoint": "https://oss-cn-hangzhou.aliyuncs.com",
      "readOnly": false
    }
  ]
}

字段说明：

字段	是否必填	说明
`mountPoints`	是	OSS 挂载点列表。
`bucketName`	是	OSS Bucket 名称。
`mountDir`	是	Sandbox 内的挂载目录，必须是绝对路径，例如 `/mnt/oss`。
`bucketPath`	否	Bucket 内子目录，建议使用绝对路径。设置为 `/` 或留空表示 Bucket 根目录。
`endpoint`	是	OSS Endpoint，应与 Bucket 所在地域匹配。
`readOnly`	否	是否只读挂载。设置为 `true` 时 Sandbox 只能读取挂载目录。

创建带 OSS 挂载的 Sandbox

以下示例在创建 Sandbox 时动态挂载 OSS，并列出挂载目录下的文件。

Python 示例：

import json
import os
import sys

from dotenv import load_dotenv
from e2b import Sandbox

load_dotenv()

api_key = os.environ.get("E2B_API_KEY")
api_url = os.environ.get("E2B_API_URL")
domain = os.environ.get("E2B_DOMAIN")
oss_bucket = os.environ.get("E2E_OSS_BUCKET")
oss_endpoint = os.environ.get("E2E_OSS_ENDPOINT")
role_arn = os.environ.get("E2E_ROLE_ARN")

if not api_key:
    print("错误: E2B_API_KEY 环境变量未设置")
    sys.exit(1)
if not oss_bucket:
    print("错误: E2E_OSS_BUCKET 环境变量未设置")
    sys.exit(1)
if not oss_endpoint:
    print("错误: E2E_OSS_ENDPOINT 环境变量未设置")
    sys.exit(1)
if not role_arn:
    print("错误: E2E_ROLE_ARN 环境变量未设置")
    sys.exit(1)

conn_opts = {}
if api_url:
    conn_opts["api_url"] = api_url
if domain:
    conn_opts["domain"] = domain

mount_dir = "/mnt/oss"
oss_config = {
    "mountPoints": [
        {
            "bucketName": oss_bucket,
            "mountDir": mount_dir,
            "bucketPath": "/e2b-test",
            "endpoint": oss_endpoint,
            "readOnly": False,
        }
    ]
}

sandbox = Sandbox.create(
    api_key=api_key,
    timeout=300,
    **conn_opts,
    metadata={
        "fc.sandbox.storage.oss": json.dumps(oss_config),
        "fc.sandbox.auth.role": role_arn,
    },
)

try:
    print(f"Sandbox created: {sandbox.sandbox_id}")

    files = sandbox.files.list(mount_dir)
    print(f"OSS files: {[file.name for file in files]}")
finally:
    sandbox.kill()

TypeScript 示例：

import { Sandbox } from "e2b";

const apiKey = process.env.E2B_API_KEY;
const apiUrl = process.env.E2B_API_URL;
const domain = process.env.E2B_DOMAIN;
const ossBucket = process.env.E2E_OSS_BUCKET;
const ossEndpoint = process.env.E2E_OSS_ENDPOINT;
const roleArn = process.env.E2E_ROLE_ARN;

if (!apiKey) {
    console.error("错误: E2B_API_KEY 环境变量未设置");
    process.exit(1);
}
if (!ossBucket) {
    console.error("错误: E2E_OSS_BUCKET 环境变量未设置");
    process.exit(1);
}
if (!ossEndpoint) {
    console.error("错误: E2E_OSS_ENDPOINT 环境变量未设置");
    process.exit(1);
}
if (!roleArn) {
    console.error("错误: E2E_ROLE_ARN 环境变量未设置");
    process.exit(1);
}

const connOpts: { apiUrl?: string; domain?: string } = {};
if (apiUrl) connOpts.apiUrl = apiUrl;
if (domain) connOpts.domain = domain;

const mountDir = "/mnt/oss";
const ossConfig = {
  mountPoints: [
    {
      bucketName: ossBucket,
      mountDir,
      bucketPath: "/e2b-test",
      endpoint: ossEndpoint,
      readOnly: false,
    },
  ],
};

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey,
  timeoutMs: 300_000,
  ...connOpts,
  metadata: {
    "fc.sandbox.storage.oss": JSON.stringify(ossConfig),
    "fc.sandbox.auth.role": roleArn,
  },
});

try {
  console.log(`Sandbox created: ${sandbox.sandboxId}`);

  const filesAfter = await sandbox.files.list(mountDir);
  console.log(`OSS files: ${filesAfter.map((file) => file.name)}`);
} finally {
  await sandbox.kill();
}

运行前设置环境变量：

export E2B_API_KEY=your-api-key
export E2B_API_URL=your-api-url
export E2B_DOMAIN=your-domain

export E2E_OSS_BUCKET=your-bucket
export E2E_OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
export E2E_ROLE_ARN=acs:ram::1234567890123456:role/your-role

python 04_sandbox_oss.py

读取和写入挂载目录

挂载成功后，可以通过 Filesystem API 或命令在 Sandbox 内访问 mountDir。

mount_dir = "/mnt/oss"

# 通过 Filesystem API 查看挂载目录。
files = sandbox.files.list(mount_dir)
print([file.name for file in files])

# 在 Sandbox 内写入文件。readOnly=true 时该操作会失败。
result = sandbox.commands.run(
    f"python3 - <<'PY'\n"
    f"from pathlib import Path\n"
    f"path = Path({mount_dir!r}) / 'outputs' / 'result.txt'\n"
    f"path.parent.mkdir(parents=True, exist_ok=True)\n"
    f"path.write_text('sandbox task finished\\n', encoding='utf-8')\n"
    f"print(path)\n"
    f"PY"
)
print(result.stdout.strip())

权限建议

使用 readOnly: true 挂载输入数据目录，避免任务误写或删除源数据。
写入结果时使用独立前缀，例如 tenants/<tenant-id>/tasks/<task-id>/outputs/。
RAM Policy 只授权任务需要的对象前缀。只读任务授予 oss:ListObjects 和 oss:GetObject；读写任务再按需增加 oss:PutObject、oss:DeleteObject、oss:AbortMultipartUpload、oss:ListParts。
不要在代码、模板或 metadata 中写入长期 AK/SK。访问 OSS 应通过 fc.sandbox.auth.role 指定的 RAM Role 完成。

注意事项

fc.sandbox.storage.oss 必须是合法 JSON 字符串，不能直接传 Python dict 或 JavaScript object。
OSS 挂载需要同时配置 fc.sandbox.auth.role，否则 Sandbox 无法获得访问 OSS 的权限。
endpoint 应与 Bucket 地域匹配；跨地域访问可能导致延迟升高或访问失败。
bucketPath 建议使用绝对路径，例如 /e2b-test。挂载根目录时使用 /。
mountDir 应避免与模板内已有系统目录冲突，推荐使用 /mnt/oss 或 /home/user/oss。
临时产物建议配置 OSS 生命周期清理规则。