Skip to Content
操作流程管理存取政策

管理存取政策

誰： 部門管理者。這裡所有操作的前提： Worker 已部署且 active — 否則 409 Department Worker must be deployed and active。成功的回應都是 Cache-Control: no-store。

本頁管理的是 Worker 層級政策，也就是每個操作預設繼承的那一份。逐操作的覆寫與逐操作的金鑰是另一組 API：見下方的「逐操作存取」一節。

讀取

GET /worker/access-policy
→ { "mode": "teamsync_internal", "ip_allowlist": [], "api_key_configured": false,
    "revision": 0, "public_url": "https://…/public/dw-…" }

revision 是下面每個變更的 CAS 權杖。值為 null 的欄位會被省略：設定了金鑰才會出現 api_key_last_four，政策被寫入過才會出現 updated_at。部門的第一次部署起始為 mode: "teamsync_internal"、revision 0 — 在你切換模式（base_revision: 0）之前，公開 URL 一律回 403。已存有政策的 Worker 在後續部署中保留原政策。

替換模式／允許清單

PUT /worker/access-policy
{ "base_revision": 4, "mode": "api_key_and_ip", "ip_allowlist": ["203.0.113.0/24"] }
  • 替換是整個物件 — 永不合併。
  • 模式↔允許清單配對有驗證（422）：ip_allowlist/api_key_and_ip 需要 1–64 條 CIDR；public/api_key/teamsync_internal 必須是空清單。CIDR 會被正規化（with_prefixlen）並排序；正規化後指向同一網段的兩個項目會被當成重複而拒絕（422），不會被合併。
  • 過期的 base_revision → 409 Access policy revision is stale：重新 GET 再套用。
  • 超過 16 KiB（16 384 位元組）→ 413 Worker access policy request exceeds limit；這個上限同樣適用於下面輪替與撤銷的 body。
  • provider 回傳的不是恰好 base_revision + 1 加你的 mode／allowlist → 503 Department Worker access policy is unavailable（信任但驗證；當成故障處理，不是衝突）。
  • 503 Department Worker control change is unavailable：耐久的稽核意圖無法寫入，所以沒有任何東西送到 Worker。重試即可。
  • 503 {"code":"worker_release_unavailable","message":"Worker release changed; retry this request"}：後端讀取之後、呼叫控制通道之前，Worker 的 release 變了（剛好有部署落地）。這次變更沒有被套用；重新 GET 政策再重試。同一個有代碼的 503 可能出現在每一種控制面變更：輪替、撤銷、執行期設定、操作設定與機密。

detail 在多數錯誤是字串，有代碼的錯誤則是 {code, message} 物件；生成的 OpenAPI 把這些路由的錯誤描述成純字串，所以用戶端兩種都要能解析。

切到 api_key/api_key_and_ip 不會自動生金鑰。在舊版 release（builder 政策早於 v2.8）上，先輪替一把（順序：先輪替、再切模式；兩步都是對連續 revision 的 CAS）。v2.8 起 Worker 層級金鑰不能再產生 — 請讓各操作擁有自己的金鑰（見下方「逐操作存取」）。

輪替金鑰（僅限舊版 release）

POST /worker/access-policy/api-key        { "base_revision": 5 }
→ { "api_key": "tsw_…47 chars…", "header_name": "X-TeamSync-Worker-Key", "policy": { …, "revision": 6 } }

明文只出現一次 — 現在就存好。平台只保留 SHA-256 摘要與後四碼（api_key_last_four 讓你辨識現役金鑰）。輪替會立即取代先前的金鑰。

輪替只在上線 release 以 早於 v2.8 的 builder 政策建置時可用。上線 release 以 v2.8 或更新版本建置時（截至後端 5.22.0，每次新提交都以 v2.10 建置；版本的 build_policy_version 可在 GET /worker/versions/{version_id} 讀到），只要請求格式合法，不論 base_revision 為何，這條路由都會在接觸 Worker 之前拒絕：

409 { "detail": { "code": "worker_wide_key_legacy_only", "message": "Rotate an operation key instead" } }

不是 active 的 Worker 仍然先拿到 409 Department Worker must be deployed and active。請改為輪替操作金鑰：管理逐操作存取。各 builder 政策開啟的能力見提交管線。

撤銷金鑰（所有 release）

DELETE /worker/access-policy/api-key      { "base_revision": 6 }
→ { "revoked": true, "policy": { …, "revision": 7 } }

撤銷在每個 release 上都可用，包含以 v2.8 或更新版本建置的 release，所以你仍能淘汰較早的 release 產生的 Worker 層級金鑰。它絕不會動到操作金鑰。冪等：未設定金鑰時撤銷回 revoked: false 且不推進 revision（稽核為 no-op）— 前提是 base_revision 為最新；過期的仍是 409。在 api_key/api_key_and_ip 模式下撤銷會讓公開呼叫者無法滿足該模式 — 記得同時換模式。

逐操作存取（builder 政策 v2.8 起）

上線 release 以 builder 政策 v2.8 或更新版本建置時，部門管理者可以逐操作覆寫存取模式與 CIDR 清單，並讓每個操作擁有自己的 API 金鑰，路由為 GET/PUT /worker/operation-settings 與 POST/DELETE /worker/operation-settings/{operation_id}/api-key。本頁的政策仍是預設值：沒有覆寫值的操作繼承它的模式與 CIDR。使用方式見管理逐操作存取；它如何與本頁政策組合見逐操作存取。

這對該類 release 上的 Worker 層級金鑰有以下意義：

  • 它不能輪替（上述 409），所以第一次部署就是 v2.8 或更新版本的 Worker 永遠沒有這把金鑰。繼承 api_key 或 api_key_and_ip、又沒有自己金鑰的操作，會拒絕所有公開呼叫（api_key 下 401、api_key_and_ip 下 403），直到你為它輪替一把操作金鑰。
  • 較早的 release 產生的 Worker 層級金鑰會跨後續部署保留，仍可讓繼承金鑰模式、且從未擁有操作金鑰的操作通過。
  • 曾經擁有過金鑰的操作，永遠不會再退回 Worker 層級金鑰，即使它自己的金鑰之後被撤銷也一樣。

稽核與耐久性

每個變更都走耐久的控制面稽核 outbox，最終成為回執背書的稽核事實（access_policy.replaced、…api_key.rotated、…api_key.revoked/revoke_noop）— 只有摘要，永遠沒有 CIDR 值或金鑰材料。provider 的 revision 衝突是乾淨的 409；provider 結果未知則背景重試並對你回 503 — 重試變更前先輪詢政策。自後端 5.22.0 起，變更也可能被拒絕並回 409 worker_serving_target_unavailable（後端無法驗證是哪個位置在服務該 Worker）。平台維運者搬移該 Worker 期間，會回 503 Department Worker control change is unavailable；但在搬移的短暫暫停期間，會先讀取該 Worker 狀態的呼叫改回該路由慣用的修訂版過期 409（錯誤、搬移 Worker）。概念：存取模式、稽核。

Last updated on
呼叫 API管理逐操作存取