從連線到產物驗證

將雲端 Mac 接入你的建置流程

這不是概念說明，而是一套可逐項執行的操作流程。先完成獨享實體節點的身分核驗與安全設定，再準備 Xcode、簽署材料與自動化工作；遇到異常時，依統一格式收集網路輸出與建置記錄。

5 類 支援主題
6 步 自動化打包流程
2 種 可追蹤的聯絡管道
立即租用雲端 Mac 查看 Runner M4 設定
RUNNER SUPPORT ROUTE MAC-01
01
取得與核驗 連線參數、主機指紋、首次密碼
準備
02
準備建置環境 Xcode、工具鏈、簽署材料、目錄
設定
03
執行自動化工作 檢出、快取、封存、匯出、驗證
執行
04
收集診斷材料 節點、訂單、時間、指令與完整輸出
排查
所有診斷都從可重現的輸入開始
首次連線

五步完成節點身分核驗與安全設定

RunnerVM 提供的是獨享實體 Mac mini，而非虛擬機器。首次操作的重點不是盡快執行指令，而是確認連線到訂單對應的裝置，並將初始存取方式替換為團隊自己的安全設定。

  1. 01

    在控制台取得交付資訊

    核對訂單識別碼、節點區域、連線位址、SSH 連接埠、VNC 參數與初始使用者名稱。不要透過聊天工具轉發完整憑證；團隊協作時，只將必要欄位交給實際操作者。

  2. 02

    先記錄主機指紋

    將控制台顯示的主機指紋與首次 SSH 提示逐字比較。若演算法或摘要不一致，請停止連線並提交工單，不要刪除本機 known_hosts 記錄來繞過異常。

  3. 03

    建立 SSH 命令列連線

    使用訂單提供的主機、連接埠與使用者名稱連線。登入後先執行 sw_vers、uname -m 與 hostname，將系統版本、Apple Silicon 架構與裝置名稱寫入交付記錄。

  4. 04

    按需建立 VNC 遠端桌面

    在本機 VNC 用戶端填入控制台提供的位址、連接埠與密碼。首次使用預設解析度驗證鍵盤、指標與視窗縮放；確認工作階段穩定後，再提高畫面尺寸。

  5. 05

    更新密碼並限制權限

    立即更新初始密碼，檢查 SSH 公開金鑰與管理員權限，只保留任務所需的存取權。完成後重新建立 SSH 與 VNC 工作階段，確認新憑證有效，再開始匯入專案或簽署材料。

指令執行範例

從連線驗證到封存輸出

以下依常見建置工作的順序展示 SSH、xcodebuild 與 fastlane 輸出。指令中的主機、工作區、Scheme、匯出設定與 lane 都應替換為專案實際值，不可直接複製後假定適用於所有儲存庫。

  • 先確認連線目標，再切換至專案目錄。
  • 封存路徑使用任務專用目錄，避免並行工作互相覆寫。
  • 儲存完整標準輸出與結束代碼，不要只保留最後一行。
runner-build-session zsh
連線節點 SSH 
$ ssh -p 22 runner@10.0.0.12
Host key fingerprint: SHA256:…
$ sw_vers
ProductName: macOS
$ uname -m
arm64
產生封存 XCODEBUILD 
$ xcodebuild archive \
-workspace RunnerApp.xcworkspace \
-scheme RunnerApp \
-archivePath build/RunnerApp.xcarchive
** ARCHIVE SUCCEEDED **
執行自動化流程 FASTLANE 
$ bundle exec fastlane ios build
[08:42:16]: Resolving signing settings
[08:43:02]: Archive completed
[08:43:11]: Export verified
[08:43:11]: fastlane finished successfully
範例指令需依專案的工作區、Scheme、簽署方式與目錄結構調整。
環境準備

讓 Xcode、簽署材料與目錄各自可核驗

環境問題通常不在於「Xcode 能否開啟」，而在於圖形介面選擇、命令列路徑、專案宣告與簽署環境是否一致。請依下列順序檢查，更快區分工具鏈與專案問題。

01

確認 Xcode 版本與路徑

執行 xcodebuild -version 與 xcode-select -p。若節點安裝了多個版本，先確認專案需求，再切換開發者目錄，避免圖形介面與自動化工作使用不同版本。

02

驗證 Command Line Tools

執行 xcrun --find xcodebuild、xcrun simctl list 以及一次未簽署的專案解析。若工具不存在或 SDK 清單異常，請先修復工具鏈，不要直接修改專案檔案。

03

建立任務專用簽署鑰匙圈

將自動化工作使用的憑證放入獨立鑰匙圈，設定明確的解鎖步驟與最小存取範圍。不要將密碼寫入儲存庫、腳本參數或建置記錄。

04

匯入憑證與描述檔

