技术排障指南生成

故障排除文档：Kubernetes 生产集群订单微服务 v2.3.1 出现 CrashLoopBackOff/OOMKilled/HTTP 500

一、问题

• 现象
  • 订单微服务升级至 v2.3.1 后，Pod 频繁重启，状态 CrashLoopBackOff。
  • 高峰期 HTTP 500 间歇出现，延迟显著上升。
  • 监控显示 CPU 突增，伴随 OOMKilled 事件。
• 环境与配置
  • Kubernetes v1.27（containerd），Ubuntu 22.04，3 节点工作池；Ingress NGINX；Calico；HPA 开启。
  • Pod 资源：requests 300m/256Mi，limits 1.5cpu/512Mi（曾提升至 768Mi 仍重启）。
  • 技术栈：Java 17 Spring Boot，G1 GC；Redis 6.2（缓存）；PostgreSQL 13 主从；Kafka；镜像基于 Alpine。
  • 启用 liveness/readiness 探针与 OpenTelemetry 指标；配置通过环境变量注入。
• 已尝试措施与线索
  • 回滚至 v2.3.0 可暂时缓解。
  • 提高内存 limits 至 768Mi 无法根治。
  • 关闭部分 JIT 优化无明显改善。
  • 清理 Redis 热键后短暂恢复。
  • 堆转储显示大量字典对象与热点键占用。
  • 延长探针初始延迟与超时后失败率下降但仍不稳定。
  • 调整连接池参数效果有限。

二、诊断 目标：与 SRE 与开发协作，判断是否为资源配置不足、热键导致缓存失衡、探针设置不当、JVM 参数问题或外部依赖异常。

A. 快速确认与数据采集

1. Pod/容器状态

• 查看事件与上一轮崩溃日志：
  • kubectl describe pod -n
  • kubectl logs -c -n --previous
• 关注：
  • Last State/Reason 是否为 OOMKilled。
  • 探针失败次数、终止原因（Exit Code），重启次数增长速率。

2. 资源使用

• kubectl top pod -n ，关注 memory/CPU 峰值与 limits 接近度。
• 指标：container_memory_working_set_bytes、container_cpu_usage_seconds_total。
• 对比 GC/分配速率（若开启 GC 日志或 OTel/Java metrics）。

3. 流量与错误

• Ingress NGINX 日志/指标（4xx/5xx、upstream 状态、超时）。
• 应用错误日志中 HTTP 500 的异常类型与堆栈。
• p95/p99 延迟与 QPS 曲线，高峰期是否同时出现 CPU/OOM/探针失败。

4. 版本变更对比

• 比较 v2.3.0 与 v2.3.1 的变更（缓存键策略、序列化、日志级别、OTel/拦截器、线程/连接池、JVM 参数）。
• 确认镜像基础层变化（Alpine 版本、glibc/musl 差异）及依赖库版本。

B. 资源配置不足（容器内存/CPU）定位

• 现象指征：OOMKilled、RSS 接近 limits、GC 频繁且 CPU 高、CrashLoopBackOff 与 liveness/readiness 同时失败。
• 步骤：
  1. 在容器内采样 RSS、堆与原生内存占用：
     • jcmd VM.flags
     • jcmd GC.heap_info
     • jcmd GC.class_histogram
     • 进程视角：cat /proc//status（VmRSS、Threads）
  2. 栈外内存核查：直接内存（Netty/ByteBuffer）、Metaspace、线程栈、代码缓存、JNI/native 分配。
     • 若使用 Netty/HTTP 客户端，查看 direct buffer 使用（应用指标或日志）。
  3. GC 行为：
     • 启用 GC 日志（-Xlog:gc*,safepoint:time,level,tags）观察 STW 停顿、晋升失败、混合回收频率。
  4. 数值评估：
     • 比较堆峰值 + 原生分配（估算）与容器 limits；若 headroom < 20%，高峰期易触发 OOMKill。

C. 热键与缓存失衡定位（Redis/应用内缓存）

