工程支援流程

先定位故障發生在哪個階段,再決定是否升級處理

VMRunner 提供獨享 Apple Silicon 實體節點。連線失敗、建置異常、簽署中斷、磁碟需求、節點切換諮詢與帳單核對,都應從可重現的資訊開始,而不是反覆重新啟動或重複提交工單。

  • 連線失敗
  • 建置異常
  • 磁碟需求
  • 節點諮詢
  • 帳單核對
執行診斷

建置節拍診斷板

節點可回應
  1. 01
    連線交握 核對節點位址、連接埠、主機指紋與憑證
    檢查
  2. 02
    環境基準 記錄系統時間、磁碟剩餘空間與工具版本
    檢查
  3. 03
    重現工作 使用相同分支、命令與參數再次執行
    執行
  4. 04
    整理記錄 保留第一個錯誤及其前後相關輸出
    擷取
  5. 05
    升級處理 提交訂單識別碼、節點、時間與預期結果
    工單
實體節點使用 1 個訂單 = 1 台獨享節點
首次排查順序

六項基準檢查,比直接清除環境更快

先保留現場,再逐項縮小範圍。每完成一項都記錄結果,避免在連線、系統與專案設定之間反覆猜測。

  1. 01

    核對連線憑證

    確認節點位址、使用者名稱、連接埠和金鑰檔案來自目前訂單。若主機指紋變更,先核對節點資訊,不要直接忽略驗證。

    ssh -v vmrunner-node
  2. 02

    檢查網路可連通性

    分別驗證 DNS、目標連接埠與本機網路。切換網路後再次測試,可區分本機出口、路由與節點連線問題。

    nc -vz node.example 22
  3. 03

    查看磁碟剩餘空間

    同時查看系統磁碟區、工作目錄與快取目錄。建置失敗不一定發生在磁碟寫滿之後,剩餘空間不足也可能觸發相依套件解壓縮或封存異常。

    df -h
  4. 04

    核對系統時間

    時間偏差會影響憑證驗證、權杖有效期限與相依套件下載。記錄系統時區與目前時間,再與工作記錄中的時間戳記比對。

    date && systemsetup -gettimezone
  5. 05

    固定開發工具版本

    記錄 Xcode、Command Line Tools、Ruby、Fastlane 與套件管理器版本。重現過程中不要同時升級多個元件。

    xcodebuild -version
  6. 06

    保留第一個有效錯誤

    從工作開始的位置往後尋找第一個錯誤,不要只截取最後一行。最後出現的失敗通常是上游錯誤造成的結果。

    tee build.log
命令列重測

使用相同命令留下可比較的輸出

以下命令分別涵蓋 SSH 連線、Xcode 建置與 Fastlane 流程。複製後依專案實際的 scheme 與 lane 調整,不要在公開工單中附上金鑰或完整權杖。

build-session · ssh / xcodebuild / fastlane
連線與環境基準
ssh -v vmrunner-node
sw_vers
date
df -h
xcode-select -p
xcodebuild -version
Xcode 建置重現
set -o pipefail
xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  clean build | tee xcodebuild.log
Fastlane 輸出節錄
bundle exec fastlane beta --verbose | tee fastlane.log
grep -n -E "error:|failed|Exit status" fastlane.log
Xcode 與簽署

先分清編譯失敗、封存失敗還是簽署失敗

同一條流程可能依序經過相依套件解析、編譯、測試、封存與匯出。先確認失敗階段,再檢查對應設定。

憑證

憑證有效性

檢查憑證是否能在目前的 Keychain 中看見、是否仍在有效期限內,以及私密金鑰是否能與憑證正確配對。只看見憑證名稱不代表簽署鏈完整。

security find-identity -v -p codesigning
Keychain

解鎖鑰匙圈

非互動式工作需要在 Runner 工作階段中明確解鎖指定的 Keychain,並確認簽署工具能存取私密金鑰。不要將密碼直接寫入儲存庫或建置記錄。

security list-keychains -d user
描述檔

描述檔配對

核對 Bundle Identifier、憑證類型、目標環境與描述檔涵蓋範圍。不要在同一個 target 中交叉使用自動簽署與手動簽署。

xcodebuild -showBuildSettings
快取

清理 DerivedData

