從連線到交付

跑通第一條 iOS 封存 pipeline

先確認連線正常，再鎖定工具鏈，最後接入 CI。依照實際操作順序，將一台獨享實體 Mac 設定為可重複執行封存工作的節點。非虛擬機，可使用 macOS 圖形介面與命令列。

租用 iOS 封存機登入控制台

已有主機，請從下方「開通與登入」開始；尚未選型的話，可先用單一工作驗證建置，再決定並行規模。

開通與登入

核對訂單與主機憑證，完成首次 SSH 連線並新增自己的登入公鑰。

查看首次連線步驟

遠端連線

腳本與 CI 使用 SSH；除錯 Xcode、模擬器及圖形介面時，使用 VNC 螢幕共享。

查看連線設定

CI 整合

註冊 self-hosted runner、確認工具鏈標籤，並先將每台主機的建置並行數設為 1。

設定 runner

帳單與續租

核對計費週期、附加項目及到期時間。訂單、付款與續租狀態以控制台顯示為準。

查看帳單指南

先確認連線正常

開通後第一小時，先完成這四件事

以下為建議操作順序，並非開通或處理時限承諾。請先在控制台確認服務已開通，再使用該執行個體實際提供的位址、連接埠與使用者名稱。請勿猜測主機憑證。

核對執行個體

登入控制台，在對應服務詳情中核對機型、節點與租期。記下主機編號；後續排查、續租與工單都會以此編號識別。連線位址與初始憑證只可在授權帳戶中查看。
首次 SSH 登入

將控制台提供的資料填入本機連線參數。首次連線時，請核對主機金鑰指紋；若沒有可信的指紋來源，請先透過工單確認，切勿直接略過驗證。連線成功後，檢查系統與使用者資訊。
變更登入密碼

在互動式 SSH 工作階段中執行 passwd，並依提示變更目前使用者的密碼。請勿將密碼寫入命令參數、程式碼儲存庫、聊天記錄或建置日誌。保持目前的工作階段，再開啟另一個工作階段確認新憑證可用。
新增登入公鑰

在自己的電腦上產生專用金鑰，只將公鑰加入主機。確認可透過公鑰登入後，再調整密碼登入設定；變更 SSH 服務設定前，請保留可用的工作階段，避免無法再登入主機。

本機連線參數與主機檢查

ssh -p "$MAC_SSH_PORT" "$MAC_USER@$MAC_HOST"

whoami
sw_vers
uname -m
xcode-select -p
df -h
passwd

連線前，請在本機設定 MAC_SSH_PORT、MAC_USER、MAC_HOST，值請從控制台取得。其餘命令請在登入後的主機上執行；xcode-select -p 用來檢查目前的開發工具路徑。

主機端 · 加入已複製的公鑰

install -d -m 700 "$HOME/.ssh"
touch "$HOME/.ssh/authorized_keys"
chmod 600 "$HOME/.ssh/authorized_keys"
printf '%s\n' "$LOGIN_PUBLIC_KEY" >> "$HOME/.ssh/authorized_keys"

先將 LOGIN_PUBLIC_KEY 設為完整的公鑰文字，再執行追加命令。請勿上傳私鑰，也不要重複加入相同公鑰。連線逾時、驗證失敗與主機金鑰變更是不同問題，提交工單時請分別說明。

打造可重現的環境

鎖定 Xcode，再準備模擬器

先記下專案所需的 Xcode、SDK 與 runtime 版本，不要直接升級至最新版。系統與 Xcode 的相容性會決定可安裝的版本範圍；既有專案應先沿用本機成功建置的組合，再另外驗證升級。

如果主機尚未安裝 xcodes，請依照團隊認可的軟體安裝流程準備此工具。安裝指定版本時，請使用合法取得且符合專案需求的本機 Xcode 安裝套件；以下的 XCODE_VERSION 與 XCODE_XIP 分別代表已核對的版本號與安裝套件絕對路徑。請勿將安裝過程中的互動步驟放入無人值守的建置工作。

主機端 · 安裝並核對開發工具

xcodes installed
xcodes install "$XCODE_VERSION" --path "$XCODE_XIP"
xcodes installed

export DEVELOPER_DIR="$XCODE_APP/Contents/Developer"
xcodebuild -version
xcodebuild -showsdks
xcrun simctl list runtimes

