Xcode
固定專案要求的工具鏈版本
先讀取專案文件與 CI 設定中的版本限制，再選擇對應的 Xcode。切換後同時檢查編譯器路徑、SDK 清單與命令列工具，避免圖形介面版本與終端機實際路徑不一致。
xcode-select -p
xcodebuild -version
xcrun --show-sdk-path判斷標準：本地開發與持續整合輸出的 Xcode 主版本、SDK 與工具路徑一致。
先找到正確路徑
六類問題，對應六條最短處理路徑
如果現象跨越多個分類，先從「首次連線」核對基本資訊，再進入「故障排除」。帳戶、訂單與節點的實際狀態以控制台回傳結果為準。
首次連線
不要一開始就反覆重新連線，先完成五項基本檢查
首次使用時，最常見的問題來自節點資訊抄寫錯誤、本地網路限制或顯示參數不合適。依序檢查可以避免將環境問題誤判為節點問題。
-
01
在控制台讀取本次訂單資訊
確認訂單編號、機型、節點區域、連線位址、使用者名稱與存取憑證屬於同一筆訂單。請勿使用舊訂單截圖或聊天記錄中的歷史資訊。憑證僅應儲存在受控的密碼管理工具中。
完成標準：機型、區域與目前訂單一致 -
02
建立遠端桌面連線
使用支援 macOS 圖形介面的遠端桌面用戶端，逐字輸入連線位址與使用者名稱。連線失敗時，先切換一次本地網路，排除公司代理伺服器、出口防火牆或公共網路策略的影響。
完成標準：可以看到 macOS 圖形介面並操作桌面 -
03
完成基本安全設定
首次進入後更換系統登入密碼，檢查螢幕鎖定時間，並確認專案私鑰、簽署憑證與存取權杖沒有寫入共用腳本、命令歷史記錄或公開儲存庫。請勿將密碼或私鑰提交給支援人員。
完成標準：存取憑證已更換並由團隊安全保存 -
04
調整解析度與影像品質
依據本地顯示器選擇合適的縮放比例。網路波動時，先降低影像品質與解析度，再判斷節點回應；滑鼠延遲與畫面模糊並不等同於編譯或磁碟效能下降。
完成標準：文字清晰，輸入與視窗拖曳都能穩定回應 -
05
執行首次登入檢查
開啟終端機確認系統時間、可用磁碟空間、網路解析與 Xcode 命令列路徑。接著建立暫存目錄，完成寫入、讀取與刪除測試，確認目前使用者擁有專案目錄所需的權限。
完成標準：時間、磁碟、網路與目錄權限均正常
開發環境
先固定版本與目錄，再安裝專案相依套件
雲端 Mac 是專用實體機，並非虛擬機。團隊仍應將環境設定寫成可重現的清單，避免個人手動修改長期累積後無法還原。
Homebrew
使用 Brewfile 管理可重現的相依套件
不要把已安裝的工具清單只留在個人記憶中。先從現有環境匯出 Brewfile，清理無關套件，再在雲端 Mac 上依清單安裝。私有來源的存取權杖應透過受控環境變數注入。
brew bundle dump --force
brew bundle check
brew bundle install判斷標準：Brewfile 可在乾淨目錄中執行，且不會要求將敏感權杖寫入儲存庫。
Git
將儲存庫身分與專案權限分開
檢查使用者名稱、提交電子郵件、預設分支與換行規則。多個專案使用不同儲存庫權限時，分別設定金鑰檔案與主機別名，不要讓單一高權限憑證覆蓋所有建置任務。
git config --global --list
git remote -v
ssh -T git@your-git-host判斷標準：拉取、提交與子模組存取分別使用預期身分，日誌中不輸出權杖。
簽署與命令列
將敏感材料放在建置流程之外
憑證、私鑰與簽署憑證應透過團隊核准的安全流程匯入，並依專案設定最小存取範圍。Node、Ruby、Python、CocoaPods 等工具應固定版本，並將版本檔案納入儲存庫。
node --version
ruby --version
python3 --version
pod --version判斷標準：新工作階段可以從版本檔案還原環境，建置日誌不包含憑證內容。
CI/CD 串接
將雲端 Mac 作為可追蹤的常駐建置節點
串接 GitLab CI Runner 時，先定義節點職責，再註冊執行器。單一節點可以承載多個佇列，但高權限簽署任務與一般編譯任務應使用不同標籤、目錄與憑證範圍。
安裝並註冊 GitLab CI Runner
使用專案或團隊分配的註冊資訊完成安裝。為節點設定能表達架構、Xcode 版本與任務類型的標籤，停用無標籤任務接入，避免任意流水線佔用建置節點。
- 記錄 Runner 名稱與所屬專案
- 標籤包含工具鏈與任務類型
- 驗證執行使用者的目錄權限
管理常駐建置任務
將 Runner 作為受控的背景任務執行，確認重新啟動後能恢復。請勿使用個人終端機工作階段長期掛起建置程序；工作階段中斷不應影響正在執行的編譯或測試。
- 檢查程序擁有者與啟動方式
- 限制同時執行的任務數量
- 為逾時任務設定退出規則
固定快取目錄與清理界線
將相依套件快取、DerivedData、封存檔與最終產物分開。快取可以重複使用，封存檔需要追蹤，暫存檔應依流水線清理。磁碟異常增加時，先定位目錄，不要直接刪除未知專案資料。
- 分別記錄快取與產物路徑
- 依專案設定獨立目錄
- 定期檢查磁碟剩餘空間與增加來源
隔離簽署憑證與儲存庫權限
依專案注入最小權限憑證，限制只有受保護分支才能執行簽署任務。日誌中只記錄憑證是否載入成功，不輸出密碼、私鑰、權杖或簽署材料內容。
- 保護敏感變數並限制分支
- 為一般編譯與簽署任務設定不同標籤
- 任務結束後清理暫存檔
串接驗收
用一條最小化流水線驗證，不要直接遷移所有任務
- 拉取一個不含敏感資料的測試儲存庫。
- 輸出 Xcode、SDK 與相依工具版本。
- 執行一次未簽署的編譯並儲存產物。
- 檢查任務結束後的快取、日誌與暫存目錄。
服務可用率
使用統一指標判斷服務狀態，不要以單次網路波動取代結論
MacMLab 雲端 Mac 節點全年 365 天正常運作。連線品質也會受到使用者本地網路、出口策略、遠端桌面參數與任務負載影響，排查時需要將這些因素與節點狀態分開記錄。
- 服務可用率指標
- 99.9%
- 狀態觀察範圍
- 90天
訂單符合適用條件且核驗為平台服務問題後，將依據服務條款與對應訂單記錄處理服務賠付。
正常運作記錄
從較早記錄到最近記錄
故障決策樹
從現象進入分支，每次只變更一個變數
先記錄發生時間與原始錯誤，再執行檢查。不要同時重新安裝工具、切換網路與清理目錄，否則即使恢復也無法確認根本原因。
節點能否建立遠端連線？
先確認控制台中的訂單狀態、節點區域與連線資訊，再選擇下方與現象最接近的分支。
位址無回應或憑證遭拒
- 確認連線資訊來自目前訂單。
- 切換本地網路並暫停代理伺服器後重新測試。
- 記錄用戶端錯誤原文與發生時間。
提交：訂單編號、節點區域、本地網路類型、錯誤截圖與用戶端名稱。
畫面延遲、輸入遲緩或任務變慢
- 降低遠端桌面解析度與影像品質。
- 區分桌面畫面延遲與終端機命令耗時。
- 檢查 CPU、記憶體、磁碟與並行任務。
提交：慢速操作名稱、開始與結束時間、任務並行數及去識別化資源摘要。
寫入失敗或可用空間持續下降
- 查看專案、快取、封存檔與日誌目錄大小。
- 確認是否有失敗任務留下暫存檔。
- 只清理可重建的快取，不要刪除未知資料。
提交：磁碟剩餘空間、增加最快的目錄、最近任務及清理前後的去識別化結果。
編譯器、相依套件或簽署流程發生錯誤
- 記錄 Xcode、SDK 與相依工具版本。
- 在乾淨目錄中重現最小建置任務。
- 比較本地與 CI 的環境變數名稱。
提交：失敗命令、退出碼、第一個有效錯誤與已去識別化的相關日誌片段。
多個獨立操作同時失效
- 排除單一儲存庫、單一工具與單一用戶端。
- 記錄終端機與圖形介面的共同現象。
- 停止重複重試，保留現場資訊。
提交：訂單編號、節點區域、異常時間線、影響範圍與最近一次正常操作。
聯絡支援
技術問題優先提交工單，一般諮詢可寄送支援郵件
MacMLab 對外僅提供控制台工單與支援信箱兩種聯絡管道。涉及現有訂單、節點或帳單的事項，請優先提交工單，方便關聯訂單記錄並持續更新處理狀態。
建議管道
登入控制台提交工單
適合處理連線失敗、節點異常、建置環境、帳單狀態與訂單相關問題。工單中請先寫結論，再依時間順序列出重現步驟。
標題建議
節點區域 + 現象 + 首次發生時間
內文順序
訂單編號 → 影響範圍 → 重現步驟 → 錯誤原文 → 已執行的檢查
附件要求
只上傳已去識別化的截圖與日誌摘要，遮蓋密碼、私鑰、權杖與簽署憑證
一般諮詢
support@macminilab.com
寄送支援郵件
適合處理尚未下單的設定確認、企業需求背景、文件回饋或無法登入控制台的情況。
隱私提醒
查看資料處理說明
支援人員不需要你的秘密資訊
請勿傳送系統密碼、私鑰、存取權杖、簽署憑證或完整業務資料。日誌應保留錯誤內容，同時替換儲存庫位址、使用者名稱與金鑰內容。