• 现象指征：清理 Redis 热键后短暂恢复；堆中大量字典对象；高峰期错误与延迟激增。
• 步骤：
  1. Redis 端：
     • redis-cli INFO memory、INFO stats（keyspace_hits/misses、instantaneous_ops_per_sec、evicted_keys、latency）。
     • redis-cli SLOWLOG GET 128（是否存在单个大 value 或热点命令）。
     • redis-cli MEMORY STATS、对疑似大键执行 MEMORY USAGE 。
     • 采样 MONITOR（短时间）或在应用侧增加键访问计数，识别高频键。
  2. 应用侧：
     • 检查缓存策略（Spring Cache/Caffeine/自定义）：是否无界、是否按键聚合大 Map/字典存入缓存、TTL 是否过长、压缩/序列化开销。
     • 分布式缓存击穿/热点保护（请求合并、单飞/去重、锁）是否缺失。
  3. 网络与分片：
     • Redis 实例是否单点；热点键集中于单分片；连接池饱和与排队。

D. 探针设置不当定位

• 现象指征：探针失败与重启时间相关；延长初始延迟后失败率下降；高峰期更易失败。
• 步骤：
  1. 对比 liveness/readiness 触发时段与 GC 暂停/CPU 峰值。
  2. 检查探针逻辑：
     • liveness 是否依赖外部服务（应仅检测进程健康）。
     • readiness 是否同时检查数据库/Redis/下游依赖，导致瞬时波动下反复不就绪。
  3. NGINX/Ingress 超时与后端返回 500/502/504 的对应关系。

E. JVM 参数问题定位

• 现象指征：升级后 JVM 参数变更、OTel/日志级别升高带来分配增大；G1 回收频繁；直接内存未限流；线程数增加。
• 步骤：
  1. 获取当前 JVM 内存相关参数：-Xms/-Xmx、-XX:MaxRAMPercentage、-XX:MaxDirectMemorySize、Metaspace 设置、代码缓存大小。
  2. 栈外内存来源梳理：Netty/HTTP 客户端、OTel 导出、压缩/序列化、unsafe/DirectByteBuffer。
  3. 线程/栈检查：应用线程数、线程栈大小（-Xss），线程泄漏或过量并发。

F. 外部依赖异常定位（PostgreSQL/Kafka/网络）

• 步骤：
  1. PostgreSQL：pg_stat_activity、pg_stat_statements 检查慢查询、阻塞、重试风暴；连接池用量与超时。
  2. Kafka：消费者/生产者滞后、重试与批量大小；队列堆积导致应用内存上涨。
  3. 网络/Ingress：上游重试叠加；Nginx upstream 超时和重试策略是否导致流量放大。
  4. 校验错误码来源：HTTP 500 是否为应用内部异常（NullPointer/Timeout/CircuitBreakerOpen），与 OOM/探针失败的时间关联。

三、解决 根据诊断结果选择或组合执行以下方案。

A. 资源与 JVM 内存治理（优先消除 OOMKill）

• 明确容器内存预算与堆、原生内存分配关系；在高峰期给足可预测的余量。
• 建议：
  1. 显式设置堆与直接内存，避免不受控增长：
     • Xmx：不超过容器 limits 的 50–65%（例如 limits=512Mi 时，Xmx≈256–320Mi；limits=768Mi 时，Xmx≈384–480Mi），为 Metaspace、直接内存、线程栈、代码缓存预留空间。
     • -XX:MaxDirectMemorySize：为 Netty/HTTP I/O 设定上限（如 128–256Mi，按流量与负载评估）。
     • 保持 Xms < Xmx，避免启动时一次性占满。
  2. 启用并收集 GC 日志，验证回收与暂停：
     • JAVA_TOOL_OPTIONS: "-Xlog:gc*,safepoint:file=/var/log/app-gc.log:time,uptime,level,tags"
  3. 如堆占用长期维持高位且 GC 无法回收，结合堆 dump 分析对象保留路径，指向缓存与热点键问题。
  4. 如果观察到 CPU 因 GC 过高，评估短期提高 limits（如至 1Gi）以止血，再回到治理（不可长期依赖仅提限）。
• HPA 调整：避免仅以 CPU 触发扩缩导致内存不足的Pod被放大流量。
  • 引入内存或自定义业务 QPS/延迟指标作为 HPA 信号；设置 stabilizationWindow 防抖。
  • 确保新副本就绪后再切流（readiness gate）。

