連線問題
位址可連通，但無法進入工作階段
先核對節點位址、連接埠、使用者名稱與憑證，再檢查本機網路限制、用戶端加密選項與工作階段狀態。不要反覆嘗試舊憑證。
開啟連線檢查步驟
支援入口總覽
依症狀進入對應檢查路徑
不要同時修改網路、系統版本與建置設定。一次只變更一個變數，保留原始錯誤文字與時間點，才能判斷問題屬於連線層、環境層或專案層。
Xcode 建置
編譯、封存或上傳失敗
記錄失敗階段，接著檢查磁碟空間、Xcode 與 SDK 版本、相依套件鎖定檔、簽署資料與完整建置日誌。優先保留第一個實際錯誤。
查看建置診斷順序
CI/CD
Runner 離線或工作未排程
檢查 runner 服務程序、註冊狀態、標籤比對、工作目錄權限與並行上限。平台顯示線上，不代表目前工作的標籤一定能相符。
核對 runner 設定
儲存空間擴充
快取與建置產出物佔滿空間
區分原始碼、相依套件快取、DerivedData、封存檔與交付產出物的使用量。先匯出必要檔案，再依目錄清理，不要直接刪除用途不明的資料。
閱讀儲存空間常見問答
節點移轉
團隊位置或儲存庫位置變更
先記錄目前節點、儲存庫託管區域、主要操作者位置與大型檔案傳輸方向，再評估移轉。移轉前必須準備程式碼與建置產出物的獨立副本。
比較節點與網路
帳單問題
需要核對訂單、週期或付款狀態
準備訂單編號、所選設定、計費週期、付款方式與控制台顯示狀態。僅提交交易識別碼，不要傳送完整卡片資訊或任何私密金鑰。
在控制台提交帳單工單
首次使用流程
先固定節點基線，再安裝專案工具
首次進入節點時，先完成連線與安全檢查，再設定開發環境。如此可將系統問題與專案相依套件問題分開，後續更容易重現。
-
01
從控制台取得連線資訊
核對訂單對應節點、伺服器位址、連接埠、使用者名稱與臨時憑證。連線資訊僅供目前獲授權成員使用，不得透過聊天記錄或公開文件轉發。
完成標誌：能穩定建立工作階段，並確認進入的是訂單對應節點。 -
02
完成帳戶安全設定
首次進入後更新臨時憑證，建立符合團隊權限政策的系統帳戶，確認管理員操作僅交由需要安裝工具或調整服務的成員執行。
完成標誌：不再使用臨時憑證，且已區分日常帳戶與管理帳戶的用途。 -
03
記錄系統與開發基線
記錄 macOS 版本、晶片、可用磁碟空間、Xcode 版本、命令列工具路徑與目標 SDK。團隊應將這些資訊寫入自己的建置執行手冊。
完成標誌：能用同一組版本資訊說明本機與雲端建置的差異。 -
04
安裝相依套件與 runner
依專案鎖定檔安裝相依套件，設定獨立快取目錄，再註冊 self-hosted runner。首次工作先以低並行度驗證簽署、封存與上傳路徑。
完成標誌：最小建置工作可重複執行，並留下完整日誌。
建議保留的環境清單
- macOS 與 Xcode 完整版本號
- 目標 SDK、命令列工具路徑
- 相依套件管理器與鎖定檔版本
- Runner 名稱、標籤與工作目錄
- 快取目錄與最大並行工作數
以最小工作確認整條流程
先擷取一個確定可建置的提交，只執行相依套件安裝、編譯與封存。確認成功後，再加入平行工作、快取還原與交付步驟。
準備連線檢查
建置故障診斷
依失敗流程逐項排除，不要同時修改六個變數
建置問題通常沿著空間、簽署、版本、相依套件、日誌與並行六個層面展開。每完成一層就重新執行同一提交，記錄結果是否變化。
01
容量
磁碟空間
分別檢查系統磁碟區可用空間、DerivedData、相依套件快取、封存目錄與匯出產出物。空間不足時先儲存必要產出物，再依目錄清理。
02
簽署
憑證與描述檔
確認專案選用的團隊、憑證有效狀態、描述檔目標與 Bundle Identifier 一致。不要在日誌或工單中附上簽署私密金鑰。
03
版本
Xcode 與 SDK 版本
記錄實際執行建置的 Xcode 路徑，確認命令列工具未指向其他版本，並核對專案要求的目標 SDK 是否存在。
04
相依套件
相依套件快取
對照鎖定檔判斷快取是否過期。先嘗試不還原快取的乾淨建置；若成功，再逐一還原相依套件快取，定位不一致來源。
05
日誌
完整建置日誌
保留執行指令、結束碼與第一個實際錯誤。只截取最後一個畫面往往會漏掉前置失敗，應附上從工作開始到結束的去識別化日誌。
06
並行
平行工作數量
將並行度降至單一工作重現，觀察記憶體、磁碟與網路使用量。單一工作成功而平行工作失敗時，再逐級增加並行度，找出穩定上限。
完成六層檢查仍無法定位時，請提交失敗提交識別碼、執行指令、環境版本、結束碼與去識別化日誌。
提交建置問題工單
CI/CD 支援
讓 runner 可識別、可恢復、可稽核
獨享實體節點適合作為 self-hosted runner，但穩定執行有賴清晰的註冊策略、標籤、服務管理、快取邊界與權限控制。
註冊
每個節點使用唯一 runner 名稱，記錄所屬儲存庫或組織、註冊範圍、工作目錄與服務帳戶。移轉節點時先撤銷舊註冊。
標籤
標籤應表達穩定事實，例如晶片架構、Xcode 主版本、節點區域與用途。不要堆疊臨時專案名稱，形成難以維護的標籤組合。
服務維持運作
將 runner 作為受管理服務執行，記錄啟動方式與日誌位置。系統重新啟動後確認服務是否自動恢復，並測試一個最小工作。
快取目錄
將相依套件、DerivedData 與封存檔分目錄管理，設定清理門檻。快取用於加速，不應成為專案唯一副本或長期交付儲存庫。
最小權限
日常建置帳戶只取得工作所需的目錄與指令權限。安裝工具、修改系統設定與管理服務時，再使用管理員權限。
Runner 離線時的檢查順序
提交 runner 工單
服務程序 → 註冊有效性 → 標籤比對 → 工作目錄權限 → 外部連線 → 平台工作佇列。
術語小辭典
先統一術語，再描述問題
在工單中使用一致術語，可避免將實體節點、遠端工作階段、runner 與建置快取混為同一個故障對象。
- 實體節點
- 實際執行 macOS、Xcode 與建置工作的 Apple Silicon Mac 裝置。節點是硬體交付單位，不是共享虛擬資源。
- 獨享
- 一個訂單對應的節點資源由該客戶使用，CPU、記憶體與本機儲存空間不會與其他客戶的工作混合排程。
- 非虛擬機器
- 系統直接執行於實體 Mac 上，不是將一台裝置拆分為多個虛擬執行個體。硬體規格與訂單設定直接對應。
- VNC
- 用於遠端查看與操作 macOS 圖形介面的連線方式。位址、連接埠、帳戶與加密選項需依連線資訊填寫。
- Self-hosted runner
- 由團隊自行註冊至 CI/CD 平台，並在獨享節點上執行工作的 runner，可控制工具版本、快取與並行策略。
- 建置快取
- 用於減少重複下載或編譯的可重新產生資料，包括相依套件快取與 DerivedData。快取損壞時應能安全重建。
- 簽署憑證
- 建置與交付流程中的敏感簽署資料。排查時僅描述憑證名稱、狀態與錯誤，不要向工單上傳私密金鑰。
- 節點區域
- 實體節點所在區域。選擇時同時考量開發者位置、程式碼儲存庫位置、交付目標與大型檔案傳輸方向。
節點與網路排查
依區域查看完整工作流程，不要只看單次延遲
VMArm 提供新加坡、日本（東京）、韓國（首爾）、香港、美國西部共 5 個節點區域。應同時比較遠端操作、儲存庫擷取、相依套件下載與產出物上傳方向。
新加坡
適合東南亞團隊，以及主要服務位於東南亞的儲存庫與交付流程。
日本（東京）
適合日本與東亞團隊，便於兼顧遠端桌面操作與區域內建置資源存取。
韓國（首爾）
適合韓國與東北亞方向的開發成員、相依套件鏡像與交付流程。
香港
適合華南與東南亞協作團隊，選擇前應同時測試儲存庫與遠端工作階段流程。
美國西部
適合北美西岸團隊，以及主要儲存庫、相依套件來源或交付系統位於北美的專案。
| 檢查對象 | 如何測試 | 需要記錄 | 判斷重點 |
|---|---|---|---|
| 遠端工作階段 | 分別測試工作時段與非尖峰時段的連線與互動 | 本機網路、節點、用戶端版本、發生時間 | 持續異常或特定時段波動 |
| 程式碼儲存庫 | 使用同一儲存庫與同一提交測試複製、擷取與子模組 | 儲存庫所在區域、耗時、失敗指令、結束碼 | 建立連線慢或大型檔案傳輸慢 |
| 相依套件下載 | 關閉快取後執行一次完整相依套件解析 | 相依套件來源、套件管理器版本、失敗套件與重試次數 | 單一相依套件來源異常或整體頻寬異常 |
| 產出物上傳 | 使用相同大小的去識別化測試檔案比較傳輸 | 檔案大小、目標區域、開始與結束時間 | 上行鏈路、目標服務或檔案大小的影響 |
提交工單所需資訊
一次提供完整診斷背景
工單的目的不是證明問題存在，而是讓支援人員能定位同一訂單、同一節點、同一時間與同一失敗步驟。
診斷資訊單
7 REQUIRED FIELDS
01
訂單編號
用於確認對應設定、計費週期與交付記錄。
02
節點區域
請寫明新加坡、日本（東京）、韓國（首爾）、香港或美國西部。
03
發生時間
提供含時區的時間，並說明問題是否可重複發生。
04
系統版本
寫出完整 macOS 版本，不只填寫主版本名稱。
05
Xcode 版本
同時寫出實際命令列工具指向的版本與路徑。
06
重現步驟
從正常狀態開始，依實際點選或指令順序逐步描述。
07
去識別化日誌
保留錯誤背景與結束碼，移除權杖、私密金鑰與其他敏感資訊。
提交前移除存取權杖、簽署私密金鑰、完整付款資訊與其他敏感內容。需要了解資料處理方式時，請閱讀隱私權政策。
服務範圍與回應流程
從確認問題到關閉工單，每一步都有明確產出
回應順序取決於影響範圍與可重現程度。支援流程負責節點交付、連線、環境與訂單問題；專案商業邏輯仍需由專案維護者確認。
-
01
問題分級
依無法連線、建置完全中斷、部分工作異常或一般諮詢判斷影響範圍，並確認是否存在可行的替代路徑。
-
02
確認回覆
確認已收到訂單編號、節點、時間、環境與日誌；缺少必要資訊時，會明確列出需要補充的欄位。
-
03
診斷更新
說明目前檢查層級、已排除項目、下一步驗證動作與需要使用者執行的測試，避免重複執行沒有新增資訊的步驟。
-
04
關閉條件
問題已恢復、根因與規避方法已說明，或確認屬於專案設定並提供可執行的檢查方向後，工單進入關閉流程。
支援範圍內
- 訂單與節點交付狀態核對
- VNC 位址、連接埠與工作階段連線排查
- 節點系統、磁碟、網路與權限基本診斷
- Runner 服務狀態與一般設定檢查
- 計費週期與付款狀態說明
需要專案團隊共同確認
- 商業程式碼邏輯與第三方 SDK 行為
- 專案自訂指令碼與內部相依套件來源
- 團隊自行制定的簽署與發佈流程
- 儲存庫權限、分支策略與工作觸發條件
- 建置產出物的業務驗收標準
下一步
將下一次建置放到獨享實體 Mac 節點
選擇 VMArm M4 Core 或 VMArm M4 Plus，並從新加坡、日本（東京）、韓國（首爾）、香港、美國西部中選擇節點。實際可用狀態以控制台即時回傳為準。