Webhook 設定（YouTrack）
於專案掛載 Webhook Triggers：產生長隨機 webhook token（常見做法如 openssl rand -hex 32）、選擇承載權杖的標頭名稱（預設 X-YouTrack-Token）、只填 HTTPS 端點。先從 issueUpdated 或「欄位進入建置中」等窄事件開始，確認對應關係後再擴大。
- 步驟 1. 所有 URL 一律指向
https://<gateway>/youtrack/webhook，不要指向各台 Mac；加節點只加內部工作者。 - 步驟 2. 記錄誰能改 Webhook 與權杖，避免假日前後無人可輪替。
- 步驟 3. 載荷為 JSON，含
event、timestamp、id、numberInProject、summary、project.shortName等；issueUpdated會帶changedFields，可在入佇列前過濾雜訊。
簽名校驗（標頭權杖）
與部分平台不同，YouTrack 這條路徑不以 HMAC 簽本文，而以共享權杖標頭驗證。網關應先讀設定好的標頭名稱，與離線保存的密鑰做常數時間比對，再解析 JSON，避免偽造請求放大解析面。
- 步驟 1. 權杖檔權限收緊（例如
0440），僅守護行程可讀，對齊其他出站 Webhook 的密鑰衛生。 - 步驟 2. 不符回
401，日誌只留去識別中繼資料，切勿回顯權杖。 - 步驟 3. 可選：已知 YouTrack 出口的 IP 允許清單、邊緣 mTLS 或私有轉送，降低共享 VPC 上的撞庫風險。
- 步驟 4. 驗證通過後再掛
correlation_id；若尚未持久化入佇列，不要貿然回200，以免 YouTrack 重試造成幽靈任務。
多節點路由與佇列
把 MeshMac 節點視為可替換工作者：網關對外持信，節點對內持 Xcode 與磁碟。事件正規化為精簡任務（議題 id、專案、請求者、git ref、腳本名、idempotency_key）後推入共享佇列。排序、反壓與 mesh_node_id 標註可對照 部署與任務佇列同步。
- 步驟 1. 僅在入佇列已提交後回
200，冪等鍵建議混合議題 id 與正規化「轉移意圖」。 - 步驟 2. 聊天廣播 URL 留在網關，避免各節點腳本各自對外，維持單一通知故事。
- 步驟 3. 若同一議題也觸發雲端 CI，分車道與優先序，避免與本機簽章身分互搶。
重試、退避與摘要回傳
區分入站重試（YouTrack→網關）與出站重試（網關→聊天 REST、YouTrack REST）。入站：佇列寫入成功即快回 200，讓 YouTrack 停止重試；若寫入失敗，刻意回 500 以觸發對方退避。出站：對 429／5xx 採指數退避＋完整抖動，設嘗試上限，並以 idempotency_key + state 在至少一小時窗內去重廣播。旋鈕細節見 任務佇列重試步驟。
失敗摘要以 YouTrack REST 發短留言：狀態圖示、短 SHA、mesh_node_id、測試或日誌尾段、封存連結，控制在五行內。若聊天與追蹤器在退避上限後仍失敗，改走 IM 告警與權杖綁定輪替，避免通知閉環靜默中斷。
權杖輪換清單
- Webhook 權杖：產生新值→部署至網關檔案→更新 YouTrack 設定→以合成議題轉移驗證→從備份移除舊值。
- REST 永久權杖：於 Hub 建立替換、最小權限、雙權杖並行約十五分鐘供閘道重載，再刪舊權杖。
- 責任人與行事曆：至少每季檢查；外包輪替時同步更新，避免多機網格與設定漂移。
FAQ
- 網關自測一直 401？
- 確認處理常式讀的標頭名稱與 YouTrack 設定一致、權杖欄位無尾端空白，並檢查 TLS 終止層是否剥自訂標頭。
curl留言成功，OpenClaw 卻失敗？- 核對永久權杖是否仍具該專案留言權、REST 是否使用正確議題 id（非僅可讀編號），並讀取 API 錯誤本文以排除節流或 schema 漂移。
- 聊天頻道出現重複成功訊息？
- 在提供者層以訊息鍵去重；確保僅網關發廣播，禁止各節點腳本各自打聊天 Webhook。
- 第一天就要開「全部事件」嗎？
- 不必。先限定事件並證明冪等與摘要，再逐步放寬，以免日誌與佇列被雜訊淹沒。
下一步（僅公開頁）
先把通知閉環做穩，再擴節點與併發。下列皆免登入公開頁：首頁、購買／套餐、幫助中心、部落格、OpenClaw 索引。結帳前在套餐頁對齊地域與節點數，網關與建置機分離，小團隊即可用多機協同分攤峰值而不重拉整合。