Function Compute：動態掛載 OSS

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。該角色需要授予Function Compute服務可扮演許可權，並具備訪問目標 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
    }
  ]
}

欄位說明：

建立帶 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 完成。

注意事項

• 由於安全問題，OSS 掛載暫不支援 KMS（Key Management Service，Key Management Service）服務端加密（SSE-KMS）。

• 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 生命週期清理規則。