依命令與錯誤關鍵字定位

從連線節點到交付 iOS 建置產物。

面向首次使用者、發佈工程師與 CI/CD 維護人員。輸入命令、錯誤片段或工作名稱，先縮小問題範圍，再依預期輸出逐項核對。

目前顯示 8 個操作入口。

立即租用 Mac 建置節點 聯絡技術團隊
RUNBOOK / OAK-06 建置節點驗收索引
01
連線入口SSH · VNC · 螢幕共享
核對
02
建置環境Xcode · 簽署資產 · 快取
核對
03
工作執行runner 標籤 · 隔離目錄
核對
04
交付結果archive · export · logs
封存
排查原則 一次只變更一個變數
操作入口

先依症狀進入對應卷宗

每個入口都提供核對對象、命令或觀察指標。篩選只會變更下方入口，不會隱藏完整操作章節。

CONNECTION

首次連線與本機檢查

從控制台取得連線資訊，核對 SSH、圖形介面、密碼與時區。
BUILD

iOS 自動化封存與匯出

確認 Xcode 工具鏈、簽署輸入、封存路徑與建置產物保存規則。
AUTOMATION

CI/CD runner 接入

區分平台註冊、節點標籤、並行上限與每次工作的工作目錄。
DISPLAY

遠端畫面調校

依解析度、色彩、影格率與網路抖動逐層排除互動卡頓。
GLOSSARY

建置環境術語

統一節點、runner、快取與簽署資產的含義，減少協作歧義。
DIAGNOSTICS

命令式故障診斷

將網路、磁碟、Xcode 與簽署問題整理為命令、預期結果與分支。
ESCALATION

整理工單資料

提交區域、時間、工作編號與去識別化日誌，讓支援人員重現路徑。
STORAGE

快取與產物空間檢查

區分可重建快取、封存結果與必須保留的發佈產物。
首次連線

先確認入口，再變更節點設定

連線資訊以控制台目前的執行個體詳細資料為準。不要從舊工單、聊天記錄或歷史腳本複製位址與憑證。

建議順序 · 4 項

首次登入驗收單

先建立一種穩定連線，再檢查密碼與時區。不要同時切換網路、解析度和驗證方式，否則難以判斷是哪個變數造成變化。

  1. 01

    從控制台讀取目前連線資訊

    核對節點區域、主機位址、連接埠、使用者名稱與執行個體狀態。憑證只保存在受控的密碼管理工具中，不要放入程式碼儲存庫或建置日誌。

  2. 02

    先用 SSH 驗證基礎連線

    執行 ssh -v user@host 查看解析、握手與驗證階段。若在建立連線前逾時，先檢查本機網路與連接埠；若驗證失敗，再核對使用者名稱與目前憑證。

  3. 03

    依工作選擇圖形連線

    需要操作 Xcode 介面時，使用 VNC 或螢幕共享。先維持預設解析度與色彩設定，確認鍵盤、滑鼠及剪貼簿運作正常後，再調整畫質。

  4. 04

    完成首次登入檢查

    變更初始密碼，執行 date 與 systemsetup -gettimezone 核對時間與時區，並確認專案目錄歸屬目前工作使用者。

自動化封裝

將建置輸入與產物路徑寫入卷宗

一次可重現的 iOS 建置，需要固定工具鏈、專案入口、簽署資產、封存參數與匯出位置。只記錄「建置失敗」不足以供複查。

01 / TOOLCHAIN

鎖定 Xcode 命令列工具

先執行 xcode-select -p 與 xcodebuild -version，確認腳本實際呼叫的開發者目錄與 Xcode 版本。切換版本後重新執行這兩項，不要依賴終端機視窗標題判斷。

02 / SIGNING

分離憑證、私密金鑰與描述檔

簽署資產應依專案與環境控管存取範圍。匯入後使用 security find-identity -v -p codesigning 檢查可用身分，不要將憑證密碼輸出到流水線日誌。

03 / ARCHIVE

明確指定 workspace、scheme 與封存路徑

腳本應明確指定 workspace 或 project、共用 scheme、configuration 以及 -archivePath。在建置機上不要依賴上一次 Xcode 圖形介面的臨時選擇。

04 / EXPORT

同時保存匯出結果與日誌

