Apple Push Notification service certificates are valid for one year and must be renewed annually in the Apple Developer Portal to avoid interrupting device communication. If you’re responsible for a Capacitor app, an expired or revoked credential can stop notifications even while the app itself appears healthy.
苹果推送通知服务证书有效期为一年，必须在苹果开发者门户中每年续期以避免中断设备通信。如果您负责一个__CAPGO_KEEP_0__应用，过期或被吊销的凭证即使应用本身看起来健康也可以停止通知。
目录
为什么推送通知停止工作
APNs 位于您的提供商服务器和用户的 Apple 设备之间。您的服务器向 Apple 进行身份验证、提交通知，并依赖于 APNs 将其路由到已注册的应用程序和设备。如果凭证过期、被撤销、与错误身份相关或安装不正确，请求可能在交付开始之前失败。
Apple 表示 APNs 保持一个被撤销的证书列表，并拒绝使用该列表中证书的服务器的 TLS 连接。这使得证书卫生成为交付要求，而不是管理偏好。服务器可能继续处理通知任务本地，而 Apple 拒绝提供商连接。
将应用推送与 MDM 推送分开
第一个诊断问题很简单： 您正在尝试操作哪个服务？
| 凭证路径 | 它的作用 | 典型的拥有者 |
|---|---|---|
| App Push | 将应用程序通知发送到终端用户设备 | 移动或后端工程 |
| MDM Push | 让设备管理平台与受管理的Apple设备通信 | IT、终端或企业移动管理 |
这些凭证不可互换。MDM平台在其MDM推送凭证过期时可能会与已注册的设备失去联系，而应用程序后端由于其App Push凭证无效而可能会丢失通知发送。
对于Capacitor和Ionic团队来说，用户面向的警报的相关路径通常是 App Push.应用程序仍然需要推送通知能力、正确签名、设备注册和一个发送到适当APNs环境的后端。如果您的团队还在分发即时的Web资产，请将推送身份验证与发布流程分开。 Capacitor 通知插件文档 涵盖了应用侧的集成，APNs凭证属于在提供商配置中
从拒绝开始，而不是从UI开始
在更改通知内容或重建应用之前，从您的提供商服务器检查APNs响应。然后验证包标识符、凭证身份、环境和证书状态。通知权限问题会影响用户看到警报的能力，但它不会解释APNs TLS拒绝
如果失败出现在发布后，比较新建和旧建的签名和特权。如果它没有应用更改，首先检查证书过期、吊销、信任存储更改和部署密钥 查看Expo推送通知设置指南.
创建并下载APNs证书
推送通知的发布可能会在发送第一条通知之前失败，如果证书是为错误的App ID发行的，或者私钥仍然在另一个Mac上。Apple的工作流程有两个部分：您的机器创建一个 证书签名请求，或CSR，Apple签署它为所选的App ID。CSR不是服务器凭证。它连接了发行的证书到一个本地创建的私钥
准备App ID
登录Apple开发者门户并打开 证书、标识符和配置文件. 选择 标识符, 选择应用程序的包标识符，并打开其配置。确认 推送通知 上下文:Capgo营销网站。角色:短的UI标签或导航项。消息键`push_notifications` (推送通知)。
在颁发任何内容之前，确保已启用。
APNs凭据与应用程序身份相关联。不要选择一个附近的包标识符，其名称与应用程序类似。独立配置每个应用程序，并颁发匹配凭据。 在将密钥保留的Mac上，打开 钥匙串访问
一台显示Linux终端命令行界面的计算机监视器，用于生成SSL证书。
In 证书, 选择 Apple Push Notification 服务证书选项。 选择 App ID, 上传 CSR, 提交请求。 下载 Apple 发出的证书。
双击下载的文件在拥有私钥的 Mac 上。 它应该安装在 钥匙串访问中，方便您验证证书及其匹配的私钥。 未能导入该私钥的证书无法提供您的后端所需的完整凭证。
使用一个命名约定来记录应用程序身份、环境、所有者和过期日期信息。 将原始证书、 CSR 所有权信息和门户帐户详细信息存储在您的团队的凭证系统中。 开发者的下载文件夹或个人笔记本不是一个可操作的备份。
证书仅支持一次传递的部分。 应用程序必须注册远程通知，服务器必须保留结果设备令牌，提供商必须以匹配的主题和环境发送。 保持这些依赖项在同一个运行书中。 对于客户端设置，请参阅 Capacitor 通知集成指南。 将此证书视为一个管理凭证，而不是一次下载，因为后续的导出、令牌迁移、续订和恢复取决于谁控制其密钥。
导出证书到私钥
A下载的Apple证书并非自动就绪用于Node.js服务或托管推送提供商。 服务器需要证书及其对应的私钥，通常以一个 PKCS#12 .p12 文件.
打开 Keychain Access 在Mac上安装证书的机器上。 搜索APNs证书，展开或检查它，然后找到与匹配身份和过期信息的私钥。 选择证书和私钥，然后使用导出操作来保存一个 .p12 文件。
在部署之前验证捆绑包
为导出设置一个强密码。 密码保护私钥内的捆绑包，所以不要将其放在仓库、工单、聊天消息或构建日志中。 通过您的机密管理系统上传文件和密码，然后只向发送通知的服务授予访问权限。
实用规则： 一个
.p12文件没有其匹配私钥不是一个完整的提供商凭证。
在生产环境使用之前，测试包在受控环境中。确认您的后端可以加载文件、建立APNs连接并在Apple拒绝请求时返回结构化错误。如果提供商，如Capgo，要求iOS推送凭证，请通过指定的机密配置上传 .p12 和其密码，而不是将其嵌入应用code中。
该格式还暴露了遗留工作流程的弱点。您必须保留原始私钥、重复手动导出、保护文件并在续期时替换部署机密。运营多个应用的团队很容易混淆哪个包属于哪个App ID。
使用 在CI/CD管道中 安全机密管理 .p12 来控制谁可以读取或替换凭证。保留上传和轮换的审计记录，但永远不要记录私钥或
密码。 .p12对于新后端工作，评估证书认证是否仍然适用。现有的集成可能需要
，但通常情况下令牌认证会从提供商连接中移除年度证书替换。然而，这并没有消除凭证管理。它改变了您保护和轮换的内容。
迁移到新令牌认证 Apple已经将APNs认证转向了提供商令牌。，常被称为 p8工作流程. 不再需要为长期TLS身份提供证书和私钥，相反，提供商使用Apple Push Notification服务认证密钥签署认证令牌。
在Apple Developer门户下创建 证书、标识符和配置文件,然后打开 密钥 并注册APNs认证密钥。下载 .p8 文件并在秘密存储中记录相关的Key ID和Team ID。将下载的文件视为高价值签名密钥。
务必有计划地进行
切换生产流量时，不要在未经测试的环境中替换文件。同时在现有证书路径旁边构建令牌认证，验证沙盒和生产行为，并比较APNs响应。然后在受控部署中进行提供商配置更改。
该迁移从发送路径中移除了证书续期和Keychain导出步骤，但您的团队仍然需要明确的所有权模型。决定谁可以创建、撤销和部署密钥。限制对签名提供商令牌的后端服务的访问，并确保在当前密钥不可用之前存在紧急替换流程。
对于一个 Capacitor 应用，客户端仍然需要正确的通知注册和权限。主要的迁移改变了 服务器到 APNs 的身份验证,而不是设备令牌注册 code. 您的后端必须继续将令牌与正确的应用程序和环境关联。
了解何时仍然需要证书
一些企业工具和已建立的集成仍然暴露了基于证书的配置。不要强制 p8 迁移，直到接收系统支持它，并且您的团队已经测试了完整的路径。保持遗留凭证在过渡期间受保护，但不要在令牌身份验证适用时创建新的依赖项。
如果您需要了解周围的应用程序流程，请查看 Ionic 和 Capacitor 推送通知与 Firebase. Firebase 可以提供应用程序交付层，但 Apple 凭证、权限、注册和 APNs 响应仍然需要有意的配置。
更新和管理证书生命周期
将 APNs 证书视为从创建它的那一天起即过期的生产依赖项。 Apple 说这些证书有效期为 从创建之日起一年的时间 并且必须在到期前重新生成以保留设备通信。苹果还警告说，如果不重新生成，可能需要用户重新注册iOS、iPadOS和Mac设备，并可能导致服务中断。请参阅苹果的 推送通知证书续期文档.
续期路径如下:
- 生成新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 Root USERTrust RSA证书颁发机构 阅读 苹果APNs服务器证书公告 并将信任存储所有权纳入您的平台检查清单
使用一个共享的续期日历、一个命名的所有者和一个部署运行书。该 Capgo 证书管理文档 可以与管理iOS交付凭证的团队的移动发布流程一起存储在一起。
故障排除和处理丢失的凭证
难以处理的事件不一定是过期的警告。它可能是管理员离开的那天，私钥只存在于旧Mac上，或者在清理过程中证书被撤销。标准的续期流程依赖于原始Apple ID和正确的证书身份，因此访问和证明的重要性与文件本身一样重要。
首先分类失败:
- 过期证书: 通过原始账户生成替换证书，重新安装匹配的私钥，更新提供商，测试推送。若设备通信已中断，应遵循苹果的恢复指南，而不是假设服务器端替换立即恢复所有设备。
- 撤销证书: 停止对旧凭证的恢复。苹果拒绝使用撤销证书的服务器端TLS连接，因此创建一个有效的替换证书并从活跃部署中移除撤销的密钥。检查谁撤销了它，并且是否其他系统复制了相同的凭证。
- 丢失
.p12密码: 一个没有可用密码的证书文件可能不可操作。从备份中恢复批准的备份或发行替换证书，而不是弱化生产密钥控制。 - 丢失私钥: 重新下载公共证书不会重新创建私钥。使用受控机器创建一个新的CSR并发行一个替换凭证。
- 丢失苹果ID访问权: 确认组织是否可以通过其身份和部署过程恢复账户。苹果将支持通过相关门户创建的APNs证书的支持指引 部署程序支持.
恢复需要身份，而不是仅仅是文件名。 在意外事件发生之前，记录Apple ID的拥有者、App ID、证书身份、私钥位置、提供商配置和替换程序。
构建一个可操作的安全网
将证书和 .p8 密钥存放在一个共享的、受控访问的安全库中。将密码存放在文件之外，限制生产访问，并记录准确的门户账户用于续订。您的CI/CD系统应该在部署时间注入机密，并运行一个健康检查以检测认证失败之前用户报告丢失的警报。 .p12 在允许控制替换的平台上保留旧凭证，但不要让过时的机密活跃不止。测试在生产使用的相同后端路径中替换，包括提供商的环境、包标识符和设备令牌存储。
当已经发生故障时，保留APNs响应体和时间戳，识别第一个被拒绝的请求，并比较部署机密在事件发生之前和之后。不要无限重试一个无效凭证。首先修复身份或认证问题，然后发送一个小验证通知到已知的测试设备。
__CAPGO_KEEP_0__可以存储和配置iOS推送凭证作为__CAPGO_KEEP_1__通知工作流的一部分，而您的团队仍然负责Apple账户访问、机密保管和续订决策。
Capgo can store and configure iOS push credentials as part of a Capacitor notification workflow, while your team retains responsibility for Apple account access, secret custody, and renewal decisions. Visit Capgo 了解如何将其移动端交付工具与您的APNs凭证生命周期和发布流程整合。
