雲端 Mac 說明中心與疑難排解指南

依問題類型進入

先選擇範圍，再執行最短檢查路徑

五類入口對應訂單生命週期中的不同環節。切換分類後會顯示建議優先確認的資訊、常見原因與下一步處理方向。

訂單生命週期

訂購與交付

適合處理付款結果待確認、節點資訊尚未顯示、區域或機型核對，以及首次連線資料確認等問題。

確認控制台中的訂單編號、機型、租期與區域是否與提交內容一致。
付款確認後，系統會依序執行節點配置、健康檢查與連線資訊產生，典型流程約 4 分鐘。
超過典型時間仍未取得連線資料時，請勿重複建立訂單；記錄訂單編號並提交工單。

快速診斷

五類常見故障的初步檢查

每張卡片依照「先確認狀態、再縮小變數、最後保留證據」的順序排列。一次只變更一個變數，才能判斷是哪個步驟恢復了服務。

無法連線至節點

在控制台確認節點處於正常執行狀態。
逐項核對位址、連接埠、使用者名稱與連線協定。
從另一個網路測試相同連接埠，排除本機出口或防火牆限制。
記錄用戶端錯誤原文與發生時間，請勿連續嘗試大量密碼。

查看遠端存取指南

建置突然失敗

記錄失敗的提交、建置命令、退出碼與第一個有效錯誤。
執行 xcodebuild -version 確認目前工具鏈。
檢查相依套件鎖定檔、環境變數與簽署資產是否發生變更。
僅在確認快取異常後清除對應快取，避免一開始就刪除全部證據。

前往 Xcode 疑難排解步驟

磁碟空間不足

使用 df -h 查看磁碟區容量，請勿只查看單一目錄。
檢查 DerivedData、封存檔、模擬器資料與套件管理器快取。
先刪除可重新建立的內容，再處理建置產物與專案檔案。
持續成長的目錄應加入流水線清理規則，並設定容量監控。

查看安全清理順序

憑證失效

確認失效的是系統登入、SSH 金鑰、儲存庫權杖，還是簽署權限。
確認憑證有效期限、檔案權限及使用該憑證的使用者身分。
輪替憑證後同步更新流水線變數，並撤銷舊值。
請勿將完整憑證貼到命令歷程記錄、螢幕截圖或工單內容中。

查看安全與權限說明

網路延遲或抖動

記錄本機城市、電信業者、節點區域與問題發生時間。
連續測試多次並取中位數，請勿根據單次峰值下結論。
分別檢查互動延遲、封包遺失與大型檔案傳輸吞吐量。
關閉非必要的音訊、視訊與高色彩品質，再比較 VNC 使用體驗。

查看連線最佳化方法

核心術語

了解節點、連線與建置脈絡

以下定義採用本服務中的實際含義。提交工單時使用一致術語，有助於減少反覆確認問題範圍。

實體節點: 實際執行工作負載的獨立 Mac mini 裝置。它具備明確的晶片、記憶體、儲存空間與所在區域，不是共用運算執行個體。
獨享: 租期內，該節點的運算資源由目前訂單使用，不會與其他客戶的工作負載混合排程，效能與環境邊界更清楚。
VNC: 用於存取 macOS 圖形介面的遠端顯示協定。適合需要桌面操作、查看 Xcode 介面或調整系統設定的工作。
SSH: 用於加密命令列連線的協定。適合執行指令碼、傳輸檔案、管理 runner，以及排查不需要圖形介面的問題。
self-hosted runner: 由團隊自行管理並接入程式碼託管流水線的執行器。工作會在指定的雲端 Mac 上執行，工具鏈、快取與並行策略由團隊控制。
程式碼簽署: 使用憑證、私密金鑰與描述檔確認應用程式來源及授權範圍的流程。相關資產應限制權限、定期輪替，並避免寫入儲存庫。
建置快取: 用於重複使用相依套件、編譯中間結果或工具下載內容的資料。它能縮短建置時間，但錯誤或過期的快取也可能造成不一致。
節點區域: Mac mini 所在的資料中心區域。目前目錄涵蓋新加坡、日本（東京）、韓國（首爾）、香港、美國東部與美國西部 6 個區域。

交付與憑證

從訂單確認到首次安全登入

典型交付約 4 分鐘，由四個連續步驟組成。實際可用狀態與連線資料以控制台即時回傳為準。

01

訂單與付款確認
約 1 分鐘

核對機型、租期、節點區域與附加項目。付款結果確認後，訂單便會進入配置流程；請勿透過重複付款嘗試加快處理。
應保存：訂單編號、付款結果識別碼、提交時間。
02

節點配置
約 1 分鐘

系統會依照訂單目錄配置獨立的 Mac mini 實體節點。兩種機型均可選擇新加坡、日本（東京）、韓國（首爾）、香港、美國東部與美國西部。
應核對：節點 ID、機型、區域。
03

節點健康檢查
約 1 分鐘

交付前檢查系統啟動、網路連線與遠端存取服務。所有節點全年 365 天持續正常運作。
請等待：控制台狀態變更為可連線。
04

