場景與風險清單
典型組合：基底在 ghcr.io、產物在私有登錄檔，多階段來回拉取。跨境下易變成排隊雪崩：docker pull 搶 TLS 與層下載，寫入尖峰再拖慢解壓。
- 429：權杖或配額被打滿；忽略
Retry-After的硬重試會放大失敗。 - 5xx：代理／上游暫態；退避係數應與 429 分開，勿共用「過猛」階梯。
- x509／CA：鑰匙圈與 Docker 信任庫不一致時，錯誤像隨機發生。
- 磁碟／inode：層快取與 BuildKit 暫存同卷，空間夠仍可能因 metadata IO 看似卡住。
| 維度 | 建議值／階梯 | 決策備註 |
|---|---|---|
| 併發拉取層數 | 單 job：3–5；共享多 job：每 job 2–3，全節點總量受磁碟同時寫層限制 | 看 P95 與 iowait；BuildKit 另限全域並行 |
| docker login 令牌 TTL | 長效 PAT：勿上機；CI 建議45–90 分鐘可刷新（OIDC 更佳）；唯讀機器人：12–24 小時輪替 | TTL 須低於最長 job 並留 10–15 分鐘裕度 |
| HTTP 429 退避（秒） | 10+jitter→20→40→80，封頂300；有 Retry-After 則優先 | 限流語意；避免多點並行刷新登入 |
| HTTP 5xx 退避（秒） | 2–4+jitter→8→16→32，封頂120；最多5–7 次 | 暫態過載；仍設上限防占滿 worker |
| 磁碟水位 | 系統卷：警戒 18–20%、嚴重 12–15%；Docker 根卷：警戒 22–25%、嚴重 15–18%；inode：12%／8% | 警戒限流／prune；嚴重停新 job 並附 df 快照 |
認證與最小權限
採唯讀 package與單一命名空間；登入僅包在拉取步驟外側，避免長效密碼常駐機。
| 憑證型態 | 建議範圍 | TTL／輪換節奏 | 不建議做法 |
|---|---|---|---|
GitHub Actions GITHUB_TOKEN | 僅在同 repo workflow 讀取 GHCR；跨 repo 改 OIDC／PAT | 隨 job 自動失效 | 把同一 token 複製到自建 runner 長期檔案 |
| 細粒度 PAT／機器人帳號 | read:packages 或供應商同等唯讀 scope | 對齊上表 TTL；每週或每兩週輪替窗口 | 寫入權限預設開在拉取專用 runner |
| 企業私有 Registry | 專案級 robot＋IP 允許清單（若可行） | 與稽核日誌欄位對齊（subject、workflow、image digest） | 將密碼印在 build log 或 compose 明文 |
TTL 低於最長建置時，採分段登入：拉前／推前各刷新一次。
跨境網路與鏡像端點選型對照表
選型看失敗降級與成本（出境、維運、法遵），而非單次延遲。
| 端點策略 | 命中／延遲 | 法遵與稽核 | 維運成本 | 較適合 |
|---|---|---|---|---|
直連 ghcr.io／原廠域名 | 路徑最短；跨境 jitter 大 | 流量出境；日誌需自行留存 | 低 | PoC、低頻釋出、已有充足預算頻寬 |
| 區域中繼／Pull-through 快取 | 第二次後命中佳；首次仍可能慢 | 資料停留內網區；需定 digest 與垃圾回收策略 | 中–高 | 中高頻建置、嚴格資料邊界 |
| 企業私有 Registry 同區部署 | 內網 RTT 低；仍需備援上游 | 最佳：憑證與存取邊界一體化 | 高（同步／複製） | 釋出產線、需映像簽章與准入掃描 |
雙端點時分開 DOCKER_AUTH_CONFIG，避免預設登入覆寫導致 401 迴圈。
CI 整合步驟（含示例命令占位）
宣告兩個登錄檔端點與命名空間（占位）：GHCR_HOST=ghcr.io、CORP_REGISTRY=<YOUR_REGISTRY_HOST>、NS_BASE=<org/base>、NS_APP=<corp/app>。
注入短期權杖：以 CI 秘密 GHCR_TOKEN、CORP_TOKEN 於記憶體匯出，勿寫入工作目錄檔案。
限流拉取：依「可執行參數總表」設定每 job 層平行度；與全域重型拉取計數器二選一或疊加。
# 占位：登入 GHCR（請改為實際 secret 注入方式） echo "$GHCR_TOKEN" | docker login ghcr.io -u "$GHCR_USER" --password-stdin # 占位：登入企業私有 Registry echo "$CORP_TOKEN" | docker login "$CORP_REGISTRY" -u "$CORP_USER" --password-stdin # 占位：限制 BuildKit 平行層（依工具鏈調整；示例為環境變數風格） export BUILDKIT_MAX_PARALLELISM=<例如 4> # 占位：拉取多階段所需映像（標籤請替換） docker pull "$CORP_REGISTRY/$NS_APP:<TAG>"
退避寫進腳本或 CI 重試；日誌記錄狀態碼、等待秒與 digest 以便回調閾值。
FAQ（拉取卡住／證書／代理）
卡住：區分層下載停滯（頻寬／429）與解壓慢（水位／iowait）；共享節點先降併發層數。
證書：引擎與使用者讀同一套 CA；更新後必要時重啟 daemon；勿全域關 TLS。
代理：校驗 HTTPS_PROXY／NO_PROXY，避免內網庫誤走外網代理。
總結：以端點選型定邊界，最小權限＋短 TTL降外洩，429／5xx 分開退避並磁碟水位聯動限流。頁首 JSON-LD 已含 HowTo／FAQPage 可作複合結果基礎；進階可為步驟補圖並以 ImageObject 關聯 BlogPosting。