Oakmini 支援作業手冊

讓雲端 Mac 問題停在可定位的一步

先判斷故障屬於連線、開發環境、CI/CD、儲存空間、網路或帳戶管理，再依固定順序驗證狀態、參數與日誌。Oakmini 提供的是獨享 Mac mini 實體節點，而非虛擬機；排查時應分開驗證本地連線條件、節點狀態與專案工具鏈。

查看主機狀態 準備支援請求
6 類排查入口 5 個在售節點區域 365 天正常運作
雲端 Mac 工程工作台與終端連線狀態情境
connection-check 
$ uname -m
arm64
$ sw_vers -productVersion
macOS ready
$ ssh -v oak-node
debug1: Authentication succeeded
$ df -h /
Filesystem status: available
TRIAGE / 01

先將問題分到正確的排除路徑

不要同時變更網路、憑證與工具版本。先選擇最接近的症狀，每次只驗證一個變數，並記錄發生時間、執行動作與結果。這樣可避免一次變更掩蓋另一個問題。

無法連線

適用於 SSH 逾時、VNC 黑畫面、憑證遭拒或連線後立即中斷的情況。

從主機狀態開始檢查

開發環境

適用於 Xcode 路徑、Homebrew 套件、Git 設定、Fastlane 或語言執行環境版本不一致。

核對路徑與版本清單

CI/CD

適用於 runner 離線、標籤不符、工作排隊、快取異常或建置輸出不完整。

從 runner 註冊狀態開始

儲存空間

適用於磁碟空間不足、快取持續增長、工作目錄混亂或建置產物無法匯出。

核對容量、目錄與使用量

網路

適用於互動延遲升高、偶發封包遺失、檔案傳輸緩慢或只有特定本地網路無法存取。

比較不同連線與時段

帳戶管理

適用於訂單識別、主機管理權限、續用狀態或控制台操作結果未更新。

先核對訂單與操作記錄
儲存空間

先找出空間消耗位置

使用 df -h 查看磁碟區容量，再使用 du -sh 檢查專案、建置快取與匯出目錄。刪除前確認產物已備份，不要直接清空未知的系統目錄。

網路

分開判斷互動延遲與工作耗時

分別記錄 SSH 建立連線、VNC 操作、程式碼拉取與本地建置所需時間。若只有圖形介面反應遲緩，應先調整 VNC 畫質；若命令列與傳輸同時異常，再檢查本地連線與節點可達性。

帳戶管理

以控制台訂單狀態為準

確認目前登入帳戶、訂單識別碼、所選區域與最近一次操作時間。主機狀態、訂單與管理操作統一在控制台完成，支援請求中只提供訂單識別碼，不要傳送登入憑證。

CONNECTION / 02

依五個層級執行連線診斷

連線失敗通常發生在主機狀態、本地網路、連線參數、防火牆或憑證其中一層。請依順序驗證，前一層未通過前不要修改後一層。

  1. 01

    檢查控制台中的主機狀態

    確認訂單對應的雲端 Mac 處於可連線狀態，核對節點區域與連線資訊是否屬於同一台實體節點。若剛完成管理操作，請記錄操作時間與目前狀態，不要重複提交相同動作。

    通過條件：主機狀態正常，訂單識別碼、節點區域與連線目標一致。
  2. 02

    驗證網路可達性

    先確認本地網路可以存取目標位址與連接埠，再與另一條可信任網路比較。僅在辦公室網路失敗時檢查出口策略；所有網路都失敗時，保留測試時間、目標連接埠與錯誤類型。

    nc -vz HOST PORT
ssh -vvv USER@HOST
    通過條件：連接埠可達，連線不會在交握前逾時。
  3. 03

    逐字核對 SSH 或 VNC 參數

    確認主機位址、連接埠、使用者名稱與連線方式來自目前訂單。SSH 設定別名可能覆寫連接埠或金鑰路徑，可使用詳細日誌查看最終採用的參數；VNC 則應核對目標位址、顯示設定與用戶端儲存的舊記錄。

    ssh -G oak-node
ssh -v USER@HOST -p PORT
    通過條件：用戶端實際參數與控制台提供的資訊完全一致。
  4. 04

    檢查本地防火牆與安全策略

    臨時測試前先記錄現有規則。檢查終端機、SSH 用戶端或 VNC 用戶端是否允許發起連線，以及企業網路是否限制目標連接埠。不要為了排查而長期關閉整套本地防護。

    通過條件：目標程式與連接埠擁有明確的輸出權限，替代網路測試結果一致。
  5. 05

    驗證憑證是否有效

    區分「網路逾時」與「驗證遭拒」。前者不應透過更換密碼解決；後者需要確認使用者名稱、金鑰檔案、檔案權限，以及最近是否變更過憑證。支援請求只能附上驗證錯誤文字，不得附上密碼或私密金鑰內容。

    chmod 600 ~/.ssh/id_ed25519
