GitLab Runner macOS 重啟後離線？2026 企業修復指南

「Mac 可以 Ping 到」只證明網路路徑可能恢復。排障時，我們先把狀態拆成四層：

• 主機啟動：核心、網路介面與基本系統服務已啟動。
• 磁碟解鎖：FileVault 保護的啟動磁碟已可讀取。
• 使用者登入：安裝 Runner 的專用 CI 帳戶建立了自己的工作階段。
• 服務與工具可用：LaunchAgent 載入，Runner 能連回 GitLab，Keychain、Xcode 和模擬器也在正確上下文中運作。

GitLab 的 macOS 安裝方式把 Runner 作為使用者層級服務處理；Apple 對 launchd 的說明也區分了使用者 Agent 與系統 Daemon 的執行上下文。排查起點應以GitLab macOS 安裝文件和Apple 的 launchd 工作說明為準。

先記錄證據，不要先刪除設定：

whoami
id
launchctl print "gui/$(id -u)"
gitlab-runner status
gitlab-runner list

上述結果要連同時間、主機名稱、目前帳戶和 GitLab 頁面狀態保存。若 gitlab-runner status 顯示服務不存在，與「服務存在但未接單」是兩種不同故障。

注意： 網路可達、SSH 可登入和 Runner 可接單不是同一個健康指標。任何一項恢復，都不能代替下一項的驗證。

先確認安裝帳戶與設定檔是否一致

macOS Runner 應由專用 CI 帳戶安裝。常見錯誤是 IT 人員以管理員帳戶安裝一次，再以 CI 帳戶安裝第二次，最後產生多份設定檔、不同 system_id 或重複的 LaunchAgent。

我們會核對：

• 執行 gitlab-runner 的帳戶是否就是預期的 CI 帳戶。
• 設定檔是否位於該帳戶的使用者目錄。
• LaunchAgent 的標籤是否屬於這台主機，而不是舊節點。
• GitLab 頁面中的 Runner 標籤，是否與專案 Job 的標籤相符。
• 是否存在未使用的舊服務、舊 Token 或殘留註冊。

可先在目標帳戶下查看服務：

launchctl print "gui/$(id -u)/com.gitlab.gitlab-runner"
gitlab-runner verify

服務標籤若不同，不要立即判定 Runner 損壞。先找出實際載入的 plist、設定檔位置和執行帳戶，再決定只清理重複項目或重新註冊。

為何不應直接改成 LaunchDaemon

LaunchDaemon 屬於系統層級；LaunchAgent 則與使用者工作階段相關。Apple 對兩者的權限和執行上下文有明確區分，詳見Apple 的 Agent 與 Daemon 設計說明。

把 Runner 硬改成 LaunchDaemon，可能短期內讓程序在開機後出現，但同時改變：

• HOME、工作目錄和環境變數。
• 登入 Keychain 的可見性。
• 圖形工作階段與模擬器的存取條件。
• 檔案權限和簽名身份的使用者歸屬。
• GitLab 官方服務模式的支援邊界。

因此，修復方向不是「把服務提升到系統層級」，而是讓專用 CI 帳戶、使用者工作階段和 LaunchAgent 在受控條件下正確恢復。

FileVault 是重啟後最容易被忽略的阻斷點。磁碟仍然鎖定時，主機可能已接上電源，但使用者目錄、Runner 設定、Keychain 和 Xcode 工具都不能正常使用。

Apple 的自動登入說明指出，自動登入會受安全設定影響；FileVault 的部署與管理則應參考Apple FileVault 管理文件。企業不能把「已加密」和「一定能無人值守登入」當成同一個設計結果。

我們建議先作這些核查：

• 目標 Mac 是否為 Apple Silicon。
• 目前 macOS 版本和裝置管理政策是否允許預期的登入流程。
• FileVault 是否要求受控帳戶在開機時解鎖。
• Remote Login 是否已啟用，且防火牆、路由和存取控制允許連線。
• 恢復帳戶是否有明確擁有人、最小權限和稽核紀錄。

Apple Remote Login 說明只能協助確認遠端登入配置，不能保證 FileVault 解鎖或圖形使用者工作階段會自動建立。對高保密環境，我們通常保留受控的人工解鎖路徑；對需要無人值守恢復的環境，則必須由安全負責人正式接受自動恢復帶來的風險。

Runner 心跳恢復後，先不要直接跑完整發布流水線。完整流程同時包含依賴安裝、Xcode、模擬器、簽名和上傳，失敗時很難定位。

我們把驗收拆成四個最小測試：

1. 普通 Shell 測試：確認 Job 能在預期目錄執行，並記錄 whoami、HOME 和工作目錄。
2. Xcode 建置測試：用不涉及發布憑證的最小專案確認 Xcode 可啟動。
3. 模擬器測試：確認使用者工作階段可建立或存取指定模擬器。
4. 簽名測試：只驗證受控測試身份，不在除錯日誌輸出憑證內容。

