127.0.0.1），觸發依賴鏡像預拉取並把成功／失敗摘要回傳內部 CI；同時維護出站白名單，只放行 Registry、OIDC 與回呼端點。延伸閱讀：私有 Registry 拉取矩陣、閘道安全強化、併發與磁碟 FAQ。
目標與前置條件
目標：在推送當下把常用基底鏡像與服務映像預熱到建置節點，縮短後續 docker pull；並以結構化摘要讓編排器決定是否繼續流水線。
前置條件：遠端 Mac 已安裝 Docker Desktop 或對等執行環境；Harbor 專案具 Webhook 權限；內網可達閘道對外 URL（TLS 終止建議在反向代理）。
工具鏈（引用式）：2026 社群常見做法為以套件管理器安裝 curl、jq 等輔助工具，再安裝 Node 22+ 與 OpenClaw CLI；完成後執行 openclaw doctor 檢查版本與憑證。
守護程序（引用式）：執行 openclaw onboard，若需常駐可加上 --install-daemon（實際旗標以你安裝的 OpenClaw 版本說明為準），並以 launchd 寫死 PATH／NODE_BINARY，與 SSH 互動殼層一致。
閘道自檢：對 http://127.0.0.1:PORT/health 發送帶 Authorization: Bearer … 的探針，確認 HTTP 狀態碼與延遲；排程每 60 秒一次並寫入本地日誌。
# 閘道狀態自檢（替換 PORT、GATEWAY_TOKEN）
curl -sS -o /dev/null -w '%{http_code}\n' \
-H 'Authorization: Bearer YOUR_GATEWAY_TOKEN' \
--connect-timeout 3 --max-time 10 \
http://127.0.0.1:PORT/health
可複現串聯：Harbor 建立 Webhook Endpoint → 反向代理轉發至閘道路徑 → Handler 驗簽 → 呼叫預拉取腳本 → curl 將 JSON 摘要 POST 至 CI 回呼 URL。
Harbor Webhook 事件欄位與簽名校驗清單
Harbor 事件本文多為 JSON，實務上請先列印一筆真實推送再對照欄位設計 Handler，避免版本差異。下列為校驗清單（非 Harbor 版本綁定）：
| 檢查項 | 說明 | 未過關時行為 |
|---|---|---|
type／事件類型 | 僅處理如推送工件等必要類型 | 直接 204 忽略並寫審計 |
operator／觸發者 | 可選：限制機器人帳號或命名空間 | 標記為人工覆核 |
| 資源路徑 | 自 event_data 內巢狀取出 repository.name、tag、digest | 拒絕並回錯誤摘要 |
| 簽章本體 | 對原始 HTTP 本文位元組計算 HMAC 或比對共享祕鑰標頭 | 401，不執行 pull |
| 重放／時效 | 可選：檢查時間戳窗口與事件 ID 去重 | 丟棄重複事件 |
Content-Type | 固定 application/json | 避免中介改寫造成簽章漂移 |
若 Harbor 與閘道之間還有 API 閘道，請確認未重新序列化 JSON，否則 HMAC 將與傳送端不一致。
遠端 Mac 上預拉取腳本參數（並行／逾時／磁碟配額）
建議以環境變數驅動同一套腳本，方便在 OpenClaw Handler 內與手動除錯時共用。參數語意如下表；數值可依節點 CPU、網路與磁碟型號調整。
| 變數 | 用途 | 起步值（參考） |
|---|---|---|
PREFETCH_CONCURRENCY | 同時 docker pull 條目數上限 | 2～4（弱網改 1～2） |
PULL_TIMEOUT_SEC | 單一映像拉取逾時（外層 timeout 或 client 旗標） | 300～900 |
MIN_FREE_GB | 工作卷可用空間低於此值則中止或改排程 | 30～80（視映像基線） |
REGISTRY_USERNAME／REGISTRY_PASSWORD | 機器人唯讀帳密或短期權杖 | 與 Harbor Robot 帳號對齊 |
# 單一映像預拉取（示例；實務請改為清單迴圈＋並行控制）
export PULL_TIMEOUT_SEC=600
timeout "${PULL_TIMEOUT_SEC}" docker pull harbor.example.com/app/api:v2026.04.15
- 腳本開頭以
df -h或diskutil info取得同一掛載點剩餘空間，換算 GB 後低於MIN_FREE_GB即exit 2讓上游感知。 - 並行請搭配 Registry 限流策略；必要時在 Harbor 前加區域拉取快取。
OpenClaw 閘道路由與失敗摘要模板
在閘道設定中將 Harbor 專用路徑（例如 /hooks/harbor）綁定至固定 Handler：先驗簽、再解析映像清單、最後以非同步佇列執行預拉取，避免阻塞 Harbor 重試窗口。
出站白名單：於主機防火牆或出口代理列出允許的 FQDN：Harbor UI／Registry 主機、OIDC（若啟用）、以及 CI 回呼 URL；其餘對外 HTTPS 預設拒絕，降低誤設 Webhook 目標造成的 SSRF 面。
# 建議摘要 JSON 範本（寫入檔後以 curl POST）
{
"source": "harbor-webhook",
"repository": "library/demo",
"tag": "v2026.04.15",
"digest": "sha256:…",
"prefetch_status": "failed",
"error_code": "PULL_TIMEOUT",
"duration_ms": 0,
"host_disk_free_gb": 12.4
}
成功時將 prefetch_status 設為 ok 並帶上耗時；失敗時務必帶穩定機讀錯誤碼（如 AUTH_DENIED、DISK_LOW），方便 CI 規則引擎分支。
# 回傳摘要至內部 CI（替換 CALLBACK_URL、CI_TOKEN） curl -sS -X POST "$CALLBACK_URL" \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CI_TOKEN" \ --data-binary @/tmp/harbor-prefetch-summary.json \ --connect-timeout 5 --max-time 25
常見報錯 FAQ（鑑權／逾時／磁碟滿）
鑑權：Harbor 回 401 或 Robot 權杖被拒？
確認映像路徑與 Robot 範圍一致；權杖是否過期；docker login 與實際 docker pull 引用是否同一 Registry 主機名；企業 MITM 是否已信任根憑證。
逾時：Webhook 已重試但 Mac 端仍卡住？
降低 PREFETCH_CONCURRENCY；為每層拉取設定合理 PULL_TIMEOUT_SEC；檢查 HTTPS_PROXY 是否與 Daemon 一致；對照出站白名單是否漏放行 CDN 或子網域。
磁碟滿：預拉取中途報 no space？
先以 docker system df 檢視可回收空間；設定 MIN_FREE_GB 門檻並在成功建置後排程 docker image prune；將 Docker 資料目錄遷至獨立 APFS 卷。
閘道 /health 正常但 Harbor 日誌顯示 delivery failed？
核對反向代理路徑、TLS SNI、以及 Harbor Endpoint 是否指向正確埠；檢查來源 IP 是否被邊界 ACL 攔截。