連線、遷移與疑難排解

將雲端 Mac 整合至現有工作流程

先確認控制台中的節點與連線資料，再透過 SSH 或 VNC 建立首次工作階段。遷移、建置或 MLX 服務發生異常時，依本頁順序縮小問題範圍，避免在設定、網路與任務日誌之間反覆猜測。

3 個階段
連線、遷移、整合
2 種入口
SSH 與 VNC
365 天
節點正常運作
立即租用雲端 Mac 登入控制台
首次接入手冊 VMKeep / CONNECT
待核對
01
帳戶與訂單

確認訂單狀態、節點區域、機器名稱與租期資訊一致。

控制台
02
連線資料

複製主機位址、使用者名稱與臨時憑證，勿轉發給無關成員。

SSH / VNC
03
更新憑證

首次連線後更新密碼，新增團隊使用的 SSH 公開金鑰。

必要
04
基線驗證

記錄 macOS、Xcode、磁碟空間與網路存取結果。

建議
提交工單前保留指令輸出與發生時間 RUNBOOK-04
首次連線路徑

先建立可重現的連線基線

不要一開始就遷移儲存庫或安裝大量相依套件。先完成四項基礎核對，確認機器身分、連線方式與憑證更新都能正常執行。

  1. 01 帳戶確認

    核對控制台資料

    登入控制台，檢查訂單號碼、節點區域、機器名稱、租期與連線資料。節點與訂單不一致時先停止操作，避免將檔案遷移至錯誤機器。

    • 記錄訂單號碼與節點區域
    • 確認機器名稱與租期
    • 僅從控制台讀取連線資料
  2. 02 建立工作階段

    選擇 SSH 或 VNC

    命令列設定、自動化與日誌檢查優先使用 SSH；需要圖形介面、Xcode 設定或桌面操作時使用 VNC。建議首次連線時各驗證一次。

    • SSH 核對主機指紋與使用者名稱
    • VNC 核對位址與顯示解析度
    • 記錄成功連線所用的網路環境
  3. 03 更新憑證

    更換密碼並寫入公開金鑰

    進入機器後立即更新臨時密碼，再將團隊核准的 SSH 公開金鑰寫入授權清單。金鑰應按成員區分，離開專案時個別撤銷。

    • 使用獨立且足夠長的密碼
    • 為每位成員保留獨立公開金鑰
    • 限制私密金鑰與連線資料的分發範圍
  4. 04 記錄基線

    驗證系統與磁碟狀態

    安裝工具前記錄系統版本、Xcode 路徑、可用磁碟空間與基礎網路結果。後續故障可直接與這份基線比較。

    • sw_vers 查看系統版本
    • xcode-select -p 查看工具鏈路徑
    • df -h 查看磁碟空間
遷移路徑

從本機 Mac 到雲端 Mac，分三次遷移

遷移順序決定疑難排解成本。先移動可驗證的資料，再還原固定版本的工具鏈，最後整合 CI 或 self-hosted runner。

01
資料同步

只遷移必要檔案

優先透過 Git 下載程式碼儲存庫。大型模型、建置快取與產出物應個別同步，傳輸完成後核對檔案大小或雜湊值。

輸入
儲存庫、模型檔案、指令碼、必要設定
檢查
目錄權限、忽略規則、剩餘磁碟空間
產出
可獨立驗證的專案工作副本
02
還原工具鏈

固定 Xcode 與相依版本

確認專案要求的 Xcode、命令列工具、Ruby、Node.js 與 CocoaPods 版本。先執行最小建置，再還原完整相依快取。

輸入
版本清單、鎖定檔、安裝指令碼
檢查
預設 Xcode、SDK、執行階段與 PATH
產出
可重複執行的本機建置指令
03
整合自動化

註冊 runner 並觀察首輪任務

將 runner 工作目錄、快取目錄與日誌目錄分開。首次任務不要並行，先觀察下載、建置、測試與封存各階段的輸出。

輸入
runner 註冊資訊與任務標籤
檢查
執行使用者、目錄權限、失敗結束碼
產出
可重複執行且日誌可追蹤的任務
指令執行記錄

用最短鏈路驗證 SSH、建置與封存

以下記錄展示排查順序，不包含專案專用憑證。先確認遠端工作階段，再執行 Xcode 建置，最後觀察自動化工具是否回傳成功狀態。

