工程師可執行的排查路徑

先定位問題，再用最短步驟恢復雲端 Mac。

從首次 SSH 連線、Xcode 工具鏈到 CI/CD 執行器與節點網路，本頁先提供檢查指令，再說明判斷條件。若仍無法恢復，可附上訂單編號、節點、時間與已去識別化的日誌提交工單。

前往控制台提交工單 查看首次連線步驟
優先路徑
4 步完成首次連線
問題範圍
6 類常見任務
人工支援入口
電子郵件與控制台工單
ONCEMAC SUPPORT BOARD 節點檢查清單
可開始排查
A1
確認連線資料 主機位址、使用者名稱、金鑰檔案
連線
B2
確認工具鏈 Xcode、CLT 路徑、建置日誌
建置
C3
確認執行邊界 磁碟、網路、程序與重新啟動記錄
節點
提交前請移除金鑰、存取權杖與完整 IP
快速定位

依任務尋找答案，不必從頭閱讀。

選擇連線、Xcode、CI/CD、儲存空間、網路或續租，頁面會保留相關入口。也可以輸入指令、現象或工具名稱進行搜尋。

目前顯示全部 6 類說明入口。

首次連線 核對位址、使用者名稱、金鑰權限與 SSH 指令。 Xcode 工具鏈 確認版本、Command Line Tools、簽署環境與日誌。 CI/CD 整合 檢查執行使用者、工作目錄、並行工作、快取與結束代碼。 檔案與環境遷移 使用 rsync、Git 與 Brewfile 重建可重複的環境。 故障排除 依連線、建置、磁碟、網路與重新啟動現象逐項縮小範圍。 續租與訂單 在控制台核對租期、續租記錄、帳單與節點狀態。
首次使用優先

四步建立第一次 SSH 連線。

連線資料以控制台實例詳細資料頁顯示為準。不要根據舊工單或歷史指令猜測主機位址，節點重新交付後應重新複製目前資訊。

  1. 01

    複製目前連線資料

    進入控制台的實例詳細資料，複製主機位址、SSH 使用者名稱、連接埠與金鑰資訊。先確認所選訂單與節點一致，再將指令貼到本機終端機。

  2. 02

    將私密金鑰儲存至受控目錄

    將金鑰檔案放在本機使用者可控的目錄，不要提交至 Git 儲存庫、建置產物或團隊聊天記錄。檔名可自訂，但後續指令路徑必須相符。

  3. 03

    收緊本機檔案權限

    在 macOS 或 Linux 本機終端機執行 chmod 600 ~/.ssh/oncemac_key。若 SSH 提示私密金鑰權限過於寬鬆，應先修正權限，不要透過關閉安全檢查來繞過。

  4. 04

    連線並核對節點身分

    執行控制台提供的 SSH 指令。首次連線時核對主機指紋來源；進入節點後執行 hostname、sw_vers 與 whoami，確認主機、系統與目前使用者。

指令執行順序

先驗證連線與版本，再啟動完整建置。

每次排查只變更一個變數。先確認 SSH 工作階段穩定，再讀取 Xcode 版本，最後執行包含結果套件與日誌的建置指令。如此可區分連線問題、工具鏈問題與專案本身的問題。

  • 連線層SSH 成功後記錄節點名稱與目前使用者。
  • 工具層確認目前生效的 Xcode 與開發者目錄。
  • 專案層保留 scheme、destination、結束代碼與日誌。
  • 自動化層僅擷取已去識別化的 fastlane 輸出，用於工單。
once-node / build-diagnostics
SSH 
$ ssh -i ~/.ssh/oncemac_key user@host
Last login: current session
connected: once-node

$ xcodebuild -version
Xcode 16.x
Build version 16x

$ xcode-select -p
/Applications/Xcode.app/Contents/Developer

$ set -o pipefail
$ xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -destination 'generic/platform=iOS' \
  -resultBundlePath ./BuildResults.xcresult \
  build | tee build.log

** BUILD SUCCEEDED **

$ bundle exec fastlane ios build
[fastlane] resolving dependencies
[fastlane] archive completed
[fastlane] lane finished successfully
工具鏈核對

將 Xcode 問題拆分為版本、路徑、簽署與日誌。

「本機可以建置、節點卻不行」通常不足以定位原因。應對照相同提交、依賴鎖定檔、scheme、destination 與環境變數，再比較兩端輸出。

XC-01

確認 Xcode 版本

執行 xcodebuild -version，記錄主要版本與 Build version。若流水線依賴特定版本，應在任務開始時輸出版本，而不是只在初次設定時檢查。

xcodebuild -version
xcrun --find simctl
swift --version
XC-02

確認開發者目錄

執行 xcode-select -p 檢查 Command Line Tools 目前路徑。若使用多個 Xcode 版本，應在執行器環境中明確設定 DEVELOPER_DIR，避免互動式工作階段與自動化任務讀取不同路徑。

