環境變數

Edge Workers 沒有 Pydantic settings class — 每個元件各自 os.getenv 並在呼叫點驗證。除註明外預設值皆為 ""。以下佔位符來自 example.env；實際值由 Infisical 按環境佈建。截至後端 5.22.0，後端讀取下列 EDGE_WORKERS_* 名稱（另有三個屬於維運者專用的 Worker 搬移流程、不在此說明）、三個單數的 EDGE_WORKER_* 名稱，以及 EDGE_BACKUP_FENCE_MAX。

後端 — provider 選擇

不合法的值不會被夾住。提交與部署路由回 503 Edge Worker provider is not configured，產物儲存與閘道無法使用，60 秒回收迴圈每輪都略過（Edge Worker recovery skipped: edge_workers_provider_invalid），已取得租約的部署則結算為 failed（調解模式下為 uncertain），error_code: "edge_workers_provider_invalid"。以下各節依 provider 而異：值為 cloudflare 時適用 Cloudflare 的各節，值為 onprem 時適用地端各節；地端後端從不讀取 EDGE_WORKERS_CLOUDFLARE_*、EDGE_WORKERS_DISPATCH_ORIGIN 或 EDGE_WORKERS_R2_*。

後端 — Cloudflare 控制面

後端 — 調度閘道與簽章

後端 — 環境宣告與服務帳號

閘道不再從 EDGE_WORKERS_CLOUDFLARE_DISPATCH_NAMESPACE 推導預期的 dispatcher，而是使用 API 自己的環境宣告：APP_ENV（否則 ENVIRONMENT），去除前後空白並轉小寫 — staging 選 staging dispatcher，prod 或 production 選 production dispatcher。若 HOST（否則 PUBLIC_HOST）是 TeamSync 代管的 API hostname 之一，它就暗示了所屬環境；同時設了 APP_ENV/ENVIRONMENT 時，兩者必須一致。互相矛盾、除 dev、development、test 之外的任何非空環境值，或完全沒有可辨識的宣告，都會讓沒有預期的 dispatcher：EDGE_WORKERS_DISPATCH_ORIGIN 隨即驗證失敗，所有閘道呼叫都以 Edge Worker dispatcher is not configured 失敗。

後端 — 每次呼叫的上限

在每個簽章請求時讀取，鑄進調度斷言的 limits claim，dispatcher 再套用到部門 Worker。不在 example.env 內；未設定時使用預設值。調整任一項是後端設定變更加重啟 — 不需要重新部署 dispatcher。

不合法的值絕不會被夾住：後端拒絕簽章，所有簽章呼叫都會以無法使用的方式失敗（invoke → 503 Department Worker gateway is unavailable、存取政策／runtime config 路由 → 503，部署的就緒探測也無法成功，最終成為 uncertain worker_readiness_timeout）。公開通道不使用這兩個變數 — 它沿用下方 dispatcher 自己的 EDGE_WORKER_* 變數。地端時，edge host 忽略 CPU 上限（改用 30 秒的牆鐘預算），並在簽章通道套用 EDGE_WORKERS_LIMIT_SUBREQUESTS，且以每個 Worker 行程為單位共用額度（見地端）。

後端 — 產物儲存

專屬 bucket + 憑證對；絕不退回應用憑證或 AWS_S3_BUCKET。使用雲端 provider 時儲存體是 R2，且 S3_PROVIDER 必須恰為 r2：

使用地端 provider 時，產物改存在 kit 自己的產物儲存體，不會讀取 EDGE_WORKERS_R2_*（見地端一節）。兩種 provider 路徑都使用每個行程一個有界的 S3 client：連線逾時 5 秒、讀取逾時 20 秒，botocore standard 重試模式、2 次重試（最多 3 次嘗試），最多快取 8 個 client。

後端 — 地端 provider

只在 EDGE_WORKERS_PROVIDER=onprem 時使用。kit 的 setup 腳本會寫入這組變數（見地端）；provider 在每次部署前檢查它，不完整的設定以 edge_workers_provider_invalid 拒絕。

