連線問題
SSH 或圖形桌面無法進入
從位址、連接埠、金鑰權限、主機指紋與憑證有效性開始。能連上 SSH 但圖形工作階段異常時，再檢查解析度、鎖定狀態與工作階段恢復。
節點執行支援
先定位故障層級，再執行下一個指令
這裡集中整理獨享 Apple Silicon 實體節點的連線、建置、執行器、網路與儲存排查路徑。每個步驟都列出檢查對象、指令，以及可用來判斷下一步的回傳結果。
已有節點時，請先記錄節點編號與問題發生的時間範圍；尚未訂購時，可先查看三種在售配置與四個可選節點。
RUNBOOK / NODE CHECK
L0—L4
L0
節點狀態
核對節點編號、區域與控制台回傳狀態
先確認
L1
連線鏈路
位址、連接埠、金鑰權限與主機指紋
SSH
L2
工具鏈
Xcode、簽署材料、Keychain 與建置記錄
BUILD
L3
工作執行
執行器程序、工作目錄、快取與並行工作
CI
L4
硬體路徑
磁碟剩餘空間、外接 SSD、網路與 Thunderbolt 5
I/O
工單最少資訊集
節點編號 + 時間範圍 + 指令輸出
選擇排查入口
依故障發生位置分流
不要同時修改多個層面的設定。先選擇最接近現象的類別，完成其中的基本檢查，再帶著結果進入下一層。
SSH 快速診斷
從本機權限與握手程序開始
連線失敗不一定代表節點離線。先區分位址錯誤、連接埠無法連線、本機金鑰權限不合規、主機指紋變更，以及伺服器拒絕驗證。
連線檢查指令
SSH / VERBOSE
$ chmod 600 ~/.ssh/orbvps_node
$ ssh-keygen -F node-address
$ nc -vz node-address 22
$ ssh -vvv -p 22 \
-i ~/.ssh/orbvps_node \
node-user@node-address
Permission denied
驗證材料不相符
確認使用者名稱與私鑰對應目前節點，並檢查本機 SSH 設定中的其他 IdentityFile 是否覆寫了該金鑰。
Connection timed out
尚未建立連線
核對控制台顯示的位址與連接埠，暫時停用本機代理規則後重新測試，並記錄發生時間與所在網路。
Connection refused
目標可連線但連接埠未接受連線
保留完整的 verbose 輸出，不要反覆刪除主機記錄；先確認連接埠是否與節點交付資訊一致。
REMOTE HOST IDENTIFICATION
主機指紋與本機記錄不同
不要直接忽略警告。先將顯示的指紋與控制台交付記錄核對，確認節點資訊後再更新本機記錄。
核對連線參數
從控制台重新讀取位址、連接埠與使用者名稱，不要使用舊終端機歷程中的位址猜測。
收緊金鑰權限
私鑰建議僅限目前使用者讀寫，SSH 設定與上層目錄也不應允許無關使用者修改。
保存握手輸出
使用 verbose 模式重試一次，保留從開始連線到失敗位置的完整輸出，並將位址去識別化。
圖形桌面連線
依憑證、顯示、鎖定、重新連線的順序處理
圖形工作階段與 SSH 是兩條不同的連線路徑。SSH 正常不代表圖形工作階段設定一定正常，因此需要分別記錄現象。
確認憑證歸屬
僅使用目前節點交付的圖形工作階段憑證。憑證輪換後，清除用戶端儲存的舊密碼，避免舊記錄持續自動重試。
降低首次連線解析度
黑畫面或畫面停滯時，先以較低解析度及單一顯示器連線。進入桌面後再逐步提高尺寸，確認問題是否與顯示參數有關。
檢查工作階段鎖定狀態
若看得到鎖定畫面但無法繼續，先驗證鍵盤輸入與焦點，再透過 SSH 檢查系統負載與磁碟剩餘空間。
中斷後重新建立工作階段
先主動關閉用戶端連線，等待工作階段釋放後再重新連線。不要連續快速建立多個並行圖形工作階段，以免混淆目前使用的桌面。
需要支援時記錄兩組結果
說明 SSH 是否正常、圖形用戶端停在哪個步驟、使用的解析度、用戶端錯誤原文，以及最近一次正常連線的時間範圍。請勿提交完整存取密碼。
Xcode 與簽署
固定工具鏈，再縮小簽署失敗範圍
先確認實際使用的 Xcode 路徑與版本，再檢查可用簽署身分、描述檔、Keychain 存取權與專案快取。不要在同一次排查中同時升級相依套件與更換簽署材料。
確認 Xcode 與命令列工具
- 保存
xcodebuild -version的完整結果。 - 使用
xcode-select -p核對目前的 Developer 目錄。 - 確認流水線與互動式終端機使用相同的環境變數。
分開檢查身分與描述檔
- 列出目前可用於程式碼簽署的身分及其有效狀態。
- 核對描述檔的 App ID、團隊與有效期限。
- 確認建置程序能讀取對應的 Keychain，而不只是目前桌面使用者可見。
建立可重現的乾淨基準
- 先保存失敗記錄，再清理目標專案對應的 DerivedData。
- 使用相同的 scheme、configuration 與 destination 重新執行。
- 封存原始
.xcresult，不要只提交終端機最後幾行。
簽署與版本檢查
XCODE / CODESIGN
$ xcode-select -p
$ xcodebuild -version
$ security find-identity \
-v -p codesigning
$ profiles show \
-type provisioning
$ xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Release \
-resultBundlePath Build.xcresult \
build
記錄範圍
保留指令、scheme、configuration、失敗目標、第一個 error 及其上下文。提交前移除儲存庫憑證、權杖與業務資料。
CI/CD 執行器
確認工作究竟停在程序、目錄還是資源層
self-hosted runner 顯示在線上不代表工作環境完整。檢查執行器程序、工作目錄權限、快取用量、並行工作，以及重新啟動後的自動恢復路徑。
程序狀態
確認執行器服務仍以預期使用者執行，啟動參數指向正確設定。若程序反覆結束，先保存結束碼與最近的記錄。
ps aux | grep -i runner
工作目錄
檢查目錄擁有者、剩餘空間與舊工作鎖定檔。不要直接刪除仍被執行中工作使用的工作目錄。
df -h && du -sh ./work
快取策略
區分相依套件快取、DerivedData 與建置產物。先定位異常快取索引，再清理單一專案，避免一次清空所有可重用內容。
du -sh ~/Library/Developer/Xcode/DerivedData
並行與恢復
核對是否有多個工作競爭同一個 Keychain、模擬器或工作目錄。重新啟動後先執行一項受控測試工作，再恢復正常佇列。
uptime && sysctl -n hw.memsize
恢復順序
暫停新工作 → 保存記錄 → 結束異常程序 → 驗證目錄 → 啟動執行器 → 執行單一工作測試
如果測試工作成功但並行工作失敗，請同時提供並行數量、工作標籤與共用資源清單。
網路與儲存
分開驗證連線品質、磁碟容量與裝置識別
吞吐量下降、建置變慢與外接磁碟區消失可能呈現相似現象。先擷取系統內建診斷結果，再判斷問題屬於網路、檔案系統或外接裝置路徑。
網路
驗證基本連線品質
使用系統內建的網路品質工具記錄上下載能力與回應性，同時記錄測試時間範圍。跨區域結果會受到本地電信業者與路徑影響。
networkQuality -v
route -n get default
ifconfig
內部儲存
檢查容量與磁碟區狀態
先確認系統磁碟區與資料磁碟區的剩餘空間，再找出佔用最大的工作目錄。建置失敗時尤其要檢查暫存目錄與 DerivedData。
df -h
diskutil list
du -sh ~/Library/Developer/*
外接裝置
確認 SSD 與 Thunderbolt 5 路徑
分別檢查磁碟清單與 Thunderbolt 裝置樹。裝置可見但磁碟區未掛載時，先擷取狀態，不要立即抹除或重新分割。
diskutil list external
system_profiler SPThunderboltDataType
diskutil info /Volumes/VolumeName升級與執行變更
先保留回復基準，再安排重新啟動驗證
OrbVPS 節點全年 365 天正常運作。涉及系統升級、工具鏈切換或需要重新啟動的操作，請由使用者依工作負載自行安排；若基礎設施出現必須處理的緊急變更，相關資訊將記錄於控制台。
建立變更清單
記錄目前的 macOS、Xcode、執行器版本、關鍵相依套件與可回復的建置記錄，不要在沒有基準的情況下直接覆蓋工具鏈。
完成資料備份
備份儲存庫、簽署材料、執行器設定、快取策略與必要建置產物，並在獨立位置驗證備份可讀取。
安排使用者端重新啟動時段
暫停新工作，等待執行中的工作完成，保存記錄後再重新啟動。重新啟動期間不要同時修改網路、簽署與建置設定。
執行恢復驗證
依序驗證 SSH、圖形桌面、磁碟掛載、Xcode 版本與一項受控建置工作，再恢復正常並行佇列。