CI 里的公证凭证应该怎么保存？

不要把密码、私钥或令牌写进脚本、仓库或普通日志。使用团队批准的密钥管理方式限制注入范围，只让确实需要提交或查询的任务读取；为密钥指定所有者、轮换和撤销流程，并在失败日志中检查是否回显敏感参数。

notarytool 返回 Invalid 后先看哪里？

用对应 submission ID 获取 Apple 返回的公证日志，检查错误路径、签名无效信息和警告，关联到本次构建的提交、签名身份与归档哈希。先修复具体产物问题，再重新提交；保留原日志与构建记录，避免只根据终端里的 Invalid 文本猜测原因。

公证成功后还需要 stapler 吗？

视交付格式和离线验收要求而定。Apple 建议将票据附加到适用的 App、磁盘映像或平面安装包；ZIP 本身不能直接 stapling，应先处理其中适用的项目，再重新打包，并对最终交付件复验。公证状态通过也不代表发布检查全部完成。

Notary API 能完全替代 Mac CI 里的 notarytool 吗？

不能。Apple 文档说明 Notary API 可替代 notarytool 工作流中的部分上传和状态查询操作；它不负责替你完成 Xcode 构建、代码签名或需要 stapler 的票据处理。应逐项核对流水线的输入输出，再决定哪些步骤可以移出 macOS 节点。

Apple notarytool 企业 CI 怎么搭？2026 部署指南

Q: Apple notarytool 怎样接入 macOS CI？

先在 macOS 构建节点产出并签名待发布包，再通过 notarytool 提交，保存 submission ID，检查最终状态与日志；对适用的 App、DMG 或安装包执行 stapler 并验证交付文件。不要把上传成功或 CI 任务结束当作公证和发布验收完成。

负责 Mac App Store 外分发的团队，应将签名、公证提交、状态检查、票据处理和最终验收设计成可追溯的发布链路。本文按实施时间线讲解凭证治理、产物检查、失败日志和 Notary API 的适用边界，并提供发布放行条件。

结论：Apple notarytool 企业 CI 应拆成可追溯的签名、公证提交、状态核验、票据 stapling 和最终验收；依赖 Xcode 构建或 stapler 的环节，要在 macOS 环境验证，Notary API 只能替代部分提交与查询操作。面向 Mac App Store 外分发的 Developer ID 产物按这条路径设计；App Store 分发不走同一公证流程。(Apple 公证说明)

本周建议动作：选一份真实的候发版产物，跑通从构建签名到最终分发文件复验的完整链路，再按每个阶段的输入、输出和责任人设门禁。

这篇适合负责 Mac App Store 外分发的 macOS 应用团队、治理 CI 权限与凭证的 IT 团队，以及负责发布验收的工程师。
如果你的应用只经 Mac App Store 分发，或当前仅需本地开发签名，可以先确认分发方式与开发阶段，避免照搬不适用的公证流水线。

发布路径与待验收产物

先确定交付的是 macOS 应用、安装包还是磁盘映像，再把同一个最终交付对象作为验收基准。Apple 文档列出可公证的 macOS 应用、UDIF 磁盘映像和平面安装包等类型；ZIP 也可用于提交，但它与可直接 stapling 的对象并不相同，具体格式与票据处理边界见公证说明。

公证不是 App Review。对外分发的应用应使用适用的 Developer ID 签名，并按 Apple 的要求检查 Hardened Runtime、时间戳和签名状态。对于 macOS 应用，Apple 将 Hardened Runtime 列为公证前提之一；该能力也可能影响应用加载插件的方式，所以不要只检查主程序。可对照 Hardened Runtime 配置说明与 Developer ID 分发文档核查签名和运行时设置。

构建完成不等于产物已具备公证条件。把源代码提交标识、构建任务、签名身份、导出产物和产物哈希关联起来；如果导出或重打包改变了待提交文件，就要确保后续公证与发布验收指向同一版本，而不是仅凭某个 CI job 显示成功放行。

凭证准备与权限边界