B. 热键与缓存策略修正

• Redis 层：
  1. 限制大 Key 或热点 Key：缩小 value、分片/拆键、压缩（如 Snappy/LZ4），设置合理 TTL。
  2. 增加热点保护：请求合并/单飞（single-flight）、本地锁/分布式锁，避免击穿导致风暴。
  3. 如为单实例，评估 Redis Cluster 或增加副本以分摊热点；必要时加入前置本地有界缓存。
• 应用内缓存：
  1. 使用有界缓存（如 Caffeine）并设置最大条目数与最大权重（对象大小），禁用无界 Map 缓存。
  2. 避免将大型字典/聚合对象按单键整块缓存；改为细粒度缓存或分页缓存。
  3. 对热键增加短 TTL 与主动刷新（后台刷新）避免集中失效时的突发。
• 监测：
  • 在应用侧增加键访问频次统计与体积监控，形成热键名单；对 Redis 使用 SLOWLOG、MEMORY USAGE 定期抽样。

C. 探针合理化

• 原则：
  • liveness 只检测进程与基本运行状况，不依赖外部服务。
  • readiness 检测对外可服务能力，可包含对关键依赖的探测。
• 建议配置（按启动时长与负载调整）：
  • liveness：/actuator/health/liveness，initialDelaySeconds 60–90，periodSeconds 15，timeoutSeconds 2–3，failureThreshold 3。
  • readiness：/actuator/health/readiness，initialDelaySeconds 30–60，periodSeconds 10，timeoutSeconds 2–3，failureThreshold 3；对依赖检测设置更宽松超时与降级策略。
• 防止探针“放大故障”：
  • 在高 GC/高负载时放宽超时或降低探测频率。
  • 确保 readiness 从不在短暂抖动中频繁切换（应用侧引入健康状态缓冲或半开状态）。

D. JVM 与运行时参数优化

• 降低分配与原生内存压力：
  1. 控制线程数与栈：合理配置线程池，避免无界增长；如线程数多，适当减小 -Xss（结合调用深度评估）。
  2. 限制直接内存：-XX:MaxDirectMemorySize 明确上限；检查 Netty/HTTP 客户端的池化与缓冲策略。
  3. OpenTelemetry：降低采样率/批量队列、减少导出器缓冲，避免高峰时内存放大。
  4. 日志级别：避免在高峰期启用过细的 DEBUG/TRACE，减少对象创建与 I/O。
• G1 调参（如确有暂停问题）：
  • 可试 -XX:MaxGCPauseMillis=<目标>（如 200ms），并结合 GC 日志评估实际效果；避免过度依赖调参掩盖缓存问题。

E. 外部依赖稳定性

• PostgreSQL：设置合理的连接池大小与超时；对慢查询优化索引；避免重试风暴（指数退避与上限）。
• Kafka：控制批量、重试与缓冲大小；监控消费者滞后，避免应用端内存堆积。
• Ingress/Nginx：确认 upstream 超时设置；避免过度重试导致请求放大。

四、验证

• 指标与现象
  1. Pod 稳定：重启计数不再增长；无 OOMKilled 事件。
  2. 资源：container_memory_working_set_bytes 低于 limits 至少 20–30% 余量；CPU/GC 暂停降至可接受水平。
  3. 性能：p95/p99 延迟恢复；HTTP 500 比例下降至基线（或 ≤ 0.1% 按 SLO）。
  4. Redis：evicted_keys 接近 0；SLOWLOG 中无持续慢命令；instantaneous_ops_per_sec 与延迟平稳。
• 检查点
  • GC 日志：无频繁晋升失败、无长时间 STW；堆占用有回落。
  • 探针：readiness/liveness 成功率稳定，未触发频繁切换。
  • Ingress 日志：无集中 502/504；与应用 500 不再相关联。
• 回归测试
  • 在预生产/灰度环境进行高峰压测，覆盖热点请求路径与缓存命中场景；确保措施生效后再全量上线。

五、预防

