macOS 螢幕共享
適合從 Mac 用戶端進入圖形介面。連線目標應使用主控台提供的主機位址與連接埠，登入帳戶必須與系統帳戶完全一致。
- 初始解析度
- 1920×1080
- 色深
- 24-bit
- 建議可用頻寬
- ≥ 15 Mbps
- 互動建議
- 優先使用自動調整畫質
畫面延遲時先停止背景同步，再降低遠端解析度。不要同時調整解析度、色深與壓縮等級，否則難以判斷真正的影響因素。
連線 / 工具鏈 / 診斷
先完成遠端連線，
再逐層排查問題。
本指南適用於接入獨享實體節點：先核對節點位址與系統憑證，再設定 SSH、VNC、Xcode 與 CI runner。遇到異常時，依網路、驗證、系統、工具鏈、儲存空間的順序排查，減少無效重試。
連線方式
SSH / VNC
系統介面
GUI / CLI
資源類型
獨享實體機
節點運作
365 天
01 / 首次連線
首次連線前，逐項核對五類資訊
不要先猜測網路問題或重設系統。主控台中的節點記錄是唯一核對基準；複製位址時不要帶入通訊協定前綴、空格或連接埠以外的字元。
-
01
節點位址與區域
確認目前執行個體的節點編號、區域、主機位址與連接埠。區域應與訂單一致；若團隊使用網路允許清單，也請記錄用戶端目前的公網出口位址。
檢查：NODE ID / HOST / REGION / PORT
-
02
系統帳戶
帳戶名稱區分大小寫。SSH 指令中的帳戶名稱、VNC 登入欄位中的帳戶名稱與主控台顯示值必須一致，請勿以電子郵件地址代替系統使用者名稱。
格式：username@host
-
03
臨時憑證
首次使用前確認憑證仍是主控台目前版本。登入完成後立即更換臨時密碼；若已更新密碼，後續連線應使用新密碼，舊密碼不會繼續生效。
操作：登入 → 更換 → 安全儲存
-
04
SSH 用戶端
macOS 與常見 Linux 環境可直接使用終端機。先執行連接埠連通性檢查，再發起 SSH；首次出現主機指紋時，核對節點位址後再確認。
建議：連線逾時 10s / 保活 30s
-
05
螢幕共享或 VNC 用戶端
準備支援 VNC 的用戶端，並確認連線目標包含正確連接埠。首次連線先採用較低解析度與自動調整畫質，確認輸入穩定後再提高顯示參數。
起始值：1920×1080 / 24-bit / 自動調整
建議的驗證順序：先用 SSH 驗證位址、連接埠、帳戶與憑證，再連線至圖形介面。SSH 正常而 VNC 異常時，排查範圍可直接集中到圖形服務、VNC 連接埠與用戶端參數。
02 / 詞彙小抄
先統一術語，再對照設定
以下詞語會出現在訂單、主控台、連線文件與故障記錄中。每個術語都對應明確的資源範圍或技術操作。
- 實體節點
- 實際執行 macOS 的 Mac mini 硬體。節點位址、區域與節點編號共同識別目前交付的資源。
- 獨享
- 由單一租戶使用整台裝置的晶片、記憶體與儲存空間，不與其他租戶共用作業系統執行個體。
- 雲端 Mac
- 部署於遠端節點、透過網路存取的 Mac。MiniDeploy 提供的是獨享實體機，而非虛擬機器。
- VNC
- 傳輸遠端圖形介面、鍵盤與指標操作的通訊協定。使用體驗主要受往返延遲、解析度、色深與畫面變化量影響。
- SSH
- 用於遠端命令列、檔案同步與自動化操作的加密連線方式，適合環境檢查、建置與日誌收集。
- self-hosted runner
- 由團隊自行管理、接收 CI 工作的執行端。可固定 Xcode 版本、快取路徑、工作目錄與建置相依項。
- 工具鏈
- 完成建置所需的 Xcode、命令列工具、套件管理器、Ruby、fastlane、指令碼與環境變數集合。
- 節點延遲
- 用戶端與節點之間的資料往返時間，通常以毫秒表示。數值越低，遠端桌面的輸入回應通常越即時。
03 / 終端機範例
用三段輸出驗證連線、建置與上傳
終端機輸出應能回答三個問題：是否進入正確節點、Xcode 是否選取預期版本，以及建置產物是否已由流水線接收。
$ ssh -o ConnectTimeout=10 developer@node.example
Last login: Tue Mar 11 09:42:18
node: M4-Core / memory: 16GB / storage: 256GB
$ xcode-select -p
/Applications/Xcode.app/Contents/Developer
$ xcodebuild -workspace Demo.xcworkspace \
-scheme Demo -configuration Release build
Resolve Package Graph
CompileSwiftSources normal arm64
** BUILD SUCCEEDED **
$ bundle exec fastlane upload_build
[09:47:22]: Validating archive
[09:47:36]: Uploading artifact
[09:48:04]: Upload complete
[09:48:04]: Pipeline result: success
SSH 可連線
已確認 Xcode 路徑
產物上傳成功
範例中的主機名稱僅用於說明指令結構。實際位址、連接埠、帳戶與節點編號以主控台記錄為準。收集日誌時保留時間戳記與失敗指令，移除密碼、私密金鑰與簽署材料。
04 / 遷移路徑
本機 Mac 到雲端 Mac 的三段遷移路徑
不要一次搬遷所有目錄。先遷移專案資料，再重現工具鏈，最後接入 CI。每個步驟都設定可驗證的完成條件。
-
STEP 01
同步專案與設定清單
優先同步程式碼儲存庫、建置指令碼與必要資源。大型檔案單獨傳輸，並在傳輸前後計算校驗值。不要直接複製舊機器上的所有快取。
- 記錄儲存庫分支與提交雜湊
- 匯出相依版本清單
- 校驗關鍵檔案數量與大小
驗收條件 程式碼可取出，相依清單可讀取 -
STEP 02
重現 Xcode 與簽署工具鏈
明確記錄 Xcode 主版本、命令列工具路徑、Ruby 與 fastlane 版本。簽署材料應透過受控流程匯入，並檢查檔案權限與有效範圍。
- 確認 xcode-select -p
- 鎖定套件管理器與指令碼版本
- 執行一次本機 Release 建置
驗收條件 相同提交可穩定完成封存 -
STEP 03
接入 self-hosted runner
為 runner 建立獨立工作目錄與服務帳戶。限制標籤比對範圍、設定並行數，並將快取、日誌與產物路徑從原始碼目錄分離。
- 註冊後執行最小測試工作
- 驗證快取命中與清理規則
- 確認失敗日誌可回傳
驗收條件 提交觸發、建置、回傳的閉環完成
05 / 遠端桌面
遠端 Mac 桌面參數從低負載開始
遠端桌面體驗不只取決於頻寬。節點延遲、解析度、色深、影格率、用戶端縮放與背景檔案傳輸都會影響輸入回應。
通用 VNC 用戶端
適合跨平台存取。啟用自動調整壓縮，並關閉不必要的動畫效果。若用戶端支援分別控制畫質與色深，先維持畫質自動調整，僅降低色深。
- 初始解析度
- 1600×900
- 弱網路色深
- 16-bit
- 建議可用頻寬
- ≥ 10 Mbps
- 連線保活
- 30–60s
輸入有明顯延遲但畫面清晰時，優先檢查用戶端到節點的往返延遲。高解析度無法修復網路抖動，只會增加編碼與傳輸負擔。
| 使用情境 | 解析度起點 | 色深 | 頻寬建議 | 優先調整項目 |
|---|---|---|---|---|
| 終端機與輕量編輯 | 1600×900 | 16-bit | ≥ 8 Mbps | 降低動態畫面 |
| Xcode 編碼與除錯 | 1920×1080 | 24-bit | ≥ 15 Mbps | 維持低延遲連線 |
| 多視窗開發 | 2560×1440 | 24-bit | ≥ 25 Mbps | 先確認穩定性 |
| 畫面頻繁變化 | 1920×1080 | 24-bit | ≥ 30 Mbps | 降低影格率或畫質 |
頻寬數值是設定起點，不代表延遲結論。遠端桌面主要用於開發與管理時，應優先選擇距離用戶端較近的節點，並在實際網路環境中驗證。
06 / CI/CD
讓 runner 可重現，而不是只執行一次
CI 接入完成的標準不是看到一次成功結果，而是相同提交在清理工作目錄後仍能重複建置，失敗時也能保留足夠日誌。
runner 註冊
- 使用獨立服務帳戶執行
- 標籤至少區分架構與 Xcode 版本
- 預設並行數設為 1，確認負載後再調整
- 註冊權杖僅在設定階段使用
工作目錄隔離
- 每個工作使用獨立取出目錄
- 原始碼、快取、日誌與產物分開儲存
- 工作結束後清理暫存檔案
- 禁止不同專案共用可寫入的設定檔
快取策略
- 快取金鑰包含相依鎖定檔摘要
- 為快取設定容量上限與失效條件
- 命中異常時允許完整重建
- 不要快取簽署材料與短期憑證
建置憑證
- 依專案匯入必要材料
- 限制檔案權限與可存取帳戶
- 記錄有效期限並提前檢查
- 工作日誌不得輸出敏感內容
日誌保留
- 保留工作編號、提交雜湊與時間戳記
- 同時儲存標準輸出與錯誤輸出
- 在失敗階段上傳診斷摘要
- 提交支援請求前先完成去識別化
最小驗收工作
- 輸出系統與 Xcode 版本
- 拉取相依項並執行單元測試
- 產生可識別的建置產物
- 清理目錄後再次執行
資源界線：M4 Core 設定為 Mac Mini M4、16GB RAM、256GB SSD。並行工作會同時佔用記憶體、儲存 I/O 與網路；接入多條流水線前，應先測量單一工作的峰值，而不是直接提高並行數。
07 / 診斷樹
依症狀進入故障排查樹
每次只變更一個變數，並記錄時間點、指令、回傳值與用戶端網路狀況。重複點擊連線按鈕通常不會增加有效資訊。
無法連線：先判斷位址不可達還是連接埠不可達
- 在主控台確認節點狀態、位址、區域與連接埠沒有抄錯。
- 檢查本機網路是否限制目標連接埠；切換網路僅用於比對，不作為長期解決方案。
- 使用連接埠探測確認是逾時、拒絕，還是能夠建立連線，並記錄完整時間點。
- 若 SSH 與 VNC 均不可達，提交節點編號、用戶端城市、網路業者與探測結果。
- 若 SSH 可達而 VNC 不可達，繼續檢查 VNC 連接埠、用戶端目標格式與圖形服務狀態。
驗證失敗：核對帳戶、憑證版本與輸入方式
- 確認使用的是系統帳戶名稱，而非電子郵件、節點編號或裝置名稱。
- 重新從主控台核對臨時憑證；若已更換密碼，應使用更新後的憑證。
- 檢查鍵盤配置、大小寫、前後空格與特殊字元輸入，避免從富文字內容複製。
- SSH 金鑰驗證失敗時，檢查公開金鑰是否寫入正確帳戶，以及目錄與檔案權限。
- 連續失敗後停止重試，記錄用戶端、時間點與回傳資訊，再提交工單。
畫面延遲：區分高延遲、頻寬不足與背景資源佔用
- 先測量用戶端到節點的往返延遲，並持續觀察是否有明顯抖動或封包遺失。
- 暫停程式碼同步、相依項下載與大型檔案上傳，觀察輸入回應是否恢復。
- 將解析度降至 1600×900，將色深降至 16-bit，其他設定維持不變。
- 關閉動態桌布、透明效果與高頻更新視窗，減少畫面變化量。
- 若只有特定用戶端出現異常，請使用另一個用戶端進行比對並記錄版本。
建置失敗：從版本、相依項、權限與環境變數逐步縮小範圍
- 輸出目前的 Xcode 版本、命令列工具路徑、架構與目標 SDK。
- 核對相依鎖定檔，清除專案層級衍生資料後執行一次完整建置。
- 比較本機與節點上的 Ruby、fastlane、套件管理器及指令碼版本。
- 檢查工作目錄、暫存目錄與產物目錄是否具備正確的讀寫權限。
- 保存第一個實際錯誤及其前後日誌，不要只提交最終結束代碼。
磁碟空間不足：先定位增長目錄，再執行可復原的清理
- 查看系統磁碟區剩餘空間，並依目錄統計原始碼、快取、衍生資料、模擬器資料與封存檔大小。
- 先刪除可重新產生的專案快取與失敗工作暫存檔。
- 為 CI 工作目錄設定保留數量，避免歷史取出內容與產物持續累積。
- 將長期產物同步至團隊儲存空間，確認校驗結果後再刪除節點副本。
- 若工作負載長期超過 256GB SSD 容量，訂購時請評估儲存空間加購項目。
08 / 安全操作
把首次連線視為安全交接
獨享實體機提供清晰的資源界線；節點內的帳戶、金鑰、專案檔案與存取來源仍應由團隊依最小權限原則管理。
更換臨時憑證
首次登入後立即設定新的高強度密碼，並儲存於團隊認可的憑證管理工具中。不要透過建置日誌或一般文件傳遞密碼。
限制遠端存取來源
將 SSH 與 VNC 的暴露範圍限制於實際需要的團隊出口位址。成員網路變更時更新規則，不要長期保留臨時測試來源。
使用最小權限帳戶
日常建置、遠端操作與 runner 服務分別使用職責明確的帳戶。僅在安裝或系統設定時暫時提升權限，完成後立即退出。
移除臨時金鑰
遷移、排障或外部協作結束後，刪除臨時公開金鑰、短期權杖與測試帳戶。同時檢查自動化指令碼是否仍引用舊憑證。
日誌去識別化範圍：可保留節點編號、時間戳記、指令名稱、結束代碼與錯誤堆疊；應移除密碼、私密金鑰、存取權杖、簽署材料、完整環境變數與專案中的敏感業務資料。
09 / 支援升級
提交可重現資訊，支援才能直接進入排查
技術問題請優先透過主控台工單提交，方便關聯執行個體並持續補充日誌。無法進入主控台或需要售前確認時，可寄送電子郵件。
適合節點與連線問題
登入主控台後進入工單區域，建立技術支援請求並關聯對應節點。每張工單聚焦一個主要問題，避免將無關異常混在同一筆記錄中。
- 節點編號與所在區域
- 含時區的發生時間
- 用戶端城市、網路與連線方式
- 最短重現步驟與預期結果
- 去識別化後的指令輸出與日誌
適合帳戶存取與售前確認
郵件主旨建議使用「問題類型 + 節點編號或訂單識別碼」。內文依時間順序描述已完成的檢查，不要傳送密碼、私密金鑰或未去識別化的簽署材料。
- 聯絡信箱與所在時區
- 問題影響範圍與優先順序
- 已執行的排查步驟
- 可配合排查的時段
- 需要確認的具體問題
提交前
重現一次並記錄準確時間
提交時
附上節點編號與去識別化日誌
提交後
在同一張工單持續補充資訊