平台工程已经把 Archive 跑绿，却在 公证（Notarization） 或 stapler 阶段被「钥匙串弹窗、轮询超时、同一台远程 Mac 上多 Job 争用临时目录」拖进夜班。本文写给熟悉 VPS 运维、要把 macOS 当成独占构建平面的团队：先用七条清单拆穿无人值守公证里最常见的隐性假设，再用一张「分发渠道 × 技术动作」对照表收敛你是否必须 staple，然后给出六步可交接 Runbook（API Key、notarytool submit/store、日志留存、重试与并发边界），并链到站内 Fastlane 与 CI、可复现构建与钥匙串 的分工阅读。
Apple 的公证链路在文档层面很清晰，但落到长期在线的 CI 用户与共享 NVMe上时，失败往往表现为「偶发、难复现、日志分散」。下面七条用于把风险从「感觉能脚本化」推进到「能写进变更单」。
把公证当成 Archive 的附属品：未单独为 notarytool 分配退出码处理与产物留存时，排障会退化成「谁 last green 谁背锅」；应与发布流水线的审计字段对齐。
混用个人 Apple ID 与 CI API Key：会话型凭据在无人值守环境不可控；2026 年应以 App Store Connect API Key 为默认，与 Fastlane 无头发布 的密钥合同一致。
忽略 stapler 的分发语义：把 staple 写进所有流水线会增加时间与失败面；应对「直接下载分发 / 企业内部分发 / 仅 TestFlight」分支化，见下一节对照表。
多 Job 共用默认临时目录：/var/folders 与自定义 zip 工作区若冲突，会出现上传损坏或哈希不一致；需要像 DerivedData 一样按 pipeline 分桶。
不做 notarytool 轮询退避：Apple 侧队列波动时，线性重试会把同一提交打爆；应使用指数退避与最大墙钟预算，并把 submission id 记入工单。
钥匙串与 TCC 仍按「桌面用户」配置：无人值守构建应使用专用登录会话或明确的 CI 钥匙串分区，并与 可复现构建 的 Keychain 合同一起评审。
没有「公证失败样本库」：团队只在绿线时看日志，遇到 Invalid 或 Hardened Runtime 问题时缺少对照截图与版本三元组；应在知识库固定采集模板。
这些假设的共同根因，是把远程 Mac 当成「能跑 Xcode 的 Linux」，而不是带公证状态机与钥匙串边界的独占节点。与 企业构建资源池 篇联动：当多应用共用机群时，公证并发与签名材料隔离必须写进平台 SLA，而不是交给单个业务仓库「自己看着办」。
与纯 xcodebuild 相比，公证阶段更强调可观测性与幂等：同一二进制重复提交、同一 request UUID 的幂等语义、以及失败后在工单系统里的「可回放命令」。把这三件事写进 Runbook，才能把远程 Mac 从「能编」升级到「能签、能证、能审计」。
若你同时跑夜间 Archive 与白天 PR，建议把公证 Job 与编译 Job 的资源组隔离：公证往往受网络与 Apple 侧队列影响，和 CPU 密集编译混排会放大尾延迟；这与 GitLab resource_group 或 Actions 并发上限的治理思路一致，只是资源名应改成「notarization slot」这类可读模型。
最后，远程供应商若提供固定出口 IP 或区域选择，应把公证链路的 RTT 与 TLS 拦截策略纳入验收：企业代理对 Apple 端点的中间人解密是「绿本地、红公证」的经典根因之一。
没有一张表能在所有组织里直接「拍板」，但评审时可以用「用户如何拿到包」为主轴，把技术动作收敛成可测试的验收项。
| 维度 | 直接下载 .dmg/.zip | 企业内部分发门户 | TestFlight / App Store |
|---|---|---|---|
| 公证提交 | 通常需要：Gatekeeper 默认路径要求公证票据可验证 | 需要：与 MDM/门户验签策略对齐 | 由 Apple 托管分发链主导；本地 stapler 需求与直接下载不同 |
| stapler staple | 强烈建议：离线安装时票据随包走 | 视门户是否二次重打包；重打包后需重新 staple 或改分发策略 | 一般不等同于「本机构建完必 staple」；以发布通道为准 |
| 失败影响面 | 用户侧弹窗与安装拦截；支持成本高 | 合规与审计字段；可能触发安全事件复盘 | 多体现为上传/处理队列；与 CI 公证并不同构 |
| 远程 Mac 侧收益 | 独占磁盘与稳定出口；便于保留 notary zip 与日志 | 与内网 artifact 仓库相邻部署可降低传输时间 | 与 Fastlane 流水线衔接；公证与上传角色拆分 |
| 典型误区 | 以为「公证通过」等于「用户双击一定绿」；忽略 staple 时机 | 门户病毒扫描改写包体导致票据失效 | 把桌面端 notarytool 经验硬套到 App Store Connect 处理延迟上 |
「像买 VPS 一样租 Mac」在公证语境里，买的是可重复的提交平面：固定用户、可预期的磁盘水位、以及能把 submission id 和构建指纹绑进工单的状态机。
对照 notarytool 与已弃用路径时，评审应明确维护窗口：团队是否仍残留依赖 GUI 会话的旧脚本；是否所有调用方都已切到 JSON 输出与结构化日志。把「切换完成」定义为 CI 模板与内部脚手架全部更新，而不是某个仓库局部 green。
若你在多地区有机群，公证上传的地理就近不如编译那么敏感，但仍建议把「出口路径与代理策略」写入每台节点的 Runbook，避免「东京编、硅谷证」这类路径在合规上踩雷。
下列顺序强调「先身份与密钥，再产物与提交，最后才放开并发」：与 可复现构建 的指纹采集脚本对齐，避免「能 submit 却不能复盘」。
创建专用 CI 用户与登录会话基线：禁止与个人 Apple ID 混用；确认屏幕锁定策略不会中断长时间轮询。
安装 API Key 与 notarytool 凭据：使用 p8、Issuer ID、Key ID 三件套；密钥文件权限限制为 CI 用户只读；禁止把 p8 明文贴进公共仓库。
在流水线内生成可上传产物：对 .app 正确签名后打包 zip/dmg；路径含 pipeline id；计算 SHA256 并随构建日志输出。
执行 submit 并捕获 submission id：使用 --wait 或自建轮询；把 Apple 返回状态写入 artifact 目录备查。
store log 与失败分类：对 Invalid 类错误拉取详细日志；在工单系统关联 xcodebuild -version 与仓库 commit。
按分发策略 staple 并验收：stapler validate 与试安装矩阵（干净 VM 优先）；再进入门户或对象存储上传。
ZIP_PATH="dist/MyApp.${CI_PIPELINE_ID}.zip"
xcrun notarytool submit "$ZIP_PATH" \
--key "./AuthKey_XXXXX.p8" \
--key-id "$ASC_KEY_ID" \
--issuer "$ASC_ISSUER_ID" \
--wait \
--output-format json > "logs/notary-${CI_PIPELINE_ID}.json"
# 失败时拉详细日志（submission id 从 json 解析）
# xcrun notarytool log <submission-id> --key ... > "logs/notary-detail.txt"
xcrun stapler staple "dist/MyApp.app"
提示：若同一流水线还承担 App Store Connect 上传，请阅读 Fastlane 与 CI 衔接，把 API Key 角色（Developer vs App Manager）与 notarytool 最小权限写进变量表，避免「一把钥匙开所有门」。
在 Xcode 或 macOS 大版本升级日，建议先对「最小 zip 包」做金丝雀公证：固定一个 hello-world 级别的 signed bundle，验证 notarytool 与 staple 全链，再放开业务仓库；这与黄金镜像回滚策略互补。
若远程 Mac 由供应商提供快照能力，请把「公证链版本」写进快照标签：包含 Xcode build 号、CLI tools 版本与 notarytool 行为变更记录，避免团队在新镜像上集体踩默认参数变化。
平台工程里最常见的误判，是把「能同时开几个 xcodebuild」的并发模型直接套到公证上。实际上，上传带宽、Apple 侧队列、zip 压缩 CPU 与 钥匙串解锁 会在不同阶段成为瓶颈。
建议为公证单独定义 notary_slots：例如每台远程 Mac 同时最多 1–2 个 submit，其余 Job 在队列里等待；并把墙钟超时与「可接受的排队 SLA」写进内部文档。与 SwiftPM/Pods 磁盘治理 篇联动：公证临时 zip 往往体积大，应与 DerivedData 分卷或分目录，避免系统盘在夜间批量任务时触顶。
注意：不要在磁盘低于安全水位时继续硬塞公证任务：半写入的 zip 会上传失败且难以复现；应先停调度与清理，并记录删除路径以便审计。
重试策略上，应对「网络瞬断」与「Apple 侧繁忙」分层：前者可在秒级做有限次重试；后者应使用分钟级退避并上限，避免触发速率限制。所有重试必须记录 submission id 与产物哈希，防止「重复 staple 旧包」类事故。
若组织使用集中式代理，请把 Apple 相关域名与 TLS 绕过策略写成显式白名单；否则会出现「编译全绿、公证全红」且日志只在代理层的现象，排障成本极高。
与仅在本机笔记本上偶尔 Archive 相比，独占远程 Mac 的价值在于7×24 可预测环境与固定 SSH 运维面：平台可以把公证 Runbook、磁盘水位与密钥轮换绑进同一套节点画像，而不是让每台开发机各自为政。
下列条目用于内部对齐；具体阈值以你们包体大小与并发度为准。数据与比例来自常见平台工程实践，实施前请在你们环境复测。
--wait 设置显式上限 + 可告警。submission id、产物 SHA256、xcodebuild -version 三行，以便跨团队复盘。纯办公室笔记本做公证常受睡眠策略、VPN 抖动与个人钥匙串干扰；纯 Linux 又无法完成官方 macOS 签名链。把执行平面放到独占、长期在线、SSH 可达的远程 Mac，并把 notarytool 与 staple 写进可重复模板，才能把「能发包」变成「能证明、能审计、能交接」。相比自建零散机器或在不透明虚拟化层里硬跑 Xcode，NodeMini 的 Mac Mini 云端租赁在固定 SSH、清晰磁盘档位与可复制的节点画像上更利于平台治理；需要对比规格与价格时，可先阅读 租赁价格说明，再结合 帮助中心 完成接入与验收。
落地时建议把本 Runbook 与内部「发布等级」绑定：灰度、正式与热修复对应不同的公证并发、日志保留天数与 staple 验收矩阵。