• 容量与内存预算
  • 为每个微服务建立容器内存预算模型：Xmx（50–65%）+ 直接内存 + Metaspace + 线程栈 + 代码缓存 + 安全余量。
  • 在 PR/发布流程中强制校验 JVM 参数与 Kubernetes 资源配额一致性。
• 缓存治理
  • 统一热键监控与告警（应用侧统计 + Redis 指标）；定期审计大 Key。
  • 所有本地缓存必须有界并设 TTL；禁止无界字典对象缓存。
  • 引入请求合并/热点保护中间件（如基于单飞策略）。
• 探针与弹性
  • 标准化 liveness/readiness 规范与门槛；在负载测试中验证探针稳定性。
  • HPA 使用多指标（CPU+自定义业务指标/内存），设置稳定窗口，避免抖动。
• 发布与可靠性
  • 灰度/金丝雀发布，流量分阶段放量；在 OTEL/日志级别变更时进行性能回归。
  • 建立内存泄漏与对象保留路径的定期检查（自动化 heap dump/分析于预生产）。

六、升级路径

• T0（立即止血，SRE 主导）
  1. 临时提高 limits（如至 1Gi）并设置 Xmx 与 MaxDirectMemorySize 的明确上限，避免再次 OOMKill。
  2. 放宽探针超时与初始延迟；必要时仅保留 liveness，调整 readiness 减少流量抖动。
  3. 扩容副本或限流（Ingress/网关）以削峰填谷。
• T1（当天内，SRE+开发）
  1. 启用并收集 GC 日志；获取堆 dump（在低风险时段）；对热点对象与保留路径分析。
  2. 应用侧开关：降低 OTEL 采样与批量，回退新增的高开销日志级别。
  3. Redis 排查并处理热点键：降 TTL、拆键、降尺寸；必要时添加副本/分片。
• T2（本周内，开发主导，SRE配合）
  1. 改造缓存策略（有界化、单飞、细粒度缓存、后台刷新）。
  2. 明确 JVM 内存参数基线策略，纳入配置管理（Xmx、MaxDirectMemorySize、线程池规模）。
  3. HPA 指标与探针标准模板落地，预生产压测验证。
• 若依旧不稳定，升级至架构层面：
  • 评估 Redis Cluster / 本地多级缓存（边界与一致性策略）。
  • 对高频接口做隔离（独立副本/队列/读写分离）。
  • 与数据库/消息团队协作优化查询与消息堆积问题。

附：执行中的关键命令与数据点（参考）

• kubectl describe pod / kubectl logs --previous / kubectl top pod
• jcmd VM.flags / GC.heap_info / GC.class_histogram
• Redis：INFO memory / INFO stats / SLOWLOG GET / MEMORY USAGE / MEMORY STATS
• Postgres：pg_stat_activity / pg_stat_statements
• Ingress：查看 upstream 日志与超时配置

说明

• Java 17 默认具备容器感知，但堆与原生内存的总占用仍可能超过容器 limits，需显式控制 Xmx 与直接内存上限。
• Redis 并无通用“热键”内置命令用于直接统计访问频次，建议通过应用侧统计或短期 MONITOR 采样结合 SLOWLOG、MEMORY USAGE 进行识别。
• 探针设计需保证在短暂抖动与 GC 暂停期间不会误杀进程；liveness 不应依赖外部资源。

标题：APNs（Token 认证）迁移后 iOS 生产环境推送异常（BadDeviceToken / 410 Unregistered）故障排除指南

适用范围：

• 客户端：iOS 16.7、iOS 17.1，Swift 5，UserNotifications、BackgroundTasks
• 服务端：Node.js 18，APNs JWT Auth Key（Token-Based Authentication），HTTP/2 直连 api.push.apple.com
• 错误码：BadDeviceToken、410 Unregistered
• 推送负载：包含 mutable-content 与 content-available
• 运行条件：部分设备处于公司 VPN 或低电量模式；用户近两周重装应用

目标：

• 指导定位并解决生产环境中订单通知与静默推送不达的问题
• 输出结构化、可直接发布的多语言排障内容（中文/English）
• 覆盖证书/密钥、环境区分、设备令牌生命周期、权限与网络等关键因素