ssh-add -l
    通過條件：交握完成、驗證成功，連線進入 macOS 命令列或圖形介面。
最小證據集：訂單識別碼、節點區域、發生時間與時區、連線方式、用戶端錯誤原文、已驗證步驟。日誌應刪除使用者名稱以外的敏感欄位，並遮蔽主機憑證、金鑰與權杖。
TOOLCHAIN / 03

以版本、路徑與專案結果核對開發環境

「已安裝」不等於「流水線正在使用」。工具鏈排查需要同時記錄可執行檔路徑、版本、目前 shell 環境與專案實際呼叫結果。

工具 先核對 建議指令 常見差異
Xcode 目前開發者目錄、版本、SDK 清單 xcode-select -p
xcodebuild -version		 命令列指向另一套 Xcode，專案要求的 SDK 不在目前版本中
Homebrew 二進位檔路徑、軟體清單、診斷結果 brew --prefix
brew doctor		 shell 未載入正確路徑，遷移後套件清單與本地環境不一致
Git 版本、遠端位址、儲存庫權限與使用者設定 git --version
git remote -v		 runner 與互動式 shell 使用不同憑證或不同工作目錄
Fastlane 呼叫來源、依賴鎖定、lane 與環境變數名稱 bundle exec fastlane --version 直接呼叫全域版本，未依專案依賴檔案執行
語言執行環境 直譯器路徑、版本管理器與專案鎖定版本 which ruby
which node		 互動式 shell 與非互動工作載入不同初始化檔案
環境基準

保留一份機器可讀清單

記錄 macOS 版本、晶片架構、Xcode 版本、Homebrew 軟體清單、Git 版本與語言執行環境。每次升級只變更一個主要元件，並在升級前後各儲存一次清單。

路徑管理

檢查工作實際看到的 PATH

在本地終端機可執行但 runner 失敗時，將 echo "$PATH"、which 與版本指令寫入臨時診斷步驟。確認後刪除不必要的環境輸出，避免日誌帶出敏感變數。

可重現驗證

使用最小專案重現

先執行依賴解析，再執行一次乾淨建置，最後確認產物路徑與結束碼。若最小專案成功而業務專案失敗，應回到專案設定、依賴鎖定與指令碼權限繼續定位。

BASELINE COMMANDS

環境快照指令

以下輸出足以建立基礎版本記錄。提交支援請求前，請刪除目錄中的專案名稱與任何敏感參數。

uname -m
sw_vers
xcode-select -p
xcodebuild -version
brew --prefix
git --version
which ruby
which node
df -h /
CI/CD / 04

從 runner 線上狀態追查到單次工作日誌

CI/CD 問題應依「是否接收工作、是否進入工作目錄、是否取得權限、是否命中依賴、是否完成建置」逐層判斷。不要只根據最終失敗提示下結論。

01

Runner 註冊

確認 runner 服務正在執行、註冊關係仍有效，且控制台顯示線上。重新啟動前記錄最後上線時間與最近一次成功工作。

  • 核對 runner 名稱與目標專案
  • 確認服務程序與啟動使用者
  • 檢查系統重新啟動後是否自動恢復
02

標籤匹配

工作長時間排隊但 runner 上線時，比較工作要求的標籤與 runner 實際標籤。標籤包含大小寫、空格或架構差異時，工作可能不會被領取。

  • 保留一個明確的 Apple Silicon 標籤
  • 刪除已停用的歷史標籤
  • 驗證目標分支是否允許使用此 runner
03

權限與工作目錄

確認 runner 使用者對儲存庫目錄、快取目錄與產物目錄擁有所需權限。不要用擴大所有目錄權限的方式掩蓋單一路徑設定錯誤。

  • 記錄工作實際執行使用者
  • 檢查指令碼是否具備執行權限
  • 確認暫存目錄可以建立與清理檔案
04

快取與並行

快取失效時，先執行一次不讀取舊快取的對照工作。並行工作互相覆寫檔案時，為每個工作分配獨立工作目錄，並檢查 Oak Core 或 Oak Forge 的記憶體與儲存空間是否符合工作規模。

  • 記錄快取鍵與依賴鎖定檔版本
  • 區分共用快取與工作目錄
  • 比較單一工作與並行工作的結果
05

日誌與結束碼

保留工作開始時間、runner 名稱、提交識別碼、關鍵工具版本、失敗步驟、結束碼與末段日誌。若失敗可重現，記錄最短重現步驟；若為偶發問題，至少保留一次成功與一次失敗的對照。

  • 為關鍵階段印出開始與結束時間
  • 將建置日誌與測試報告儲存為產物
  • 上傳前移除權杖、金鑰與簽署材料

