VPC 網路設定 - Function Compute

VPC 網路設定用於讓 Sandbox 訪問專用網路中的資源，例如 RDS、Redis、NAS、內網 API、ACR EE 鏡像倉庫或自建服務。

雲沙箱通過 Sandbox metadata 傳入 VPC 配置。建立 Sandbox 時，將 vpcId、securityGroupId 和 vSwitchIds 序列化為 JSON 字串，並寫入保留欄位 fc.sandbox.network.vpc。該配置隨本次 Sandbox 建立生效，不需要把 VPC 資訊固化到模板中。

前提條件

使用前需要準備：

雲沙箱 API Key，以及當前地區對應的 E2B_API_URL 和 E2B_DOMAIN。
目標 VPC ID。
至少一個 vSwitch ID。vSwitch 應位於Function Compute支援的可用性區域；如果目標資源在其他可用性區域，同一 VPC 內不同 vSwitch 預設可通過私網互連。
一個非雲端服務託管的安全性群組 ID。安全性群組出方向規則需要允許 Sandbox 訪問目標資源的協議和連接埠。
目標資源的內網地址和連接埠，例如 RDS 內網地址、NAS 服務地址、Redis 內網地址或內網 HTTP API。

如果目標資源還配置了白名單，例如 RDS 白名單或自建服務存取控制，請將所選 vSwitch 的網段加入白名單。網路可達不等於業務鑒權通過，資料庫帳號、API Token、RAM Role 等許可權仍需單獨配置。

VPC metadata 格式

fc.sandbox.network.vpc 的值必須是 JSON 字串，結構如下：

{
  "vpcId": "vpc-xxxxxxxx",
  "securityGroupId": "sg-xxxxxxxx",
  "vSwitchIds": ["vsw-xxxxxxxx"]
}

欄位說明：

欄位	是否必填	說明
`vpcId`	是	Sandbox 需要接入的專用網路 ID。
`securityGroupId`	是	Sandbox 關聯的安全性群組 ID，用於控制出方向存取範圍。
`vSwitchIds`	是	vSwitch ID 列表。建議配置兩個或更多 vSwitch，提高可用性並降低單個網段 IP 不足的風險。

建立帶 VPC 配置的 Sandbox

以下樣本參考 08_vpc_config.py：建立 Sandbox 時通過 metadata 傳入 VPC 配置，然後在 Sandbox 內執行命令確認建立成功。

運行前設定環境變數：

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

export E2E_VPC_ID="vpc-xxxxxxxx"
export E2E_SECURITY_GROUP_ID="sg-xxxxxxxx"
export E2E_VSWITCH_ID="vsw-xxxxxxxx"

Python 樣本：

import json
import os

from dotenv import load_dotenv
from e2b import Sandbox

load_dotenv()

vpc_config = {
    "vpcId": os.environ["E2E_VPC_ID"],
    "securityGroupId": os.environ["E2E_SECURITY_GROUP_ID"],
    "vSwitchIds": [os.environ["E2E_VSWITCH_ID"]],
}

conn_opts = {
    "api_key": os.environ["E2B_API_KEY"],
    "timeout": 300,
}
if os.environ.get("E2B_API_URL"):
    conn_opts["api_url"] = os.environ["E2B_API_URL"]
if os.environ.get("E2B_DOMAIN"):
    conn_opts["domain"] = os.environ["E2B_DOMAIN"]

sandbox = Sandbox.create(
    **conn_opts,
    metadata={
        "fc.sandbox.network.vpc": json.dumps(vpc_config),
    },
)

try:
    print(f"Sandbox created: {sandbox.sandbox_id}")
    result = sandbox.commands.run("echo 'VPC config applied'")
    print(result.stdout.strip())
finally:
    sandbox.kill()

如果業務需要指定模板，可在 Sandbox.create() 中增加 template="code-interpreter-v1" 或自訂模板 ID。VPC 配置仍然放在 metadata 中。

TypeScript 樣本：

import { Sandbox } from "e2b";

function required(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is required`);
  }
  return value;
}

const vpcConfig = {
  vpcId: required("E2E_VPC_ID"),
  securityGroupId: required("E2E_SECURITY_GROUP_ID"),
  vSwitchIds: [required("E2E_VSWITCH_ID")],
};

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: required("E2B_API_KEY"),
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 300_000,
  metadata: {
    "fc.sandbox.network.vpc": JSON.stringify(vpcConfig),
  },
});

try {
  const result = await sandbox.commands.run("echo 'VPC config applied'");
  console.log(result.stdout.trim());
} finally {
  await sandbox.kill();
}

驗證內網訪問

建立成功只表示控制面接受了 VPC 配置。建議再訪問一個 VPC 內目標地址，驗證資料面是否可達。以下樣本用 TCP 串連測試目標主機和連接埠，可用於 NAS 2049、RDS 3306、Redis 6379 或內網 HTTP 服務連接埠。

運行前設定：

export E2E_INTERNAL_HOST="<internal-host-or-ip>"
export E2E_INTERNAL_PORT="3306"

在 Sandbox 內執行連通性檢查：

host = os.environ["E2E_INTERNAL_HOST"]
port = int(os.environ["E2E_INTERNAL_PORT"])

command = (
    "python3 - <<'PY'\n"
    "import socket\n"
    f"host = {json.dumps(host)}\n"
    f"port = {port}\n"
    "try:\n"
    "    socket.create_connection((host, port), timeout=5).close()\n"
    "except OSError as exc:\n"
    "    print(f'reachable=0 error={type(exc).__name__}: {exc}')\n"
    "else:\n"
    "    print('reachable=1')\n"
    "PY"
)

result = sandbox.commands.run(command, timeout=10)
print(result.stdout.strip())

如果需要證明 VPC 配置確實生效，可以先建立一個不帶 fc.sandbox.network.vpc metadata 的 Sandbox，驗證同一個內網地址不可達；再建立帶 VPC metadata 的 Sandbox，驗證同一個地址可達。

常見問題

現象	可能原因	處理方式
建立 Sandbox 失敗	`vpcId`、`securityGroupId` 或 `vSwitchIds` 不存在，或不屬於同一地區	檢查資源 ID、地區和帳號是否一致。
建立成功但內網地址不可達	安全性群組出方向未允許存取、目標資源白名單未包含 vSwitch 網段，或目標服務未監聽對應連接埠	檢查安全性群組出方向規則、目標資源白名單和服務監聽狀態。
提示 vSwitch 可用性區域不支援	vSwitch 所在可用性區域不在Function Compute當前地區支援範圍內	在同一 VPC 中建立Function Compute支援可用性區域下的 vSwitch，並更新 `vSwitchIds`。
偶發建立失敗或串連失敗	vSwitch 網段可用 IP 不足，或只配置了單個可用性區域	使用更大網段，或配置兩個及以上 vSwitch。
需要訪問公網和 VPC	只配置 VPC 不代表固定公網出口；公網訪問能力以雲沙箱和Function Compute網路原則為準	按業務需要確認公網訪問、NAT 或固定公網 IP 方案。

注意事項

fc.sandbox.network.vpc 是 FC Extensions 使用的保留 metadata 欄位。普通業務 metadata 不會自動改變網路設定。
fc.sandbox.network.vpc 的值必須是 JSON 字串，不能直接傳 Python dict 或 JavaScript object。
VPC、vSwitch、安全性群組、雲沙箱和目標資源應位於同一地區或可連通的網路範圍內。
只開放 Sandbox 訪問目標資源所需的連接埠和位址範圍。
不要在代碼、模板、metadata、環境變數或日誌中暴露長期憑證。