Jenkins Mac 構建節點驗收：2026 上線前檢查

「Agent 在線」只證明 Jenkins Controller 與 Agent 之間建立了某種通信，不代表節點已能處理正式交付。單次測試構建通過，也可能只是因為沒有觸發簽名、私有依賴、並發污染或重啟後接入等條件。

企業應把驗收結果分成三層：

1. 連線成功：節點出現在 Jenkins，Agent 狀態正常，基本命令可以執行。
2. 測試構建成功：使用團隊真實專案完成測試、封存或匯出，並保留完整日誌。
3. 生產可用：在真實權限、真實憑證、真實並發、真實發布窗口與故障恢復條件下，仍能達到團隊定義的服務目標。

Jenkins 官方文件把 Node、Agent 與 executor 分開描述，並指出 Agent 是代表 Controller 執行工作的程序；節點還會受到磁碟空間、暫存空間、時鐘同步與回應時間等監控項目影響。可參考 Jenkins 官方節點與 executor 文件。

建議建立一份「驗收證據表」，每列至少包含：

門檻不能由文章範例代替。每個團隊都應以自己的專案、測試數量、簽名流程、發布時段及可接受排隊時間定義「通過」。

第一步是確認 Jenkins Controller 不承擔正式構建。Jenkins 官方安全建議不鼓勵在內建節點執行構建，Controller 應專注於管理、授權、驗證與調度；正式工作應派往獨立 Agent。可參考 Jenkins Controller 隔離建議。

驗收時依次檢查：

• [ ] Controller 與 Mac Agent 的連線方式、服務帳戶及啟動方式已記錄。
• [ ] Agent 短暫斷線後，能按團隊門檻重新接入，而不是只停留在離線狀態。
• [ ] Mac 節點標籤能清楚區分 Apple Silicon、Xcode 工具鏈、測試用途及發布用途。
• [ ] Pipeline 的 agent 或 stage 級調度規則已匯出並接受程式碼審查。
• [ ] iOS 任務不會派往錯誤架構、缺少指定 Xcode 或沒有簽名環境的節點。
• [ ] 磁碟空間、暫存空間、時鐘同步與回應時間監控已接入告警。
• [ ] Agent 對 Controller 的權限邊界符合 Jenkins Agent 與 Controller 安全控制文件。

不要用「節點名稱看起來正確」作為證據。應在實際 Pipeline 中輸出節點名稱、架構、Xcode 路徑及必要環境變數，再確認日誌與預期一致。

Xcode 通過版本查詢，只能證明命令存在，不能證明團隊專案能夠完成交付。驗收需要使用真實專案執行測試、封存、匯出及必要的發布腳本，並將 xcodebuild 原始輸出保存到構建附件。

至少安排三種結果對照：

• 乾淨工作區：刪除工作目錄與既有派生資料後執行。
• 正常快取：使用團隊平日允許保留的快取執行。
• 清理快取後重跑：確認流水線不會因隱藏的 DerivedData 或模擬器狀態而偶然成功。

Swift Package 專案應提交 Package.resolved，並在直接使用 xcodebuild 的 CI 流程中評估 -disableAutomaticPackageResolution；Apple 官方文件指出，這有助於讓 CI 依照鎖定的依賴版本執行。私有套件則要另外驗證 SSH 金鑰、known_hosts 及憑證注入範圍，可參考 Apple 的 Swift Package CI 文件。

• [ ] Xcode、Command Line Tools、SDK 與 Swift Package 版本已記錄。
• [ ] Package.resolved 或其他依賴鎖定檔已納入版本控制。
• [ ] 測試、Archive 及 exportArchive 都在真實專案中通過。
• [ ] 工具鏈升級有指定批准人、並行保留方案及回滾方式。
• [ ] 節點漂移後能被識別，而不是靜默接受未審批的工具版本。

Apple 官方文件亦把 Archive 與 Export 視為分開的 xcodebuild 步驟；因此只跑 build 或單元測試，不足以代表發布節點合格。可參考 Apple 的發行簽名與 xcodebuild 文件。

簽名憑證、描述檔、App Store Connect 金鑰及程式碼倉庫憑證，不應因為「同一台 Mac 比較方便」而全部放在全域範圍。Jenkins 官方文件指出，憑證應限制在實際需要的最低範圍；定義在 Controller 層級的憑證，可能被該 Controller 上的多個 Pipeline 使用。可參考 Jenkins 憑證管理與作用域文件。

驗收應包含一次刻意的低權限測試，而不是只確認正常任務能發布：