在流水线接入公证工具前，先决定采用哪条认证路径。notarytool 可使用已存入钥匙串的凭证配置；Apple 文档也说明可以通过 App Store Connect 凭证与应用专用密码等方式提供认证信息。选择哪种方式，应以当前 Apple 官方说明和团队适用的账号策略为准，不要把 notarytool 的认证方式和 Notary API 的 JWT 私钥认证混成一套。相关配置路径见 Apple 定制公证工作流文档。

如果使用 Notary API，Apple 要求请求携带由私钥签名的 JWT；API 密钥的角色决定可访问的权限。Apple 说明团队密钥适用范围可能覆盖团队所有应用，个人密钥则受关联用户权限限制。密钥下载后应安全保管，不要提交到代码仓库；若怀疑泄露，应按官方流程撤销并更换。详见 API 密钥创建与权限说明。

落地时，把凭证放在受控的密钥存储中，仅注入实际需要认证的任务，并明确密钥负责人、轮换和撤销责任。检查流水线输出、调试日志与失败报告，确认不会打印命令参数、密码或私钥内容。不要将“能读取凭证”扩大成所有构建任务的默认权限。

签名构建与工具选择

对于 macOS 应用，先核对 Developer ID 签名、Hardened Runtime、时间戳和最终导出包；如果应用依赖插件或特殊运行时能力，也要验证对应权限是否满足产品行为。Apple 提醒，即使公证成功，日志仍可能包含需要修正的警告，因此验收不能只看最终状态。

Xcode Organizer 更适合由开发人员操作、使用 Xcode 标准分发流程的 macOS 应用；脚本化构建、多种分发格式或需要自行控制流水线的场景，可评估 notarytool。Apple 将命令行定制流程用于脚本构建、插件及复杂分发等情况；不能据此推断整个 Xcode 构建和签名链路都能脱离 Mac。(Apple 定制公证工作流文档)

路径	更适合的环节	主要边界	本文适配评分
Xcode Organizer	macOS 应用的交互式归档与分发	自动化控制和自定义步骤较少	★★★☆☆
`notarytool`	Mac CI 中的脚本提交、查询与日志处理	需要处理凭证、任务状态和分发产物	★★★★★
Notary API	由服务或脚本实现提交与状态查询	不替代 Xcode 构建、签名或 stapler	★★★★☆

评分是按“企业流水线可控性与步骤边界”作出的编辑判断，不是 Apple 评级，也不是性能测试结果。Apple 说明 Notary API 可替换定制流程中依赖 notarytool 的上传和状态检查环节；其它需要 Mac 工具的步骤仍要单独评估。具体接口边界见 Notary API 提交流程。

提交、状态检查与日志留存

提交时选择适合公证的归档或容器，并保存提交返回的 submission ID。使用 notarytool 的基本路径如下，凭证配置名应由你的密钥管理流程提供，不要替换成写死的密码：

xcrun notarytool submit "待发布产物.zip" \
  --keychain-profile "团队配置名" \
  --wait

Apple 文档给出的 --wait 用法会等待公证服务处理完成；如果流水线采用异步任务，则应保存 submission ID，后续单独查询状态并获取日志。状态要区分提交已接受、仍在处理、完成与失败，不能把“上传成功”当作“公证通过”。命令选项和流程细节见 Apple 定制公证工作流文档。

如果使用 Notary API，流程涉及创建提交、上传产物、查询状态和读取日志；Apple 的创建提交接口会返回用于追踪提交的标识。该接口还可返回供上传使用的临时凭证，其有效期为 12 小时；如果采用这条路径，应将上传任务与凭证生命周期一起设计，避免凭证过期后任务仍继续等待。可查 Notary API 提交说明。

无论选择哪种提交方式，都应留存产物标识、submission ID、最终状态和日志。Apple 的 API 文档说明，团队可通过相应接口获取最近 100 条提交记录；这可用于辅助找回记录，但不能替代你自己的 CI 归档和发布审计。

公证故障与票据处理 FAQ

