VPC 网络配置 - 函数计算

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 应位于函数计算支持的可用区；如果目标资源在其他可用区，同一 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 所在可用区不在函数计算当前地域支持范围内	在同一 VPC 中创建函数计算支持可用区下的 vSwitch，并更新 `vSwitchIds`。
偶发创建失败或连接失败	vSwitch 网段可用 IP 不足，或只配置了单个可用区	使用更大网段，或配置两个及以上 vSwitch。
需要访问公网和 VPC	只配置 VPC 不代表固定公网出口；公网访问能力以云沙箱和函数计算网络策略为准	按业务需要确认公网访问、NAT 或固定公网 IP 方案。

注意事项

fc.sandbox.network.vpc 是 FC Extensions 使用的保留 metadata 字段。普通业务 metadata 不会自动改变网络配置。
fc.sandbox.network.vpc 的值必须是 JSON 字符串，不能直接传 Python dict 或 JavaScript object。
VPC、vSwitch、安全组、云沙箱和目标资源应位于同一地域或可连通的网络范围内。
只开放 Sandbox 访问目标资源所需的端口和地址范围。
不要在代码、模板、metadata、环境变量或日志中暴露长期凭证。