Config Sync Advisory Lock Pattern

概念概覽

Advisory Lock + Fingerprint 防並發衝突

核心知識

Advisory Lock + Fingerprint 防並發衝突

Config Sync 流程： 1. preview 階段取得 advisory lock，計算 fingerprint 2. apply 階段驗證 fingerprint 是否與 preview 一致 3. 若 preview → apply 之間有其他人變更，回傳 ErrConfigSyncConflict，要求重新執行 preview

這設計序列化並發的 sync 操作，代價是需要客戶端重試。

content_mutation 封鎖機制

當偵測到 content_mutation（內容雜湊不一致）時，整個 sync 流程被 block，直到人工執行 ForceUpdateContentHash 並完成審核才能解鎖。這是保守設計，防止 drift 靜默擴散。

content_mutation detected
  → sync blocked
  → 人工審核 diff
  → ForceUpdateContentHash
  → sync 恢復正常

解鎖流程必須記錄在 Runbook

ForceUpdateContentHash 是高風險操作，使用時機與審核流程應在 runbook 中明確說明，避免誤用導致非預期 config 覆蓋。

經驗教訓

• content_mutation block 設計雖保守，但可防止 config drift 在無人知情的情況下擴散，適合生產環境

• advisory lock 序列化 + fingerprint 驗證是處理「先讀後寫」並發衝突的標準模式

常見陷阱

• content_mutation 封鎖後若沒有 runbook 指引，on-call 不知道如何解鎖，造成 sync 長時間停擺

• preview → apply 之間的延遲若過長，fingerprint 衝突率會升高，需考慮 lock TTL 設計

最佳實踐

• Runbook 必須包含 ForceUpdateContentHash 的使用時機、審核步驟及回滾方式

• ErrConfigSyncConflict 應在 client 端實作自動重試（含 backoff），減少人工介入

相關概念

• Activity Framework Settlement Idempotency
• ClaimMarker Pattern (PostgreSQL Idempotency)
• ClosureBuilder Deterministic JSON Encoding
• JWT Stateless Design at Scale with Forced Logout Gaps

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Go Server Race Condition Patterns — 共享：concurrency / 獨特：atomic, hot-reload

來源 Sessions

日期	Session	貢獻摘要

| 2026-04-02 | 157b6880-f9d3-466a-abf9-07af0459b5d5 | 記錄了 Config Sync 以 advisory lock + fingerprint 防並發衝突、content_mutation 封鎖機制及解鎖流程 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-02