登入 Keychain、系統 Keychain、CI 服務帳戶和發布簽名身份必須分開管理。若普通 Shell 和 Xcode 建置成功，但簽名失敗，排查重點就應轉向 Keychain 解鎖、簽名身份、存取權限和工作階段，而不是重裝 Runner。

啟用 Runner 除錯日誌前，要先建立受控時間窗和保存期限。GitLab 的Runner 故障排查文件提醒管理者避免讓變數和憑證進入日誌；除錯完成後應立即恢復一般日誌層級。

有些故障不是重啟本身造成，而是重啟後暴露了原本沒有整理的配置。

第一類是帳戶與服務殘留。
錯誤帳戶下的重複安裝，可能留下多個 LaunchAgent、設定檔和 Runner 身份。GitLab 頁面看似有節點在線，但 Job 實際送到另一個標籤或舊節點。處理時應先停止重複服務、備份設定，再逐項清理，不能直接刪除整個使用者目錄。

第二類是路由不匹配。
Runner 可能在線，但專案 Job 要求的標籤、保護分支權限或群組範圍不符合。請依照GitLab Runner 標籤與配置文件核對：

• Job 是否指定了該 Runner 擁有的標籤。
• Runner 是否允許執行受保護分支或標籤。
• Runner 是專案範圍、群組範圍，還是被錯誤註冊到其他範圍。
• 是否有舊 Runner 仍回報在線，造成判讀混亂。

這也是為甚麼「頁面在線」不能直接等於「生產可用」。

以下清單適合在維護窗口執行。每一項都要記錄結果、時間、執行人和失敗處置。

• [ ] 先保存 GitLab 頁面狀態、gitlab-runner status 和目前登入帳戶。
• [ ] 確認 FileVault 解鎖方式、恢復帳戶和授權紀錄已準備。
• [ ] 執行正常重啟，記錄主機重新可達的時間。
• [ ] 確認專用 CI 帳戶已建立工作階段，而不是只有 SSH 可登入。
• [ ] 以該帳戶檢查 LaunchAgent 是否載入，並確認沒有重複服務。
• [ ] 執行 gitlab-runner verify，確認 Runner 身份仍有效。
• [ ] 提交普通 Shell Job，確認工作目錄和帳戶正確。
• [ ] 執行最小 Xcode 建置，不直接使用正式發布憑證。
• [ ] 分別測試模擬器和簽名 Keychain。
• [ ] 核對 Runner 標籤、保護分支和專案路由。
• [ ] 以異常斷電或撤銷帳戶權限的情境重演恢復路徑。
• [ ] 明確記錄失敗時是人工解鎖、重新載入服務、切換節點，還是暫停發布。

若只能完成「頁面顯示在線」，卻無法完成最小 Xcode 和簽名測試，這台 Mac 不應直接進入正式發布池。

經驗： 單節點最常見的風險不是完全無法啟動，而是啟動後看似正常，直到第一個需要登入 Keychain 或模擬器的 Job 才暴露問題。

FAQ 已集中回答五個企業排障決策：自動啟動、使用者登入、LaunchDaemon、FileVault 遠端恢復，以及 Runner 在線但 Keychain 不可用。實務上，這五項應和上面的驗收證據互相對照，而不是只依賴控制台上的綠色狀態。

若現有 Mac 每次重啟都需要人員到場解鎖，或簽名流程只能由特定工程師手動修復，問題已不只是 Runner 設定，而是發布基礎設施缺少可驗證的恢復路徑。

我們會先確認三件事：

• 是否有專用 CI 帳戶，且權限、Keychain 和發布身份已隔離。
• 是否能在不暴露憑證的前提下完成遠端重啟、解鎖和最小建置驗收。
• 主節點故障時，是否有隔離的備用 Mac，以及清楚的切換條件。

若團隊正在評估遠端 Mac 的企業使用方式，應把「重啟後接單驗證、FileVault 處置、Keychain 隔離和故障換機」列入試點，而不是只比較 CPU 或儲存容量。需要特定地區節點時，也可先查看香港的 Mac 遠端方案，再按實際存取政策和資料位置作決定。

自建 Mac 的優點是硬體與安全政策完全由企業掌握；缺點是採購、備機、遠端電源、現場解鎖和硬體故障都由企業承擔。雲端虛擬環境部署較快，但不一定提供真實 Apple 硬體、完整圖形工作階段或符合簽名需求的執行上下文。若目前方案的恢復仍依賴現場人員、單一節點，並且沒有可重演的驗收紀錄，長期來看並不是穩定的發布方案。

在這種情況下，租用 MESHLAUNCH 的遠端真實 Mac 作為隔離備用節點，重點不在「多一台機器」，而在於讓團隊能先驗證遠端存取、重啟後接單和故障切換，再決定是否擴充容量。對臨時發布高峰、災備演練或需要快速建立測試環境的團隊，這通常比立即採購另一台實體 Mac 更容易控制變更範圍；但若需求是長期滿載、必須掌握實體介面，直接自購仍可能更合適。