———————————————————— 一、问题概述（Problem）

• 现象：
  • 迁移至基于 Token 的 APNs 后，生产环境的部分 iOS 设备收不到订单状态通知。
  • 服务端日志显示部分请求返回 BadDeviceToken；清理数据库失效令牌后仍有设备不接收。
  • 静默推送（content-available）用于后台同步不触发，用户重装应用后仍不稳定。
• 已知条件：
  • 使用生产 APNs（api.push.apple.com），JWT Auth Key；Topic 与 bundle identifier 一致。
  • 沙箱环境推送成功，生产失败。
  • 部分设备处于公司 VPN 或低电量模式。
  • 客户端已调用 registerForRemoteNotifications 并上报新 token。

———————————————————— 二、诊断（Diagnosis） 请按从高概率到低概率的顺序执行，以尽快定位根因。

A. 环境与令牌（Environment & Device Token）

1. 确认环境端点：

   • 生产环境必须连接 api.push.apple.com。
   • 沙箱环境必须连接 api.sandbox.push.apple.com。
   • 若向生产端点发送沙箱令牌，将返回 BadDeviceToken。 操作：
   • 在服务端日志中关联每次发送：endpoint、apns-topic、apns-push-type、token 来源（prod/sandbox/发行渠道）。
   • 校验生产队列中是否混入沙箱令牌或开发构建的令牌。

2. 令牌来源与生命周期：

   • 设备令牌与应用、设备、环境强绑定；重装应用、恢复备份、设备 OS 升级或用户清除数据后，令牌可能变化。
   • 向旧令牌发送可能返回 410 Unregistered（APNs 表示该令牌对该 topic 不再有效），应立即删除。 操作：
   • 在客户端为每次应用冷启动与每次 didRegisterForRemoteNotifications 回调上报令牌，并携带“发行渠道”（App Store/TestFlight/Development，用于区分 prod/sandbox）。
   • 在服务端核查数据库：是否仍保留近两周内重装用户的旧令牌；核对 last_seen 时间戳与应用版本；确认清理策略在 410 后即时生效。

3. 令牌编码与格式：

   • 客户端应以原始 Data 的 hex（不含空格和尖括号）上传，避免使用 description 导致格式错误。
   • 服务端存储的令牌字符串长度与字符集是否一致（64 字节 hex）。

B. APNs 请求头与负载（Headers & Payload） 4) apns-push-type 必须设置：

• 用户可见通知：apns-push-type: alert（建议 apns-priority: 10）
• 静默推送：apns-push-type: background（必须 apns-priority: 5；payload 含 {"content-available":1}；不应包含 alert） 操作：
• 抽样检查生产失败请求的 HTTP/2 头：apns-push-type、apns-priority、apns-topic、apns-expiration。
• 如果 content-available 与 mutable-content 同时出现且无 alert，移除 mutable-content 并将 push-type 设为 background。

5. apns-topic 与 bundle identifier：

   • apns-topic 必须与应用主 bundle identifier 完全一致（不使用扩展的 bundle id）。
   • 使用 JWT Auth Key 时还需确保 Team ID 与 keyId、bundleId 一致（否则会出现 InvalidProviderToken/BadTopic，但您当前报错是 BadDeviceToken/410）。 操作：
   • 确认所有生产请求均使用主应用的 bundle id 作为 apns-topic。

6. 合并与过期：

   • 背景推送存在合并与速率限制；大量频繁 content-available 会被合并或丢弃。
   • apns-expiration=0 表示仅当设备在线时立即送达，否则过期；用于后台同步时可设置合理 TTL（例如 300–900 秒）。 操作：
   • 审查后台队列是否短时间内对同一设备发送多条静默推送；必要时使用 apns-collapse-id 合并。

C. 客户端权限与状态（Client Settings & State） 7) 权限与开关：

• 用户可见通知需要用户授权；静默推送不需要授权，但需启用“后台 App 刷新”且应用未被用户强制退出。
• 低电量模式会暂停后台刷新并显著降低静默推送唤醒概率。 操作（在设备上）：
• UNUserNotificationCenter.getNotificationSettings 校验授权状态（alert/badge/sound 是否允许）。
• 设置→通用→后台 App 刷新：确认已开启；低电量模式关闭。
• 提醒用户不要强制退出应用（上滑清除），否则静默推送无法唤醒。

