全部產品
Search

搜尋本產品

    Function Compute：使用約束

    文件中心

    Function Compute：使用約束

    更新時間：Sep 24, 2026

    本文說明接入雲沙箱前必須滿足或需要明確識別的使用邊界。快速入門只示範最小接入路徑，實際業務接入前應先確認本文約束。

    地區約束

    當前雲沙箱 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 需要先在Function Compute控制台建立。前提條件、建立步驟和管理操作參見建立 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 應在Function Compute控制台建立、查看、編輯、重設、禁用和刪除，不通過 E2B SDK 管理。已禁用或已到期的 API Key 不能通過資料面認證。不要在日誌、截圖、工單或前端頁面中暴露完整 API Key。管理建議參見建立 API Key。

    配額約束

    Sandbox 建立、並發運行、模板構建、連接埠訪問和本地檔案使用都會受到帳號、地區、模板和產品配置的配額限制。

    以下能力不能按無限資源假設設計：

    • 單帳號或單地區並發 Sandbox 數。

    • 單個 Sandbox 可用 CPU、記憶體和本地磁碟空間。

    • 單個 Sandbox 可開啟的進程、連接埠和檔案數量。

    • 單次任務輸入、輸出檔案大小。

    • 模板構建並發數、構建資源和構建時間長度。

    如果業務峰值超過預設配額，Sandbox 建立、模板構建或任務執行可能失敗。需要更高配額時，應通過Function Compute控制台或阿里雲支援渠道申請提升。

    生命週期與逾時約束

    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 相容說明中維護。接入前應確認業務依賴的介面已在支援範圍內；未相容能力不應作為雲沙箱接入主路徑。