01

在控制台取得憑證

核對訂單識別碼、節點、裝置名稱與存取方式。憑證僅保存在受控的密碼管理工具中，不透過群組聊天或公開文件轉發。
02

執行連線前檢查

確認本地網路未封鎖所需連接埠，關閉會改寫路由的臨時代理，記錄目前的公網出口與測試時間。先使用穩定的有線網路驗證，再比較無線網路的表現。
03

校準解析度與剪貼簿

先使用接近本地螢幕的解析度，確認文字清晰度、按鍵配置與雙向剪貼簿。高解析度會增加弱網路下的畫面更新負擔，應先確保互動穩定。
04

驗證斷線重連

主動中斷一次工作階段後重新連線，檢查正在執行的指令是否仍在、圖形工作階段是否恢復至原桌面。長時間工作建議放入可持續的指令工作階段或 CI/CD 工作中。
05

收緊遠端存取邊界

僅向必要成員分發存取權限，團隊成員變更後立即更新憑證。不要在腳本、儲存庫、建置日誌或截圖中保存私鑰、完整密碼與遠端控制驗證碼。

指令執行紀錄

用三項結果確認節點具備建置能力

先確認 SSH 工作階段，再執行 Xcode 建置，最後驗證自動化打包工具。範例僅展示判斷路徑，專案名稱、scheme、workspace 與匯出參數應替換為團隊自己的設定。

SSH：確認已連線至訂單對應的裝置，並記錄系統版本。
xcodebuild：明確指定 workspace、scheme 與 configuration。
fastlane：先執行唯讀檢查，再執行實際打包 lane。

build-session / assigned-node UTF-8 · zsh

$ ssh developer@assigned-mac
connection established
$ sw_vers -productVersion
current macOS version returned
$ xcodebuild -workspace App.xcworkspace \
  -scheme App -configuration Release build
Resolve Package Graph
CompileSwiftSources normal arm64
** BUILD SUCCEEDED **
$ bundle exec fastlane ios verify_build
Checking signing assets
Archive validation passed
fastlane finished successfully

Xcode 與簽署

拆開驗證版本、憑證與權限

多數簽署故障並非由單一開關造成。先固定工具版本，再檢查憑證與描述檔是否相符，最後確認自動化程序能存取所需的 Keychain 項目。

確認 Xcode 選取路徑

同時記錄圖形介面的 Xcode 版本與命令列工具路徑。存在多個版本時，建置腳本必須明確選擇，避免互動工作階段與 runner 使用不同的工具鏈。

$ xcodebuild -version
$ xcode-select -p
$ xcrun --find swift

匯入憑證與描述檔

憑證、私鑰與描述檔必須屬於同一簽署流程。匯入後先檢查有效期限、團隊資訊與目標識別碼，不要直接以正式打包工作作為第一次驗證。

憑證與私鑰成對存在
描述檔涵蓋目標識別碼
建置設定引用正確團隊

檢查 Keychain 權限

圖形工作階段中可用，不代表自動化程序也可用。應以 runner 對應的使用者，在非互動環境下檢查解鎖方式、搜尋清單與程式碼簽署存取權限。

確認執行使用者一致
限制解鎖憑證的可見範圍
避免將敏感值寫入建置日誌

定位自動化簽署失敗

保留失敗指令、目標名稱、configuration、匯出方式與第一行錯誤。不要只提交最後一行的通用失敗提示，因為其中通常缺少真正原因。

先檢查第一個簽署錯誤
比較本地與 runner 環境變數
以最小目標重現問題

工具鏈變更前的相容性核對順序
檢查對象	需要記錄	通過標準	失敗時的下一步
macOS	目前版本、可用空間	目標 Xcode 明確支援	暫停變更並核對相容性矩陣
Xcode	版本、選取路徑、SDK	命令列與圖形介面一致	修正工具路徑後重新執行最小建置
簽署材料	憑證狀態、描述檔、團隊	目標識別碼與匯出方式相符	重新匯入並檢查 Keychain 權限
專案相依套件	鎖定檔、執行環境、外掛程式版本	乾淨目錄可重複安裝	清理局部快取並保留失敗日誌

Self-hosted runner

讓自動化工作可隔離、可清理、可重現

runner 不應直接重複使用日常開發目錄。為儲存庫、相依套件快取、建置產物與暫存檔案劃分界線，才能避免一次失敗的工作污染下一次建置。

GITHUB ACTIONS 儲存庫或組織層級 runner

