使用约束 - 函数计算

本文说明接入云沙箱前必须满足或需要明确识别的使用边界。快速入门只演示最小接入路径，实际业务接入前应先确认本文约束。

地域约束

当前云沙箱 API/SDK 在以下地域可用：

华北 2（北京）
华东 2（上海）
华东 1（杭州）
华南 1（深圳）
中国（香港）
新加坡
美国（弗吉尼亚）
美国（硅谷）

SDK Endpoint 中的 <region> 需要与云沙箱所在地域一致。当前支持的 <region> 包括 cn-beijing、cn-shanghai、cn-hangzhou、cn-shenzhen、cn-hongkong、ap-southeast-1、us-east-1 和 us-west-1。

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

如果 API URL、域名和实际资源地域不一致，Sandbox 创建、连接或模板访问可能失败。

版本约束

使用云沙箱需要满足 E2B SDK 和 E2B CLI 版本要求。

本文档示例中的安装命令代表对应示例的验证版本。不同示例可能来自不同验证批次，接入时需要同时关注安装命令和E2B 兼容说明中的能力边界。

Python 快速入门已通过以下固定版本验证：

e2b==2.31.0
e2b-code-interpreter==2.8.1

Python SDK 要求 Python 3.10 或更高版本。安装前运行以下命令确认本机版本：

python3 --version

TypeScript 快速入门使用 e2b@^2.31.0 和 @e2b/code-interpreter@^2.6.1，要求 Node.js 20.18.1 或更高版本。npm install 会生成或更新 lockfile；生产项目应提交 lockfile，并在升级依赖后重新验证。

CLI 不固定单一版本。使用最新兼容版本，并在安装或升级后运行以下命令确认版本：

e2b --version

如果 CLI 命令行为与本文档不一致，请先升级 E2B CLI 后重试。

鉴权与 Endpoint 约束

使用 E2B SDK 或 E2B CLI 接入云沙箱时，必须配置 API Key、API URL 和域名。建议通过环境变量传入，不要把 API Key 或 Endpoint 写入代码仓库。

API Key 需要先在函数计算控制台创建。前提条件、创建步骤和管理操作参见创建 API Key。

调用云沙箱数据面 HTTP 接口时，通过 X-API-KEY 请求头传递 API Key。使用 E2B SDK 或 E2B CLI 时，将同一个 API Key 传给 SDK 的 api_key 参数，或设置为 E2B_API_KEY 环境变量。

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"

E2B_ACCESS_TOKEN 是 E2B 已废弃的旧认证变量。新版本 E2B CLI 应使用 E2B_API_KEY。如果旧版 CLI 仍要求 E2B_ACCESS_TOKEN，请先升级 CLI 后重试。

API Key 应在函数计算控制台创建、查看、编辑、重置、禁用和删除，不通过 E2B SDK 管理。已禁用或已过期的 API Key 不能通过数据面认证。不要在日志、截图、工单或前端页面中暴露完整 API Key。管理建议参见创建 API Key。

配额约束

Sandbox 创建、并发运行、模板构建、端口访问和本地文件使用都会受到账号、地域、模板和产品配置的配额限制。

以下能力不能按无限资源假设设计：

单账号或单地域并发 Sandbox 数。
单个 Sandbox 可用 CPU、内存和本地磁盘空间。
单个 Sandbox 可打开的进程、端口和文件数量。
单次任务输入、输出文件大小。
模板构建并发数、构建资源和构建时长。

如果业务峰值超过默认配额，Sandbox 创建、模板构建或任务执行可能失败。需要更高配额时，应通过函数计算控制台或阿里云支持渠道申请提升。

生命周期与超时约束

Sandbox 创建后会持续占用资源，直到被主动终止、超时回收或进入支持的暂停状态。任务完成后，应调用 sandbox.kill() 释放资源。

暂停与恢复功能当前仅对已开通白名单的账号可用。未开通白名单时，应调用 sandbox.kill() 释放资源。

创建 Sandbox 时可以设置超时时间，也可以在创建后调整超时时间。超时时间必须在产品和 SDK 支持范围内；设置过短可能导致任务被提前回收，设置过长会增加资源占用和费用风险。

不同 SDK 的超时参数单位不同。Python 示例通常使用秒，TypeScript 示例通常使用毫秒，请按对应 SDK 的参数定义使用。

模板构建约束

使用自定义模板时，需要满足以下约束：

模板名称应唯一、可读，并便于灰度和回滚。
基础镜像应来自云沙箱可访问的镜像仓库。
镜像仓库、网络配置和云沙箱应位于同一地域。
构建依赖不宜过大，否则可能导致构建超时或失败。
生产环境不应覆盖正在使用的模板，建议创建新模板并完成验证后再切换。

更多模板构建要求参见构建自定义镜像模板。

文件与存储约束

Sandbox 本地文件系统适合当前 Sandbox 生命周期内使用。Sandbox 被终止后，本地文件不应作为长期持久化数据依赖。

需要跨 Sandbox 保留、共享或长期保存的数据，应写入 NAS、OSS 等外部存储。处理用户上传文件时，应限制文件大小、文件类型和可写路径，避免把未经校验的路径直接传给 Filesystem API 或命令行。

能力边界

Sandbox、Commands、Filesystem、Code Interpreter、Template 和 CLI 的接口边界集中在E2B 兼容说明中维护。接入前应确认业务依赖的接口已在支持范围内；未兼容能力不应作为云沙箱接入主路径。