只有在錯誤指向舊索引、模組快取或中間產物時,才清理 DerivedData。先記錄路徑與現象,避免把穩定可重現的問題清成偶發問題。

xcodebuild clean
命令列工具路徑也要納入記錄

同時執行 xcode-select -pxcrun xcodebuild -version。若圖形介面與 Runner 使用不同的 Xcode 路徑,同一個專案可能出現不同結果。

CI/CD 排查

Runner 能啟動,不代表工作環境已經一致

持續整合問題通常來自帳號權限、環境變數作用域、快取歸屬、並行競爭或產物回傳路徑。逐項核對比反覆註冊 Runner 更有效。

驗證

Runner 權限

確認執行帳號可以讀取儲存庫、寫入工作目錄、存取所需的 Keychain,並能執行建置腳本。比較互動式終端機與服務程序的使用者身分。

whoami
環境

環境變數

核對變數是否注入目前的 job,而不是只存在於登入 shell。輸出變數名稱清單即可,不要把變數值寫入記錄。

env
快取

快取目錄

檢查相依套件快取、DerivedData 與建置目錄是否由目前帳號擁有。快取鍵應包含工具版本與鎖定檔摘要,避免跨版本重複使用。

du -sh
工作

並行工作

確認多個工作沒有共用同一個工作目錄、模擬器、輸出檔名或 Keychain 狀態。先以單一並行數重測,再逐步恢復並行。

ps aux
產物

建置產物回傳

核對封存實際路徑、上傳步驟結束代碼、檔案權限與保留規則。建置成功但沒有產物時,應先檢查路徑是否遭腳本改寫。

find
遠端工作階段

畫面卡頓與節點運算效能要分開判斷

遠端畫面會受到本機網路、編碼、解析度與工作階段狀態影響。先確認命令列工作是否正常執行,再判斷問題是否只發生在圖形工作階段。

01 · 延遲

建立本機網路基準

記錄有線與無線網路下的往返延遲、抖動與封包遺失。關閉佔用上行頻寬的同步工作後再次測試,避免將本機壅塞誤判為節點故障。

02 · 畫面

降低解析度後比較

先降低解析度與更新需求,觀察輸入延遲是否改善。若命令列建置耗時穩定而畫面仍卡頓,優先排查遠端工作階段連線。

03 · 輸入

核對鍵盤配置

確認本機鍵盤配置、修飾鍵對應與遠端輸入法狀態。快速鍵異常時,先在純文字編輯器中測試,不要直接在開發工具中判斷。

04 · 工作階段

檢查鎖定與重新連線

確認原工作階段是否仍處於鎖定或中斷狀態。先安全中斷舊工作階段,再重新連線;不要同時建立多個圖形工作階段爭用同一個桌面。

提交支援請求

一次提供六類完整資訊,工單才能直接進入排查

支援請求不需要私密金鑰。請提供可關聯訂單、定位時間與重現錯誤的資訊,並在提交前完成必要的去識別化。

訂單識別碼
可在控制台核對的訂單編號
節點城市
新加坡、日本(東京)、韓國(首爾)或香港
發生時間
包含時區的故障開始時間與最近一次重現時間
重現步驟
從哪個命令或操作開始,依序列出關鍵步驟
記錄片段
第一個錯誤、結束代碼及其前後相關輸出,完成去識別化
預期結果
說明原本應產生的建置、簽署、工作階段或帳單結果
升級處理

何時應停止自行排查並聯絡支援

連線入口持續無法連線

已核對目前訂單憑證,並從另一個網路重測,但目標連接埠仍無法建立連線。

同一工作穩定重現

已固定程式碼版本、命令與工具版本,錯誤仍在相同步驟出現。

節點或磁碟需求變更

需要核對節點選擇、儲存空間擴充或工作資源界線,且現有訂單資訊不足以判斷。

帳單資訊無法對應

訂單識別碼、計費週期或付款記錄與控制台顯示無法對應,需要人工核對。

開始執行

需要新的獨享實體節點?直接選擇機型與週期

三種 Apple Silicon 設定皆可按日、週、月、季租用。新加坡、日本(東京)、韓國(首爾)與香港四個資料中心可供選擇,實際可用狀態以控制台即時回傳為準。