用戶端
準備支援的連線工具
確認用戶端版本可用，並保留一種備用存取方式。首次工作階段前，關閉會重新設定鍵盤對應、代理伺服器或顯示縮放的擴充功能。
連線與遷移手冊
從交付資訊到可重現的雲端 Mac 工作流程
先驗證節點、憑證與本機網路，再建立遠端工作階段。連線穩定後，沿著程式碼資料、工具鏈與 CI 三條路徑遷移，不要一次搬移整個本機環境。
- 連線順序
- 核對交付 → 建立工作階段 → 修改憑證
- 遷移順序
- 程式碼資料 → 工具鏈 → CI
工作階段交接登記板
REMOTE / READY
01
驗證交付資訊
節點位址、使用者名稱、存取方式
02
建立工作階段
網路、畫面、鍵盤與權限
03
遷移工作流程
資料、工具鏈、Runner 與產物
硬體類型
獨享實體主機
執行環境
非虛擬機
處理原則
小批次遷移，隨時可驗證回復
連線前檢查
先在本機排除工作階段失敗因素
首次連線時不要同時遷移專案。先完成五項基礎檢查，確認本機用戶端、網路與交付資料足以支援一段穩定的工作階段。
網路
使用穩定連線完成首次連線
優先使用有線網路或穩定的 Wi-Fi，暫停大型檔案同步與本機上傳。若經過企業代理伺服器，先確認遠端工作階段與 SSH 流量未遭改寫。
交付資料
逐項核對位址與憑證
從控制台讀取節點位址、使用者名稱與連線方式，不要從聊天記錄或舊工單複製。憑證只存放在密碼管理工具中，不要寫入指令碼或儲存庫。
顯示
先以保守解析度連線
首次連線使用單一顯示器與一般縮放，確認文字、游標與快速鍵正常後再提高解析度，避免將顯示問題誤判為網路問題。
本機檔案
只準備首輪驗證所需資料
首批只帶專案清單、相依套件鎖定檔與一個可驗證的小型分支。媒體原始檔、歷史快取與封存檔留待連線驗證完成後分批傳輸。
首次連線流程
一次只驗證一個變數
將第一次工作階段拆成位址、連線、憑證、輸入與顯示五個步驟。每一步都有明確完成條件，發生異常時即可定位到最近一次變更。
-
01
完成條件：目標資訊逐項一致
驗證節點位址
對照控制台的交付資訊，檢查主機名稱或位址、使用者名稱與連線協定。先確認目標節點一致，再嘗試建立工作階段。
-
02
完成條件：輸入與畫面持續可用
建立最小工作階段
使用單一顯示器、一般解析度與預設畫質連線，維持數分鐘並完成視窗切換、文字輸入與檔案瀏覽。
-
03
完成條件：使用新憑證重新登入成功
修改初始憑證
首次登入後立即設定獨立且強度足夠的憑證，更新密碼管理工具中的記錄，並讓交付階段使用的初始憑證退出日常流程。
-
04
完成條件：編輯器快速鍵沒有衝突
確認鍵盤配置
測試 Command、Option、Control、方向鍵及常用中英文輸入。遠端用戶端與 macOS 配置應保持一致。
-
05
完成條件：在目標畫面下穩定操作
調整顯示設定
基礎工作階段穩定後，再提高解析度、縮放與畫質。每次只修改一項，並觀察文字清晰度、游標延遲與網路用量。
遷移路徑
從本機 Mac 到雲端 Mac，拆分為三條可回復路徑
依序執行三條路徑。每欄都記錄輸入、操作、驗證結果與回復點，避免在遠端環境尚未穩定時，同時變更程式碼、工具版本與自動化設定。
資料遷移
- 輸入
- 程式碼儲存庫、相依套件鎖定檔、必要素材與校驗清單
- 操作
- 先傳送可建置的小型分支，再按目錄分批同步快取、素材與封存檔
- 驗證結果
- 儲存庫狀態一致，關鍵檔案校驗通過，範例專案可讀取
- 回復點
- 保留本機原始副本，遠端批次存入獨立暫存目錄
重現工具鏈
- 輸入
- macOS、Xcode、命令列工具、套件管理器與指令碼版本表
- 操作
- 依相依性順序安裝並鎖定版本，逐項執行診斷指令
- 驗證結果
- 同一提交可完成解析、編譯、測試與封存前檢查
- 回復點
- 保存版本清單與設定副本，失敗時回到上一組已驗證版本
CI 整合
- 輸入
- Runner 設定、變數清單、金鑰範圍、建置目錄與產物規則
- 操作
- 先註冊隔離的 Runner，再接入最小建置工作與產物上傳
- 驗證結果
- 工作可重複執行，記錄、退出碼與產物位置清楚
- 回復點
- 停用新 Runner，恢復原執行器並清理遠端暫存目錄
資料遷移指南
依可重建性決定傳輸優先順序
程式碼與設定優先，可重新產生的快取延後處理；難以重建的簽署材料與媒體原始檔則獨立驗證。大型套件遷移前，先用小型樣本驗證路徑與權限。
| 資料類型 | 首批內容 | 建議操作 | 驗證方式 | 回復處理 |
|---|---|---|---|---|
| 程式碼儲存庫 | 主要儲存庫、子模組、相依套件鎖定檔 | 從乾淨複製開始，避免直接複製帶有本機狀態的工作目錄 | 檢查分支、提交編號、子模組與未追蹤檔案 | 刪除遠端副本後重新複製 |
| 建置快取 | 只遷移已確認可重複使用的快取 | 先完成一次無快取建置，再依工具分別恢復快取 | 比較命中記錄、建置結果與磁碟用量 | 清空對應快取目錄並重新產生 |
| 簽署材料 | 專案實際需要的最小集合 | 透過受控加密通道傳輸，限制檔案與鑰匙圈權限 | 執行不上傳產物的簽署驗證 | 移除匯入項目並撤銷臨時存取權限 |
| 媒體素材 | 一組可完成流程驗證的小型樣本 | 依專案、批次與用途建立目錄，不要與快取混放 | 檢查檔案數量、大小與內容校驗值 | 刪除目前批次並從本機原始檔重新上傳 |
| 大型封存檔 | 索引、清單與單一測試封存檔 | 分卷傳輸，記錄每卷狀態，避免一次覆蓋目標目錄 | 逐卷校驗並抽查解壓結果 | 只重新傳輸失敗分卷，不重複完整傳輸 |
遷移完成判定標準
不是「檔案已經傳完」，而是遠端能根據明確的提交與相依套件清單，重現一次可核對的建置結果。
重現工具鏈
先登記版本，再恢復專案環境
不要從「安裝所有常用工具」開始。以專案實際相依項目為界，依序重現系統、編譯器、命令列工具、相依套件管理、憑證與指令碼。
登記項目
核對動作
通過訊號
macOS
記錄系統版本、架構、磁碟空間與地區設定，確認專案需求與系統能力相容。
系統資訊已歸檔
Xcode
確認專案指定版本、首次啟動元件與目前開發者目錄，不依賴圖形介面中的暫時選擇。
版本與路徑一致
命令列工具
檢查編譯器、SDK、Git、Ruby 或專案所需的其他執行環境，記錄實際解析到的路徑。
命令解析沒有歧義
套件管理器
依鎖定檔恢復相依套件，區分全域工具與專案內相依套件，避免以本機既有快取掩蓋缺漏。
乾淨安裝可重複
憑證與權限
只匯入目前工作所需的材料，核對鑰匙圈存取範圍、檔案權限與自動化程序可見性。
最小範圍驗證通過
專案指令碼
從唯讀檢查開始，再執行相依套件解析、測試與建置。指令碼不得依賴本機未登記的絕對路徑。
同一提交結果一致
CI 整合
先跑通最小工作，再接入正式管線
Runner 整合不應與工具鏈遷移同時進行。先確認人工工作階段中的建置可重複，再將同一指令放入自動化工作。
註冊隔離的執行器
為雲端 Mac 使用獨立的 Runner ID 與標籤，限制可接收的儲存庫與工作類型。先執行只輸出系統資訊的診斷工作。
分開設定變數與密鑰
一般環境變數記錄版本與路徑，敏感值交由受控的密鑰儲存區管理。記錄中禁止回顯權杖、私鑰與簽署材料。
固定建置目錄範圍
區分原始碼、相依套件快取、暫存輸出與最終產物目錄。工作開始前檢查剩餘容量，結束後只清理可重建的內容。
明確定義產物上傳規則
上傳動作只讀取約定的輸出目錄，同時保留提交編號、建置編號與校驗資訊，避免將暫存記錄混入交付套件。
讓失敗的工作可安全重新執行
擷取退出碼並清理鎖定檔、暫停程序與暫存目錄。保留診斷記錄後，下一次工作應從已知狀態開始。
切換至正式管線前
至少驗證一次全新的工作目錄建置、一次失敗後重新執行，以及一次產物上傳與校驗。三項皆通過後，再擴大工作範圍。
連線指令範例
使用唯讀指令確認工作階段與基礎環境
以下檢查不會修改系統設定。先在本機終端機設定控制台交付的主機與使用者名稱，再建立 SSH 工作階段，並記錄系統、架構、磁碟與開發工具路徑。
不要寫入儲存庫
主機、使用者名稱、金鑰路徑與權杖不得寫入專案指令碼或版本控制。
不要立即安裝
先完成唯讀檢查，確認目前狀態後再變更工具鏈。
工作階段驗證清單
READ ONLY
export SETMINI_HOST="控制台交付的節點地址"
export SETMINI_USER="控制台交付的使用者名稱"
ssh "${SETMINI_USER}@${SETMINI_HOST}"
hostname
sw_vers
uname -m
df -h /
xcode-select -p
xcodebuild -version
git --version
echo "$SHELL"
工作階段安全
將遠端工作階段視為正式環境存取管理
獨享實體主機不代表可以放鬆存取控制。憑證、權限、鎖定螢幕、登出與敏感檔案清理，都需要納入團隊交接清單。
強效憑證
為節點設定獨立憑證，並由密碼管理工具保存。成員異動、疑似外洩或發生異常登入後，立即更新。
最小權限
日常開發使用完成工作所需的最低權限。臨時提升權限後及時退出，不要將高權限寫入自動化指令碼。
離席鎖定螢幕
短暫離席也要鎖定工作階段。在共用辦公環境中，同時關閉本機螢幕預覽，避免遠端內容外洩。
完整結束工作階段
工作完成後登出遠端用戶端與 SSH 工作階段，確認背景沒有遺留互動式程序或暫存的連接埠轉送。
清理敏感檔案
移除暫存下載、除錯匯出、未加密封存檔與不再需要的簽署材料，並保留清理記錄。
回報存取異常
發現未知工作階段、異常程序或憑證風險時，先保存發生時間與必要記錄，再透過控制台提交工單。
登入控制台提交工單