連線資訊送達
約 1 分鐘

控制台會提供位址、連接埠、使用者名稱與臨時憑證。首次登入後請立即更新臨時密碼、設定獨立 SSH 金鑰，並將憑證儲存在受控的金鑰管理工具中。
應完成：首次登入、密碼更新、SSH 金鑰驗證。

憑證界線

請勿在螢幕截圖、儲存庫、建置日誌或工單中提交私密金鑰、完整密碼或完整存取權杖。需要說明憑證類型時，僅提供用途、建立時間與末尾少量字元。

Xcode 疑難排解路徑

從版本基準定位到可重現日誌

請勿一開始就清空所有快取或重新安裝工具鏈。先確認版本與路徑，再檢查簽署資產，最後執行範圍明確的清理。

01

確認 Xcode 與 macOS 版本

記錄圖形介面顯示的版本，同時以流水線使用者身分執行命令。若本機互動式建置成功、runner 失敗，還需比較兩者的執行使用者與環境變數。

xcodebuild -version
sw_vers
whoami

02

確認命令列工具選擇

使用 xcode-select -p 檢查目前開發者目錄。團隊平行維護多個版本時，應在流水線啟動階段明確選擇路徑，避免系統預設值變更。

xcode-select -p
xcrun --find xcodebuild
xcrun xcodebuild -version

03

檢查憑證與描述檔

確認簽署憑證尚未過期、建置使用者可以讀取私密金鑰，且描述檔與目標識別碼相符。自動簽署失敗時，應先保留原始錯誤，再檢查鑰匙圈權限與流水線變數。

security find-identity -v -p codesigning
ls -la ~/Library/MobileDevice/Provisioning\ Profiles

04

依範圍清理 DerivedData

優先刪除目前專案對應的目錄，而不是直接清空所有專案快取。清理前記錄磁碟使用量與失敗日誌，以便判斷問題是否確實由快取造成。

du -sh ~/Library/Developer/Xcode/DerivedData
find ~/Library/Developer/Xcode/DerivedData -maxdepth 1 -type d

05

收集 xcodebuild 日誌

保留完整命令、退出碼與第一個有效錯誤。提交工單前移除儲存庫權杖、簽署秘密、使用者路徑與內部位址，但請勿只截取最後一行。

set -o pipefail
xcodebuild test 2>&1 | tee build.log
printf "exit=%s\n" "$?"

服務請求規範

讓支援工程師能夠直接重現

完整請求不代表要上傳所有資料。目標是提供清楚的時間線、受影響範圍與經過去識別化的技術證據。

工單內容建議結構

節點 ID: 從控制台複製準確識別碼，請勿以自訂裝置暱稱取代。
發生時間: 註明日期、時區、開始時間與最近一次正常運作時間。
節點區域: 填寫訂單中的區域，請勿只填寫本機所在城市。
影響範圍: 說明受影響的是單一命令、一條流水線、所有連線，還是整個團隊。
重現步驟: 依實際執行順序列出命令、輸入、預期結果與實際結果。
已完成的檢查: 逐項寫明操作及結果，避免只寫「都試過了」。

日誌去識別化規則

將存取權杖、密碼與私密金鑰內容替換為明確的去識別化標記。
儲存庫位址可保留平台類型，但請移除組織名稱、專案名稱與驗證參數。
使用者目錄可替換為通用路徑，但請保留相對目錄層級。
憑證問題可提供名稱、有效期限與錯誤資訊，但請勿提交私密金鑰。
付款問題可提供訂單編號與結果識別碼，但請勿提交完整付款資訊。
截圖前請檢查終端機歷程、選單列、檔案名稱與通知內容。

禁止上傳

私密金鑰、完整登入憑證、完整存取權杖、未去識別化的環境變數，以及包含敏感參數的設定檔。

什麼時候應跳過自行檢查並立即提交工單？

出現異常憑證活動、主機指紋意外變更、節點狀態與實際連線能力明顯不一致，或操作可能進一步破壞證據時，應停止重複嘗試，立即提交控制台工單。

為什麼節點操作需要驗證訂單歸屬？

重設存取權、調整節點狀態或處理敏感設定可能影響獨享實體機。支援團隊需要核對登入工作階段、訂單編號與授權關係，避免未授權人員要求執行節點層級操作。

連線與建置同時失敗，應提交一張還是多張工單？

若兩者在同一時間發生，且可能由相同節點狀態引起，可在一張工單中分別列出連線與建置證據。若發生時間、節點或責任範圍不同，應分開提交，以便獨立追蹤。

升級支援

攜帶診斷結果提交可追蹤的請求

現有訂單、節點連線、建置故障與帳單問題，請優先透過控制台工單提交。售前評估、團隊部署與安全報告可透過聯絡頁面使用 support@hexvm.com。涉及節點操作時，需要完成訂單歸屬驗證。

前往控制台提交工單查看聯絡團隊方式閱讀遠端存取指南

雲端 Mac 說明中心