記錄憑證名稱、有效期、團隊識別碼與描述檔 UUID，確認 Bundle Identifier 與目標設定相符。匯入後使用 security find-identity -v -p codesigning 驗證可用身分。

05

規劃建置目錄

將原始碼、依賴快取、DerivedData、Archive、Export 與記錄分開。每次任務使用唯一封存路徑；共用快取只存放可重建內容，避免將簽署材料混入快取。

自動化打包

將一次成功建置變成六個可重複階段

自動化的目標不是把本機腳本搬到遠端，而是讓輸入、環境、簽署與輸出都能重現。每個階段都應產生明確記錄，失敗時才能知道問題發生在哪一步。

  1. 01

    檢出固定的程式碼版本

    使用提交雜湊或受保護標籤，不要依賴會持續移動的分支頂端。記錄子模組版本、Git LFS 狀態與儲存庫是否乾淨。

    git checkout --detach <commit>
  2. 02

    還原並驗證依賴快取

    快取鍵至少應包含鎖定檔摘要、工具版本與架構。快取未命中時正常安裝，不要把「必須命中快取」當作建置成功條件。

    bundle check || bundle install
  3. 03

    載入簽署設定

    解鎖任務專用鑰匙圈，匯入相符的描述檔，驗證可用簽署身分。任何金鑰與密碼都不得寫入標準輸出。

    security find-identity -v -p codesigning
  4. 04

    執行 Archive

    明確指定工作區、Scheme、Configuration、Destination 與封存路徑。儲存完整記錄與 xcodebuild 結束代碼。

    xcodebuild archive …
  5. 05

    匯出交付產物

    將匯出設定納入版本管理，但不包含秘密。匯出目錄與封存目錄分離，避免重跑時覆寫原始 xcarchive。

    xcodebuild -exportArchive …
  6. 06

    驗證並登記結果

    檢查檔案是否存在、大小、摘要、簽署資訊與任務結束代碼，將產物識別碼與提交版本、Xcode 版本及記錄路徑關聯。

    shasum -a 256 build-output
遠端桌面

VNC 用於圖形操作，長時間工作交給獨立程序

遠端桌面適合完成首次圖形設定、檢查 Xcode 介面狀態，以及處理需要視覺確認的工作。建置是否持續執行，不應取決於本機 VNC 視窗是否保持連線。

連線參數

嚴格使用控制台顯示的位址、連接埠、使用者名稱與密碼。若用戶端支援連線設定檔，也不要將密碼寫入可同步的明文檔案。

調整解析度

首次連線使用預設尺寸。確認互動穩定後再逐步提高解析度；出現輸入延遲時，先降低色深與畫面尺寸，再檢查網路路徑。

鎖定工作階段

離開裝置前鎖定圖形工作階段，不要以關閉 VNC 用戶端代替鎖定畫面。團隊交接時應撤銷不再需要的存取權限。

中斷連線後的工作

持續建置應執行於 CI runner、launchd、tmux 或其他可復原的工作階段中。先進行一次主動中斷測試，確認工作與記錄仍會持續寫入。

遠端工作階段交接單 VNC / SSH
開始前 核對節點與工作階段身分

確認訂單區域、裝置名稱與目前登入使用者。

執行中 工作寫入獨立記錄

不要只依賴螢幕輸出判斷建置是否仍在執行。

離開時 鎖定工作階段並驗證背景工作

中斷連線後透過 SSH 檢查程序、記錄增長與結束狀態。

交接後 撤銷臨時權限

移除臨時公開金鑰、一次性檔案與不再需要的憑證。

網路與延遲

一次排查同時記錄連通性、路徑、解析與連接埠

網路問題需要明確記錄「從哪裡、在什麼時間、存取哪個目標、取得什麼完整輸出」。單張截圖或一句「連線很慢」無法區分本機網路、跨區路徑、DNS、連接埠策略與目標服務狀態。

PING

檢查基本往返時間與丟包

連續傳送固定數量的封包，保留最小、平均、最大延遲與丟包率。不要用一次回應代表整段連線品質。

ping -c 20 target-host
TRACEROUTE

檢查路徑變化位置

從發生問題的來源網路執行，保留完整跳數。中間節點沒有回應不代表鏈路中斷，應結合最終目標是否可達來判斷。

traceroute target-host
DNS

檢查解析結果與耗時

記錄目前 DNS 伺服器、回傳位址與查詢耗時。若不同網路的結果不一致，請同時提交兩側輸出，不要手動改寫結果。

dig target-host
PORT

檢查目標連接埠可達性

分別測試 SSH 或專案實際使用的連接埠。連線成功只代表 TCP 可達，不代表身分驗證與上層協定已完成。

nc -vz target-host 22
工單診斷包

