用 SSH 執行指令，用 VNC 操作 macOS 圖形介面。整台獨享實體機，並非虛擬機；分批移轉原始碼、工具鏈與 CI，別把本機環境的問題也一併帶過去。
備妥交付資訊與 SSH 公開金鑰後，即可依照下列步驟開始連線。首次設定工具鏈所需時間不計入連線步驟。
準備本機終端機、SSH 公開金鑰與控制台中的主機資訊。範例中的 HOST、PORT、USER 請分別替換成配發的主機位址、SSH 連接埠和使用者名稱，請勿直接照抄。
已有專用金鑰可直接使用。若尚未建立，請在自己的電腦產生一組 Ed25519 金鑰，設定密語，再將 .pub 檔案內容新增至控制台對應的 SSH 公開金鑰設定中。
ssh-keygen -t ed25519 \
-f ~/.ssh/osxbuild_ed25519
cat ~/.ssh/osxbuild_ed25519.pub私鑰請留在本機。請勿貼到工單、電子郵件或程式碼儲存庫；上傳後，依照控制台提示確認公開金鑰已套用至目標執行個體。
從控制台的執行個體詳細資訊取得連線資料。首次出現主機指紋確認提示時，請先比對可驗證的交付資訊；若無法確認，請提交工單，勿為略過提示而關閉主機驗證。
ssh -i ~/.ssh/osxbuild_ed25519 \
-p PORT USER@HOST
sw_vers
uname -m
xcodebuild -version先確認系統、架構與 Xcode 版本。若最後一行顯示工具鏈尚未就緒，請先完成安裝並選取路徑，再設定建置工作。
將以下內容寫入本機的 ~/.ssh/config。範例別名為 bake，後續同步、通道與疑難排解指令都可沿用，免得每次手動輸入位址和連接埠。
Host bake
HostName HOST
Port SSH_PORT
User SSH_USER
IdentityFile ~/.ssh/osxbuild_ed25519
IdentitiesOnly yes
ServerAliveInterval 30
ServerAliveCountMax 3儲存後執行 ssh bake。連線保活設定可用來偵測失效連線，但無法取代網路重新連線，也不會讓終端機中的工作自動恢復。
需要設定 Xcode、檢查鑰匙圈或查看模擬器時，再開啟桌面。請先確認控制台提供的 VNC 服務資訊，別把預設連接埠當成每台主機的連線參數。
macOS 可使用系統內建的「螢幕共享」；Windows 與 Linux 可使用支援 VNC 的 TigerVNC 用戶端。若需另外安裝用戶端，請從官方發行管道下載，並確認支援服務所採用的驗證方式。
先從 1440 × 900 或 1600 × 1000 的桌面解析度開始，不必一開始就使用高解析度螢幕的完整尺寸。若可選擇色彩深度，建議先試 24 位元；網路受限時再試 16 位元。實際選項以用戶端和伺服器支援為準。
終端機建置與遠端桌面是兩種不同的操作方式。若桌面拖曳不夠順暢，可繼續透過 SSH 執行建置，再取回記錄檔和 IPA，不必讓整條工作流程都依賴畫面更新。
在本機執行以下指令，並讓此終端機保持開啟。VNC_PORT 請替換成配發的服務連接埠；範例中的 15900 是本機連接埠，可改用尚未占用的連接埠。
ssh -N \
-L 127.0.0.1:15900:127.0.0.1:VNC_PORT \
-o ExitOnForwardFailure=yes \
bake接著在 VNC 用戶端的位址欄輸入 127.0.0.1，並在連接埠欄輸入 15900。若用戶端只有單一位址欄，請依照其說明文件填入相應格式。
VNC 仍使用配發的桌面登入資料進行驗證，SSH 金鑰不能取代桌面密碼。使用完畢後，請先退出用戶端，再按 Ctrl + C 關閉通道。
| 狀況 | 優先檢查項目 | 接下來怎麼做 |
|---|---|---|
| 本機連接埠無法建立 | SSH 是否已連通、本機連接埠是否已被占用 | 更換本機連接埠，並保留通道終端機中的錯誤訊息 |
| 通道已建立，但桌面仍拒絕連線 | 配發的 VNC 連接埠與服務監聽狀態 | 核對執行個體詳細資訊，勿額外將桌面連接埠開放至公網 |
| 通過驗證後仍連線失敗 | 桌面使用者名稱、密碼與用戶端驗證相容性 | 重新核對配發的登入資料；請勿將 SSH 私鑰當成 VNC 密碼 |
| 已登入，但畫面更新緩慢 | 解析度、色彩深度、本機網路與節點距離 | 降低畫面傳輸量，並透過 SSH 繼續執行不需圖形介面的建置 |
先備妥資料，再對齊工具鏈，最後接入 CI。每個步驟都留下驗收結果；先成功完成一次乾淨的 archive，再恢復快取與自動化。
使用 Git 下載專案，或透過 rsync 同步本機工作目錄與儲存庫外的資源。第一次同步先排除 DerivedData 和舊的 build 目錄，也不要把簽章私鑰混入一般檔案同步。
rsync -az --progress \
--exclude='DerivedData/' \
--exclude='build/' \
--exclude='*.p12' \
--exclude='*.mobileprovision' \
./ bake:~/project/驗收：確認目標目錄、提交版本與必要資源一致。範例不含刪除參數，避免首次同步時誤刪遠端檔案；同步成功不代表備份已完成。
依專案需求安裝或選取 Xcode，並設定 Homebrew。依照鎖定檔還原 CocoaPods，SPM 則先重新解析；快取須與工具鏈及依賴版本相符，勿直接沿用來源不明的目錄。
xcode-select -p
xcodebuild -version
brew --version
bundle install
bundle exec pod install驗收：版本與本機基準一致，依賴套件可正常解析。只有 CocoaPods 專案才執行最後兩行。請透過受控管道將簽章憑證另行匯入鑰匙圈，並檢查有效期限及佈建描述檔是否相符。
在 GitHub Actions 或 GitLab Runner 註冊專用執行器，先檢查版本，再執行專案的 Fastlane lane。先驗證 archive 與匯出，最後再加入上傳步驟。
xcodebuild -list \
-workspace App.xcworkspace
bundle exec fastlane ios build驗收：記錄檔可追溯至提交版本、Scheme 與產物路徑。範例中的工作區和 lane 名稱須改為專案實際名稱；發佈憑證應個別授權，不隨原始碼散佈。
自架執行器使用您租用的實體節點。標籤用來指定工作路由，憑證用來授權，兩者不可混為一談。先讓單一工作順利執行，再評估平行工作數與磁碟用量。
依照儲存庫或組織設定中的指引註冊 self-hosted runner，並新增自訂標籤 osxbuild。以下工作流程會檢查工具鏈並產生封存檔，不包含注入簽章材料、匯出 IPA 或發佈。
name: iOS archive
on:
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ios-${{ github.ref }}
cancel-in-progress: false
jobs:
archive:
runs-on: [self-hosted, macOS, ARM64, osxbuild]
steps:
- uses: actions/checkout@v4
- name: Check Xcode
run: xcodebuild -version
- name: Archive
run: |
xcodebuild \
-workspace App.xcworkspace \
-scheme App \
-configuration Release \
-archivePath "$RUNNER_TEMP/App.xcarchive" \
archive請替換工作區與 Scheme，並確認 Scheme 已設為共用。只有可信任的儲存庫與工作才能使用存有簽章材料的 runner；不同分支會產生不同的並行群組，仍須避免多個工作同時使用同一個建置目錄。
在 Jenkins 新增固定節點，遠端工作目錄請使用專用的建置目錄，並將標籤設為 osxbuild-mac。選擇透過 SSH 啟動 agent，填入配發的主機和連接埠，並由 Jenkins 憑證庫管理私鑰。
pipeline {
agent { label 'osxbuild-mac' }
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Toolchain') {
steps {
sh 'xcodebuild -version'
}
}
stage('Build') {
steps {
sh 'bundle exec fastlane ios build'
}
}
}
}先確認 agent 所需的 Java 可正常使用、SSH 憑證有效，且主機指紋已驗證。透過 SSH 啟動的非互動環境可能不會載入本機 shell 設定，因此必須明確設定 Homebrew、Ruby 與 Fastlane 的路徑。
GitLab Runner 的設定順序也相同：註冊執行器、限制可信任的專案、設定專案標籤，再用版本檢查工作驗收環境。若測試需要圖形工作階段，請先個別確認執行條件。
先從一個執行槽開始。增加平行工作前，先檢查記憶體用量峰值、模擬器數量與 DerivedData 路徑；勿讓多個工作同時寫入同一個封存目錄。
若經常使用圖形桌面，優先比較團隊與節點之間的連線路徑；若主要用於 CI，則留意原始碼、依賴套件與產物的傳輸路徑。地理距離只是參考，實際體驗還會受到電信業者、路由與本機網路影響。
SG · UTC+8
適合配合東南亞團隊的工作時區。若團隊白天經常遠端操作 Xcode，可優先比較本機連線至此節點的表現。
JP · UTC+9
適合配合東亞團隊的工作時區。可在同一台主機上安排白天互動式開發與夜間封存，減少環境交接。
KR · UTC+9
適合配合東北亞團隊的工作時區。若經常使用遠端桌面，先實際測試畫面更新與輸入反應，再決定團隊固定入口。
HK · UTC+8
適合配合華南與東南亞團隊的工作時區。除了遠端操作體驗，也要檢查依賴下載與產物上傳，別只憑一次連線結果做判斷。
US-E · UTC−5 / −4
適合配合北美東部與西歐團隊協作。安排 nightly 工作時請明確設定時區，並留意夏令時間造成的當地時間變化。
US-W · UTC−8 / −7
適合配合北美西岸團隊協作。將建置時段安排在當地工作日；跨時區交接時，請在記錄檔中標明時區。
兩種方案均提供上述六個節點，實際供應情況以控制台即時資訊為準。節點全年 365 天持續運作；請將本機網路中斷或 SSH 工作階段斷線，與主機運作狀態分開判斷。
先保留一條已驗證可用的連線，再調整存取策略。每次只變更一項；確認新連線成功後，再關閉舊工作階段，避免自己無法重新連回主機。
先開啟第二個終端機，確認可使用專用金鑰登入，再依照系統的 SSH 設定方式停用密碼驗證。變更設定前先檢查語法，並確認有其他方式可重新連線；不熟悉系統設定時，請先提交工單確認操作方式。
依用途限縮遠端登入與服務入口，VNC 優先透過 SSH 通道連線。避免將除錯服務、建置控制介面或暫存檔案服務直接公開至網際網路；請一併檢查本機位址繫結與存取控制設定。
人工登入與 CI 請使用不同金鑰；人員異動或懷疑憑證外洩時，請立即撤銷舊授權。輪替金鑰時，先新增並驗證新的公開金鑰，再移除舊金鑰，最後更新執行器與團隊交接記錄。
依建置需求解鎖鑰匙圈，使用後立即收緊存取權限。透過憑證系統注入 API Key、憑證密語與 match 解密憑證；檢查指令碼是否會輸出敏感變數，並勿將私鑰檔案存入儲存庫。
將需保留的原始碼、IPA、封存檔與工作流程設定同步至團隊自有儲存空間，並確認檔案可讀。租期結束後，回收程序會清除磁碟並重新安裝系統，因此勿將主機本機目錄當作唯一副本。
提供以下資訊即可協助排查。提交工單時，請附上訂單編號、節點、錯誤發生時間與時區，以及已移除敏感資訊的最後 50 行記錄。請勿傳送私鑰、憑證密語或帳戶密碼；連線問題請透過控制台工單或 support@osxbuild.com 聯絡我們。