EDGE_WORKERS_DISPATCH_PRIVATE_KEY 與 EDGE_WORKERS_DISPATCH_KEY_ID 也必須非空。任何違規都會丟出 edge_workers_provider_invalid：origin 格式錯誤時訊息為 <NAME> must be a http origin，缺少金鑰、金鑰 id、bucket 或產物憑證時則為 Edge Worker on-prem credentials are incomplete。

setup 腳本也會寫入 EDGE_WORKERS_CONTROL_SUBNET、EDGE_WORKERS_CONTROL_RELAY_IP 與 EDGE_WORKERS_CONTROL_HOST_IP，也就是 kit 給 edge host 用的內部控制網路。只有 kit 的 setup 腳本與 compose 檔使用它們，後端不讀取（見地端）。

後端 — builder 與 starters

⚠️ 三個變數用單數 EDGE_WORKER_ 前綴；後端讀取的 EDGE_WORKERS_* 名稱用複數。已知踩雷點 — 排查「builder unavailable」前先檢查拼字。

EDGE_WORKER_STARTERS_DIR 是 API 提供的 starter 目錄與 CLI tarball 的根目錄（見Starters 與原始碼）；行程啟動時只讀取一次。

另外：EDGE_WORKERS_CLOUDFLARE_ACCOUNT_ID 在 Cloudflare client 驗證為大小寫混合 hex，但 R2 endpoint 檢查只收小寫 — 大寫值會過一邊、掛另一邊。請用小寫。

builder 子行程收到的是六變數乾淨環境（LANG、LC_ALL、NODE_ENV=production、PATH、SOURCE_DATE_EPOCH=0、TZ=UTC）— 憑證永遠到不了它。

Dispatcher（Cloudflare Worker 變數，由 deploy-platform.mjs 設定）

Transport／背景 worker 相關（共用基礎設施）

沒有任何環境變數控制這些程式碼常數：60 秒回收迴圈、三個批次上限（50）、租約 TTL 與退避階梯（見背景任務）；以及 15 秒 host 調解（退役）迴圈、它的 20 秒單輪逾時、10 秒開始預算、每個 pod 每輪 3 次 Cloudflare 退役、8 秒鎖定預算、300 秒卡住門檻與 15 分鐘上傳寬限（見退役）。

平台佈建（僅 deploy-platform.mjs）

需要（Infisical 範圍）：EDGE_WORKERS_CLOUDFLARE_API_TOKEN、…_ACCOUNT_ID、…_DISPATCH_NAMESPACE（必須是該環境的 dispatch namespace 之一）、…_WORKERS_SUBDOMAIN、…_DISPATCH_KEY_ID、…_DISPATCH_ISSUER、…_DISPATCH_AUDIENCE、…_DISPATCH_PUBLIC_JWK、…_DISPATCH_PRIVATE_KEY、…_DISPATCH_ORIGIN，以及 staging 與 production 的 dispatcher 還需要 EDGE_WORKERS_R2_BUCKET（後端已在使用的 edge 產物 bucket）。選用：EDGE_WORKERS_SERVING_ROUTES — 最多 32 768 字元、128 個項目的 JSON 物件字串，key 為 ^dw-[0-9a-f]{48}$，每個值恰為 {dispatch_namespace, routing_epoch}，namespace 須為已知的 binding、routing_epoch 為 ≥ 1 的安全整數，否則 serving routes configuration is invalid；它會寫入 dispatcher 變數 EDGE_WORKER_SERVING_ROUTES，未設定時，例行執行會讀取線上 dispatcher 並保留它目前的值。對照表中的項目優先於後端在搬移 Worker 時所記錄的啟用。任何符合 REPLACE_WITH_ENV_ / CHANGE_ME / DEPLOY_VIA_SCRIPT_ONLY 的值都被拒絕；私鑰必須能推導出完全一致的公開 JWK。--drift 只需要 …_API_TOKEN 與 …_ACCOUNT_ID。在 CI 中，這些值經由 GitHub OIDC 從 Infisical 取得 — GitHub 內不存放任何長期機密。細節：平台佈建。