提交時必須包含的五項資訊

NET-CHECK
問題時間
寫明本地日期、時間、時區與持續時間。
來源端位置
說明來源節點、辦公室或家用網路及電信商。
目標資訊
提供訂單識別碼、節點區域、目標主機與連接埠。
完整輸出
附上 ping、traceroute、DNS 與連接埠檢查的原始結果。
對照結果
若可行，補充另一個網路或另一個時段的相同測試。

提交前移除密碼、私密金鑰、權杖與業務資料，但不要刪除時間戳記、錯誤碼、路徑跳數或指令參數。

支援升級流程

先縮小問題範圍，再提交可追蹤工單

售前問題、一般諮詢及不涉及特定訂單的說明可以透過電子郵件傳送；涉及節點、建置失敗、連線異常或帳務記錄的問題，應登入控制台提交工單，以便關聯訂單並持續查看處理狀態。

  1. 01

    查找並執行對應指南

    依首次連線、環境準備、自動化或網路排查選擇流程。記錄已執行的步驟、指令、結果及首次出現異常的位置。

  2. 02

    整理最小重現材料

    提供訂單識別碼、節點區域、問題時間、重現步驟、預期結果、實際結果與去識別化後的完整記錄。建置問題還應註明提交版本與 Xcode 版本。

  3. 03

    在控制台提交工單

    選擇最接近問題的分類，將記錄作為附件或正文程式碼區塊提交。一張工單聚焦一個問題，避免將網路、建置與帳務異常混在同一筆記錄中。

  4. 04

    在原工單補充進度

    重新測試後繼續回覆原工單，補充新的時間、指令與輸出。緊急事件同樣透過控制台查看處理狀態，不要重複建立多張相同工單。

關聯特定訂單

控制台工單

適合連線失敗、節點異常、建置環境、帳務核對及需要持續跟進的問題。工單可關聯訂單，並保留完整處理時間軸。

  • 訂單識別碼與節點區域
  • 含時區的問題發生時間
  • 重現步驟與完整錯誤輸出
  • 已執行的排查指令與結果
登入控制台提交工單
一般諮詢

傳送支援電子郵件

適合售前選型、流程確認、安全報告及不需關聯節點的說明。郵件主旨請註明問題類別，正文避免包含密碼或金鑰。

support@runnervm.com
需要整理範本

先產生結構化說明

聯絡頁面會按售前、技術、帳務與安全事項列出必填資訊，適合在傳送郵件前檢查材料是否完整。

查看聯絡說明
常見判斷

開始排查前先確認這些界線

以下答案用於區分裝置交付、連線方式、建置工作與支援材料，減少在錯誤方向上反覆嘗試。

RunnerVM 提供的是虛擬執行個體嗎？

不是。訂單對應的是獨享實體 Mac mini 節點，裝置規格為 Runner M4：Mac Mini M4、16GB RAM、256GB SSD。遠端連線只是存取方式，不會將服務變成共享的虛擬資源。

中斷 VNC 後，建置工作會繼續嗎？

是否繼續取決於工作如何啟動。CI runner、launchd、tmux 或獨立背景程序通常不依賴 VNC 視窗；直接繫結圖形工作階段的互動工作可能受工作階段狀態影響。正式使用前應主動中斷一次，並檢查程序、記錄與結束狀態。

首次連線前需要準備什麼？

準備可用的 SSH 與 VNC 用戶端、團隊內部的憑證保管方式、專案要求的 Xcode 版本、簽署材料清單，以及不會寫入儲存庫的秘密管理流程。取得交付資訊後，先核對主機指紋與裝置身分。

排查問題會改變訂單計費週期嗎？

不會自動改變。Runner M4 可按日、週、月或季下單，訂單週期與處理狀態以控制台記錄為準。如需核對特定訂單，請在控制台提交關聯該訂單的工單。

工作完成後應清理哪些內容？

先匯出需要保留的封存檔、產物與去識別化記錄，再清理原始碼工作區、臨時簽署鑰匙圈、描述檔、臨時公開金鑰、存取權杖及專案快取中的敏感資訊。不要將明文憑證保留在 shell 歷史記錄或腳本參數中。

如何判斷應選擇哪個節點？

優先從實際辦公室網路或 CI 來源測試目標區域的延遲與路徑，再結合團隊時區與產物傳輸方向選擇。Runner M4 可在新加坡、日本東京、韓國首爾、香港與美國東部五個節點訂購，實際可用性以控制台即時回傳為準。

下一次建置

從一台可核驗的雲端 Mac 開始

選擇 Runner M4 與目標區域，完成訂單後依本頁步驟核驗連線、準備工具鏈，並執行第一個可重複的建置工作。

立即租用雲端 Mac 聯絡 RunnerVM 支援