2026年跨區域遠端 Mac 完成 Apple 公證與 App 上架
notarytool、Stapler、Transporter 出口與重試引數決策清單

約 23 分鐘閱讀 · MACCOME

釋出工程與 iOS 負責人把歸檔、公證與 Transporter 上傳搬到新加坡、日本、韓國、香港、美國東部、美國西部的遠端 Mac 上以後,最常見的翻車點不是「不會籤」,而是公證佇列、鑰匙串上下文、出口網路與上傳重試策略在跨區鏈路上被放大。本文給出六類可寫進發布 Runbook 的糾結點「在哪臺遠端 Mac 上跑公證/上傳」的對照表三條可與值班表對齊的量化口徑notarytool 非互動示例與 Stapler 觸發條件六步落地 Runbook;並與《Fastlane 與證書同步》《可復現乾淨構建》《多地區節點與租期指南》互補——前兩者保證簽名與構建一致性,本篇保證Apple 公證服務與 App Store Connect 側的出口與重試閉環

先把「公證與上傳為什麼總在半夜失敗」寫成六條清單

Apple 的公證與分發鏈路依賴本機工具鏈版本、可用憑證、到 Apple 服務端的雙向 TLS 質量,在遠端桌面上還會疊加會話鎖屏、代理與企業出口策略。下面六條建議與 CI 面板裡的失敗重試直方圖同一頁出現,避免把「偶發」當成「神秘」。若你尚未固定多地區構建機角色,請先讀《多地區節點與租期指南》再往下看。

  1. 鑰匙串與會話上下文:互動式登入與 ssh 非互動會話看到的鑰匙串項不一致;自動化若未顯式解鎖或指定分割槽,會在「本機手工能過、流水線偶發不過」上反覆消耗人時。
  2. 公證提交與查詢的時序:notarytool submit 返回的 id 需要輪詢 info;跨區 RTT 升高時,過短的輪詢間隔會放大限流體感,過長又會拖垮釋出窗。
  3. 磁碟與臨時目錄:公證過程會對工件做拆包與再打包,根卷剩餘空間與臨時目錄所在盤不足時,錯誤資訊可能指向「讀失敗」而非「空間不足」,與《可復現構建》裡 DerivedData 爭用同源。
  4. Stapler 前置條件誤判:需要裝訂的 .pkg.dmg 與僅應用包路徑不同;跳步會導致終端使用者側 Gatekeeper 行為與 QA 不一致。
  5. Transporter 與 API 上傳的二選一:圖形客戶端更易人工重試,但難審計;API 上傳更適合流水線,卻要把JWT 生命週期、issuer id、私鑰路徑寫進與 Fastlane 一致的金鑰治理。
  6. 跨區協作的「誰來點發布」:亞太白天、美西深夜疊加時,若上傳機與值班時區不一致,容易在「誰有權登入那臺遠端 Mac」上卡審批——這屬於組織問題,但會表現為技術失敗率上升。

把這六條與近兩次發版的失敗 HTTP 狀態分佈、重試次數、同一工件在不同機器上的透過率並列,才能把問題從「再跑一次試試」推進到可定位的出口與引數

表 1:公證與上傳應落在「哪一類遠端 Mac 出口」上

下表用於評審附件:不是比較「誰更快」,而是比較失敗時誰更好排障、誰更好寫審計欄位。列含義可與《預算治理》中的峰值機欄位對齊。

維度與製品主鏈路同區的構建機僅用於上傳/人工介入的「釋出節點」
網路路徑git/registry 拉取與公證出口一致,跨洋重複傳輸少路徑短、角色單一,適合承載 Transporter 與人工二次確認
失敗歸因構建與公證同機,日誌上下文完整需額外約定如何把工件與構建號對齊到上游流水線 ID
鑰匙串策略與 CI 使用者、守護程序模型強相關,適合長期固定可用「僅上傳專用」賬號降低暴露面,但要防止與簽名機混用證書檢視
時區與人機協同適合無人值守夜間全量適合放在與值班表重疊的時區,減少「連不上桌面」類阻塞
磁碟與 1TB/2TB同時承擔 DerivedData、歸檔與公證臨時檔案,需看峰值周可更小盤,但要把工件清理策略寫死,避免磁碟型假失敗
租期組合月租基線 + 釋出周短租補峰(與多地區指南一致)可用短租承接「只上傳」高峰,降低長期空置

三條應寫進值班表與 YAML 的「硬核」口徑

下列口徑可用內部看板採集;數值僅為工程上可解釋的佔位,團隊應以自己的基線替換。

  1. 公證輪詢節拍(NPI):notarytool info 的呼叫間隔從固定 5s 改為指數退避(例如 5s→10s→20s,封頂 60s),並把最大等待時間與釋出窗對齊;當跨區 RTT 高於 180ms 時,過密輪詢更容易觸發「體感卡頓」而非服務端真失敗。
  2. 上傳可恢復視窗(URW):記錄 Transporter 或 API 上傳在同一工件、同一出口 IP下的成功所需嘗試次數;若 URW 連續上升而 Apple 系統狀態頁無事件,應優先檢查企業代理與會話 MTU,而不是重籤。
  3. 裝訂前磁碟安全餘量(DSM):對將要執行 xcrun stapler staple 的卷,保留不低於歸檔體積 2.5 倍的可用空間(含臨時目錄所在分割槽);低於閾值時先在《可復現構建》語境下清理快取與歸檔目錄,再重試裝訂。

