無法連線
先確認是裝置無法連線，還是憑證失效
記錄控制台上的裝置狀態、SSH 或 VNC 錯誤原文、本機網路環境、首次發生時間，以及是否只有一種存取方式失敗。
準備：節點、來源網路、錯誤訊息、時間
雲端 Mac 技術支援
先找出故障層級，再提交可重現的資訊
連線問題從裝置狀態與憑證查起；建置問題則從 Xcode、相依項目與簽署環境著手。CDNMac 提供獨享實體主機，非虛擬機；專案程式碼、開發者帳號與簽署資產仍由使用者管理。
已有訂單時，請優先提供訂單編號、所選節點、發生時間及去識別化記錄。實際裝置狀態與可執行操作，以控制台即時顯示為準。
6 種問題類型
依連線、建置、簽署、網路、帳單及節點分類
6 項資料
一次備妥支援單所需資訊
全年運作
節點全年 365 天正常運作
問題交接紀錄
從問題現象到重現步驟
資訊完整後即可進入處理佇列
01
確認故障範圍
記錄問題影響單一裝置、單一儲存庫、單次建置，還是所有連線方式。
- 裝置狀態
- 查看控制台目前狀態
- 所選節點
- 記錄訂單所屬區域
02
縮小問題範圍
分別測試網路、系統存取、工具鏈、專案相依項目與簽署步驟，避免同時變更多項設定。
- 最小重現案例
- 保留穩定重現步驟
- 發生時間
- 註明首次與最近一次發生時間
03
提供必要佐證
提交已去識別化的記錄、預期結果及已嘗試的操作；請勿提供私密金鑰、權杖、憑證密碼或完整付款資料。
- 記錄範圍
- 包含指令、階段與時間戳記
- 預期結果
- 說明正常狀態應為何
先選擇問題類型
六種問題類型，各有一組必要資訊
先依主要現象分類，再準備相應資料。每次請求只保留一個主要問題；相關現象可補充在重現步驟中。
建置失敗
找出建置在哪個階段失敗
提供 Xcode 與 Command Line Tools 版本、使用的鎖定檔、失敗指令、目標 scheme、可用磁碟空間，以及記錄中的第一個有效錯誤。
準備：版本、指令、階段、去識別化記錄
簽署問題
檢查憑證、描述檔與目標設定
提交已去識別化的簽署錯誤、bundle identifier、目標環境及憑證有效狀態。請勿提交憑證密碼、私密金鑰或可直接使用的權杖。
準備：目標、識別碼、有效狀態、錯誤訊息
網路異常
分別測試往返延遲與實際下載連線
記錄來源電信業者、網路類型、目標節點、連續測試樣本的中位數，以及儲存庫或相依項目下載是否也有異常。
準備：電信業者、網路類型、樣本、目標
帳單問題
依訂單項目核對基本設定與加購項目
提供訂單編號、租用期間、基本設定，以及 SSD 或 Thunderbolt 5 並聯項目的名稱。請勿在支援單中填寫完整付款資料。
準備：訂單、期間、設定、加購項目
節點遷移
先說明遷移原因與資料交接範圍
記錄目前節點、目標連線方向、需保留的工作目錄與產出物，並說明是否可重新部署環境。可選範圍以控制台即時顯示為準。
準備：目前節點、目標方向、資料範圍
連線疑難排解
依固定順序檢查，避免把網路問題誤判為裝置故障
每完成一個步驟再進行下一步，並記錄結果。排查時請勿同時更換金鑰、修改防火牆並重新啟動本機網路，否則難以找出真正原因。
01
查看裝置狀態
先在控制台確認訂單與裝置狀態，核對目前節點和裝置識別碼。若狀態仍在變動，請等控制台顯示穩定狀態後再測試連線。
02
核對存取憑證
確認使用的是目前裝置對應的系統使用者名稱、主機位址與最新憑證。請勿將其他訂單的連線資訊套用到目前裝置。
03
測試 SSH 連線
透過可信任的網路測試主機與連接埠是否可連線，再檢查金鑰檔案權限與驗證錯誤。保留含時間戳記的錯誤訊息，請勿提交私密金鑰內容。
04
測試 VNC 工作階段
若 SSH 正常但圖形工作階段異常，請另外記錄 VNC 用戶端、連線階段與畫面狀態，避免將圖形工作階段問題歸類為基本網路故障。
05
檢查本機防火牆
確認公司網路、VPN、出口政策與本機防火牆是否封鎖目標連接埠。可改用另一個可信任的網路重新測試，判斷問題是否出在本機連線。
單次 ping 只能反映當下的網路往返時間，無法直接代表 VNC 操作流暢度、相依項目下載速度或完整建置時間。請搭配連續測試樣本與實際工作重新測試。
建置疑難排解
從工具鏈版本查到第一個有效錯誤
建置記錄常包含後續連鎖錯誤。請先找出第一個導致流程中斷的有效錯誤，再核對相關工具、相依項目、簽署或磁碟空間。
Xcode 與目標 SDK
記錄完整的 Xcode 版本、目標平台、scheme、configuration 和實際使用的工具路徑。圖形介面與命令列使用的版本應一致。
Command Line Tools
確認目前選取的開發者目錄與預期版本一致。升級 Xcode 後，請再次確認命令列工具指向正確位置，避免指令碼使用舊路徑。
相依項目與鎖定檔
保留專案使用的鎖定檔，並記錄相依項目還原指令與快取策略。先在乾淨的工作目錄重新測試，再判斷是否為快取污染。
憑證與描述檔
確認有效狀態、bundle identifier、目標環境與簽署設定相符。僅提交去識別化的錯誤訊息，請勿提供私密金鑰或憑證密碼。
磁碟空間與暫存目錄
檢查原始碼、相依項目快取、DerivedData、Archive 與匯出產出物的總空間用量。空間不足時，先清除可重新產生的快取。
記錄時間戳記與失敗階段
保留工作開始、第一個錯誤及工作結束的時間，並註明失敗發生於還原相依項目、編譯、Archive、簽署或匯出階段。
CI/CD 整合
將獨享實體主機註冊為受控的 self-hosted runner
CDNMac M4 可執行由儲存庫觸發的 iOS 建置工作。整合 GitHub Actions、GitLab CI、Jenkins 或其他排程系統時，請將執行節點視為長期運作的建置主機，而非一次性容器。
- 為每個儲存庫建立獨立工作目錄，避免多個專案共用未清理的建置快取。
- 權杖僅授予執行工作所需的最低權限，並為不同儲存庫分別設定。
- 將簽署資料存放於受控位置，避免流水線記錄輸出金鑰、權杖或憑證密碼。
- 工作完成後，清除暫存檔、衍生資料及不再需要的產出物副本。
- 為 runner 設定明確標籤，避免將不相容的工作錯誤指派給該裝置。
建置工作交接單
RUNNER / M4
A1
佇列
接收受信任的工作
依儲存庫、分支與 runner 標籤判斷是否接受工作。
B2
工作區
還原相依項目
使用鎖定檔與儲存庫專屬快取，並記錄快取命中狀況。
C3
封存
執行 Archive
固定 Xcode 路徑、scheme、configuration 與匯出參數。
D4
產出物
交付並清理
複製必要產出物後清除暫存目錄，並保留去識別化的診斷記錄。
隔離單位：儲存庫
憑證原則：最低權限
清理時機：工作結束
術語小辭典
八個常見詞彙，先統一排查用語
在支援單中使用一致的術語，有助於快速區分實體裝置、存取協定、自動化執行器與最終交付檔案。
- 雲端 Mac
- 透過網路遠端使用的 Mac 裝置。CDNMac 提供獨享實體主機，每張訂單使用不同裝置。
- 實體節點
- 裝置實際部署並連上網路的區域位置。所選區域會影響連線路徑，但無法單獨決定完整建置時間。
- 獨享
- 每張訂單使用一台專屬裝置及其資源與存取環境，不會將運算資源分配給多位租用者共同使用。
- 非虛擬機
- 工作負載直接在實體 Mac 硬體上執行，而非將一台主機切分為多個虛擬執行個體。
- VNC
- 遠端存取 macOS 圖形介面的工作階段方式，適合查看介面狀態或執行圖形操作。
- SSH
- 用於命令列、指令碼與檔案傳輸的加密連線方式，適合自動化工作與日常系統操作。
- self-hosted runner
- 註冊於持續整合系統，並由團隊自行管理的工作執行器。它會在指定的雲端 Mac 上接收並執行流水線工作。
- 建置產出物
- 編譯、Archive 或匯出流程產生的檔案與必要記錄。應複製至團隊管理的儲存空間，並設定保留期限。
提交支援單前準備
備妥六項資料，再登入控制台提交
提供完整資訊比反覆傳送簡短訊息更有助於重現問題。敏感欄位僅需說明類型與狀態，請勿提供可直接使用的明文資料。
01
訂單編號
提供控制台中的訂單編號或裝置識別碼，以確認對應的機型、租期與裝置紀錄。
02
所選節點
註明目前裝置所在節點，不要只寫「亞洲」或「美國」。如需遷移，請再說明目標連線方向。
03
發生時間
記錄首次發生、最近一次重現及工作結束時間，並註明時區，以便比對裝置與網路紀錄。
04
重現步驟
依序說明輸入內容、指令、目標與結果。若問題並非每次發生，請補充發生頻率與觸發條件。
05
去識別化記錄
保留錯誤前後文與時間戳記，移除私密金鑰、權杖、憑證密碼、個人資料及完整付款資料。
06
預期結果
說明正常情況下應出現的狀態、檔案或回傳值，並列出已嘗試但無效的操作。
服務範圍
哪些問題可由我們協助？哪些須由團隊負責？
先區分裝置與網路、系統存取、工具鏈建議及專案本身的責任，可避免在錯誤層級反覆修改設定。
硬體與網路狀態
協助確認裝置狀態、節點端網路、訂單對應關係與控制台顯示的管理狀態，並依據可重現的資訊進一步處理。
CDNMac 協助範圍系統存取協助
協助判斷裝置是否可連線、憑證是否對應目前裝置，以及 SSH 與 VNC 問題屬於網路、驗證或工作階段層級。
CDNMac 協助範圍建置工具疑難排解建議
可依據記錄協助檢視 Xcode、Command Line Tools、磁碟空間與建置階段；專案相依項目與指令碼仍須由專案團隊驗證。
共同排查範圍專案與開發者資料
專案程式碼、開發者帳號、憑證、描述檔、存取金鑰、軟體授權、相依項目版本及工作負載合法性，均由使用者負責管理。
使用者負責管理
安全提醒
將憑證、簽署資料與建置產出物納入同一套退租流程
獨享裝置可減少資源共享的風險，但無法取代團隊自身的權限管理。首次連線、持續運作與租期結束時，都應有明確的操作清單。
採用最低權限
CI 權杖、儲存庫金鑰與自動化帳號僅授予目前工作所需權限，避免多個專案長期共用同一組高權限憑證。
定期輪替憑證
建立金鑰與權杖輪替紀錄。當成員、儲存庫或工作範圍變更時，請即時撤銷不再需要的存取權限。
移除過期憑證
定期檢查憑證與描述檔的有效狀態，刪除不再使用的副本，避免流水線誤選舊設定。
預先匯出必要產出物
租期結束前，將原始碼變更、建置記錄、Archive 與必要產出物複製到團隊管理的儲存空間，並確認檔案可正常讀取。