Connection · Migration · CI/CD

如何解決問題：從連線檢查到恢復流水線

先確認問題發生在哪一層，再收集節點、時間戳記、完整錯誤訊息與最近一次變更。以下提供可直接執行的檢查順序，適用於 ArmMacs 雲端 Mac 的圖形介面、命令列、Xcode 與自託管 Runner。

登入控制台提交技術工單 查看首次連線步驟
diagnostic-checklist

01 識別節點與機型

02 記錄本機網路狀態

03 在記錄時間戳記後重現一次

04 收集已脫敏的日誌

05 將證據附加至工單

圖形介面與命令列皆完整可用 獨享實體節點，非虛擬機器 全年 365 天正常運行

支援分流

先依問題類型分流

同一種現象可能來自本機網路、節點系統、工具鏈或流水線設定。先選擇最接近的類別，並記錄發生問題的節點、當地時間與時區、原始錯誤訊息及最近一次成功時間。

無法連線

適用於 VNC、SSH、憑證遭拒、連線逾時或工作階段突然中斷。先區分「目標無法連達」與「身分驗證失敗」。

需要：節點 · 通訊協定 · 時間戳記

開發環境

適用於 Xcode 版本、命令列工具、相依性解析、簽署資料權限、建置快取與磁碟空間問題。

需要：版本 · 命令 · 原始錯誤訊息

CI/CD

適用於 Runner 離線、標籤不符、工作排隊、並行衝突、工作目錄污染或建置後清理失敗。

需要：工作 ID · 標籤 · Runner 日誌

儲存

適用於空間不足、建置產物增加、快取佔用、資料遷入、外部備份與租期結束前匯出。

需要：剩餘空間 · 路徑 · 資料量

帳單

適用於訂單狀態、租期、續期與付款記錄。訂單以美元結算，僅支援指定的兩類付款方式。

需要：訂單號碼 · 金額 · 付款時間

請保留原始錯誤訊息，不要只寫「無法使用」。提交日誌前，請刪除密碼、私鑰、存取權杖、簽署資料內容與儲存庫中的業務資料。

首次連線

首次連線四步完成

不要同時修改網路、憑證與系統設定。每完成一步先驗證結果，發生問題時才能確定故障所在環節。

  1. 01

    取得並核對憑證

    在控制台開啟對應訂單，核對機型、節點、連線位址、使用者名稱、臨時密碼或 SSH 憑證。確認目前查看的是目標執行個體，而非已結束或其他區域的訂單。憑證只應儲存在受控的密碼管理工具中。

  2. 02

    驗證本機至節點的網路

    先記錄本機網路類型、出口環境與測試時間，再檢查網域解析、目標位址可達性與所需連接埠。若公司網路失敗而備用網路可用，應優先檢查本機防火牆、代理伺服器或出口策略，不要反覆重設節點。

  3. 03

    建立 VNC 或 SSH 連線

    需要圖形介面時使用 VNC 遠端桌面；執行腳本、同步儲存庫或接入自動化時，優先使用 SSH。首次連線先完成一個短工作階段，驗證鍵盤輸入、檔案讀寫與命令執行，再開始遷移大型資料或安裝相依套件。

  4. 04

    修改初始安全設定

    立即更換臨時密碼，依團隊規則設定 SSH 公開金鑰，限制憑證可見範圍，並檢查遠端存取設定。不要將私鑰、憑證密碼或流水線權杖寫入共用腳本、建置日誌與儲存庫檔案。

連線證據

連線失敗時至少記錄以下資訊

node: SG / JP / KR / HK / US-W
protocol: VNC or SSH
local_network: office / home / mobile
timestamp: YYYY-MM-DD HH:MM timezone
result: timeout / refused / authentication failed
last_success: YYYY-MM-DD HH:MM timezone

遷移路徑

從本機 Mac 到可重現的流水線

遷移不等於複製整個使用者目錄。將專案資料、工具鏈定義與 Runner 設定分開處理，可減少環境漂移，也便於在租期結束前完整匯出。

PATH 01

遷移專案資料

  1. 整理範圍僅遷移儲存庫、必要資料集、設定範本與建置輸入，不複製無關快取。
  2. 計算容量記錄來源目錄大小、檔案數量與校驗值，並預留相依套件與建置產物的空間。
  3. 分批傳輸小型儲存庫先驗證權限與換行格式，大型資料依目錄拆分，傳輸後再抽查。
  4. 隔離秘密敏感憑證透過受控方式單獨設定，不放入壓縮檔、儲存庫或一般同步目錄。
PATH 02