工作一直排隊

優先檢查 runner 上線狀態、專案授權與標籤。此時先不要清理快取，因為工作尚未進入建置階段。

工作啟動後立即失敗

優先檢查工作目錄、指令碼權限、shell 初始化與工具路徑。比較互動式終端機與 runner 環境變數。

依賴安裝不穩定

核對鎖定檔、快取鍵、磁碟剩餘空間與網路下載日誌。使用一次乾淨快取工作建立對照，不要連續覆寫原始證據。

僅在並行時失敗

檢查記憶體使用量、共用目錄寫入衝突、連接埠占用與暫存檔命名。先降低並行數進行驗證，再決定調整工作拆分或設定。

GLOSSARY-MINI / 05

支援請求中常見的八個術語

使用一致的術語可以減少來回確認。描述問題時，請盡量指出具體物件，例如「東京節點的 SSH 連線逾時」，而不要只寫「伺服器無法使用」。

雲端 Mac
透過網路遠端使用的 macOS 開發環境，可用於圖形介面、命令列、建置工作與自動化流程。
實體節點
實際部署的 Mac mini 裝置。Oakmini 的服務以獨享實體機提供，不會將同一運算執行個體拆分成虛擬機供多人使用。
獨享
在訂單週期內由該使用者使用對應的實體節點資源，有助於讓建置並行、快取與工具版本維持可控。
VNC
用於存取 macOS 圖形介面的遠端連線方式。畫質、解析度與本地連線都會影響互動體驗。
SSH
用於安全存取命令列的連線方式，依賴主機位址、連接埠、使用者名稱與有效憑證。
self-hosted runner
部署於使用者控制環境中的 CI 執行程式，負責領取工作、進入工作目錄並執行建置指令碼。
建置快取
為減少重複下載或編譯而保存的中間資料。快取鍵、依賴版本與工作目錄不一致時，可能產生錯誤結果。
節點區域
實體節點所在的區域。目前在售範圍僅包括新加坡、日本（東京）、韓國（首爾）、香港與美國西部。
REQUEST / 06

提交一份可直接重現的支援請求

Oakmini 僅提供兩種聯絡管道：登入控制台提交工單，或寄送電子郵件至 support@oakmini.com。涉及現有訂單、主機狀態與持續排查記錄時，優先使用工單；售前或無法進入控制台時可使用電子郵件。

必須提供

問題背景

  • 訂單識別碼：只提供可用於定位訂單的識別碼，不要傳送付款憑證。
  • 節點區域：新加坡、日本（東京）、韓國（首爾）、香港或美國西部。
  • 發生時間：寫明日期、精確時間與時區，並指出是否可以重現。
  • 連線或工作類型：SSH、VNC、Xcode 建置、runner 工作或控制台操作。
  • 重現步驟：依執行順序編號，註明預期結果與實際結果。
  • 去識別化日誌：保留錯誤原文、結束碼與相關背景，刪除敏感欄位。
禁止附帶

敏感內容不得放入工單或電子郵件

  • 帳戶密碼 支援排查不需要知道密碼原文。
  • 私密金鑰或存取權杖 可提供金鑰類型或錯誤資訊，但不要提供金鑰內容。
  • 簽署憑證原文 只描述憑證用途、有效狀態與錯誤，不要上傳完整材料。
  • 付款憑證 僅提供訂單識別碼與交易狀態，不要傳送卡片或錢包敏感資料。
  • 未去識別化的專案日誌 先移除儲存庫位址、環境變數、客戶資料與內部路徑。
COPYABLE STRUCTURE

支援請求格式

逐項填寫，未知項目請寫「未確認」，不要猜測。若問題涉及多次嘗試，請按時間順序列出。

主旨：訂單識別碼 / 問題類別 / 節點區域
發生時間與時區：
連線方式或工作類型：
預期結果：
實際結果：
重現步驟：
1.
2.
3.
已完成的排查：
錯誤原文與結束碼：
去識別化日誌附件說明：
登入控制台提交工單 寄送電子郵件至 support@oakmini.com
控制台 / 07

主機狀態、訂單與管理操作統一在控制台處理

支援頁提供排查順序、指令與資訊準備方式；實際下單、續用、查看訂單、確認主機狀態與管理雲端 Mac 均在控制台完成。所有節點全年 365 天正常運作，全年持續提供服務。若狀態與實際連線結果不一致，請記錄時間並提交工單。

控制台：訂單與主機管理 支援頁：診斷與證據準備 工單或電子郵件：人工協助
管理雲端 Mac 查看首次連線指南