8. App 构建渠道：
   • App Store/TestFlight 令牌为生产；Xcode 开发/Ad Hoc 通常为沙箱。 操作：
   • 在客户端注册令牌时附加构建渠道标识（例如通过编译标志或使用收据类型判断 TestFlight vs App Store），用于服务端路由到对应端点。

D. 网络与公司 VPN（Network & VPN） 9) 设备到 APNs 的连通性：

• 设备需要能与 APNs 建立出站连接：TCP 5223（首选）或 443（回退）到 Apple IP 段（17.0.0.0/8）。
• 公司 VPN/防火墙若阻断或代理此流量，会导致推送延迟或丢失。 操作：
• 与网络团队确认：设备侧允许直连 APNs（17.0.0.0/8，TCP 5223/443）；不对该流量进行 MITM/代理。
• 在受影响设备上切换到蜂窝网络或非公司 Wi‑Fi 测试是否恢复。

———————————————————— 三、解决措施（Resolution） 按以下步骤逐项落实：

1. 强化令牌路由与清理

• 在客户端上报令牌时携带字段：deviceId（匿名标识）、appVersion、buildChannel（appStore/testFlight/development）、environment（prod/sandbox 推断）。
• 服务端持久化并以 environment+bundleId 路由到正确端点：
  • prod → api.push.apple.com
  • sandbox → api.sandbox.push.apple.com
• 实施 410 Unregistered 的即时清理：收到 410 后立刻软删除令牌，并通知客户端重新上报。
• 对近两周重装的用户：批量清理旧令牌，仅保留 last_seen 最新的令牌；对每个用户/设备仅保持一条有效令牌。

2. 规范 APNs 请求头与负载

• 用户可见通知：
  • apns-push-type: alert
  • apns-priority: 10
  • payload 包含 alert；若使用 Notification Service Extension 可保留 mutable-content: 1
• 静默推送（后台同步）：
  • apns-push-type: background
  • apns-priority: 5（必需）
  • payload 仅含 {"content-available":1} 与必要的业务数据；移除 alert 与 mutable-content
  • 合理设置 apns-expiration（例如 600 秒），防止设备离线期间过期
• 确保 apns-topic 精确等于主应用 bundle identifier。

3. 控制推送频率与合并

• 针对同一设备短期内的多次静默推送，使用 apns-collapse-id 合并，降低被系统合并/丢弃的不可控性。
• 将静默推送作为触发信号，与 BGAppRefreshTask/BGProcessingTask 配合；避免完全依赖高频静默推送完成大体量后台同步。

4. 客户端稳健性改造

• 在应用冷启动与前后台切换后调用 registerForRemoteNotifications；在 didRegisterForRemoteNotifications 中立即上报令牌。
• 记录并上报 UNUserNotificationCenter 的权限快照，便于服务端分流（例如用户未授权仅发送静默推送）。
• 为静默推送添加容错：若未触发，应用下次前台/后台刷新时补偿执行同步任务。
• 加入可观测性日志（OSLog）：didRegister 成功/失败、收到 remote notification（background）、BGTask 启动/完成。

5. 网络与终端指导

• 与公司网络部门确认防火墙策略：允许设备对 APNs 的出站连接（TCP 5223 优先，443 作为回退；目标 IP 段 17.0.0.0/8）。
• 面向用户的支持文档：如使用公司 VPN，若收不到通知，可尝试关闭 VPN 或切换网络；关闭低电量模式以允许后台刷新。

———————————————————— 四、验证（Verification） 按以下用例验证修复效果：

1. 令牌与环境验证

• 在客户端重装后，观察服务端是否收到新令牌并标记为 prod（App Store/TestFlight）。
• 使用该令牌向 api.push.apple.com 发送测试通知，响应应为 200（成功）。若返回 BadDeviceToken，核查令牌来源/环境标记。

2. 静默推送验证