Apple 在 2025–2026 週期繼續推動公證 + 上架鏈路工具鏈統一在 Xcode 命令列側,團隊若在遠端 Mac 上混用多版本 Xcode,要把 xcode-select 路徑與 notarytool 版本寫進同一行配置,否則會出現「CI 與桌面結果不一致」的經典漂移。

bash
# 非互動公證提交示例(請替換 TEAM_ID、金鑰與工件路徑;勿把金鑰提交到倉庫)
xcrun notarytool submit ./dist/MyApp.pkg \
  --apple-id "[email protected]" \
  --password "@keychain:AC_NOTARY_PASSWORD" \
  --team-id "XXXXXXXXXX" \
  --wait

# 若使用 App Store Connect API 金鑰(推薦與 Fastlane 對齊issuer)
# xcrun notarytool store-credentials --keychain "notary-profile" ...
# xcrun notarytool submit ./dist/MyApp.pkg --keychain-profile "notary-profile" --wait
info

提示:在遠端桌面裡執行時,優先用 keychain profile 或 CI 注入的只讀金鑰路徑,避免把明文密碼寫進 shell 歷史;並與《Fastlane 與證書同步》中的金鑰輪換節奏一致。

六步落地 Runbook:從歸檔到可上架工件

下列步驟假設已完成程式碼簽名與 archive;若卡在簽名,請先回到 Fastlane 篇與可復現構建篇。

  1. 凍結 Xcode 與命令列棧:在目標遠端 Mac 上執行 xcode-select -pxcrun notarytool --version,把結果寫入釋出工單,避免發版日臨時切換。
  2. 選擇出口機器:按表 1 在「同區構建機」與「釋出節點」之間勾選,並把 IP、區域三元組與租期欄位寫在同一行(可與《多地區指南》模板合併)。
  3. 公證提交與輪詢:使用非互動引數提交,按 NPI 節拍查詢;失敗時先下載日誌再重試,避免盲目三連。
  4. Staple 與校驗:對需要裝訂的載體執行 stapler staple,並用 spctl 做本地驗籤抽樣;記錄命令輸出雜湊到工單。
  5. Transporter / API 上傳:二選一固定下來;API 路徑要把 JWT 過期、私鑰許可權與上傳重試策略寫進與 CI 相同的金鑰表。
  6. 覆盤欄位:把 URW、NPI 上限觸達次數與 DSM 觸發是否發生記入季度覆盤,與買租與預算篇對齊是否要在釋出周加短租峰值機。

M4 / M4 Pro 與磁碟:公證鏈路上的第一瓶頸常常是 IO

當遙測裡出現公證日誌下載緩慢、臨時目錄頻繁抖動、同一歸檔在本地筆記本上更快時,加 CPU 往往無助於縮短總時長。此時應回到 DSM 與《多專案資源池》中的快取策略,優先保證同區製品鏈路、足夠餘量磁碟與穩定的出口,再評估是否升級到 M4 Pro 以承接更高的並行模擬器或並行公證任務。遠端 Mac 的價值在於把這條鏈路從個人裝置搬到可合同化、可審計的區域與租期組合上,而不是簡單替代一臺筆記本。

為什麼「只在本地試過一次」不足以支撐跨區域生產釋出

純依賴個人筆記本完成公證與上傳,在合規審計、交接與 24×7 釋出窗下會持續產生隱性成本:金鑰在個人鑰匙串裡難以輪換;網路出口隨辦公地點波動;失敗記錄難與 CI 工單對齊。把公證與上傳遷到與團隊區域策略一致的遠端 Mac 池,可以把出口、磁碟與租期寫成可驗收欄位,並與 OpenClaw 等需要長期線上的自動化拓撲同區部署。

雲桌面或臨時虛擬機器方案也能跑命令列,但往往帶來圖形會話、USB 與鑰匙串語義不一致等相容性折損,釋出週會在「能編不能傳」上消耗大量協同時間。MACCOME 在新加坡、日韓、香港與美東美西提供 Mac Mini M4 / M4 Pro 物理節點與彈性租期,適合作為專用構建 + 公證 + 上傳的穩定出口;公開價格與區域說明可與本文對照表同一行對齊,先把區域與磁碟檔位寫死,再把 NPI/URW/DSM 三項口徑接入看板。

試點建議:選一臺與製品主鏈路同區的遠端 Mac 連續跑兩週釋出工單,只改出口與重試引數、不動簽名鏈,通常就能把「神秘失敗」壓縮到可解釋的少數幾類。

常見問題

公證與 Fastlane 證書篇誰先誰後?

先保證簽名與 profile 一致,再進入公證與上傳;請同時開啟《Fastlane 與證書同步》與 租賃價格說明,把區域與租期寫在同一行。

多地區節點與出口如何選?

請閱讀《多地區節點與租期指南》,並把構建、公證與上傳是否同機寫進評審附件。

上架與賬單問題去哪查?

訪問 幫助中心 獲取接入與常見賬單說明。