VMKeep 建置工作階段 · zsh SESSION 01
09:14:02 $ ssh vmkeep@203.0.113.24
主機 vmkeep-m4-plus 區域 JP Shell /bin/zsh
09:14:18 $ xcodebuild -workspace Client.xcworkspace -scheme Client -configuration Release build

[1/4] 解析套件相依性

[2/4] 編譯原始碼與資源

[3/4] 執行單元測試

[4/4] 封存建置輸出

09:22:41 $ bundle exec fastlane ios build
建置成功
exit=0 · archive=Client.xcarchive · duration=08m23s

若某個步驟失敗，請保留失敗指令前後至少 30 行輸出、結束碼、Xcode 版本與發生時間。提交工單前請移除權杖、私密金鑰與簽章材料原文。

CI/CD 整合

分開管理 runner、工作目錄與快取

持續建置的問題通常來自執行身分、目錄權限、版本漂移或快取污染。以下五項應在第一條正式流程執行前確認。

A1

註冊 runner

使用獨立執行使用者註冊 self-hosted runner，為建置類型設定清晰標籤。確認服務重新啟動後 runner 能自動恢復上線狀態。

身分與標籤
A2

規劃工作目錄

將原始碼簽出、暫存建置、封存產出物與任務日誌放在不同目錄，避免失敗任務留下的檔案影響下一次執行。

權限與清理
A3

設定快取邊界

快取鍵至少包含相依鎖定檔、Xcode 版本與架構資訊。出現無法解釋的編譯錯誤時，先使用空快取重新執行一次。

版本與命中
A4

保管簽章材料

簽章檔案、密碼與權杖僅在任務執行時注入，不寫入儲存庫、一般日誌或長期共用目錄。任務結束後清除暫存副本。

最小暴露
A5

定義失敗重試

先區分網路下載失敗、相依性解析失敗、編譯失敗與測試失敗。確認任務具備冪等性後，才自動重試對應階段。

結束碼與日誌
CI/CD 常見階段與核對內容
階段 優先核對 應保留的結果 不應寫入日誌
程式碼下載 儲存庫權限、遠端位址、網路解析 提交雜湊、分支、失敗指令 存取權杖原文
安裝相依套件 鎖定檔、映像檔設定、快取鍵 工具版本、相依性解析輸出 私有憑證原文
Xcode 建置 scheme、SDK、建置設定、目標平台 完整指令、結束碼、關鍵錯誤 簽章密碼
測試與封存 測試目標、逾時、產出物目錄 測試報告、封存路徑、任務耗時 簽章材料原始檔案
MLX 服務排查

從本機推論結果追查至遠端 API

先證明模型能在機器本機完成一次請求，再檢查監聽位址與連接埠。模型尚未成功載入前，不要直接排查遠端用戶端。

  1. 01

    確認模型路徑

    檢查設定中的模型目錄、權重檔案與讀取權限。相對路徑應以服務實際工作目錄為基準。

    test -r /srv/models/model && echo readable
  2. 02

    觀察記憶體使用量

    先以單一請求載入模型，記錄載入前後的記憶體變化。若程序結束，請檢查系統日誌與應用程式結束碼。

    ps -o pid,rss,command -p <PID>
  3. 03

    驗證本機監聽

    確認服務繫結的位址與連接埠。僅監聽迴路位址時，遠端用戶端無法直接連線。

    lsof -nP -iTCP:<PORT> -sTCP:LISTEN
  4. 04

    執行本機請求

    在雲端 Mac 內部傳送最小請求，記錄回應狀態、首字延遲、總耗時與模型回傳內容。

    curl -sS http://127.0.0.1:<PORT>/health
  5. 05

    再測試遠端 API

    本機請求成功後，再從授權用戶端驗證遠端存取。比較用戶端時間、服務日誌與請求識別碼。

    curl -sS https://<YOUR-ENDPOINT>/health
模型相容性

具體模型能否執行取決於模型格式、量化方式、相依版本與所選記憶體配置。

效能判斷

首字延遲與持續吞吐量應在固定模型、固定參數與固定並行條件下比較。

工單證據

提交模型路徑結構、啟動指令、程序日誌、監聽結果與去識別化後的最小請求。

術語小辭典

八個常用的整合與排查術語

統一術語有助於減少團隊溝通偏差。提交工單時，請盡量使用下列名稱描述機器、連線方式與任務角色。