Apple notarytool 怎样接入 macOS CI 流水线？
先在 macOS 节点构建并签名待发布产物，再由公证任务提交；保存 submission ID，等待或查询最终状态，下载日志，最后对适用的交付对象处理票据并复验。把这些环节拆成独立任务，可分别定位构建、签名、认证或公证问题，不要用一个“发布成功”状态覆盖整条链路。

CI 中的公证凭证怎样保存才安全？
不要把密码、私钥或令牌写进脚本、仓库或普通日志。使用团队批准的密钥管理方式限制注入范围，只让需要提交或查询的任务读取；为密钥指定所有者、轮换与撤销流程，并检查失败日志是否回显敏感参数。若采用 API 私钥认证，还应限制私钥的读取主体和保存位置。

notarytool 显示 Invalid 时，应从哪些证据开始排查？
用对应 submission ID 拉取 Apple 返回的日志，检查错误路径、签名问题和警告，再关联到本次构建提交、签名身份与产物记录。先修复日志明确指出的问题，再重新提交；保留原始日志、构建记录和产物标识，避免只看终端的 Invalid 就推断是凭证或服务故障。

公证通过后，分发包还需要 stapler 处理吗？
要按产物格式判断。Apple 建议把票据附加到适用的应用、磁盘映像或平面安装包；如果提交的是 ZIP，不能直接对 ZIP 文件 stapling，应先对其中适用的项目处理票据，再重新打包。对最终交付对象做复验，才能避免拿公证过的中间文件误当成最终发布包。

Notary API 能替代 Mac CI 中的 notarytool 吗？
只能替代部分工作。Apple 文档明确指出，API 可用于替代上传和状态查询环节；它不替你完成 Xcode 构建、代码签名或需要 stapler 的票据处理。先标注每个任务的工具依赖，再决定提交与查询是否适合迁移，不能把“可经 API 公证”理解为“整个流程可离开 Mac”。

放行证据与 Mac CI 承载决策

发布放行前，至少逐项确认以下证据存在且互相对应：

✅ 待分发产物与构建任务、代码提交、签名身份可关联。
✅ 对适用的 Developer ID 产物完成签名与公证前置检查。
✅ 公证任务保存 submission ID，最终状态明确，相关日志已归档。
✅ 对适用的 App、磁盘映像或安装包完成票据处理；ZIP 经过内部项目处理后重新打包。
✅ 最终分发文件与验收记录对应，并完成团队自行设定的安装或启动检查。

注意：Apple 返回的公证结果是公证服务的处理结果，不等同于团队完整的发布门禁。日志中的警告、应用功能测试、安装验证及审计留存，仍需按你自己的发布策略验收。

依条件选择承载方式：

若构建、签名或票据处理依赖 Xcode、notarytool、stapler，就保留并验证 macOS CI 环节；不要因为提交或查询可以走 Notary API，就把这些工具步骤一并迁走。
若团队只想把上传与状态查询作为独立服务实现，且已能管理 API JWT、提交标识、日志和产物对应关系，可以试点 Notary API；先以非生产发布验证完整闭环。
若当前流程使用 Organizer 且能满足发布审计要求，先补齐状态、日志和产物留存证据，再判断是否值得改成脚本化流程。
若你无法证明凭证注入范围、最终交付件身份或票据验证结果，就暂不放行；先补证据，而不是依赖 CI 绿灯推断安全。

自建 Mac 的优势是团队直接控制硬件与维护方式，但要承担采购、闲置资源和故障维护；非 Mac 执行环境能负责部分 API 调用，却不能直接替代需要 Xcode 或 stapler 的 macOS 步骤。若团队要评估远程 Mac 是否适合承载这些任务，应先按实际工具链、凭证边界和交付验收要求核对条件，再查看 VPSMAC 的节点信息与 VPSMAC 服务入口中可核实的交付资料。对于需要临时测试或补充 Mac CI 承载能力的团队，这种核对比预先假设成本或安全收益更可靠；若任务长期稳定重载或要求特定本地物理接口，自购设备也可能更合适。