專案與設定
原始檔案與自動化設定應保留在團隊自己的版本控制與備份流程中。雲端 Mac 上的工作副本不應成為唯一版本。
工程排查指南
雲端 Mac 發生問題，先依順序縮小範圍
這裡集中處理首次連線、macOS 使用、Xcode 建置、MLX 推論、儲存擴充與訂單問題。先完成對應檢查，再提交訂單識別碼、發生時間與去識別化日誌，支援團隊就能減少重複確認。
- 支援範圍
- 6 類問題
- 在售配置
- 3 種機型
- 服務節點
- 4 個節點
排查分流
先定位層級，再收集證據
可提交工單
A
連線前
入口層
核對交付狀態、節點、連線資料與本地網路。
B
執行中
執行層
依版本、相依套件、磁碟、記憶體與日誌逐項排除。
C
提交前
證據層
保留時間軸與重現步驟，移除密碼、私鑰與敏感內容。
建議資料
訂單識別碼 + 機型 + 節點 + 時間 + 去識別化日誌
從問題所在環節開始檢查
六類入口同時可見。選擇最接近目前現象的一類，不要把連線失敗、建置錯誤和訂單問題混在同一段描述中。
下單前自我檢查
先說清楚用途、配置與連線條件
如果尚未建立訂單，先完成這六項。用途和資源界線越明確，越容易在三種在售配置中做出判斷，也能避免把儲存容量、網路條件或租期選擇誤當成機器故障。
節點目錄
新加坡、日本（東京）、韓國（首爾）、香港均提供三種機型。最終可用狀態以控制台即時回傳為準。
訂單準備清單
6 / 6 項
- 用途明確建置、測試、持續整合或 MLX 推論
- 機型選定M4 16GB、M4 24GB 或 M4 Pro 64GB
- 節點選定依團隊時區與資料傳輸路徑判斷
- 確認計費週期依日、週、月或季核對訂單
- 確認儲存需求區分系統、專案、相依套件快取與模型檔案
- 遠端連線環境就緒本地網路允許所需連線並保持穩定
連線失敗時，先從交付狀態開始，不要反覆修改密碼
首次進入雲端 Mac 的問題通常發生在訂單狀態、連線資料、本地網路或輸入過程。依照以下順序檢查，每一步只變更一個變數。
-
01
訂單層
確認訂單已進入可連線狀態
登入控制台查看目前訂單。如果仍在處理流程中，先等待狀態更新；不要使用舊截圖或其他訂單的連線資料嘗試。
-
02
資料層
逐欄讀取連線資料
確認節點、主機位址、連線方式和帳號屬於同一份訂單。複製時檢查前後空格，不要把真實憑證寫進聊天記錄、截圖檔名或公開儲存庫。
-
03
網路層
排除本地網路限制
確認本地網路、防火牆或代理伺服器沒有阻斷連線。可以切換到另一個可信任網路進行一次對照測試，但不要同時更換帳號、用戶端和網路。
-
04
輸入層
重新核對帳號輸入
區分大小寫與容易混淆的字元，確認鍵盤配置符合預期。如果問題可以重現，只記錄錯誤類型與發生時間，不要記錄密碼原文。
Xcode 建置報錯，依工具鏈到日誌的順序檢查
先確認實際執行建置的環境，再處理相依套件與簽署。直接清空所有快取或連續更換 Xcode 版本，會讓原始問題更難重現。
-
1
鎖定 Xcode 版本
記錄目前選用的 Xcode 路徑、版本與專案要求，確認命令列任務與圖形介面使用同一套工具鏈。
-
2
核對簽署檔案
確認所需檔案由團隊自己的秘密管理流程注入，路徑與權限正確。不要把簽署檔案內容複製到支援請求中。
-
3
縮小相依套件快取範圍
先判斷失敗發生在下載、解析、編譯還是連結階段。只清理對應相依套件的快取，並保留清理前後的日誌對照。
-
4
檢查磁碟空間
分別查看專案目錄、建置產物、封存檔與相依套件快取的用量。空間不足時先匯出必要產物，再清理可重建內容。
-
5
擷取最小必要日誌
保留首次錯誤前後的必要行、執行命令與結束狀態。移除權杖、使用者名稱、內部儲存庫位址與簽署資訊。
MLX 推論
先確認模型可載入，再測試服務並行
MLX 推論問題要區分模型格式、統一記憶體、服務監聽與請求壓力。先以單一請求建立可重現的基準，再逐步增加並行，避免把載入失敗和服務壅塞混為一談。
FORMAT
模型格式
先檢查
確認模型檔案完整、轉換方式一致，並記錄所用框架與版本。
MEMORY
統一記憶體用量
再測量
記錄載入前、載入後與首次請求後的讀數，避免只查看瞬間峰值。
LISTEN
服務監聽位址
查入口
確認監聽範圍與連接埠符合存取設計，並設定必要的存取控制。
LOAD
請求並行數
漸進測試
從單一請求開始，固定輸入後逐級提高並行數，記錄延遲與失敗類型。
LOG
模型載入日誌
留存證據
保留版本、啟動參數與錯誤內容，刪除業務輸入與敏感路徑。
依資料角色規劃容量，不要把節點當作唯一備份
系統、專案原始檔、相依套件快取、建置產物與模型權重的生命週期不同。先分組，再決定是否增加儲存附加項。
相依套件與建置快取
快取可以提升重複任務的效率，但應設定清理界線。排查磁碟問題時先依目錄統計，不要直接刪除所有內容。
模型與資料檔案
記錄模型來源、格式、版本與佔用空間。上傳大型檔案前核對節點路徑，並為租期結束前的匯出預留時間。
封存檔與產物
建置封存檔、測試報告與推論輸出應依任務批次命名。完成驗收後，將必須保留的內容匯出至團隊控制的儲存空間。
讓第一個請求直接具備排查條件
請求內容應能回答問題發生在哪份訂單、哪台機器、哪個節點、什麼時間、如何重現，以及日誌顯示了什麼。只寫「無法連線」或「建置失敗」通常不足以定位問題。
訂單識別碼
填寫控制台中的訂單識別碼，不要用自訂機器暱稱代替。
機型與節點
寫明 VMCache M4 16、VMCache M4 24 或 VMCache M4 Pro 64，以及對應節點。
發生時間
註明時區，並說明是持續發生、間歇發生，還是只出現過一次。
重現步驟
從已知正常狀態開始，逐步列出操作、輸入類型、預期結果與實際結果。
影響範圍
說明影響單一任務、單一專案還是所有任務，並列出可正常運作的對照項目。
去識別化日誌
保留錯誤內容、版本與結束狀態，移除密碼、私鑰、權杖與業務資料。
兩種聯絡方式
提交支援工單
已有訂單請優先登入控制台提交工單；無法進入控制台或屬於售前問題時，可寄送電子郵件至 support@vmcache.com。
下一步
先完成檢查，再把證據交給支援團隊
需要新資源時比較三種配置；已有訂單發生問題時，帶上訂單識別碼、節點、發生時間、重現步驟與去識別化日誌提交工單。