確認裝置狀態
先登入控制台查看執行個體是否處於可用狀態，並核對訂單對應的裝置名稱與節點。若控制台顯示裝置可用但兩種連線方式都失敗，請繼續檢查網路；不要先變更系統設定。
- 核對訂單編號、裝置識別碼與節點。
- 確認不是連線到舊記錄中的位址。
- 記錄控制台顯示的狀態與檢查時間。
從現象開始排查
先定位問題，再執行下一步
輸入錯誤訊息、工具名稱或連線方式。頁面不只提供概念說明，還會依序列出裝置狀態、日誌位置、驗證指令，以及升級人工支援所需的資料。
快速分流
依目前現象選擇檢查路徑
先選擇最接近的現象，再依頁面順序檢查。尚未確認網路與磁碟狀態前，不要直接重新安裝 Xcode、相依套件或 Runner。
首次連線
無法連線裝置時，依五個檢查點縮小範圍
連線問題通常發生在狀態、認證資訊、網路或用戶端設定的其中一層。依序檢查可避免將網路故障誤判為裝置故障。
核對存取憑證
區分系統使用者名稱、初始密碼與 SSH 金鑰。複製憑證時檢查前後空白；金鑰驗證失敗時，先確認使用正確的私鑰與使用者名稱，不要連續嘗試不同組合。
- 確認使用者名稱的大小寫與輸入法狀態。
- 檢查私鑰檔案權限是否過於寬鬆。
- 憑證異常時，請在控制台提交支援請求。
驗證本機網路
切換至另一個可信任網路重新測試，並暫時排除公司 Proxy、VPN、出口防火牆與安全軟體規則。記錄目標位址、連接埠、發生時間與逾時文字。
- 分別測試網域名稱解析與目標連接埠。
- 比較家用網路與公司網路的結果。
- 不要只提交「連線失敗」四個字。
檢查遠端桌面
確認用戶端儲存的位址、使用者名稱與顯示設定仍對應目前裝置。若畫面可以開啟但輸入延遲，先降低解析度與色彩品質，再檢查本機網路抖動。
- 刪除用戶端中的舊連線記錄後重新建立。
- 擷取錯誤文字，不要提交敏感憑證。
- 比較 SSH 是否能獨立連線。
檢查 SSH 設定
使用詳細輸出確認失敗發生在解析、交握還是驗證階段。若能完成交握但驗證失敗，請重點檢查使用者名稱、私鑰與授權檔案；若連線直接逾時，請回到網路路徑檢查。
ssh -vvv user@host
chmod 600 ~/.ssh/id_ed25519
ssh-add -l
安全界線
支援請求中不要提交密碼、私鑰、復原碼、完整付款憑證或未去識別化的憑證。需要展示設定時，只保留與故障相關的欄位。
Xcode 與簽署
分開驗證版本、簽署與封存問題
不要用一次完整的發佈工作同時驗證所有環節。先確認工具鏈版本，再用測試專案驗證簽署，最後回到實際專案查看封存日誌。
檢查項目
驗證結果
XCODE
版本與命令列工具一致
確認圖形介面選取的版本、命令列路徑與專案要求一致。切換版本後，重新開啟終端機與建置程序。
xcode-select -p
CERT
目前使用者可讀取憑證
確認所需憑證及其私鑰已完整匯入，並能在目前登入工作階段中存取。不要只看到憑證名稱就判定匯入成功。
security find-identity -v -p codesigning
PROFILE
佈建描述檔與目標相符
核對 App 識別碼、團隊、功能與有效範圍。清理舊佈建描述檔前先保存清單，避免無法復原。
~/Library/MobileDevice/Provisioning Profiles
KEYCHAIN
非互動式工作具備存取權限
圖形介面可以封存但 CI 失敗時，請重點檢查 Runner 工作階段使用的 Keychain、解鎖流程與存取控制。
security list-keychains
ARCHIVE
保留第一個根因錯誤
從封存日誌中找出最早出現的失敗，不要只複製最後的摘要。記錄目標、設定、SDK 與執行指令。
xcodebuild -showBuildSettings
CI/CD 故障手冊
工作未執行時，先檢查 Runner，再檢查工作本身
持續整合故障需要拆分為排程、執行環境、資源與腳本四個層面。直接重複執行只會覆蓋現場日誌，無法證明問題已復原。
| 現象 | 優先檢查 | 處理順序 | 復原標準 |
|---|---|---|---|
| Runner 離線 | 程序、網路、註冊資訊、執行使用者 | 確認裝置可連線後，再讀取服務日誌；核對註冊範圍與啟動使用者，不要先重新註冊。 | Runner 持續線上，並成功取得一個最小測試工作。 |
| 工作長時間排隊 | 標籤、並行上限、現有工作 | 確認工作標籤能與 Runner 相符；檢查是否存在未結束程序或已被佔用的執行槽。 | 新工作能在預期佇列中被取得，舊工作的結束狀態明確。 |
| 快取復原失敗 | 快取金鑰、目錄權限、剩餘磁碟空間 | 比較成功與失敗工作的快取金鑰；驗證目錄擁有者，再清理可重建的快取。 | 相依套件復原完成，且下一個工作能依相同快取規則重複使用快取。 |
| 腳本權限錯誤 | 執行權限、直譯器、工作目錄 | 確認腳本已加入儲存庫並保留執行權限；檢查第一行直譯器與相對路徑。 | 腳本可在 Runner 使用者的非互動式工作階段中成功執行。 |
| 建置逾時 | 最後活動階段、CPU、記憶體、磁碟 | 先找出最後一筆有效日誌，再判斷是程序阻塞、資源不足，還是等待網路相依項目。 | 相同提交連續完成，耗時接近基準且沒有遺留程序。 |
RUNNER BASELINE
保留一個最小健康檢查工作
健康檢查只驗證工作目錄、磁碟、工具鏈路徑與一個短測試。不應包含發佈憑證，也不應依賴大型快取。
whoami
pwd
df -h
xcodebuild -version
git --version效能與儲存空間
用三組證據判斷工作變慢的原因
單次工作變慢不足以判斷需要更高規格。至少同時查看活動監視器、磁碟容量與建置日誌，並與同一專案的正常基準比較。
CPU 與記憶體
觀察整個工作週期，而不是只看某一秒。CPU 長時間滿載且工作持續推進，屬於計算負載；記憶體壓力持續升高並伴隨大量交換，才表示並行數或專案規模可能超出目前規格。
- 記錄
- 峰值、持續時間、並行工作數
- 排除
- 遺留模擬器、未結束的編譯程序
磁碟與快取
先統計專案、相依套件、模擬器、封存檔與可重建快取的用量。磁碟接近容量上限時，相依套件解壓縮、封存與日誌寫入都可能異常。清理前應區分產出物與可重建資料。
- 檢查
- DerivedData、封存檔、模擬器、套件快取
- 驗證
- 清理後重新執行相同提交
建置日誌與工具鏈
若資源曲線正常，但工作停在相同腳本、相依套件下載或編譯階段，應檢查版本變更、網路相依項目與腳本等待條件。比較成功日誌比只查看總耗時更快找到偏移點。
- 比較
- 相同提交、相同工具鏈、相同指令
- 定位
- 第一個明顯偏離基準的階段
A
資源持續飽和
降低並行數重新測試；若耗時隨並行數穩定變化，再評估更高規格。
B
磁碟接近容量上限
清理可重建快取、封存舊產出物，並建立工作完成後的清理規則。
C
資源正常但階段卡住
檢查腳本、相依套件來源、工具鏈版本與非互動式權限。
節點與網路
四個在售節點，使用同一套網路記錄格式
NUMACS 提供新加坡、日本（東京）、韓國（首爾）與香港節點。所有目錄組合均可訂購，實際可用狀態以控制台即時回傳為準。
SG充足
新加坡
適合從東南亞及周邊網路存取。診斷時記錄本地電信業者、目標位址、連線方式與發生時間。
選擇新加坡節點JP充足
日本（東京）
連線異常時分別測試遠端桌面與 SSH，並註明問題是否只出現在特定本地網路。
選擇日本節點KR充足
韓國（首爾）
提交網路問題時，附上逾時或斷線時段，以及同一裝置在另一個網路下的重新測試結果。
選擇韓國節點HK充足
香港
若互動延遲突然變化，記錄目標位址、使用協定、用戶端版本與當時正在執行的工作。
選擇香港節點
網路工單記錄
一份可複核的網路報告應包含哪些內容
請同時提供發生時間與時區、所在節點、目標位址、使用協定、本地網路類型、完整錯誤文字，以及更換網路後的重新測試結果。若執行診斷指令，請提交已去識別化的文字結果，不要只提交截圖中的局部數字。
- 時間：精確到分鐘並註明時區
- 路徑：本地網路、目標位址與連接埠
- 結果：逾時、拒絕、驗證失敗或斷線
- 對照：另一個網路或另一種連線方式的結果
帳單與週期
先核對訂單週期，再核對付款記錄
裝置支援按日、週、月或季租用。訂單金額統一以美元（USD）結算，週期與規格以訂單記錄為準。
按日
適合短期驗證、臨時建置或移轉演練。提交帳單問題時，註明訂單開始時間與裝置識別碼。
按週
適合一段連續衝刺或版本驗收。核對時不要將自然週與訂單實際週期混為一談。
按月
適合穩定開發與持續整合工作流程。升級規格前，先匯出必要資料並確認移轉安排。
按季
適合持續專案與固定 Runner。團隊應提前記錄憑證輪替、備份與工作交接流程。
提交前複核
避免讓排查回到原點
以下資訊決定支援人員能否直接開始重現與定位，而不是先來回補充基礎資料。
遠端桌面和 SSH 都失敗，應先提交哪些資料？
先確認控制台中的裝置狀態，再提交訂單編號、節點、發生時間與時區、目標位址、兩種連線方式的完整錯誤文字，以及更換本地網路後的重新測試結果。不要提交密碼或私鑰。
Xcode 建置失敗後，是否應立即重新安裝工具鏈？
不建議。先保存第一個根因錯誤、Xcode 版本、命令列工具路徑、專案設定與最近變更。重新安裝會改變現場狀態，也可能刪除可用來定位問題的版本差異與日誌。
Runner 離線時，重新註冊是不是最快的方法？
先檢查裝置連線、Runner 程序、執行使用者與服務日誌。只有確認註冊資訊損壞或已失效後，才重新註冊。否則新舊 Runner 記錄可能同時存在，讓排程問題更難判斷。
日誌應如何去識別化？
保留時間、指令、錯誤碼、工具版本與和故障相關的路徑結構；替換使用者名稱、儲存庫位址、存取權杖、憑證內容、私鑰與業務資料。去識別化後重新閱讀一次，確認上下文仍足以重現問題。
如何讓緊急建置故障更快進入排查？
在主旨中註明建置故障，並提供訂單編號、節點、發生時間、可重現步驟、預期結果、實際結果與已去識別化的日誌。請求會依資訊完整度排隊處理；上下文越完整，就越能減少補充確認。