XCODE_APP 應指向安裝後實際的 App 路徑。CI 建議優先在工作環境中設定 DEVELOPER_DIR，避免多個工作爭用全域選擇。若確實需要切換系統預設工具鏈，再執行 sudo xcode-select --switch "$XCODE_APP/Contents/Developer"，然後重新核對 xcodebuild -version。

首次啟動所選的 Xcode，完成必要的元件準備。可透過遠端連線操作圖形介面；接著在 Xcode 的元件設定中安裝目標 runtime。執行 xcrun simctl list devices available，選擇符合測試目標的模擬器，先以互動方式啟動一次並等待啟動完成，再執行最小測試工作。封存實機 App 與執行模擬器測試是不同步驟，請勿將缺少 runtime 誤判為封存工具鏈故障。

在 CI 日誌開頭加入工具鏈檢查，至少輸出 Xcode 版本、SDK 清單及程式碼提交編號。更換 Xcode 後，請重新產生快取索引鍵，並驗證第三方依賴、簽章與匯出流程；只修改 runner 標籤而不核對實際工具路徑，無法確保建置環境一致。

先跑單一工作，再逐步擴充

將主機註冊為 self-hosted runner

同一台實體節點上的工作會共用 CPU、記憶體、磁碟與使用者環境。起步時每台主機只執行 1 個建置工作；確認封存、簽章與清理流程都穩定後，再依實際尖峰用量增加並行數，或新增獨立節點。

GitLab Runner：核對標籤與執行器

在專案的 runner 設定中建立專案 runner，準備對應的驗證 token，並設定 macos、arm64、ios-archive 這三個標籤。將執行個體位址與驗證 token 暫時存入 GITLAB_URL、GITLAB_RUNNER_TOKEN，再以專用建置使用者註冊 shell executor。完成後請清除暫存的 token 變數。

GitLab Runner · 註冊與並行設定

gitlab-runner register \
  --non-interactive \
  --url "$GITLAB_URL" \
  --token "$GITLAB_RUNNER_TOKEN" \
  --executor "shell" \
  --description "armrdp-ios-archive"

unset GITLAB_RUNNER_TOKEN
gitlab-runner verify

在該 runner 實際使用的 config.toml 中，將全域 concurrent = 1，並為對應的 runner 設定 limit = 1。依照已安裝版本的服務管理方式啟動 runner；互動式驗證成功，不代表背景服務已在執行。

專案端 · .gitlab-ci.yml 封存工作

ios_archive:
  tags:
    - macos
    - arm64
    - ios-archive
  script:
    - xcodebuild -version
    - xcodebuild archive -workspace "$IOS_WORKSPACE" -scheme "$IOS_SCHEME" -destination 'generic/platform=iOS' -archivePath "$CI_PROJECT_DIR/output/App.xcarchive"
  artifacts:
    paths:
      - output/App.xcarchive
    expire_in: 7 days

在專案變數中設定實際的 IOS_WORKSPACE 與 IOS_SCHEME，並先完成下一節的簽章準備。此處只執行封存，不包含匯出或上傳步驟；保留產物 7 天只是設定範例，可依團隊的保留政策調整。請勿將憑證、私鑰或臨時 Keychain 放入 artifacts。

GitHub Actions：一個 runner 程序一次執行一項工作

依照儲存庫設定提供的 runner 安裝步驟，下載適用於 macOS ARM64 的程式，並進入解壓縮目錄。將 REPOSITORY_URL 設為目前的儲存庫位址，並將RUNNER_TOKEN 設為本次註冊使用的 token。註冊設定與工作流程必須包含相同標籤，才能避免工作被派送到錯誤的工具鏈。

GitHub Actions · 主機註冊

./config.sh \
  --url "$REPOSITORY_URL" \
  --token "$RUNNER_TOKEN" \
  --name "armrdp-ios-archive" \
  --labels "macos,arm64,ios-archive" \
  --work "_work"

unset RUNNER_TOKEN
./run.sh

專案端 · GitHub Actions 工作流程

name: iOS archive
on:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ios-archive
  cancel-in-progress: false

