搬移 Worker
在雲端，Worker 位於三個 Worker 位置之一：共用位置，或兩個舊有位置之一（地端套件沒有這些位置，也沒有搬移）。平台維運者可以把既有的 Worker 連同它儲存的所有資料一起搬到共用位置。部門與串接方不需要做任何事：Worker 保有原本的公開 URL、修訂版與部署票證，不會有任何 API 呼叫、token 或金鑰變動。搬移由平台維運者發起，部門或串接方都無法發起。本頁只談作者與呼叫端看得到的部分；平台如何執行搬移屬於維運者的內部作業，不在這份手冊範圍內。
隨 Worker 搬移的內容
Worker 的 Durable Object 所存放的一切都會隨它搬移，而新位置要等到它持有的狀態副本經驗證與原件相符之後，才會接手：
- handler 程式碼用
context.storage存下的所有資料（持久儲存）； - 執行期設定與 Worker 機密（執行期設定、Worker 機密）；
- Worker 層級的存取政策與逐操作設定，含操作 API 金鑰（存取模式、逐操作存取）；
- 已交付的服務帳號憑證與其快取的登入 token（服務帳號）。
修訂版、票證與稽核事實存在資料庫；搬移不會改變它們所顯示的任何內容。
Worker 需要什麼
只有上線中的 release 以 builder 政策 department-worker-project-v2.10 或更新版本建置（提交管線）的 Worker 才能被搬移；後端 5.22.0 上每個新提交的修訂版都是。上線 release 建置得較早的 Worker 照常運作，不會被搬移；等到以 v2.10 或更新版本建置的修訂版部署之後，它才可以被搬移。handler 契約沒有任何改變：相同的 HandlerInput、相同的儲存 API 與上限。
搬移之前，平台可能會在最新的 runtime 上重建 Worker 目前的修訂版。它的歷史中會出現一個新的修訂版與部署；程式碼沒有改變。在該次重建就緒之前，呼叫可能短暫失敗。
暫停
搬移期間 Worker 會被凍結：從凍結到新位置接手為止，它會拒絕請求。各方得到的回應如下：
| 對象 | 暫停期間 |
|---|---|
| 閘道通道或公開通道上的呼叫端 | 503 migration_fenced（{"code":"migration_fenced","message":"Worker migration in progress","requestId":…}，帶 x-teamsync-request-id 與 cache-control: no-store；沒有 Retry-After header）。在閘道通道上，路由切換前後的幾秒鐘（回滾前後也一樣），回應也可能改為 409 serving_target_mismatch（Serving target changed）。請重試 |
| 凍結開始時已在執行的請求 | 可以跑完。讀取（storage.get、storage.list、secrets.get、config）仍可使用；storage.create、storage.replace 與 storage.delete 會被拒絕並對 handler 丟出例外（若未被捕捉：500 worker_execution_failed），context.teamsync.authHeaders() 會丟出 service_account_unavailable |
| 透過 API 讀取 Worker 的狀態：存取政策、執行期設定、機密清單、操作設定、OpenAPI 文件 | 該路由慣用的修訂版過期 409：Access policy revision is stale、Runtime config revision is stale、Worker secret mutation is stale 或 Operation-settings revision is stale。這個訊息容易誤導 — 沒有任何東西過期（OpenAPI 文件回的是 Access policy revision is stale）；請在暫停結束後重試 |
| 必須先讀取 Worker 狀態的變更：操作設定、操作金鑰、寫入機密；部署也是，因為它的第一步會讀取現行設定 | 同樣的修訂版過期 409（Operation-settings revision is stale、Worker secret mutation is stale） |
| 會先記錄稽核意圖的變更：存取政策（取代、撤銷金鑰）、執行期設定（取代、刪除）、刪除機密 | 503 Department Worker control change is unavailable，與下面整段尚未結束的期間相同 |
| 服務帳號路由 | 讀取單一帳號會回 503 Department Worker service-account credentials are unavailable；重設 Worker 持有或使用的憑證會回 200 並帶 delivery: "failed"（舊的機密已被撤銷；見管理服務帳號）— 搬移結束後請再重設一次；刪除帳號會回 200，但 Worker 仍保有該憑證的副本，且可能回報沒有綁定的操作 |
暫停多久。 暫停從凍結持續到平台維運者切換到新位置：這是一段短暫的暫停，通常遠不到兩分鐘，期間呼叫會回 503 migration_fenced；請以退避方式重試。它會隨 Worker 儲存的資料量、凍結開始時仍在執行的請求（搬移大約每分鐘才重新檢查一次它們），以及驗證副本到切換之間的時間而變長；光是路由切換本身就包含至少 5 秒的等待。請把「兩分鐘」當作預期，不是保證：程式碼沒有對暫停的長短設任何上限。
搬移尚未結束期間
從搬移準備好，到它完成、回滾或放棄為止 — 凍結之前與接手之後，和暫停期間一樣 — 部門無法部署這個 Worker，也無法變更它儲存的設定。暫停之外，讀取與呼叫都照常運作：
| 請求 | 回應 |
|---|---|
POST /worker/deployments | 409 worker_migration_in_progress（純字串 detail，不是帶 code 的物件）— 但若 Worker 已持有逐操作設定（部署會透過一次有稽核的變更把它帶過去），或請求本身帶有 operation_settings，則是 503 Department Worker control change is unavailable。沒有排入任何工作。搬移結束後再重試 |
| 會產生稽核紀錄的變更：存取政策（取代、撤銷金鑰）、執行期設定（取代、刪除）、機密（寫入、刪除）、操作設定與操作金鑰 | 503 Department Worker control change is unavailable。搬移結束後再重複 |
| 重設 Worker 持有或使用之服務帳號的憑證 | 200 並帶 delivery: "failed" |
| 刪除該 Worker 所屬的部門 | 400 worker_migration_state_retained |
提交新的修訂版，以及建立或編輯服務帳號，不受影響。
搬移之後
Worker 仍在同一個公開 URL 與同一條閘道路由上回應，修訂版、機密與儲存內容都相同。它所產生的回應會在 x-teamsync-serving-namespace 診斷 header 回報新位置，並在 x-teamsync-routing-epoch 回報大於零的路由 epoch；請不要讓程式邏輯依賴這兩個 header（呼叫 API）。
失敗、已回滾或已放棄的搬移
- 凍結之前，除了第二張表的拒絕之外，什麼都看不到。
- 凍結之後，少數幾種暫時性情況（請求仍在執行、結果未知的上傳、新位置尚未回應 — 最長 10 分鐘 —、路由變更尚未可見、資料庫忙碌）會在一兩分鐘後自動重試。其他任何失敗都會讓搬移停下來：Worker 會維持凍結 — 沒有任何機制會自行解凍 — 並持續回 503
migration_fenced，直到平台維運者繼續並完成搬移，或把搬移回滾。部門沒有什麼需要重試；如果 503 持續的時間超過上面說的暫停，請提供該 503 的x-teamsync-request-id。 - 回滾會把路由切回原位置並解凍：Worker 提供的正是被凍結當下的狀態。如果新位置已經接手，它之後接受的寫入會留在新位置，不會被併回，所以回滾之後 Worker 看不到它們。
- 搬移完成之後仍可回滾 — 直到 Worker 的下一次部署被接受為止。 回滾沒有時間限制；重點是搬移完成後是否已接受過部署。若沒有，回滾會被接受：進行期間上述的暫停與拒絕會再次出現，接手之後所接受的寫入不會被併回。只要搬移完成後曾接受過任何部署 — 已上線的、失敗的，或仍在執行中的 — 回滾就會被拒絕，回 409
migration_completed_rollback_requires_operator_recovery（代碼位於detail.code），而且在更動任何內容之前就已回應：搬移維持已完成、Worker 仍留在新位置，再要求一次也會得到同樣的拒絕。訊息告訴提出回滾的平台維運者：後續的部署使回滾無法進行，請改用針對目前部署的維運者復原程序；沒有自動回頭的辦法。部門與串接方不需要做任何事。 - 放棄搬移只有在尚未凍結、也尚未切換時才可以；Worker 一旦被凍結或已切換，就必須把搬移回滾。放棄會解除上述對部門變更的限制，但不改變 Worker 所提供的內容。
- 搬移完成、回滾或放棄之後，部署以及對 Worker 已儲存設定的變更都恢復正常，刪除其所屬部門也一樣。已回滾的 Worker 之後可以由新的嘗試再次搬移。
搬移不會改變 API 其餘部分的票證與錯誤詞彙：錯誤。