引言
在 macOS 软件分发流水线中，Notarization Service 的不稳定性是工程团队高频面对的痛点。与签名验证链的调试不同，Notarization Service 的核心问题集中在三个层面：提交阶段的网络超时、服务端的瞬时错误响应，以及 Stapler 在票据查找时的缓存失效。理解这三者的交互机制，并将其转化为可配置的重试参数，是保障 CI/CD 流水线稳定性的关键。
本文聚焦于 Notarization Service 超时重试逻辑与 Stapler 票据查找失败（Error 65）的工程对抗策略，为多区域发布流水线提供可落地的参数配置与监控方案。
一、超时场景分类与重试策略设计
Notarization 流程中的超时并非单一事件，而是由多个环节的不同错误组成。工程团队需要首先区分以下三类场景，再制定对应的重试策略。
第一类是传输层超时，发生在 notarytool submit 命令将构建产物上传至 Apple 服务器的过程中。这类超时与网络链路质量、代理配置以及防火墙策略强相关。在企业内网环境中，TLS 检测策略可能对长连接产生静默丢弃；在多区域 CI 环境中，跨区域上传会引入尾部延迟，导致默认超时时间不足。典型的传输层超时表现为命令长时间卡在上传阶段，最终返回网络错误或连接重置。
第二类是服务端瞬时错误，表现为返回 4xx 或 5xx 状态码，但错误信息明确指示可重试。这类错误通常包括服务器负载过高、请求频率限制或临时的后端服务异常。服务端瞬时错误的特点是状态码明确、错误消息可解析，适合通过程序化判断决定是否重试。
第三类是永久性失败，涵盖认证失败（无效的 App Store Connect API Key）、签名不匹配（提交产物的代码签名与预期不符）以及明确的业务规则违反（如越界 Bundle ID）。永久性失败不应触发重试，因为重复提交不会改变结果，反而会浪费 API 配额并在监控面板中产生噪音。
对于传输层超时和服务端瞬时错误，推荐采用指数退避（Exponential Backoff）策略。初始重试间隔建议设置为 30 秒，最大重试间隔上限为 5 分钟，单个产物的最大重试次数控制在 3 到 5 次之间。为避免在长尾场景中无限等待，单次提交的总耗时上限应设定为 1 到 2 小时。此参数组合在跨区域流水线与单区域流水线中均表现出较好的鲁棒性。
二、Stapler Error 65 的根因分析与工程对抗
Stapler 票据钉扎失败是 Notarization 流程中最常见的下游错误之一，其错误码为 65，错误信息通常为 "Could not find base64 encoded ticket in response"。从 Apple 工程师在 Developer Forums 上的技术说明可知，该错误的根本原因是代码目录哈希（cdhash）不匹配。
Apple 的 Notarization Service 在验证通过后，会将成功 notarize 的各组件的 cdhash 记录在 ticketContents 中。当执行 stapler staple 命令时，Stapler 工具从待钉扎的应用或二进制文件中提取 cdhash，然后向 Apple CloudKit 票据交付服务（api.apple-cloudkit.com）查询对应记录。如果 CloudKit 返回 "record not found"，即表示找不到匹配的票据，从而触发 Error 65。
导致 cdhash 不匹配的场景主要有三类。第一类发生在签名变更后，即在成功 Notarization 之后，对应用 Bundle 进行了任何修改（包括重新导出、通过 Organizer 分发等），都会生成新的 cdhash，导致票据查找失败。第二类发生在打包格式不匹配时，如提交 ZIP 归档后尝试直接对 ZIP 本身钉扎，而 Apple 的文档明确指出 ZIP 本身无法被代码签名，票据仅针对归档内的各个组件生成。第三类则是 Apple 内部服务偶尔出现的票据生成不完整问题，这在 Apple 工程师的回复中被称为 "bug 50294732"。
针对第一类场景，工程团队应确保在 Notarization 与 Stapling 之间严格禁止任何签名操作。具体做法是在导出阶段使用 "Developer ID" 或 "Distribution" 配置，而非手动调整签名设置。如果流水线中必须对已 notarize 的产物进行二次处理（如注入版本信息），则应将该操作移至签名之前，并在签名后重新提交 Notarization。
针对第二类场景，当使用 ZIP 归档格式时，必须对 ZIP 内的各个 .app 进行单独钉扎，而非对 ZIP 文件本身执行钉扎命令。这一要求在 Apple 官方文档中有明确说明，但由于错误信息不够直观，实践中常被忽视。如果持续遇到钉扎问题，切换至 DMG 格式可以显著简化流程，因为 DMG 本身可以被签名，票据会绑定至 DMG 内的主应用。
针对第三类场景（服务端票据生成不完整），Apple 工程师建议重新提交并等待修复。此类问题通常在数小时内自然解决，但在 CI 流水线中，可通过监控 notarization logFileURL 中的 ticketContents 字段是否包含完整的预期组件列表来提前发现问题。如果 ticketContents 缺少预期组件，应立即重试而非等待钉扎失败。
三、多区域 CI 流水线的参数配置与监控要点
在多区域 CI 环境中，Notarization Service 的延迟问题会更加突出。以下是针对跨区域流水线的关键参数配置建议。
网络超时配置方面，notarytool 命令本身支持通过 --timeout 参数设置上传超时，建议将传输层超时阈值设置为 300 秒（5 分钟）。同时，应在 CI 层面配置全局的 HTTP 客户端超时，确保与 notarytool 的超时设置保持一致。
重试间隔配置方面，建议采用以下指数退避序列：30 秒、60 秒、120 秒、240 秒、480 秒。此序列对应最多 5 次重试，总耗时约为 25 分钟，对于大部分瞬时错误场景已足够。为防止退避序列过长导致流水线阻塞，建议设置单次提交的总重试耗时上限为 90 分钟。
区域路由方面，如果 CI 集群跨越多个地理区域，应监控各区域至 Apple Notarization Service 的平均延迟，并将高延迟区域的构建节点标记为降级。对于需要极速发布的场景，可考虑将 Notarization 步骤集中路由至延迟最低的区域节点。
监控与告警方面，应重点关注以下指标：单次提交的总耗时（包含所有重试）、重试次数分布（用于评估退避参数是否合理）、票据查找失败率（用于评估是否需要切换打包格式或重新签名）。建议在流水线仪表板中为每个构建产物记录 submission ID、最终状态以及重试次数，以便在发布失败时快速定位问题环节。
四、可落地参数与检查清单
以下是工程团队可以直接应用的配置参数与检查项。
超时参数配置：传输层超时阈值设为 300 秒，退避初始间隔为 30 秒，最大间隔为 5 分钟，单次提交总耗时上限为 90 分钟。
重试策略配置：仅对传输层错误和服务端 5xx 错误实施重试；永久性 4xx 错误（如认证失败）直接中止；每个产物最多重试 5 次；使用 submission ID 实现幂等性去重。
Stapler 验证配置：Notarization 成功后立即执行钉扎，钉扎前验证 cdhash 匹配性（通过 codesign -dvvv 对比 ticketContents）；使用 ZIP 格式时对内部 .app 分别钉扎；建议优先使用 DMG 格式以简化流程。
流水线监控配置：记录 submission ID 与状态到仪表板；监控 ticketContents 完整性；告警阈值设为：单次提交总耗时超过 60 分钟或重试次数超过 3 次。
结语
macOS Notarization Service 的超时重试与 Stapler 票据失效并非独立的两个问题，而是同一个分发流水线中的两个环节。工程团队需要从整体视角理解签名、提交、验证、钉扎的完整链路，才能在错误发生时准确定位根因并采取正确的对抗策略。通过合理的超时配置、指数退避重试以及对 cdhash 匹配性的主动验证，可以显著提升 CI/CD 流水线的稳定性，将 Notarization 从不可控的外部依赖转化为可预测的可观测环节。
资料来源
- Apple Developer Forums: "Notarization: stapler error 65"，Apple DTS 工程师 Quinn 详细解释 cdhash 校验机制与 ticket 查找流程。
- Apple Developer Documentation: Customizing the Notarization Workflow，明确 ZIP 格式下需对内部组件分别钉扎的要求。
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。