xcode-select -p
echo "$DEVELOPER_DIR"
xcrun --sdk iphoneos --show-sdk-path
XC-03

檢查簽署環境

先確認鑰匙圈可存取、憑證名稱與 provisioning profile 條件相符，再檢查專案的 Team、Bundle Identifier 與簽署方式。工單只需提供已去識別化的錯誤片段，不要附上憑證、私密金鑰或密碼。

security list-keychains
security find-identity -v -p codesigning
xcodebuild -showBuildSettings
XC-04

匯出可複查的日誌

透過 set -o pipefail 保留真實結束狀態，同時使用 tee 寫入日誌。複雜失敗建議產生 .xcresult，並在分享前移除使用者名稱、路徑、權杖與業務資料。

set -o pipefail
xcodebuild build | tee build.log
echo "${PIPESTATUS[0]}"
自動化執行器

整合 CI/CD 前，先固定執行身分與工作目錄。

OnceMac 提供獨享實體節點與完整 macOS 命令列環境。具體平台功能、外掛相容性與任務定義應由團隊依自己的儲存庫與版本條件驗證。

RUNNER / 01

GitHub Actions 自架執行器

  • 確認執行器服務使用的 macOS 使用者，與手動 SSH 測試使用者是否一致。
  • 檢查儲存庫、組織或企業層級的註冊位置，避免任務被分配到錯誤標籤。
  • 為節點設定可識別的標籤，並在工作流程中明確使用對應的 runs-on 條件。
  • 驗證非互動式 shell 能讀取所需的 PATH、Ruby、Homebrew 與 Xcode 路徑。
  • 並行任務開始前，確認 DerivedData、套件管理器快取與磁碟剩餘空間。
RUNNER / 02

GitLab Runner

  • 核對 executor 類型、runner 標籤、受保護分支規則與任務比對條件。
  • 確認 LaunchAgent 或服務程序的使用者、HOME 與鑰匙圈情境。
  • 在任務開頭輸出 whoami、pwd、Xcode 版本與可用磁碟空間。
  • 快取鍵應包含依賴鎖定檔或工具鏈版本，避免重複使用不相容的快取。
  • 失敗時同時保留工作日誌、結束代碼與 runner 服務狀態。
RUNNER / 03

Jenkins 節點

  • 確認 agent 啟動方式、工作目錄與節點標籤符合 Pipeline 條件。
  • 檢查 Jenkins 執行使用者能否讀取儲存庫、建置目錄與必要的鑰匙圈。
  • 將 Xcode 選擇、依賴安裝與建置指令寫入可供審查的 Pipeline。
  • 限制同一實體節點上的並行執行器數量，避免磁碟與記憶體競爭。
  • 封存前記錄 workspace 大小、建置結果路徑與清理策略。
可重複遷移

遷移檔案，不要複製無法稽核的舊環境。

優先從 Git、鎖定檔與 Brewfile 重建工具鏈，只遷移確實需要的工作目錄與快取。整個複製舊使用者環境會將過期設定、絕對路徑與敏感憑證一併帶入新節點。

MIGRATION MANIFEST 環境遷移清單
原始碼 Git 複製並核對提交雜湊 不要複製包含未提交秘密的舊工作樹
系統工具 以 Brewfile 宣告式還原 還原後重新檢查版本與 PATH
專案檔案 rsync 增量傳輸 明確排除快取、日誌與憑證目錄
建置快取 依工具鏈版本選擇性遷移 版本變更時優先重新產生

使用 rsync 遷移工作目錄

先以預演模式檢查即將複製與刪除的內容，再執行正式同步。目標路徑中的刪除行為必須由操作者確認。

rsync -avhn \
  --exclude '.git' \
  --exclude 'DerivedData' \
  ./Project/ user@host:~/Project/

使用 Git 固定程式碼狀態

在來源節點記錄分支、提交雜湊與未提交變更。新節點完成複製後核對雜湊，再還原依賴，不要以壓縮檔取代版本記錄。

git status --short
git rev-parse HEAD
git clone repository-url
git checkout commit-hash

使用 Brewfile 重建工具

匯出前檢查清單，移除不再需要的軟體。還原後逐項驗證指令版本，不能只以安裝指令成功結束作為環境可用的依據。

brew bundle dump --file Brewfile
brew bundle check --file Brewfile
brew bundle install --file Brewfile
遷移前單獨核對敏感憑證

SSH 私密金鑰、儲存庫權杖、簽署資料、環境變數檔案與服務金鑰不應隨專案目錄批次複製。確認新節點具備最小權限後，透過團隊認可的安全流程重新設定。

故障最短路徑

先排除可驗證條件，再提交完整脈絡。

以下五類問題都依「確認現象、執行最小指令、記錄結果、停止無效變更」的順序處理。展開對應項目即可查看檢查清單。

