確認區域與連線入口
核對訂單中的 SG、JP、KR 或 HK 節點代碼，並記錄交付位址。節點會影響存取路徑，但不應透過修改專案相依性來掩蓋網路問題。
- 驗證點
- 訂單節點與交付節點一致
- 記錄項目
- 節點代碼、測試來源網路
從核對事實開始排查
將交付、連線與建置問題拆解為可執行步驟
先確認實體節點、設定、租用期間與憑證，再檢查網路、開發環境與工作記錄。每一步都提供輸入、驗證點與完成標準，適用於首次啟用、日常建置與故障定位。
需要連線方式說明時，可以先閱讀遠端存取流程；若涉及現有訂單，請在工單中附上訂單編號與節點代碼。
任務登機檢查板
BUILD SUPPORT / 04
排查順序已就緒
輸入
驗證
復原
機器與節點
設定、區域與租期逐項符合訂單
先核對
帳戶與工作階段
分開保存位址、系統帳戶與一次性憑證
再連線
工具鏈與 runner
版本、標籤、並行數、快取與結束清理
再執行
時間軸與記錄
統一時區並擷取故障前後的關鍵記錄
供定位
完成標準
問題可重現、邊界可說明、記錄已去識別化
六類入口
先依問題所在階段選擇檢查路徑
不要一開始就重裝環境。先判斷問題發生在交付、連線、工具鏈、任務執行、資料讀寫或結算資訊，能大幅減少無效變更。
01
首次交付
核對節點、機器設定、系統帳戶、存取憑證、租用起訖時間與安全設定。
完成標準：訂單與機器資訊一致 02遠端連線
依序確認位址可連通、連接埠策略、帳戶狀態、網路抖動、鍵盤配置與工作階段復原。
完成標準：可穩定重新連線並輸入 03開發環境
記錄 Xcode、命令列工具、憑證、描述檔、相依性快取與專案目錄權限。
完成標準：本機與遠端基準可比較 04CI/CD
檢查 runner 註冊、標籤路由、並行上限、快取目錄、金鑰注入與任務後清理。
完成標準：任務可重複執行且不混用環境 05儲存空間
區分系統磁碟、專案目錄、建置快取與團隊儲存空間，先判斷容量、權限與同步狀態。
完成標準：資料路徑與移出責任清楚 06帳單
核對機型、租用期間、節點、SSD 加購容量與 Thunderbolt 5 並聯數量，再比對應付項目。
完成標準：每筆費用皆可追溯至設定
交付前六項
首次登入前，先保存一份交付基準
基準用於判斷後續變化來自訂單、系統設定還是專案工具鏈。核對時只記錄必要資訊，不要將密碼、私密金鑰或完整權杖寫入團隊文件。
核對晶片、記憶體與磁碟
在系統資訊中確認訂單對應的 M4 或 M4 Pro、記憶體容量與系統磁碟容量。外接或加購儲存空間應單獨記錄掛載位置。
- 驗證點
- 設定與訂單逐欄一致
- 記錄項目
- 晶片、RAM、SSD
區分管理帳戶與任務帳戶
確認初始系統帳戶可登入，再為自動化任務設定最小權限帳戶。不要讓日常 runner 長期使用不必要的高權限。
- 驗證點
- 帳戶可登入且權限符合用途
- 記錄項目
- 帳戶角色，不記錄密碼
首次使用後更新一次性憑證
分別保存遠端位址、系統使用者名稱與工作階段憑證。更新後執行一次登出與重新連線，確認新憑證能以預期方式生效。
- 驗證點
- 舊憑證失效，新憑證可重新連線
- 記錄項目
- 變更時間與執行人
統一起訖時間與團隊時區
將租用起訖時間寫入專案行事曆，並標註使用的時區。長時間任務應在到期前預留檢查點保存、產物同步與環境清理時間。
- 驗證點
- 團隊成員讀取到相同時間
- 記錄項目
- 起訖時間、時區、負責人
先收緊入口，再安裝工具
檢查共用帳戶、遠端存取範圍、目錄權限與金鑰存放位置。安裝腳本應可供檢視，敏感變數只在任務執行時注入。
- 驗證點
- 最小權限與存取邊界明確
- 記錄項目
- 允許來源、目錄與輪換責任
關鍵術語
先對齊八個詞，溝通少一層歧義
這些術語描述資源歸屬、連線方式與建置環境。提交問題時直接使用對應名稱，方便支援人員判斷問題所在層級。
- 實體節點
- 承載雲端 Mac 的實際裝置及其所在區域。SoarMac 提供指定節點中的 Apple Silicon 實體機器，而非抽象化的共用運算執行個體。
- 獨享
- 租用期間內，機器資源由單一訂單使用，不與其他訂單共用系統環境。團隊內部仍應自行規劃帳戶、目錄與任務權限。
- 非虛擬機器
- 系統直接執行於對應實體機器上。排查效能或裝置能力時，應先查看實際設定、目前任務與儲存狀態，而不是套用虛擬機器規格概念。
- VNC
- 用於存取 macOS 圖形介面的遠端工作階段方式。適合介面操作與視覺檢查，不等同於檔案同步，也不應取代自動化任務記錄。
- self-hosted runner
- 註冊於團隊 CI/CD 平台、實際執行於雲端 Mac 的任務執行器。需要明確的標籤、並行限制、工作目錄與結束清理規則。
- 建置快取
- 為減少重複下載與編譯而保留的相依性或中間產物。快取必須具備可識別的索引鍵、容量上限與失效條件，不可與專案原始檔混放。
- 簽署環境
- 執行簽署檢查所需的工具版本、憑證、描述檔、權限與任務變數集合。應記錄來源與輪換責任，不要在一般記錄中輸出敏感內容。
- 工作階段憑證
- 用於建立遠端工作階段的位址、使用者名稱與臨時驗證資訊。這與專案金鑰、程式碼儲存庫權杖不是同一類資訊，應分開保存與輪換。
CI/CD 接入
讓 runner 可重複執行，而不是只成功一次
接入順序應固定為註冊、路由、限流、快取、金鑰與清理。每次變更 Xcode、相依性或簽署材料後，都使用同一條最小化流水線重新驗證。
註冊 runner
使用專案或組織要求的註冊方式建立執行器，記錄 runner 名稱、所屬範圍與服務啟動方式。完成後先執行不含敏感變數的診斷任務。
規劃標籤
標籤至少應表達系統、晶片系列、Xcode 基準與用途，例如建置、測試或媒體處理。不要讓通用標籤將高負載任務錯誤路由至輕量佇列。
限制並行數
先以單一任務驗證 CPU、記憶體、磁碟寫入與衍生資料目錄，再逐步增加並行數。出現抖動時保留佇列長度與任務時間軸，不要只看最終失敗代碼。
劃分快取目錄
相依性快取、建置中間產物與匯出檔案分開儲存。為快取設定容量界線、索引鍵規則與清理條件，避免錯誤重用舊架構或舊工具鏈產物。
注入金鑰
敏感變數只在任務執行階段進入環境，關閉記錄中的命令回顯並限制可讀取任務。驗證失敗時檢查變數是否存在，不要輸出變數原文。
任務後清理
結束時移除暫存檔、卸載暫時掛載、終止殘留程序並清除短期憑證。即使前置步驟失敗也應執行清理，並保留可供檢視的結果代碼。
最小化驗證任務
工具版本 → 下載相依性 → 編譯 → 測試 → 匯出摘要
需要保留
runner 標籤、提交識別碼、任務時間、結束代碼、去識別化記錄
不應寫入記錄
密碼、私密金鑰、完整權杖、簽署材料原文
開發環境基準
先記錄版本，再判斷是環境差異還是專案問題
遠端建置失敗不代表機器異常。將工具版本、相依性解析、目錄權限與簽署材料拆開驗證，才能找到真正發生變化的層級。
核對 Xcode 版本
記錄完整版本、建置號與目前選取的路徑。在流水線中明確選擇版本，避免圖形介面與命令列呼叫到不同工具鏈。
命令列工具
檢查編譯器、套件管理器與腳本直譯器的實際路徑。不要只依據安裝介面判斷版本，任務記錄應輸出不含敏感資訊的版本摘要。
憑證與描述檔
核對有效範圍、用途與讀取權限。記錄只保留識別資訊與檢查結果，不輸出憑證私密內容；輪換後執行一次最小化簽署驗證。
相依性快取
快取索引鍵應包含相依性鎖定檔、工具版本與架構資訊。遇到無法解釋的編譯差異時，使用空快取驗證，而不是直接刪除所有專案資料。
專案目錄權限
確認 runner 分別擁有原始碼、快取與匯出目錄所需的權限。避免以全域放寬權限解決單一目錄問題，並記錄目錄擁有者的變化。
儲存路徑
分開管理系統、專案、快取與交付檔案
磁碟問題通常來自路徑混用、快取沒有上限、權限漂移或同步尚未完成。先確認資料屬於哪一層，再決定清理、擴充容量或遷移。
保留執行餘裕
持續觀察可用空間，避免建置中間產物擠占系統執行所需容量。系統目錄不應作為團隊共用產物儲存庫。
明確擁有者
原始碼與設定由固定任務帳戶管理。目錄遷移後重新核對權限、符號連結與腳本中的絕對路徑。
設定失效條件
依專案、架構與工具版本劃分快取，並為容量與保留週期設定清理規則，避免舊產物影響新任務。
同步後再清理
先驗證匯出產物的完整性，再同步至團隊儲存空間。租用期結束前完成移出並保留交接記錄。
連線排查順序
一次只變更一項條件，並記錄結果
先確認本地網路與目標位址，再進入驗證與工作階段層。畫面、鍵盤與剪貼簿屬於工作階段體驗問題，不應與位址無法連通混在同一步處理。
| 現象 | 第一步 | 第二步 | 仍未復原時保留 |
|---|---|---|---|
| 無法建立工作階段 | 確認節點、位址與本地網路可用，排除公司網路策略攔截。 | 更換已知可用網路重新測試，不要同時變更帳戶與連線參數。 | 節點、發生時間、來源網路、錯誤原文與連續測試結果。 |
| 畫面延遲 | 降低解析度與色彩品質，暫停本地大量上傳。 | 比較不同網路下的往返延遲與抖動，確認問題是否持續。 | 節點、解析度、網路類型、延遲樣本與問題時段。 |
| 鍵盤配置異常 | 核對本地輸入法、工作階段鍵盤配置與系統地區設定。 | 使用純文字編輯器測試修飾鍵、符號鍵與快速鍵。 | 本地系統、鍵盤配置、異常按鍵與重現步驟。 |
| 剪貼簿未同步 | 確認工作階段工具已允許剪貼簿傳輸，並測試短純文字。 | 重新建立工作階段後再測試，避免先複製大型檔案或豐富文字。 | 工作階段工具、內容類型、方向與可重現的最小文字。 |
| 重新連線失敗 | 完全結束舊工作階段並等待連線釋放，再使用原位址重試。 | 檢查系統帳戶是否仍有效，避免連續快速發起連線。 | 中斷原因、重試間隔、錯誤原文與最近一次成功時間。 |
| 憑證失效 | 確認使用最新的系統使用者名稱與工作階段憑證，未混用舊記錄。 | 由具備權限的負責人核對最近變更與輪換時間。 | 訂單編號、節點、使用者名稱、失效時間；不要附上密碼。 |
| 大型檔案傳輸中斷 | 改用可驗證且可續傳的檔案同步流程，不依賴剪貼簿。 | 比較來源檔案與目標檔案的大小及檢查結果。 | 檔案大小、傳輸方向、開始時間、失敗階段與檢查摘要。 |
服務目標
99.9% 可用率目標，以事件記錄核對
所有節點全年 365 天正常執行，不設定週期性停機時段。若發生異常事件，控制台時間軸會記錄開始時間、影響範圍、復原過程與結束時間；補償資格與計算方式以服務條款為準。
最近 90 天
三個 30 天核對區間
實際記錄以時間軸為準
D−90 — D−61
每日狀態、異常開始時間與影響範圍
D−60 — D−31
復原動作、階段更新與節點範圍
D−30 — D−1
結束時間、持續時間與後續說明
- 計算依據
- 受影響服務記錄與訂單時間軸
- 申請入口
- 控制台工單
- 提交資料
- 訂單編號、節點、時間與影響說明
帳單核對
按設定項目逐行比對，不要用總價反推
訂單費用由機器級別、租用週期、節點、SSD 加購容量與 Thunderbolt 5 並聯數量構成。每次調整週期或附加項目後，重新確認訂單摘要。
機器與租用期間
先核對 SoarMac M4 Air、SoarMac M4 Plus 或 SoarMac M4 Pro，再確認日、週、月或季租用週期。
節點與附加項目
確認 SG、JP、KR 或 HK 節點，以及 +1TB SSD、+2TB SSD 或 Thunderbolt 5 並聯台數。
結算記錄
所有價格均以 USD 結算，僅支援 USDT-TRC20 與 Visa / Mastercard / Amex（經 Stripe）；實際可用付款閘道以系統回傳為準。
提交前準備
讓工單第一輪就具備定位條件
只寫「無法使用」會讓排查停留在補充資訊階段。請依以下順序提供事實，並從記錄中移除密碼、私密金鑰、完整權杖與簽署材料。
01
訂單編號
用於關聯機型、租用期間與交付記錄，不要附上付款憑證。
02
節點
寫明 SG、JP、KR 或 HK，以及發起連線時所在的大致網路區域。
03
發生時間
使用含時區的時間，註明首次出現、最近重現與最後一次正常執行時間。
04
重現步驟
從初始狀態開始逐步描述輸入、操作、預期結果與實際結果。
05
去識別化記錄
保留錯誤原文、結束代碼與前後文，移除密碼、私密金鑰、完整權杖與個人資料。