先以單一儲存庫驗證，再擴大工作範圍

註冊：在對應的儲存庫或組織產生短期註冊資訊，並在目標裝置上完成 runner 設定。
標籤：使用能表達晶片、用途與工具鏈的標籤，避免工作被派送至錯誤環境。
服務：以固定的非特權使用者執行，確認重新啟動後能恢復接收工作。
驗證：先執行版本檢查與最小建置，再接入封存、測試與發布工作。

GITLAB RUNNER 專案或群組層級 runner

以標籤與執行邊界控管工作來源

註冊：確認 runner 所屬的專案或群組，不要將註冊資訊保存在腳本儲存庫中。
執行器：依建置方式選擇本機執行路徑，並限制可執行的工作類型。
標籤：要求工作明確符合標籤，避免未經審核的工作進入簽署環境。
稽核：保留工作識別碼、提交版本與失敗階段，方便支援團隊重現問題。

WORK 工作目錄

每個儲存庫各自獨立，工作結束後移除暫存檔案，不重複使用來源不明的簽出目錄。

CACHE 相依套件快取

依鎖定檔或工具版本產生快取鍵，版本變更時主動失效，不無條件完整重複使用。

OUTPUT 建置產物

將產物與原始碼分開保存，成功上傳後依團隊保留策略清理本地副本。

SECRETS 敏感變數

使用平台密鑰機制注入並限制日誌輸出，不寫入專案檔案、快取或封存檔。

系統升級策略

由你安排升級，先留下可追溯的環境記錄

VMOwn 節點全年 365 天正常運作，不設定期停機。系統升級屬於使用者主動變更，應選擇不影響發布與建置的時段，並在操作前完成工具鏈相容性驗證。

升級前狀態記錄

系統與硬體: macOS 版本、晶片、統一記憶體、剩餘空間
開發工具: Xcode、命令列工具、SDK、執行環境版本
專案相依套件: 套件管理鎖定檔、Ruby、Python、Node 環境
簽署設定: 憑證狀態、描述檔、Keychain 搜尋清單
自動化工作: runner 狀態、標籤、工作目錄、最近成功的工作
復原材料: 程式碼備份、設定匯出檔、關鍵日誌、訂單識別碼

變更前

先執行一條基準流水線

升級前完成一次可重複的建置、測試與封存，記錄提交版本與結果。升級後使用相同輸入重新執行，差異才具備定位價值。

準備診斷資訊

變更失敗

停止連續修改並保留現場

記錄最後一個成功步驟與第一個失敗步驟，不要反覆刪除所有快取。整理工具版本、錯誤日誌與重現指令後提交工單。

提交控制台工單

診斷資訊清單

讓支援團隊能在相同條件下重現問題

「連線失敗」或「建置錯誤」不足以開始定位。請提供問題發生的情境、準確時間、第一個錯誤與最小重現步驟，同時移除日誌中的敏感內容。

工單附件核對表 6 REQUIRED FIELDS

節點與訂單識別碼

提供新加坡、日本（東京）、韓國（首爾）、香港或美國西部中的實際節點，以及控制台內的訂單識別碼。

系統與工具版本

記錄 macOS、Xcode、命令列工具與直接相關相依套件的版本，不必提交整台裝置的軟體清單。

發生時間與時區

寫明問題發生時間、持續時間與時區。連線問題還應註明本地網路所在地與網路類型。

第一個有效錯誤

保留錯誤前後的必要情境，優先提交第一個失敗資訊，不要只截取最後一行的結束狀態。

最小重現步驟

從已知正常狀態開始，依序寫出指令、介面操作、輸入與實際結果。

已嘗試的處理方式

說明是否重新連線、重新啟動工作、切換網路、清理局部快取或回復設定，避免重複操作破壞現場。

仍未解決

附上診斷記錄，讓支援從第一個錯誤開始排查

售前選型與一般技術問題可透過 support@vmown.com 聯絡；已有訂單的問題，請優先登入控制台提交工單，以便關聯裝置、節點與訂單記錄。

開啟聯絡頁面進入控制台管理訂單

一次理順遠端 Mac 接入、建置與故障排除

先確認你卡在哪個步驟

連線至雲端 Mac

設定開發工具

接入 CI/CD

處理系統問題

管理訂單

先驗證連線路徑，再安裝開發相依套件

在控制台取得憑證

執行連線前檢查

校準解析度與剪貼簿

驗證斷線重連

收緊遠端存取邊界