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 与证书同步》与 租赁价格说明,把区域与租期写在同一行。

多地区节点与出口如何选?

请阅读《多地区节点与租期指南》,并把构建、公证与上传是否同机写进评审附件。

上架与账单问题去哪查?

访问 帮助中心 获取接入与常见账单说明。