透過 -exportArchive 和受版本控制的匯出設定產生產物。保存封存檔、匯出結果、建置日誌及提交識別碼，失敗時也保留可去識別化的診斷資訊。

BUILD RECORD 封存命令骨架 
xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -archivePath "$PWD/output/App.xcarchive" \
  clean archive
輸入提交識別碼、依賴鎖定檔、Xcode 版本、scheme
輸出封存目錄、匯出目錄、原始日誌、工作編號
失敗時保留退出碼、第一個錯誤區段、環境版本，不保留敏感值
CI/CD 接入

runner 註冊只是開始，隔離規則決定能否長期執行

OakVM 節點是獨享實體機，並非虛擬機。透過增加獨享節點擴充並行量；同一節點上的工作仍應明確劃分佇列、標籤與工作目錄邊界。

GITHUB ACTIONS

使用標籤將專案路由至指定節點

  • 在儲存庫或組織範圍建立 self-hosted runner，並記錄註冊歸屬。
  • 使用區域、晶片與用途標籤，例如將專案發佈與日常測試分開。
  • 工作流程透過 runs-on 精確匹配，不使用含義模糊的通用標籤。
  • 工作結束後清理暫存鑰匙圈、暫存目錄及僅本次執行需要的環境變數。
GITLAB CI

清楚標示 runner 範圍與工作標籤

  • 確認 runner 屬於執行個體、群組還是專案，避免無關專案取得執行機會。
  • 在工作中宣告 tags，並關閉不需要的未標記工作接收能力。
  • 為快取設定專案層級索引鍵，避免不同分支或不同應用程式共用不相容的結果。
  • 保留工作編號、提交識別碼與 runner 名稱，方便對應節點日誌。
GENERIC RUNNER

通用 runner 先定義生命週期

  • 註冊腳本、服務啟動方式與日誌位置應寫入團隊執行手冊。
  • 每次工作建立獨立工作目錄，結束後依保留策略處理快取與產物。
  • 為同一實體節點設定明確的並行上限，避免多個大型封存工作爭用資源。
  • 節點全年 365 天正常運作，工作重試仍應設定上限並記錄失敗原因。

隔離基線：分別管理專案目錄、建置快取、簽署資產與產物目錄。不要以清空整台節點作為日常隔離手段，也不要讓兩個專案共用同一組可寫入的簽署目錄。

遠端畫面

從畫面負載逐層排查至網路連線

VNC 與螢幕共享的主觀卡頓不一定來自節點運算負載。依固定順序測試，可以區分編碼壓力、本機網路抖動與背景工作爭用。

  1. 01

    降低解析度

    先將顯示解析度降至目前操作所需的最低等級，關閉不使用的額外顯示區域。若回應明顯改善，問題更可能與畫面編碼量有關。

    觀察指標與視窗拖曳
  2. 02

    減少色彩與動態內容

    暫停影片、動畫預覽與持續重新整理的監控視窗。建置時關閉不必要的模擬器畫面，觀察靜態編輯操作是否恢復穩定。

    比較靜態與動態畫面
  3. 03

    控制預期影格率

    程式碼編輯與發佈操作通常不需要高影格率。先以輸入回應與文字清晰度為目標，再逐步提升畫面流暢度。

    記錄輸入延遲變化
  4. 04

    檢查網路抖動

    對節點位址執行連續的短時延遲測試，關注波動與封包遺失，而不只查看單次最低值。切換本機網路後，使用相同樣本數重新測試。

    保留樣本摘要
  5. 05

    確認團隊共享方式

    同一項工作只保留一名主要操作者，其他成員透過建置日誌與產物記錄協作。多人同時操作圖形介面會增加情境衝突。

    明確目前操作者
術語小詞典

先統一詞義，再討論設定與邊界

以下術語用於 OakVM 頁面、控制台與支援溝通。它們描述交付形式與工作流程，不代表第三方平台對服務的背書。