重現 Xcode 與相依套件

  1. 鎖定版本記錄 Xcode、命令列工具、語言執行環境與套件管理工具的版本。
  2. 恢復相依套件優先使用鎖定檔與可執行的安裝腳本，不直接複製本機建置快取。
  3. 執行基準建置先執行最小目標，再執行測試與完整封存，分別保存結束代碼與日誌。
  4. 固定檢查清單將版本、安裝順序、環境變數名稱與驗證命令寫入團隊運行手冊。
PATH 03

接入 CI/CD Runner

  1. 建立專用執行環境將流水線工作與日常遠端桌面操作分開，減少權限與目錄衝突。
  2. 設定精確標籤標籤至少應表示平台、晶片等級與 Xcode 主版本，避免工作誤派送。
  3. 從單一並行開始先驗證建置、測試、封存與產物回傳，再評估是否需要並行。
  4. 定義清理動作工作結束後清理臨時憑證、衍生資料與無用產物，同時保留必要日誌。

Xcode 診斷

分層排查 Xcode 雲端建置

先確認工具鏈，再檢查權限、快取與儲存空間。不要在同一次重試中同時升級 Xcode、更新相依套件並替換簽署檔案，否則日誌無法判斷是哪項變更生效。

檢查層級 需核對的事實 建議動作 工單證據
版本選擇 Xcode 圖形版本、命令列工具路徑與專案要求的 SDK 是否一致 固定一個版本完成最小建置，確認流水線與互動式終端使用相同路徑 版本輸出、選取路徑、失敗目標
簽署檔案 檔案是否完整、是否已過期，以及目標與設定是否正確引用 在隔離環境驗證檔案可讀性，避免將敏感內容寫入日誌 脫敏後的名稱、有效期限、原始錯誤訊息
憑證權限 執行建置的使用者能否存取所需憑證與金鑰資料 比較互動式建置與 Runner 使用者的權限環境，縮小差異 執行使用者、權限結果、失敗階段
Derived Data 舊快取是否來自其他分支、Xcode 版本或建置設定 保存一次失敗日誌後清理目標快取，再執行相同命令進行比較 清理前後的結束代碼與日誌差異
磁碟空間 系統卷宗剩餘空間、封存目錄、模擬器資料與相依套件快取佔用量 先刪除可重新產生的快取與過期產物，不要刪除唯一副本 失敗前的剩餘空間與最大目錄
建置日誌 第一個實際錯誤、失敗目標、結束代碼與前後文是否完整 保存原始文字日誌，截取第一個錯誤前後的相關行並進行脫敏 命令、時間戳記、結束代碼、日誌附件

日誌只需保留定位問題所需的上下文。提交前搜尋並刪除權杖、密碼、私鑰內容、憑證密碼、內部儲存庫位址與業務資料。

Runner 手冊

兩類 Runner 的接入與清理基準

ArmMacs 提供獨享實體機，因此工作目錄與工具鏈可跨建置保留。持久化也表示快取、憑證與舊產物不會自動消失，必須在流水線中明確定義清理範圍。

GitHub Actions

自託管 Mac Runner

  1. 註冊使用專用 Runner 身分完成註冊，確認服務啟動後能持續顯示在線上，並記錄 Runner 名稱與工作目錄。
  2. 標籤保留平台標籤，並新增晶片等級、Xcode 主版本與用途標籤。工作流程只匹配實際需要的標籤組合。
  3. 並行先以單一工作串行執行。多個 Xcode 封存同時執行會競爭磁碟、快取與簽署資源，增加偶發失敗。
  4. 清理每個工作結束後刪除臨時憑證與工作層級檔案；依金鑰與容量限制保留快取，封存成功回傳後清除本機過期副本。
GitLab CI

macOS Runner

  1. 註冊明確定義 Runner 的歸屬範圍與執行方式，驗證建置使用者的目錄權限，並保存註冊時間與設定摘要。
  2. 標籤為 macOS、晶片等級、Xcode 主版本與工作類型設定標籤，禁止無標籤工作誤佔專用節點。
  3. 並行初始並行數設為 1。只有在工作目錄、連接埠、快取與簽署資料完全隔離後，才評估增加並行數。
  4. 清理在工作結束階段清理工作目錄中的秘密檔案與臨時產物；失敗工作也必須執行清理，並單獨保留已脫敏日誌。

上線前最小驗證矩陣

checkout ✓ dependency restore ✓ build ✓ test ✓ artifact export ✓ secret cleanup ✓

遠端桌面

遠端桌面問題先區分畫面、輸入與工作階段

VNC 體驗同時受本機網路、跨區域路徑、解析度與畫面變化頻率影響。發生問題時先記錄節點與本機網路狀態，再只變更一個變數進行比較。