• 构造仅含 {"content-available":1} 的负载：
  • Headers：apns-push-type: background、apns-priority: 5、apns-topic: <主 bundle id>
  • 设备不在低电量模式，后台 App 刷新开启，应用未被强制退出
• 期望结果：application(_:didReceiveRemoteNotification:fetchCompletionHandler:) 或等效路径触发，并启动 BGTask 执行同步。
• 观察客户端日志与服务端回执（HTTP 200）。若未触发，检查设备侧网络/VPN 与系统状态。

3. 用户可见通知验证

• 发送含 alert 的推送：
  • Headers：apns-push-type: alert、apns-priority: 10
  • payload 包含 alert 与（可选）mutable-content: 1
• 期望：设备收到并显示通知；服务端返回 200。

4. 错误回执验证

• 人工向已卸载应用的旧令牌发送一条推送，确认收到 410 Unregistered；验证服务端自动清理逻辑是否生效（令牌被标记失效，后续不再发送）。

———————————————————— 五、预防（Prevention）

• 令牌管理：
  • 令牌模型包含 deviceId、bundleId、environment（prod/sandbox）、buildChannel、appVersion、lastSeenAt。
  • 每次收到 410 立即清理；设置定期清理任务，删除 30 天未见的旧令牌。
• 发送策略：
  • 必填 apns-push-type；背景推送固定优先级 5。
  • 合理设置 apns-expiration 与 apns-collapse-id，减轻合并与过期风险。
• 可观测性：
  • 监控 APNs 响应分布（200/BadDeviceToken/Unregistered/…）、端点维度（prod/sandbox）、设备操作系统版本。
  • 建立告警：BadDeviceToken 或 410 突增时触发排查。
• 客户端健壮性：
  • 每次启动/更新后强制重新上报令牌；在设置变更（权限、后台刷新）时上报状态。
  • 为静默推送建立前台补偿路径与 BGTask 回退。

———————————————————— 六、升级路径（Escalation） 若完成上述步骤后仍存在生产设备无法接收：

• 收集材料：
  • 失败请求的完整 HTTP/2 头（apns-topic、apns-push-type、apns-priority、apns-id、apns-expiration、endpoint）
  • APNs 回执（含错误原因）、对应设备的构建渠道、令牌生成与上报时间、客户端日志（didRegister/背景接收）
  • 受影响设备的网络环境（VPN/防火墙策略、端口 5223/443 可用性）
• 提交 Apple Developer Technical Support/TSI：
  • 描述问题、附加最小可复现样例（一个令牌在 sandbox 成功、prod 失败的对比）
  • 若涉及公司网络，附加防火墙例外策略说明与抓包/连通性测试结果

———————————————————— 附：关键事实与要求摘要

• APNs 生产端点：api.push.apple.com；沙箱端点：api.sandbox.push.apple.com（HTTP/2，端口 443；可选 2197）。
• 设备到 APNs 的连接需求：出站 TCP 5223（首选）或 443 到 Apple IP 段 17.0.0.0/8。
• apns-push-type 必填（iOS 13+）；alert 用于用户可见通知，background 用于静默推送。
• background 推送必须 apns-priority: 5；payload 含 content-available: 1；不包含 alert。
• 410 Unregistered 表示令牌对该 topic 不再有效（如应用卸载/令牌失效），应停止继续发送并清理。
• BadDeviceToken 常见原因：环境端点与令牌不匹配（在 prod 端点使用 sandbox 令牌）、令牌过期/格式错误、bundleId 不匹配。

———————————————————— English version (for publication)

Title: Troubleshooting Guide — APNs (Token-Based) Migration: iOS Production Push Failures (BadDeviceToken / 410 Unregistered)

Scope:

• Client: iOS 16.7/17.1, Swift 5, UserNotifications, BackgroundTasks
• Server: Node.js 18, APNs JWT Auth Key (Token-Based), HTTP/2 to api.push.apple.com
• Error codes: BadDeviceToken, 410 Unregistered
• Payload: includes mutable-content and content-available
• Conditions: some devices on corporate VPN or Low Power Mode; users reinstalled the app recently

1. Problem