• [ ] 程式碼讀取憑證、測試簽名憑證及生產發布憑證已分開。
• [ ] Jenkins Credentials 的作用域限制在必要的 Folder、Job 或 Pipeline。
• [ ] 構建使用者不能讀取其他專案的私有金鑰或描述檔。
• [ ] 鑰匙圈解鎖只在必要 stage 發生，並且不把秘密寫入 Console Log。
• [ ] 以低權限 Job 嘗試存取不相關秘密時，結果是拒絕。
• [ ] 開發構建與生產發布節點已分離；若無法證明隔離，則拆分 Agent 或獨立 Mac 主機。

Jenkins 的權限文件也提醒，能夠配置 Agent 的使用者可能讓 Job 被派到其具備較高檔案權限的電腦，因此「誰能改節點設定」本身就是安全審查項目。相關權限可對照 Jenkins 官方權限說明。

多條 iOS 流水線是否能共用一台 Jenkins Mac Agent，不能由 Apple Silicon 型號直接推算。executor 數量代表可同時執行的任務數，但真正瓶頸可能在記憶體、硬碟 I/O、模擬器、DerivedData、暫存目錄、簽名鑰匙圈或網路頻寬。

Jenkins 官方文件把「每個節點一個 executor」列為較安全的配置起點；只有在工作負載較輕且監控證明仍有餘量時，才應逐步提高並發。詳情可參考 Jenkins executor 配置說明。

• [ ] 以團隊高峰隊列重播，而不是只執行單一構建。
• [ ] 記錄排隊時間、executor 使用率、CPU、記憶體、磁碟 I/O 及暫存空間。
• [ ] 確認不同 Job 不會共用錯誤工作區或覆蓋 DerivedData。
• [ ] 確認並行任務不會爭用同一個模擬器、登入狀態或鑰匙圈。
• [ ] 以失敗率與可接受排隊時間決定單節點並發，而非只看核心數。
• [ ] 對發布節點採用比一般測試節點更保守的並發策略。

若高峰負載不穩定，可採用固定容量加彈性節點的方式：固定節點承擔日常構建，短期或發布窗口則增加經驗證的遠程 Mac。這樣做的前提是每一台新增節點都必須重新通過工具鏈、憑證及恢復驗收。

遠程登入成功，不等於完整災難恢復。Apple 官方說明，macOS 可透過 Remote Login 使用 SSH 或 SFTP，但開啟遠程登入也會增加暴露面，應限制可登入使用者及必要權限。可參考 Apple Remote Login 官方說明。

驗收至少執行以下故障注入：

• [ ] 計劃重啟後，Mac 能回到可管理狀態。
• [ ] Agent 程式異常退出後，能自動啟動或按明確流程重新接入。
• [ ] Jenkins 與 Mac 之間短暫斷網後，節點不會接收不完整任務。
• [ ] 磁碟空間告警會阻止新構建，並留下可追查的告警記錄。
• [ ] FileVault 解鎖條件、Remote Login 及登入帳戶已由指定負責人確認。
• [ ] 恢復流程寫明所需權限、人工介入點、回退方案及證據位置。
• [ ] 夜間發布窗口使用真實 Pipeline 驗證，而不是只做人工 SSH 登入。

在 Apple Silicon Mac 搭配 macOS 26 或以上版本、且 Remote Login 已開啟並具備網路連線時，Apple 文件說明 FileVault 可在重啟後透過 SSH 解鎖；這是可核對的官方能力，但不代表所有團隊環境都能直接無人值守。仍需按目標 macOS、帳戶策略、網路及裝置管理設定實際復測，可參考 Apple FileVault 管理文件。

本篇不填入 NUKCLOUD 未公開的地域、配置、租賃周期或恢復耗時；企業向任何遠程 Mac 供應方索取驗收資料時，應要求提供交付方式、主機重啟記錄、Agent 斷線記錄、遠程恢復步驟及連續運行測試的原始證據，而不是只接受「可 7×24 小時使用」的描述。

完成測試後，不宜只寫「通過」或「不通過」。建議將結論分成四類，並為每類結論指定負責人：

FAQ 已將常見的 Agent 調度、共享節點、重啟恢復及 executor 決策集中整理；若需進一步了解遠程 Mac 的使用方式，可參考 NUKCLOUD 繁體中文說明中心。

完成這份清單後，若團隊仍缺少可用於重啟恢復、真實並發及發布簽名測試的獨立 Mac 環境，較穩妥的做法是先申請一台按周期使用的遠程 Mac 作為驗收節點，將真實 Jenkins Pipeline 導入並保存證據，再決定長期固定節點數與峰值擴容方式。相較於直接購置多台 Mac，這種試運行方式可避免過早承擔硬體折舊、維護、閒置容量及夜間恢復責任；若要了解可用的租用入口，可前往 NUKCLOUD 繁體中文訂購頁。