認證資訊是否對應目前節點
確認使用者名稱、金鑰或連線密碼來自目前訂單，不要重複使用已結束訂單的連線資料。檢查金鑰檔案權限，以及複製過程中是否增加空格或換行。
恢復工作流程
從連線檢查到建置日誌，依序找出問題
適用於 iOS、macOS、CI/CD 與 Apple Silicon 實驗負載的疑難排解指南。先確認節點與網路，再檢查工具鏈和工作日誌，避免同時變更多個變數。
5
級連線檢查
4
類建置故障
6
個在售節點
工作單
先保留現場，再逐項排除
READY
A01
確認節點資訊
區域、主機位址、連線方式、訂單狀態
01
A02
驗證本機路徑
DNS、連接埠、防火牆、封包遺失與抖動
02
A03
縮小工具鏈範圍
Xcode、SDK、相依項目、簽署與測試
03
A04
提交最小證據集
發生時間、重現步驟、日誌與影響範圍
04
請勿傳送密碼、私密金鑰或復原碼
SUPPORT / NODE
首次連線
四步完成首次連線
控制台會提供目前訂單對應的節點資訊。複製欄位時請保留原始格式，不要手動猜測位址、使用者名稱或連接埠。
-
01
讀取節點欄位
登入控制台，核對訂單、區域、主機位址、使用者名稱與允許的連線方式。節點位於新加坡、日本（東京）、韓國（首爾）、香港、美國東部或美國西部其中之一。
-
02
檢查本機網路
確認辦公室網路沒有封鎖目標連接埠，關閉會改寫路由的臨時代理，並分別記錄有線、無線或其他網路下的連線結果。
-
03
選擇連線方式
命令列、檔案同步和自動化工作優先使用 SSH；需要 macOS 圖形介面時使用 VNC。首次測試只建立一種連線，避免結果互相干擾。
-
04
完成基準驗證
登入後記錄系統版本、磁碟可用空間、Xcode 路徑與目前網路時間。先執行最小專案，再遷移完整工程和建置快取。
首次登入只驗證基礎連線
在確認連線穩定前，不要批次上傳專案、修改系統設定或註冊 CI runner。先保留一組可重現的基準結果。
連線診斷
依固定順序排查 SSH 與 VNC
連線失敗時，從身分資訊逐步檢查至網路外層。每一步只變更一個條件，並保留命令輸出或錯誤提示。
連接埠能否從本機連達
使用控制台顯示的連接埠執行連通性測試。逾時通常表示網路路徑有問題；立即拒絕通常表示目標可達，但服務或連接埠不匹配。
本機防火牆是否封鎖
檢查終端機安全軟體、企業出口政策與路由器規則。改用另一個已知可用的網路重新測試，可快速區分本機限制與節點端問題。
網路路徑是否穩定
記錄延遲、抖動與封包遺失，不要只看一次 ping。VNC 對持續抖動更敏感，SSH 建置也可能因下載連線重設而中斷。
節點狀態是否正常
返回控制台核對執行個體與訂單狀態。若不同網路均無法連線且認證資訊無誤，保留發生時間與錯誤原文後提交節點異常工單。
工具鏈核對
Xcode 問題先檢查版本選擇，再檢查工程
同一個提交在不同工具鏈下可能產生不同結果。將系統環境與專案相依項目分開驗證，才能判斷故障屬於節點、工具鏈或儲存庫設定。
版本與路徑
- 執行
xcodebuild -version，記錄 Xcode 與建置版本。 - 執行
xcode-select -p，確認 Command Line Tools 指向預期目錄。 - 檢查腳本中是否寫死舊版 Xcode 路徑。
SDK 與相依項目
- 確認 scheme、destination 與 SDK 名稱存在。
- 重新解析 Swift Package、CocoaPods 或其他專案相依項目。
- 比較鎖定檔、相依項目來源與下載失敗時的具體位址類型。
簽署環境
- 核對建置設定讀取的簽署變數是否存在。
- 確認 CI 程序能存取所需材料，且不會將內容寫入日誌。
- 將簽署失敗與編譯失敗分開重新執行，並記錄結束代碼。
BASELINE
建議的最小環境快照
sw_vers
xcodebuild -version
xcode-select -p
df -h
自動化接入
將 self-hosted runner 視為受控執行器
runner 註冊成功不代表工作流程已能安全重現。執行範圍、工作目錄、認證資訊與並行策略需要同時落實。
註冊並標記執行器
使用專案或組織提供的短期註冊資訊，設定能表達晶片、區域和用途的標籤。註冊完成後刪除本機暫存命令記錄。
交付物：runner 名稱與標籤清單限制可執行範圍
只允許受信任的儲存庫、受保護分支與明確工作流程呼叫節點。外部貢獻觸發的工作應經過審核，不讓未知腳本直接取得節點權限。
交付物：儲存庫與分支授權規則清理工作目錄
在工作前後處理暫存檔案、衍生資料與無效快取。保留快取時記錄鍵名、來源與失效條件，避免舊產物污染新建置。
交付物：清理腳本與快取策略輪換存取認證資訊
權杖、SSH 金鑰與簽署材料應納入受控金鑰流程。成員離開團隊、儲存庫權限變更或出現異常日誌後，立即撤銷並重新簽發。
交付物：認證資訊負責人與輪換記錄
日誌分流
從第一條有效錯誤判斷建置故障類型
不要只截取日誌末尾的通用結束代碼。保存完整日誌，在首次出現錯誤的位置向上讀取目標、命令與相依項目背景。
| 故障類別 | 常見日誌訊號 | 先檢查 | 工單應附內容 |
|---|---|---|---|
| 相依項目解析 | 套件版本衝突、儲存庫擷取失敗、鎖定檔不一致 | 鎖定檔、相依項目來源、快取鍵與網路下載結果 | 相依管理方式、失敗套件名稱、第一段錯誤 |
| 簽署設定 | 憑證匹配失敗、權限無法使用、設定變數缺失 | scheme、建置設定與金鑰注入流程 | 去識別化後的錯誤原文與建置目標 |
| 測試失敗 | 斷言失敗、模擬環境差異、測試逾時 | 失敗案例、destination、平行參數與重試結果 | 案例名稱、結束代碼、可重現命令 |
| 網路下載 | 連線重設、解析失敗、下載逾時 | 對同一位址重複請求、DNS、代理與出口路徑 | 發生時間、目標類型與網路測試結果 |
01
保留完整原始日誌
02
定位第一條有效錯誤
03
使用最小命令獨立重現
04
刪除認證資訊後提交節錄
資料操作
分開管理專案、快取與附加 SSD
增加容量不能取代資料分類與備份。先定義哪些內容必須保留，再決定同步、快取與遷出的方式。
專案同步
優先透過版本庫同步原始碼，將大型二進位檔與私有相依項目納入受控儲存流程。首次遷移後比較提交雜湊、子模組與鎖定檔。
- 分開核對原始碼與設定
- 記錄大型檔案的同步方式
- 遷移後執行最小建置
快取清理
DerivedData、套件快取和 runner 工作目錄都可能影響重現。刪除前記錄目錄大小與快取鍵，清理後比較建置時間和錯誤變化。
- 先測試磁碟可用空間
- 只清理可重新產生的內容
- 避免並行工作同時修改快取
附加 SSD 使用邊界
附加 SSD 適合需要更多工作空間的工程、快取或資料集。掛載點、讀寫路徑與工作權限應在投入正式工作前確認。
- 明確資料儲存位置
- 監控增長速度與剩餘容量
- 遷出前驗證檔案完整性
遷移前由使用者保留必要副本
專案資料、簽署材料、認證資訊和建置產物應依團隊策略備份。租期結束前完成遷出並驗證副本可讀取，不要將節點上的單一副本視為長期封存。
工單證據集
一次提交即可提供足以開始排查的資訊
支援請求越具體，就越容易直接進入重現與定位。先說明影響，再提供時間線和最小日誌，不要傳送任何秘密值。
請求範本
複製欄位並填寫事實
CASE
- 節點區域
- 新加坡、日本（東京）、韓國（首爾）、香港、美國東部或美國西部
- 發生時間
- 註明當地時間和時區，並說明問題是持續發生還是間歇出現
- 重現步驟
- 從登入、執行命令到出現錯誤，依實際順序列出
- 日誌節錄
- 包含第一條有效錯誤、結束代碼與前後必要背景資訊
- 影響範圍
- 單一工作、單一成員、全部建置或整個節點連線
- 已完成的檢查
- 列出更換網路、重試命令、清理快取等已執行動作及結果
請勿提交以下內容
密碼、私密金鑰、復原碼、完整權杖、簽署材料以及完整付款憑據。若日誌包含秘密值，請先刪除或替換為明確的去識別化標記。
關聯現有訂單
登入控制台建立工單並選擇對應訂單，有助於支援人員核對正確的節點與服務記錄。
登入控制台建立工單
升級流程
依問題類型進入對應處理佇列
連線中斷、節點異常和帳務疑問需要不同證據。選擇正確分類並在同一個工作階段補充材料，避免背景資訊被拆散。
認證資訊正確但無法建立 SSH 或 VNC
附上本機網路類型、目標連接埠測試、錯誤原文與發生時間。若改用另一個網路後恢復，也應說明兩次測試的差異。
分類：連線與存取多個工作同時失敗或節點狀態異常
說明影響範圍、最後一次正常時間、執行個體狀態和最小重現命令。不要透過連續重新啟動或批次修改設定覆蓋原始現場。
分類：節點執行訂單週期、附加項目或付款記錄需要核對
提供訂單識別碼、帳務週期、相關附加項目與問題描述。所有訂單均以美元（USD）結算，請勿在工單中傳送完整付款憑據。
分類：訂單與帳務
在同一工作階段持續追蹤
進入控制台追蹤工單
處理進度、補充問題與最終結論均在控制台對應工單中更新。補充新日誌時標明擷取時間和本次變更，方便比較前後結果。
準備好節點資訊，開始可重現的疑難排解
新訂單可直接選擇兩種方案與六個節點；現有訂單問題請登入控制台提交關聯工單。