jobs:
  archive:
    runs-on: [self-hosted, macos, arm64, ios-archive]
    env:
      DEVELOPER_DIR: ${{ vars.DEVELOPER_DIR }}
      IOS_WORKSPACE: ${{ vars.IOS_WORKSPACE }}
      IOS_SCHEME: ${{ vars.IOS_SCHEME }}
    steps:
      - uses: actions/checkout@v4
      - name: Archive
        run: |
          xcodebuild -version
          xcodebuild archive \
            -workspace "$IOS_WORKSPACE" \
            -scheme "$IOS_SCHEME" \
            -destination 'generic/platform=iOS' \
            -archivePath "$RUNNER_TEMP/App.xcarchive"

先設定儲存庫變數中的工具路徑、workspace 與 scheme。此範例採手動觸發，方便先驗證環境；請勿直接讓不受信任的外部程式碼使用含簽章憑證的 runner。一個 runner 程序同時只接一項工作，concurrency 也會限制同一組工作流程的執行；但它不是主機層級的資源限制。

驗證通過後，請依照下載程式提供的服務腳本設定常駐執行，並確認服務使用者與手動測試使用者相同。若在一個使用者帳戶下準備簽章，服務卻以另一個帳戶執行，常見情況是互動式建置成功，但 CI 找不到憑證或描述檔。

憑證與程式碼分開管理

以建置使用者設定簽章環境

發佈憑證、對應的私鑰與描述檔必須符合專案所屬團隊及 Bundle Identifier。請先在受控工作中驗證簽章，再整合無人值守流程；不要藉由停用簽章檢查來掩蓋匯出失敗。

自動化工作請使用獨立的建置 Keychain，並透過 CI 受保護的秘密變數提供密碼。匯入憑證後，只授權確實需要的簽章工具存取；不要開放所有 App 使用私鑰。以下檢查命令可確認目前使用者看得到有效簽章身分，但無法證明描述檔、匯出設定與專案設定完全相符。

主機端 · 檢查簽章身分與描述檔目錄

security list-keychains -d user
security find-identity -v -p codesigning
printf '%s\n' "$HOME/Library/MobileDevice/Provisioning Profiles"
printf '%s\n' "$HOME/Library/Developer/Xcode/UserData/Provisioning Profiles"

不同 Xcode 版本使用的描述檔位置可能不同，請以目前工具鏈實際讀取的路徑為準。匯入後檢查有效期限、App 識別碼與簽章類型。若封存成功但匯出失敗，請優先核對匯出設定中的發佈方式、團隊識別碼與描述檔對應，而非反覆重新安裝 Xcode。

團隊已使用 fastlane match 的話，請沿用現有的加密憑證儲存庫與存取政策。驗證階段請使用 bundle exec fastlane match appstore --readonly，先讀取現有簽章資料，避免建置節點意外修改團隊憑證。請分別管理儲存庫存取憑證、解密密碼與 Keychain 密碼；生產環境的簽章變數只開放給受保護分支或受控的手動工作。

工作結束後，請清除暫存檔並鎖定臨時 Keychain。日誌只保留必要的錯誤碼與步驟結果，不要輸出私鑰內容、憑證密碼、註冊 token 或完整的秘密變數。獨享實體機能隔離資源，但專案中的憑證權限仍應遵循最小授權原則。

把快取視為可重建資料

確認擴充磁碟區，再遷移 DerivedData

可加購 +1TB SSD 或 +2TB SSD。請先在訂單與主機端確認擴充已完成，再安排資料遷移；磁碟區名稱、掛載路徑與檔案系統依實際交付資訊為準，請勿照抄其他主機的磁碟識別碼。

執行 diskutil list 與 df -h，核對容量與掛載點。請勿對不明磁碟執行清除或分割命令。為建置使用者建立具有寫入權限的快取目錄，並以小型檔案測試讀寫；確認重新啟動後的掛載行為，再讓常駐 runner 使用新路徑。

遷移前，請暫停接收新工作，並等待進行中的封存與簽章完成。DerivedData 是可重建的快取，建議在新位置重新產生，而不要複製可能仍在寫入的舊快取。以下使用明確指定的 -derivedDataPath，無須將整個使用者目錄遷移至擴充磁碟區。

主機端 · 檢查掛載並指定建置快取

diskutil list
df -h

test -d "$BUILD_VOLUME" && test -w "$BUILD_VOLUME"
mkdir -p "$BUILD_VOLUME/DerivedData/$CACHE_KEY"

