架構：控制面與資料面
前端呼叫什麼
幾乎所有 sandbox API 都在 /private/module/sandbox（module 是單數 — 後端把這條路當安全相關路徑做請求內容遮罩）。
不在 /private/module/sandbox 底下的租戶相關路徑有兩組，都不必登入：確認目錄（前端直接呼叫），以及公開產出物下載 GET /public/sandbox/artifacts/{token}（由下面第 4 點的 public-link 鑄出、給收件人點的連結，不是前端呼叫的 API）。確認目錄是：
GET /public/info/sandbox/regions
GET /public/info/sandbox/profiles下拉選單用這兩個。不要自己發明 region 或 profile 字串。租戶 runtime 子集仍是 GET /settings.allowed_regions。營運端啟用仍是 /root/sandbox/regions。
/private/module/sandbox 底下的前綴：
| 資源 | 前綴 |
|---|---|
| 公司設定 | /settings |
| 環境／版本／建置／context 上傳 | /environments |
| 任務／版本／分享／公司執行歷史 | /tasks |
| Bindings（與 granted-jobs 啟用同一釘選） | /bindings |
| Secrets／授權 | /secrets、/secret-approvals |
| 選單、granted-jobs、執行 | /chatrooms/{chatroom_id}/... |
任務受眾（誰擁有、誰可分享、啟用代表什麼）見 任務受眾。
前端看不到的世界
| 路由群 | 用途 | 認證 |
|---|---|---|
/sandbox-control/* | 隔離工作負載回呼、結果物件上傳、控制面內部的建置內容串流；地端部署另有 executor 的 work lease（/sandbox-control/onprem/work/*） | Google 服務帳戶 OIDC + capability（地端：以地端 executor token 取代 Google OIDC）；include_in_schema=False。人類不該打 |
/root/sandbox/* | 營運／root | 營運與 Root |
POST /public/module/custom_tables/callback/command-output/{token_id} | 由 Command 輸出 run 自己的 work script 呼叫（v5.21.0），不是前端 | 該 run 的密封 Bearer 憑證；見任務輸出交給自訂表格 Command |
六個位元組接觸點
前端碰位元組的地方有六個。其餘（R2 key、R2 multipart part、runner 串流）都在控制面。
- 建置 context 封存 — environment owner-scope manager 在
/environments/{id}/context-uploads走init → PUT（X-Sandbox-Upload-Capability）→ complete，再把owned_object_id送到建立版本。單一部分，最大 1 GiB。這是租戶 capability；不是 generic blob_id，也不是 R2 presign。見 建立環境並建置。 - 執行
input—POST .../runs的 canonical JSON。 - 產出物下載 —
POST .../download回一個 5 分鐘的capability_token，不是 URL。沒有租戶兌換路由。 - 永久公開連結 —
POST .../runs/{run_id}/{log|output}/public-link鑄出一個不必登入、沒有 TTL 的GET /public/sandbox/artifacts/{token}URL，給 run 的 log 或 output 用。見 內容、Digest 與下載。 - 公開目錄 — 很小的 JSON 列表，不是封存。
- 腳本檔上傳——兩條路由。
POST /tasks/{task_id}/script-uploads（multipartfile，一個 UTF-8 文字檔 ≤1 MiB，owner-manager）在版本還沒建立時就先驗證檔案，回一個 24 小時可重用的 handle，建立／修改版本時當startup_script_id／work_script_id帶入——建版本表單走的就是這條。POST /tasks/{task_id}/versions/{vid}/script-file?target=startup|work（同樣的檔案規則，只限草稿）直接寫進既有草稿；語意等同用字串 PATCHstartup_script／work_script。
建立版本時單獨送 source_digest 是重試／測試逃生門，而且該 digest 必須已經對應一個完成的 context 物件。新的產品 UI 應該先上傳，再送 owned_object_id。
租戶面的 OpenAPI 雙 tag：總 tag Module: Sandbox 加上分區 Module: Sandbox - Settings／Environments／Tasks／Bindings／Secrets／Runs。
沒有 streaming
租戶面沒有 WebSocket／SSE／StreamingResponse。建置與執行進度用輪詢。見 狀態機。
Last updated on