無法連線 SSH 逾時、拒絕連線或金鑰驗證失敗
  1. 從目前的實例詳細資料重新複製主機位址、連接埠與使用者名稱，確認未使用舊訂單資訊。
  2. 執行 chmod 600 檢查本機私密金鑰權限，並確認指令中的金鑰路徑存在。
  3. 使用 ssh -vvv 取得連線階段資訊，但提交工單前請移除完整位址、使用者名稱與金鑰路徑中的個人資訊。
  4. 切換至另一個可信任網路重新測試，用於區分本機出口限制與節點連線問題。
  5. 工單附上訂單編號、節點、發生時間、錯誤類型與已去識別化的除錯末段。
建置失敗 xcodebuild、依賴解析或簽署階段結束
  1. 記錄提交雜湊、scheme、destination、Xcode 版本與開發者目錄。
  2. 清楚區分依賴解析失敗、編譯失敗、測試失敗、簽署失敗與封存失敗。
  3. 使用 set -o pipefail 保留真實結束代碼，並匯出 .xcresult 或完整日誌。
  4. 不要同時升級依賴、切換 Xcode 與清除所有快取；一次只變更一個變數。
  5. 工單附上首個關鍵錯誤前後的日誌，移除儲存庫權杖、簽署資料與業務資料。
磁碟空間不足 建置中斷、封存失敗或工作目錄持續增長
  1. 執行 df -h 查看磁碟區剩餘空間，再使用 du -sh 定位工作區、DerivedData、封存檔與依賴快取。
  2. 確認日誌、測試結果與歷史產物是否有明確保留週期，不要直接刪除整個使用者目錄。
  3. 清理前儲存仍需下載的建置產物，並確認沒有執行中的任務使用對應目錄。
  4. 若長期容量需求超過基礎 SSD，可在方案中評估 +1TB SSD 或 +2TB SSD 附加選項。
  5. 工單附上磁碟用量摘要、增長目錄與失敗任務時間，不要上傳專案原始檔。
網路波動 SSH 卡頓、依賴下載失敗或儲存庫連線不穩定
  1. 分別記錄本機到節點、節點到目標儲存庫或依賴來源的現象，不要將兩段鏈路混為一個結論。
  2. 連續取樣時記錄測試地點、電信商、節點、指令與樣本數量，單次 ping 不能代表持續體驗。
  3. 檢查 DNS 解析、代理環境變數、Git 遠端與套件管理器來源是否符合團隊設定。
  4. 使用另一個可信任的本機網路進行對照，避免將本機 Wi-Fi 或出口策略誤判為節點異常。
  5. 工單附上發生時間範圍、目標類型、失敗比例與已去識別化的輸出。
節點重新啟動 工作階段中斷、服務未恢復或執行器離線
  1. 先在控制台查看目前節點狀態，不要連續重複傳送電源操作。
  2. 恢復連線後執行 uptime，核對啟動時間與問題發生時間是否一致。
  3. 檢查自架執行器、GitLab Runner 或 Jenkins agent 的啟動方式與目前服務狀態。
  4. 確認建置工作區是否完整，並重新驗證未完成任務的產物，不要沿用狀態不明的封存檔。
  5. 工單附上訂單編號、節點、發生時間、重新啟動前後現象與需要恢復的服務名稱。
人工支援

一次提交足夠資訊，減少來回確認。

現有訂單、節點狀態與續租問題優先透過控制台工單提交；尚未下單的設定與使用範圍問題可傳送電子郵件。對外聯絡信箱僅為 support@oncemac.com。

SUPPORT PACKET 工單資訊包
01

訂單與節點

提供訂單編號、配置名稱與節點區域，不要提供付款憑據或完整帳單資料。

02

發生時間

註明時區、首次發生時間、最後一次重現時間，以及問題是否持續。

03

重現操作

列出執行指令、預期結果、實際結果與結束代碼，避免只寫「無法使用」。

04

已去識別化日誌

保留錯誤脈絡，移除金鑰、權杖、密碼、完整 IP、簽署資料與業務資料。

05

已完成的檢查

說明已驗證的網路、版本、路徑、磁碟與重試結果，避免重複執行無效步驟。

現有訂單

透過控制台提交工單

適合處理節點連線、建置異常、帳單、續租與訂單狀態問題。工單會關聯登入帳戶，方便核對實例脈絡。

進入控制台
售前與一般諮詢

傳送結構化電子郵件

請說明用途、目標節點、Xcode 版本、並行建置數、儲存空間需求與預計啟用時間。

support@oncemac.com
獨享實體 Mac mini 節點

需要新節點？直接選擇配置與租期。

OnceMac 提供 3 種在售配置與 6 個節點，全年 365 天正常運作。所有訂單均以美元結算，可在控制台統一管理訂單、節點與工單。

立即租用雲端 Mac 聯絡團隊