xcodebuild archive \
  -workspace "$IOS_WORKSPACE" \
  -scheme "$IOS_SCHEME" \
  -destination 'generic/platform=iOS' \
  -derivedDataPath "$BUILD_VOLUME/DerivedData/$CACHE_KEY" \
  -archivePath "$BUILD_VOLUME/Archives/$BUILD_ID/App.xcarchive"

執行前，請將 BUILD_VOLUME 設為已確認可寫入的掛載目錄。CACHE_KEY 應能區分儲存庫、Xcode 版本與建置設定；BUILD_ID 請使用目前工作專屬的唯一識別碼，避免不同工作覆寫封存檔。並行工作不要共用同一個可寫入的 DerivedData 目錄。

先執行一次不使用快取的建置，再觀察後續工作的快取命中情況與磁碟用量增長。為封存檔、模擬器資料及依賴快取分別設定保留政策；刪除前確認沒有工作仍在使用。建置產物應另外儲存至由團隊管理的產物儲存空間，不要將主機快取當作唯一備份。租期結束前完成匯出，並確認備份可讀取。

查看儲存空間附加項目價格

讓問題容易重現

工單寫清楚操作步驟，比只貼錯誤訊息更有效

如有主機、訂單或付款問題，請登入控制台提交工單，以便對應實際服務。若無法登入，可寄送電子郵件至 support@armrdp.com。以上兩種方式皆為正式聯絡管道。

依問題類型補充資料，請勿提供密碼、私鑰或完整付款憑證。
欄位	建議填寫內容	用途
主機或訂單編號	控制台中的對應編號，以及目前使用的節點	找出正確的服務，避免查錯執行個體
發生時間	開始與結束時間、時區，以及問題是否仍在持續	比對服務記錄與工作日誌
問題類別	連線逾時、驗證失敗、建置失敗、簽章失敗或帳單狀態	區分網路、工具鏈與付款問題
重現步驟	執行順序、最簡命令、預期結果與實際結果	減少來回確認所需的背景資訊
環境與日誌	Xcode 版本、runner 服務使用者，以及錯誤發生前後的去識別化日誌	確認問題是否與版本或權限有關
業務影響	受影響的是單一工作還是整台主機，以及是否有可用的替代建置方式	說明影響範圍與目前的處理情況

分開看回覆時間與解決時間

工單處理進度與回覆時間以控制台中的實際紀錄為準，首次回覆不代表問題已解決。連線問題可能需要檢查主機狀態與連線路徑；建置問題通常還需要工作日誌與重現步驟；付款問題則需要關聯訂單及交易紀錄。這些情況無法套用同一個固定的解決時限。

等待期間，建議將新證據補充到同一張工單，註明已等待時間及影響是否擴大。請勿重複執行可能改變現場狀況的重新安裝、清除磁碟或大量清理操作。如果錯誤只出現在 CI，請保留同一使用者帳戶下互動式執行與服務執行的差異；若涉及簽章，只提供已去識別化的錯誤資訊。

帳單、續租與到期前檢查

服務採天、週、月、季預付。查看訂單時，請一併核對機型、節點、週期起訖時間與附加項目。續租、自動續租設定及付款結果，均以控制台目前設定與實際回應為準；提交付款不代表訂單已開通，請勿只憑付款頁面截圖判斷服務狀態。

僅支援 USDT-TRC20 與 Visa / Mastercard / Amex（透過 Stripe），一律以美元結算；實際可用的付款閘道以後端回應為準。使用鏈上付款時，請核對網路、收款資訊與金額；需要排查時，請提供訂單編號與交易識別碼，切勿提供錢包私鑰或完整信用卡資料。

到期前，請先停止新增建置，匯出程式碼變更、封存產物及必要設定，並在自己的儲存空間確認資料可還原。若打算繼續使用，完成續租後請再次確認新的到期時間；若打算結束租用，請勿將到期後的主機當作長期封存空間。

登入並提交工單查看帳單與使用常見問題

先讓一個 scheme 穩定完成封存

從單一主機、單一工作開始，驗證工具鏈、簽章與產物，再擴充至多台 runner。獨享實體 Mac 按天租用，入門價格為 $21.1/天；實際供應狀態以控制台即時資訊為準。

租用 iOS 封存節點比較三種機型