實體節點
實際執行 macOS 與任務的 Apple Silicon 裝置，而非抽象化的運算執行個體。
獨享
一筆訂單對應一台獨立實體機，執行資源不與其他租戶共用同一執行個體。
非虛擬機
系統與任務直接執行於所分配的實體裝置上，不透過共用虛擬化執行個體交付。
VNC
用於存取 macOS 圖形介面的遠端連線方式，適合 Xcode 設定與桌面操作。
SSH
用於命令列管理、檔案傳輸、日誌檢查與自動化執行的加密遠端連線方式。
self-hosted runner
註冊於團隊 CI 系統中，由這台雲端 Mac 執行建置任務的自託管執行器。
MLX
面向 Apple Silicon 的機器學習框架，可用於模型轉換、量化、推論與服務封裝。
建置快取
為減少重複下載與編譯而保留的中間檔案；快取鍵不完整時，可能引入舊結果。
常見連線問題

依現象檢查，不跳過基礎項目

每類問題都先核對訂單與節點，再檢查用戶端、網路與機器內部狀態。展開對應項目即可查看建議順序與工單資訊。

無法登入 SSH 或 VNC

檢查順序：確認訂單與節點資料，重新複製主機位址與使用者名稱，檢查輸入法與密碼字元，核對 SSH 主機指紋或 VNC 位址，再換用已知可用的網路重新測試。

工單資訊：訂單號碼、節點區域、發生時間、用戶端名稱、完整錯誤文字，以及已隱藏主機敏感部分的連線指令。

建立連線後頻繁中斷

檢查順序：記錄中斷時間，測試本機網路穩定性，關閉可能改寫路由的代理程式後重新測試，查看 SSH keepalive 設定，並確認中斷是否與高負載任務同時發生。

工單資訊：中斷時段、所在網路環境、連續測試次數、用戶端日誌、任務類型與中斷前後的系統負載。

VNC 畫面延遲或操作不順暢

檢查順序：降低顯示解析度與色彩品質，暫停佔用大量頻寬的同步任務，比較有線與無線網路，確認是否僅在特定時間或特定用戶端出現。

工單資訊：節點區域、用戶端版本、顯示解析度、本機網路類型、延遲出現時間與可重現的操作步驟。

磁碟空間不足或建置目錄持續增長

檢查順序：執行 df -h 查看分割區，再按目錄統計 DerivedData、封存產出物、相依快取、模擬器資料與任務工作區。刪除前先確認產出物已匯出。

工單資訊：磁碟使用結果、增長最快的目錄、最近執行的任務、已執行的清理指令，以及是否需要評估儲存空間附加項目。

本機可建置，但 runner 任務失敗

檢查順序：比較執行使用者、環境變數、工作目錄、Xcode 版本、相依鎖定檔與快取鍵。使用 runner 的執行身分手動執行相同的建置指令，找出最早出現差異的位置。

工單資訊：完整建置指令、Xcode 版本、runner 標籤、失敗結束碼、去識別化日誌，以及手動執行與自動任務之間的差異。

支援入口

先整理證據，再選擇聯絡方式

已有訂單與運作中節點的問題，優先透過控制台提交工單；方案選擇、部署範圍與尚未下單的問題，可透過聯絡頁寄送電子郵件諮詢。

工單資料清單

一次提交即可直接進入排查的資訊

5 項
訂單號碼

用於定位對應機器與租期，請勿提交帳戶密碼。

節點區域

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

發生時間

提供包含時區的時間範圍，方便對應連線與任務記錄。

指令輸出

保留結束碼與錯誤前後的上下文，並移除權杖與敏感憑證。

重現步驟

從初始狀態寫到問題出現，每一步註明預期結果與實際結果。

已有訂單

透過控制台提交工單

適合連線異常、機器狀態、建置問題、帳單與訂單關聯問題。工單會保留上下文，方便持續補充去識別化日誌。

登入控制台提交工單
售前與部署

透過聯絡頁準備電子郵件

適合設定選擇、團隊部署範圍、目標節點與租期諮詢。對外聯絡信箱統一為 support@vmkeep.com。

前往聯絡服務團隊
下一步

先選擇設定，再依本頁建立連線基線

三種 Apple Silicon 獨享實體機方案皆為非虛擬機，可按日、週、月或季租用。節點即時可用狀態以控制台回傳為準。

選擇設定並租用 查看三種租用方案