• After migrating to token-based APNs, some iOS devices don’t receive order status notifications in production.
• Server logs show BadDeviceToken on some requests; after cleaning invalid tokens, delivery remains unreliable on a subset of devices.
• Silent pushes (content-available) for background sync do not fire; reinstall did not stabilize.

2. Diagnosis A. Environment & Token

• Verify endpoints: production → api.push.apple.com; sandbox → api.sandbox.push.apple.com. Sending a sandbox token to production returns BadDeviceToken.
• Token lifecycle: tokens can change on reinstall/OS updates; sending to old tokens should return 410 Unregistered — remove immediately.
• Token encoding: upload hex of the raw device token (no spaces/brackets); server-side strings should be consistent (64-byte hex).

B. Headers & Payload

• apns-push-type is mandatory (iOS 13+):
  • alert for user-visible notifications (apns-priority: 10 recommended)
  • background for silent pushes (apns-priority: 5 required; payload includes {"content-available":1}; do not include alert)
• apns-topic must match the main app bundle identifier exactly.
• Control coalescing/expiration: set reasonable apns-expiration and use apns-collapse-id to avoid excessive silent push bursts.

C. Client Permissions & State

• User-visible notifications require user authorization.
• Silent pushes require Background App Refresh enabled and the app not force-quit; Low Power Mode reduces wake-up likelihood.
• Record build channel (App Store/TestFlight/Development) at registration to route tokens to correct endpoints.

D. Network & VPN

• Devices must reach APNs: outbound TCP 5223 (preferred) or 443 to Apple IP range 17.0.0.0/8.
• Corporate VPN/firewalls must not block or proxy APNs traffic.

3. Resolution

• Strengthen token routing: store environment/buildChannel with tokens; route prod tokens to api.push.apple.com, sandbox tokens to api.sandbox.push.apple.com.
• Immediate cleanup on 410 Unregistered; keep only the most recent token per device/user.
• Normalize headers:
  • alert pushes: apns-push-type=alert, apns-priority=10
  • silent pushes: apns-push-type=background, apns-priority=5, payload only content-available
  • apns-topic equals the app’s bundle id
• Rate control: collapse silent pushes per device; use BGTasks for actual work.
• Client robustness: re-register and upload token on cold start; log notification settings; add compensating sync on next foreground if silent push didn’t fire.
• Network guidance: ensure devices can reach APNs (5223/443 to 17.0.0.0/8); advise users to test on cellular or non-corporate Wi‑Fi.

4. Verification

• Token/env: after reinstall, confirm new token marked prod; sending to api.push.apple.com should return 200. BadDeviceToken indicates env mismatch or formatting issues.
• Silent push: background push with headers (push-type=background, priority=5) should trigger background handler when not force-quit and Low Power Mode off.
• Alert push: push-type=alert, priority=10 should display notification.
• Error handling: sending to an old token should return 410; verify automatic cleanup.

5. Prevention

• Token model: deviceId, bundleId, environment, buildChannel, appVersion, lastSeenAt; periodic cleanup of stale tokens; immediate removal on 410.
• Sending policy: always set apns-push-type; priority 5 for background; sensible expiration/collapse-id.
• Observability: monitor APNs responses by endpoint and OS version; alert on spikes in BadDeviceToken/410.
• Client hygiene: re-upload token at startup/update; report permission/background changes; provide fallback for silent push.

6. Escalation

• Collect: full HTTP/2 headers, APNs response bodies, device build channel, token timestamps, client logs, network/VPN details.
• File an Apple DTS/TSI with a minimal repro (token succeeds on sandbox, fails on prod) and network evidence.

Key Facts

• APNs endpoints: production api.push.apple.com; sandbox api.sandbox.push.apple.com (HTTP/2 over 443; 2197 optional).
• Device connectivity: outbound TCP 5223 (preferred) or 443 to 17.0.0.0/8.
• apns-push-type mandatory; background requires priority 5 and content-available.
• 410 Unregistered → token invalid for topic; stop sending and delete.
• BadDeviceToken → mismatched environment, invalid/old token, or formatting errors.

—— 发布建议：

• 将本指南以中/英双语形式发布；在内部平台附加“运维清单”（端口/IP 开放项）与“客户端集成清单”（令牌上报字段、权限日志）。