遠端 Mac CI 使用 rsync 清單縮小傳輸面的示意

2026 年遠端 Mac CI 縮小 rsync 傳輸面：`--files-from`、分層 manifest 與 sparse-checkout 決策指南

遠端 Mac CI 最常見的效能陷阱往往不是磁碟不足，而是把整棵工作區當成 rsync 目標：海量小檔在跨國鏈路上長時間停在掃描階段，也更易把日誌與快取誤推到正式產物目錄。2026 較穩健的做法，是把流程拆成「可驗證清單 → 只傳必要路徑 → 在 staging 做原子切換」，並以 sparse-checkout 收斂 Git 工作區，讓 CI 在編譯前就少生成無謂的中繼檔。

目錄 (TOC)

1. 盲同步為何拖垮遠端 Mac CI

第一類成本是列舉：rsync 仍需知道哪些路徑參與比對；DerivedData、SwiftPM 快取與索引資料庫會讓跨國 RTT 下的 stat 往返變成數分鐘浪費，而真正要上傳的可能只有數百 MB 的 .ipa／.app／dSYM。

第二類是誤傳：環境檔、暫存金鑰或未脫敏日誌若進入多人 SFTP 目錄，會直接衝撞最小權限與稽核要求。

第三類是一致性：沒有 manifest 就只能靠時間戳猜測；路徑＋雜湊＋位元組數才能把「可驗證」前移到傳輸之前。

  1. 掃描爆炸：無關小檔增加時，CPU 與中繼資料往返同步放大。
  2. 頻寬浪費：重複推送未變更的素材包或切片。
  3. 協作摩擦：平行 Job 共用可寫上傳根目錄時，缺少 staging 分層更易互相覆寫。

2. 決策矩陣：archive、清單與 tarball

下列矩陣協助判斷何時由整目錄 -a 遷移到 manifest＋--files-from，以及何時仍應採 tarball（假設遠端 Mac 對外提供 SFTP／rsync，下游自動拉取）。

維度 整目錄 rsync 清單＋files-from 分層 tarball
路徑可控度 低 高（允許清單） 高但多解壓步驟
掃描成本 隨目錄膨脹 近似線性隨清單 單檔上傳較低
稽核友善 需額外比對 manifest 即證據鏈 可外掛摘要檔
典型場景 小型靜態站 iOS／macOS 產物樹 巨型素材包

3. How-to：manifest、dry-run、staging 紅線

建議七步：分層輸出 → 產生 manifest → 匯出 files-from → dry-run → 寫入 staging → 雜湊驗收 → 切換 current。

rsync -avh --files-from=manifest.txt --checksum --partial \
  -e "ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=4" \
  ./build/ ci-upload@remote-mac:/srv/releases/staging/build-123/
  1. 依晶片、通道與符號表分層；勿把 DerivedData 直接掛在同步根。
  2. manifest 採 CSV（path, sha256, bytes, mtime）；失敗時列印最大檔案協助定位膨脹。
  3. 明確排除 .env、簽章暫存與偵錯日誌。
  4. 範本變更後第一週固定 -n，並保存差異輸出。
  5. --delete 僅指向 staging 葉節點；共用快取唯讀。
  6. 跨國鏈路加 alive；多 Job 並行可用 --bwlimit 禮讓鄰居。
  7. 雜湊對齊後才更新 current 指標或軟連結。

4. sparse-checkout 與最小工作區

巨大 monorepo 可用稀疏檢出把編譯子樹收斂到有限模式；將 CI 設定寫入版本庫並在 checkout 後輸出 git sparse-checkout list 以利觀測。確認 Xcode workspace 參照未被誤剪；混合原生與前端資產時，額外驗證素材目錄完整性。

sparse-checkout 不能取代 manifest，但能縮短清單並降低把快取當產物的人為錯誤。

5. 量化指標與回滾口徑

每次建置追蹤清單筆數、manifest 總位元組與rsync 實際送出位元組；當列舉由數萬路徑收斂到數百內，跨國掃描常可由數分鐘降到數十秒級（仍受 RTT／磁碟影響）。回滾以「上一版 manifest 仍可還原」為準，而非憑記憶。

平行 Job 建議獨立 staging 前綴並寫入 job_id；共用依賴應唯讀掛載，避免 --delete 波及。

6. FAQ

問：隱藏檔會漏嗎？答：在產生器顯式納入 .xcconfig 等並用 dry-run 計數檢查。

問：能與圖形 SFTP 並行？答：需單一權威目錄或拆分人工上傳子樹以免覆寫。

問：xattr？答：確認遠端支援後使用 -E，並對簽章旁資料 spot-check。

7. 總結

清單驅動 rsync 與 sparse-checkout 能把時間花在「有價值的位元組」，但仍仰賴穩定上行、可預期 IO 與長時間在線。

自建節點常遇家用頻寬抖動、磁碟爭用與多人同帳號上傳；具目錄隔離、可稽核路徑與骨幹頻寬的託管遠端 Mac，較易把流程沉淀成預設安全。

若欲跳過線路試錯，可參考 SFTPMAC 遠端 Mac 租賃，把上傳模組化為可複製基線。