Apple 推送通知服务证书有效期为一年，需要在 Apple 开发者门户中每年重新认证以避免中断设备通信。如果您负责的应用程序有 Capacitor，过期或被撤销的凭证可以停止通知，即使应用程序本身看起来健康。
失败通常出现在最糟糕的时刻。发布一个版本，安排了一次活动，通知传递突然陷入沉默。您的应用程序服务器可能仍然接受任务，但 APNs 可能会在消息到达设备之前拒绝 TLS 连接。实用的解决方案不是仅仅创建另一个证书。您需要了解您的系统使用哪个 APNs 凭证，保留私钥，计划续订，并将适合的工作负载转移到基于令牌的身份验证中。
目录
- 为什么推送通知停止工作
- 创建和下载 APNs 证书
- 导出证书到私钥
- Migrate to New Token-Based Authentication
- Renew and Manage Certificate Lifecycles
- 解决问题和处理丢失的凭证
推送通知停止工作
APNs sits between your provider server and the user’s Apple device. Your server authenticates to Apple, submits a notification, and relies on APNs to route it to the registered application and device. If the credential is expired, revoked, associated with the wrong identity, or installed incorrectly, the request can fail before delivery begins.
Apple states that APNs keeps a revoked-certificate list and refuses TLS connections from servers using certificates on that list. That makes certificate hygiene a delivery requirement, not an administrative preference. The server may continue processing notification jobs locally, while Apple rejects the provider connection.
Separate App Push from MDM Push
首个诊断问题很简单： 您正在尝试操作哪个服务？
| 证书路径 | 它的作用 | 典型所有者 |
|---|---|---|
| 应用推送 | 向终端用户设备发送警报和其他应用程序通知 | 移动或后端工程 |
| MDM推送 | 允许设备管理平台与受管理的Apple设备通信 | IT、终端点或企业移动性管理 |
这些凭证不可互换。 MDM 平台在其 MDM 推送凭证过期时可能会与已注册的设备失去联系，而应用程序后端可能会因为其 App Push 凭证无效而丢失通知发送。将两者视为一个“Apple 推送证书”问题会导致调试方向不正确。
对于 Capacitor 和 Ionic 团队来说，用户面向的警告路径通常是 应用推送. Capacitor 通知插件文档 涵盖了应用侧的集成，而 APNs 凭证属于提供商配置。
从拒绝开始，而不是 UI
检查您的提供商服务器从 APNs 获得的响应之前不要更改通知文本或重建应用。然后验证包标识符、凭证身份、环境和证书状态。通知权限问题会影响用户看到警告的能力，但不会解释 APNs TLS 拒绝。
如果失败出现在发布后，请将新构建的签名和特权与之前的构建进行比较。如果没有应用更改，请先检查证书过期、吊销、信任存储更改和部署密钥。 有关更广泛的实现路径，请参见.
Expo 推送通知设置
创建和下载您的 APNs 证书 推送发布可能会在发送第一条通知之前失败，如果证书为错误的 App ID 或私钥仍然在另一个 Mac 上。Apple 的工作流程有两个部分：您的机器创建一个或 CSR，苹果会签署它以选定的 App ID。 CSR 不是服务器凭证。它连接到本地创建的私钥的颁发的证书。
准备 App ID
登录苹果开发者门户并打开 证书、标识符和配置文件. 选择 标识符,选择应用程序的包标识符，并打开其配置。确认 推送通知 已启用前发出任何内容。
在颁发任何内容之前，确保
推送通知 已启用。 使用您的组织批准的证书工具生成 CSR, 或者使用 CSR 生成工具。请确保请求文件和私钥在同一控制的所有权下。若另一个管理员生成 CSR, 则该管理员可能持有私钥, 后续用于可用的服务器包。
签发已签名的证书
在 证书中, 选择 Apple Push Notification 服务证书选项。选择 App ID, 上传 CSR, 并提交请求。下载 Apple 发出的证书。
双击下载的文件, 在 Mac 上拥有私钥的机器上。它应该在 钥匙串访问中安装, 在那里您可以验证证书及其匹配的私钥。没有私钥的证书无法提供您的后端所需的完整凭证。
使用一个命名约定来记录应用程序身份, 环境, 所有者, 和过期日期。存储原始证书, CSR 所有权信息, 和门户账户详细信息在您的团队的凭证系统中。开发者下载文件夹或个人笔记本不是一个可操作的备份。
证书仅支持一个分发部分。应用程序必须注册远程通知, 服务器必须保留结果设备令牌, 提供商必须发送匹配的主题和环境。保持这些依赖项在同一操作手册中。对于客户端设置, 请参见 Capacitor 通知集成指南. 将此证书视为一个管理的凭证，而不是一次下载，因为后续的导出、令牌迁移、续期和恢复都依赖于知道谁控制其密钥。
导出证书到私钥
下载的苹果证书并不是自动准备好用于 Node.js 服务或管理推送提供商的。 服务器需要证书及其对应的私钥，通常打包为一个 PKCS#12 .p12 文件.
打开 钥匙串访问 在 Mac 上安装证书的机器上。 搜索 APNs 证书，展开或检查它，然后找到与匹配身份和过期信息的私钥。 选择证书和私钥，然后使用导出操作来保存一个 .p12 文件。
在部署之前验证包
给导出的文件起一个强密码。 密码保护私钥内的私钥，所以不要将其放在仓库、工单、聊天消息或构建日志中。 上传文件和密码通过您的秘密管理系统，然后只向发送通知的服务授予访问权限。
实践规则： A
.p12没有匹配的私钥的文件不是完整的提供商凭证。
在生产环境使用之前，在受控环境中测试捆绑包。确认您的后端可以加载文件、建立APNs连接并在Apple拒绝请求时返回结构化错误。如果提供商Capgo要求iOS推送凭证，请通过指定的机密配置上传文件及其密码，而不是将这些值嵌入应用Capgo。 .p12 and its password through the designated secret configuration rather than embedding either value in application code.
使用
Use 来控制谁可以读取或替换凭证。为上传和轮换保留审计记录，但永远不要记录私钥或密码。 对于新后端工作，评估证书身份验证是否仍然适用。现有的集成可能需要 .p12 password.
新后端工作 .p12证书身份验证是否仍然适用。现有的集成可能需要
Migrate to the New Token-Based Authentication
Apple将APNs认证转向 提供者令牌，常被称为 p8工作流。相比于提供一个长期有效的TLS身份的证书和私钥，
您的提供者使用Apple Push Notification服务认证密钥签署认证令牌。 在Apple Developer门户下, 然后打开 中创建密钥，然后打开 Keys .p8 并注册APNs认证密钥。下载文件并在您的机密存储中记录关联的Key ID和Team ID。将下载的文件视为高价值签名密钥。
让迁移有意为之
请勿在未测试环境中替换文件来切换生产流量。 在现有证书路径旁边构建令牌认证，验证沙盒和生产行为，并比较APNs响应。 然后在受控部署中进行提供者配置更改。
迁移从发送路径中移除证书续期和钥匙链导出步骤，但您的团队仍需要明确的所有权模型。 决定谁可以创建、撤销和部署密钥。 限制访问签署提供者令牌的后端服务，并确保在当前密钥不可用之前存在紧急替换过程。
对于一个Capacitor应用，客户端仍然需要正确的通知注册和特权。 迁移主要改变 服务器到APNs的身份验证而不是设备令牌注册code。 您的后端必须继续将令牌与正确的应用程序和环境相关联。
了解何时仍然需要证书
一些企业工具和已建立的集成仍然暴露了基于证书的配置。 不要强制p8迁移，直到接收系统支持它，并且您的团队已经测试了完整路径。 在过渡期间保护遗留凭证，但不要在令牌身份验证适用时创建新的依赖项。
如果您需要了解周围的应用程序流程，请查看 使用Ionic和Capacitor推送通知与Firebase. Firebase可以提供一个应用程序交付层，但Apple凭证、权限、注册和APNs响应仍然需要有意识的配置
更新和管理证书生命周期
将APNs证书视为从创建之日起即过期的生产依赖项。 Apple说这些证书有效期为 一年自创建 并且必须在过期前重新续订以保留设备通信。 Apple还警告说，如果不续订，可能需要用户重新注册iOS、iPadOS和Mac设备的APNs，并可能导致服务中断。 请参阅Apple的 推送通知证书续订文档.
续订路径如下:
- 生成新CSR: 通过您的批准工作流程创建请求并保留相关密钥材料
- 使用原始Apple ID: 使用创建现有证书时使用的相同Apple ID登录
- 选择即将过期的证书： 在选择之前，请匹配 App ID、主题 DN、UID 和过期日期 续期.
- 上传 CSR: 在 Apple Push Certificates Portal 中提交新请求。
- 下载并重新安装: 获取更新的
.pem将其安装到私钥可用的位置，并导出一个替代.p12如果您的提供商要求，请 - 部署和测试: 更新服务器密钥，发送一个受控通知，并检查 APNs 响应。
比较提供商格式
| 需求 | 证书流程 | 令牌流程 |
|---|---|---|
| 主要密钥 | 证书加密私钥 | .p8 身份验证密钥 |
| 续期问题 | 证书过期需要定期替换 | 不需要每年替换证书 |
| 部署工作 | 安装、配对、导出和上传 | 存储签名密钥并配置令牌生成 |
| 主要故障风险 | 错误的证书、缺少的私钥、过期或被吊销 | 丢失、泄露或被吊销的认证密钥 |
苹果的证书生态系统也需要定期进行信任链的工作。苹果宣布了APNs沙盒服务器证书更新的时间为 2025年1月20日 和生产环境的时间为 2025年2月24日，要求信任存储包含 SHA-2根证书USERTrust RSA证书颁发机构 阅读苹果APNs服务器证书公告 并将信任存储的所有权纳入您的平台检查清单 并将信任存储的所有权作为您的平台检查清单的一部分。
使用一个共享的续期日历、一个命名的拥有者和一个部署的运行书。 Capgo 证书管理文档 可以与管理 iOS 交付凭证的团队的移动发布流程一起放置。
解决问题和处理丢失的凭证
不容易遇到的事件不是总是过期的警告。它是管理员创建证书的那个人离开了，私钥只存在于旧的 Mac 上，或者在尝试清理时证书被撤销。标准的续期流程依赖于原始 Apple ID 和正确的证书身份，所以访问和来源性质与文件本身一样重要。
开始通过分类失败:
- 过期的证书： 通过原始账户生成一个替代证书，重新安装匹配的私钥，更新提供商，测试交付。如果设备通信已经被中断，遵循 Apple 的恢复指南，而不是假设服务器端的替换立即恢复每个设备。
- 被撤销的证书： 停止对旧凭证进行恢复。Apple 拒绝使用被撤销证书的服务器建立 TLS 连接，所以创建一个有效的替代证书并从活动部署中移除被撤销的密钥。检查谁撤销了它，是否其他系统复制了相同的凭证。
- 丢失的密码：
.p12password: A证书文件没有可用的密码可能无法正常工作。请从备份中恢复已批准的证书或重新生成一个新的证书，而不是弱化生产密钥控制。 - 丢失私钥: 重新下载公钥不会重新生成私钥。请在受控机器上创建一个新的CSR，然后重新生成一个新的凭证。
- 丢失Apple ID访问权限: 确认组织是否可以通过其身份和部署流程恢复账户。Apple将APNs证书创建于相关门户的支持转交给 部署程序支持.
恢复需要身份，而不是仅仅是文件名。 在意外事件发生之前，记录Apple ID的所有者、App ID、证书身份、私钥位置、提供商配置和替换程序。
构建一个操作性安全网
将证书和 .p8 keys 在一个共享、受访问控制的密钥库中。存储 .p12 将证书和密钥存储在一个共享的、受控访问的安全库中。将密码与文件分开存储，限制生产访问，并记录用于续期的准确门户账户。您的CI/CD系统应该在部署时注入机密，并在用户报告缺失警报之前运行一个健康检查以检测身份验证失败。
保持旧的凭证在控制替换期间可用，但不要让过时的密钥持续活跃。测试在生产使用的相同后端路径中进行替换，包括提供商的环境、包标识符和设备令牌存储。
当停机已经发生时，保留APNs响应体和时间戳，识别第一个被拒绝的请求，并比较部署密钥在事件发生前后。不要无限重试一个无效凭证。首先修复身份或身份验证问题，然后向已知测试设备发送一个小验证通知。
Capgo可以存储和配置iOS推送凭证作为Capacitor通知工作流的一部分，而您的团队仍然负责Apple账户访问、密钥保管和续订决策。访问 Capgo 前往了解其移动交付工具如何与您的APNs凭证生命周期和发布过程相匹配。
