連線成功不代表環境已準備就緒
SSH 連線成功後，接著檢查 Ruby、Bundler 與專案相依套件。優先使用儲存庫鎖定的版本，避免以全域升級指令變更整個團隊的建置環境。
驗收項目：同一使用者可以進入儲存庫並執行安裝相依套件的指令。
建置串接指南
將節點接入 CI 流程
整台實體 Mac 專供團隊使用。先確認連線，再固定工具鏈，最後註冊 Runner。依照這份清單安排前 30 分鐘；專案相依套件下載與完整建置所需時間則視專案而定。
尚未租用節點？Apple Silicon M4 / M4 Pro，整台專屬使用，非虛擬機，每天 $20.1 起。
接機檢查 · 建議優先完成
先確認能獨立連回節點
註冊自動化工作前，先保留一種可用的圖形介面連線，再驗證 SSH。唯一的連線方式尚未確認可用前，請勿關閉密碼登入。
- 01
取得連線資訊
登入控制台，前往對應的執行個體詳細資料，確認節點編號、位址、使用者名稱與連線說明。登入資訊僅供在帳戶內查看，請勿複製到支援單內容、CI 設定或程式碼儲存庫。
- 02
開啟桌面並變更密碼
從執行個體詳細資料開啟瀏覽器遠端桌面，確認畫面顯示的是該執行個體的 macOS 環境。首次登入後變更系統使用者密碼，並使用團隊的密碼管理工具保存；也請確認續租與登入資訊輪替的負責人。
- 03
設定遠端登入
在 macOS「系統設定」的「共享」選項中檢查「遠端登入」，並只允許必要使用者存取。使用控制台提供的位址與連接埠連線；若使用的不是預設連接埠，請在 ssh 指令中明確指定。
- 04
驗證金鑰登入
在工作電腦上建立專用 SSH 金鑰，只將公開金鑰附加至節點的 authorized_keys。保留目前的連線工作階段，另開終端機確認金鑰登入成功，再調整其他驗證設定。
檢查節點端權限
mkdir -p ~/.ssh
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
whoami
sw_vers
uname -m檢查結果：使用者名稱應與執行個體登入資訊一致，系統版本應符合專案需求，Apple Silicon 環境的架構輸出應為 arm64。首次使用 SSH 連線出現指紋提示時，請先確認主機身分；請勿為了連線而直接停用主機金鑰驗證。
連線後 · 先執行一次指令
先讓命令列順利執行，再交給 CI
以下是輸出格式範例，並非節點的實際測試結果。範例專案名稱為 TeamApp；請替換成儲存庫中的 workspace、scheme 與簽章設定。
glide-m4 — ssh
$ ssh "$NODE_USER@$NODE_ADDRESS"
Authenticated using "publickey".
$ uname -m
arm64
$ xcodebuild -workspace TeamApp.xcworkspace \
-scheme TeamApp -configuration Release \
-destination 'generic/platform=iOS' \
-archivePath build/TeamApp.xcarchive archive
** ARCHIVE SUCCEEDED **
$ bundle exec fastlane gym --scheme TeamApp
Successfully exported and compressed dSYM file
Successfully exported and compressed ipa file
Successfully generated ipa file:
build/TeamApp.ipa分別檢查封存與匯出
Archive 成功但 IPA 匯出失敗時，優先檢查匯出方式、簽章憑證與描述檔。保留第一個錯誤及其前後文，不要只截取最後一行失敗訊息。
驗收項目：目標路徑中有可供後續工作使用的建置產物。
自動化入口 · 連結團隊儲存庫
使用明確標籤將工作派送至這台 Mac
節點為專屬實體機，但專案能否平行執行仍受記憶體、磁碟與工作隔離方式影響。先以一項建置工作驗證完整流程，再增加並行數量。
GitHub Actions 自架 Runner
在儲存庫或組織的 Actions 設定中新增 self-hosted runner，選擇 macOS 與 ARM64。請依該頁面目前提供的下載、驗證及註冊指令操作，不要使用來源不明的舊安裝套件。
註冊時使用專用系統使用者，並新增 vmfly、ios-build 等用途標籤。將工作流程的 runs-on 設為對應標籤，避免工作繼續派送至共用執行環境。
runs-on: [self-hosted, macOS, ARM64, vmfly, ios-build]驗收項目：管理頁面顯示 Runner 在線上，手動觸發的工作由此節點接收。
GitLab Runner
使用與 GitLab 環境相容的 Runner 版本，依專案或群組的 Runner 建立流程取得驗證權杖。在 macOS 上使用 shell executor，並為節點加上 macos-arm64 及用途標籤。
在 CI 工作中指定相同的 tags。確認 Runner 工作目錄屬於執行使用者；憑證、相依套件快取與封存輸出也應由同一使用者存取，避免互動式終端機執行成功、自動化工作卻失敗。
ios_archive:
tags:
- macos-arm64
- ios-build
script:
- bundle exec fastlane gym驗收項目：測試工作能輸出系統架構，並使用專案所需的工具鏈。
也要驗證重新啟動後能恢復服務
GitHub Runner 可在註冊目錄中使用服務指令碼執行 ./svc.sh install 與 ./svc.sh start。GitLab Runner 則依安裝方式執行 gitlab-runner install 與 gitlab-runner start。同一個 Runner 請勿重複安裝兩套自動啟動機制。
在 macOS 上以使用者 LaunchAgent 執行的服務，通常需要該使用者已登入。請檢查服務實際產生的設定與執行身分，不要把「電腦已開機」當成「建置使用者已登入」。沒有發佈工作時，先驗證重新啟動後服務是否上線、路徑與鑰匙圈是否可用，以及產物能否匯出。
將簽章資料妥善控管
透過團隊核准的安全方式匯入建置憑證與描述檔。憑證必須包含對應的私密金鑰；僅匯入公開憑證無法完成簽章。將解鎖密碼與自動化權杖存放於 CI 的受保護變數，並限制可使用這些資料的分支與工作。
使用 fastlane match 的團隊，應沿用既有的儲存與存取規範；CI 讀取既有簽章資料時，優先採用唯讀模式。先確認 bundle identifier、目標團隊、匯出方式及描述檔效期一致，再排查封存指令本身。
無人值守工作必須能存取指定的鑰匙圈。請勿將長期明文密碼寫入指令碼，也不要在日誌中輸出所有環境變數。分享日誌前，請移除私密金鑰、權杖、密碼及簽章資料。
工具鏈檢查 · 確保版本可重現
固定 Xcode 路徑，分開管理快取
先檢查節點目前的環境，再決定是否安裝專案所需版本。不要假設互動式桌面選取的 Xcode，就是 Runner 程序正在使用的版本。
檢查目前選取的版本；切換路徑時請替換成實際安裝目錄
xcodebuild -version
xcode-select -p
xcrun simctl list runtimes
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcodebuild -checkFirstLaunchStatus並存多個版本
為不同版本的 Xcode App 使用容易辨識的檔名。共用節點上的多個專案若使用不同版本，建議優先在工作中設定 DEVELOPER_DIR，而非每次建置都變更系統的全域選擇。
驗收項目：在 Runner 實際工作的日誌中輸出 xcodebuild -version，並確認符合專案需求。
模擬器執行環境
在 Xcode 設定中安裝專案所需的執行環境，安裝後使用 xcrun simctl list 檢查可用裝置。UI 測試請明確指定 destination，避免測試工作等待不存在的系統版本或裝置。
驗收項目：先單獨啟動目標模擬器，再執行一組最小規模的 UI 測試。
DerivedData 與建置產物
為專案指定獨立的 DerivedData 路徑，保留必要快取並設定產物保留政策。清理前先停止相關建置，確認目錄內容與磁碟使用量；不要直接對共用工作目錄執行遞迴刪除。
驗收項目：相依套件、快取與 IPA 各有明確目錄，且磁碟剩餘空間足以進行下一次封存。
接入自動化前，請先完成 Xcode 首次啟動所需元件的安裝。如果互動式終端機找得到指令，但 CI 顯示找不到，請比較執行使用者、PATH、工作目錄與 Shell 初始化方式，不要一開始就重裝所有相依套件。
圖形介面連線 · 保留備用方式
依偵錯工作選擇連線方式
瀏覽器桌面適合首次設定；需要長時間操作圖形介面時，可比較不同用戶端；無人值守建置則交由 SSH 與 Runner 處理。請勿將任何一種圖形介面連線當成保存程式碼與建置產物的唯一位置。
| 連線方式 | 適用工作 | 建議起始設定 | 發生卡頓時優先檢查 |
|---|---|---|---|
| 瀏覽器遠端桌面 | 首次登入、系統設定、暫時查看建置狀況 | 從控制台的執行個體詳細資料進入；先使用單一螢幕與適中解析度 | 本機網路、瀏覽器縮放，以及是否同時開啟多個桌面工作階段 |
| VNC 用戶端 | 長時間操作圖形介面、調整用戶端編碼與畫質 | 依照執行個體的連線說明設定；先選擇自動編碼或平衡畫質 | 逐步降低畫質或色深，避免同時變更多個參數 |
| macOS 螢幕共享 | 從本機 Mac 進行桌面偵錯與輔助操作 | 使用執行個體支援的連線方式；從單一螢幕、1920 × 1080 開始 | 高解析度、動態畫面與跨網路連線都可能影響效能，先降低解析度再比較 |
分開記錄「畫面延遲」與「建置緩慢」
桌面畫面殘影不代表編譯工作變慢。透過 SSH 查看工作輸出與資源使用量，確認建置是否仍在進行。反之，桌面操作流暢也不代表簽章、相依套件下載或遠端儲存庫連線正常。
連線異常時，記錄使用方式、發生時間與時區、本機網路類型，以及 SSH 是否仍可連線。若要變更遠端登入或螢幕共享設定，請保留目前可用的工作階段，避免變更後失去所有連線方式。
訂閱管理 · 先核對訂單
依建置安排處理帳單變更
帳戶、執行個體與帳單皆透過控制台管理。先核對訂單編號與執行個體編號，再處理續租或規格調整，避免將發佈工作排在尚未確認的租用期間之後。
續租與到期
在控制台查看目前的訂閱、到期時間與待付款帳單。付款完成後，請再次確認訂閱狀態。到期前將程式碼、憑證備份與建置產物同步至團隊控管的位置，不要將即將到期的節點當成長期備份空間。
未續租的節點到期後將停止服務並清除整台磁碟。需要保留的資料請提前移出。
升級與擴充儲存空間
Glide M4 配備 Apple Silicon M4、16GB 記憶體與 256GB SSD；Cruise M4 Pro 配備 Apple Silicon M4 Pro、64GB 記憶體與 2TB SSD。升級前請透過支援單確認處理方式，勿將其視為原機可即時升級記憶體。
下單時請確認 +1TB SSD、+2TB SSD 與 Thunderbolt 5 並聯選項；已租用節點如需調整，請先提交支援單確認。
付款與入帳確認
僅支援 USDT-TRC20 與 Visa / Mastercard / Amex（透過 Stripe），一律以美元計價。實際可用的付款閘道以介面回傳為準；確認付款後才會開始配置實體機。
付款狀態未更新時，請提供訂單編號與付款憑證；使用 USDT 付款還需附上交易雜湊值。請勿重複付款，也不要傳送完整卡號。