畫面延遲或捲動不流暢時如何處理

記錄節點、本機網路類型、測試時間及是否使用代理伺服器。先降低遠端桌面解析度與畫質，關閉持續變化的動畫或影片，再比較輸入回應。若備用網路明顯改善，應檢查本機出口壅塞或策略；若多個網路在同一時間表現一致，再提交節點與時間戳記。

解析度不符或介面縮放異常時如何處理

先在單一顯示器環境下設定常用解析度，斷線後重新建立工作階段。確認用戶端縮放模式與遠端顯示設定沒有同時放大。需要錄製問題時，請同時保留用戶端視窗尺寸與遠端解析度數值。

快速鍵或符號輸入不一致時如何處理

核對本機與遠端鍵盤配置，先使用純文字編輯器測試字母、數字、符號與組合鍵。問題只出現在特定應用程式時，記錄應用程式名稱與快速鍵；所有應用程式都異常時，附上兩端配置與用戶端版本資訊。

工作階段中斷後應立即重新啟動節點嗎

不要立即重新啟動。先確認本機網路是否切換、裝置是否休眠、VNC 是否中斷但 SSH 仍可連線，並記錄中斷時間。能透過 SSH 存取時，先保存工作狀態與相關日誌；兩種協定都無法連達時，再透過控制台提交工單。

重新連線前應保留哪些資訊

保留節點、協定、本機網路、用戶端版本、最後成功時間、中斷時間與原始錯誤訊息。重新連線時只變更一個條件，例如切換網路或降低解析度，並記錄結果，避免多項變更使比較失效。

儲存責任

儲存、備份與租期結束前匯出

實體節點上的工作目錄適合建置與實驗，但不應成為程式碼、憑證、模型或建置產物的唯一副本。資料遷入、外部備份與最終匯出需要由使用團隊納入專案計畫。

01

遷入前分類

將資料分為可從儲存庫恢復、可從相依套件來源重建、必須備份與禁止上傳四類。估算專案、相依套件、Derived Data、封存與日誌的峰值容量，不要只看原始碼大小。

02

建立快照外部備份

關鍵程式碼、憑證、模型、資料集與最終產物應保存至團隊管理的外部備份位置。定期抽查恢復結果，確認備份不只是檔案清單，而是包含可用內容。

03

管理敏感憑證

依最小必要權限設定憑證，區分人工操作與流水線用途。不要寫入 shell 歷史記錄、儲存庫、一般環境檔案或建置產物；輪換後及時刪除舊副本。

04

控制快取增長

為相依套件快取、Derived Data、模擬器資料與封存設定保留規則。刪除前先確認內容可重新產生，磁碟不足時優先處理過期快取與已回傳產物。

到期前

租期結束前操作清單

  • 匯出尚未推送的程式碼、資料集、模型、封存與測試結果
  • 驗證外部副本的檔案數量、大小與關鍵校驗值
  • 停止 Runner，並從流水線移除對應執行節點
  • 撤銷權杖、SSH 金鑰授權與臨時存取憑證
  • 刪除節點上的業務資料、秘密檔案與不再需要的日誌
  • 在控制台核對租期、續期狀態與訂單結束時間

支援工單

提交可直接重現問題的工單

租用節點發生故障時，請優先登入控制台提交工單。控制台可將問題與訂單關聯，方便核對機型、節點與交付狀態。無法進入控制台時，您可以寄送電子郵件至 support@armmacs.com。

前往控制台提交工單 寄送支援郵件
ticket-evidence.txt 
訂單號碼：
機型：
節點：
問題類型：
發生時間與時區：
最後成功時間：
重現步驟：
預期結果：
實際結果：
原始錯誤訊息：
最近一次設定變更：
本機網路狀態：
附件：已脫敏日誌 / 螢幕截圖

重現步驟必須可執行

依實際順序寫出連線方式、執行命令、目標專案與失敗階段。若問題不是每次都發生，請說明發生頻率與已驗證的比較條件。

時間戳記必須包含時區

使用完整日期、小時、分鐘與時區。只寫「剛才」或「今天」無法與節點事件及 Runner 日誌準確對應。

附件先進行脫敏

螢幕截圖與日誌不得包含密碼、私鑰、權杖、憑證密碼與業務資料。保留原始錯誤訊息、結束代碼與必要上下文即可。

準備開始診斷

節點、時間戳記與日誌都準備好了

登入控制台關聯訂單並提交工單。帳單僅以美元結算，支援 USDT-TRC20 與 Visa / Mastercard / Amex（經 Stripe），實際可用的支付閘道以控制台回傳結果為準。

立即提交技術支援工單 立即租用雲端 Mac