實體節點
直接承載 macOS 與建置工作的 Apple Silicon 實體裝置，是訂單對應的運算單元。
獨享
租用期間，節點運算資源由目前訂單使用，不與其他客戶的工作共用同一台實體機。
雲端 Mac
部署於資料中心、透過網路存取的 Mac 環境，可用於圖形操作、命令列建置與自動化工作。
非虛擬機
訂單交付的是獨享實體機，不是從共用主機切分出的虛擬運算執行個體。
VNC
遠端查看與操作 macOS 圖形介面的其中一種連線方式，體驗會受解析度、畫面變化與網路抖動影響。
self-hosted runner
註冊至 CI/CD 平台，在自有或租用節點上接收並執行流水線工作的執行代理程式。
建置快取
為減少重複下載或編譯而保留的資料，例如依賴快取與 DerivedData；它應可失效並可重建。
簽署資產
完成應用程式簽署所需的憑證、私密金鑰、描述檔及相關存取權限，應依最小權限原則管理。
故障診斷

每項檢查都記錄命令、預期輸出與異常分支

先保存原始退出碼與第一個有效錯誤，再進行修復。連續執行多種清理命令會遺失問題現場，也可能將依賴錯誤誤判為節點故障。

雲端 Mac 常見故障命令式檢查清單
檢查對象 命令或動作 預期結果 異常分支
網路解析與可達性 ping -c 20 host
ssh -v user@host		 位址解析一致；樣本沒有持續封包遺失；SSH 能進入握手與驗證階段。 解析錯誤時核對位址；連線前逾時則更換本機連線重新測試；驗證失敗時只檢查目前使用者名稱與憑證。
磁碟與建置空間 df -h
du -sh ~/Library/Developer/Xcode/DerivedData		 目標磁碟區有足夠空間保存原始碼、依賴、封存檔與匯出結果；快取大小在團隊門檻內。 先移轉必須保留的產物，再依專案刪除可重建快取；不要直接刪除無法確認歸屬的封存目錄。
Xcode 工具鏈 xcode-select -p
xcodebuild -version		 開發者目錄與版本和流水線記錄一致，命令可正常回傳。 路徑錯誤時明確切換工具鏈；版本不符時停止工作，避免產生無法比較的封存結果。
專案與 scheme xcodebuild -list -workspace App.xcworkspace 目標 scheme 可見，且用於自動化的 scheme 已共用。 清單為空時檢查工作目錄與依賴產生步驟；scheme 不可見時檢查專案共用設定與名稱大小寫。
簽署身分 security find-identity -v -p codesigning 目前工作所需的簽署身分可見，輸出不包含因失效或重複選擇造成的歧義。 身分缺失時檢查匯入範圍、鑰匙圈存取與描述檔匹配關係；不要將私密金鑰或密碼貼到公開頁面。
封存與匯出 保留 xcodebuild 退出碼、封存路徑與匯出日誌。 封存目錄存在，匯出結果與提交識別碼、工作編號已建立對應關係。 從日誌中的第一個 error 開始排查；分別判斷編譯、簽署、封存與匯出階段，不要用最後一行概括整個失敗。
RULE 01

一次變更一個變數

切換網路後維持畫面設定不變；切換 Xcode 後維持原始碼提交不變。如此才能比較前後結果。

RULE 02

保留第一個有效錯誤

後續錯誤通常是連鎖結果。記錄最早出現的錯誤區段、退出碼與對應命令。

RULE 03

先將日誌去識別化再分享

移除主機憑證、權杖、私密金鑰內容與專案敏感路徑，同時保留時間、工作編號與工具版本。

升級支援

無法自行定位時，提交一份可複查的工作記錄

已有使用者請優先登入控制台提交工單；無法登入時，寄送電子郵件至 support@oakvm.com。兩種管道都不需要在公開頁面貼上連線憑證。

SUPPORT PACKET 建議附上 6 項資訊
01節點區域

新加坡、日本（東京）、韓國（首爾）、香港、美國東部或美國西部。

02發生時間

註明日期、時間與時區，確保節點日誌能夠對齊。

03工作編號

提供訂單、執行個體或 CI 工作中的可識別編號。

04重現步驟

列出執行入口、命令，以及問題出現前最後一個成功步驟。

05預期與實際結果

分別描述預期輸出與實際輸出，不要只寫「無法使用」。

06去識別化日誌

保留錯誤情境、退出碼與版本，移除憑證、權杖與私密金鑰內容。

獨享實體機 · 非虛擬機 · USD 結算

需要一台可接入現有流水線的雲端 Mac？

選擇 OakVM M4 或 OakVM M4 Pro，在六個可選節點區域中設定租用期間。所有區域全年 365 天正常運作，實際可用性以控制台即時回傳為準。

立即租用 Mac 建置節點 查看價格與設定