quickstart.md 4.0 KB
普通业务推送：原生通道部署与回退
状态（2026-09-29）：服务端具备 FCM/APNs 路由能力，默认 uni，尚未启用原生推送。本功能不处理音视频通话，也不包含 App 端 token 获取、上报和展示改造；未完成真机验证前不要切换生产环境。
配置与凭据
ruoyi-admin/src/main/resources/application.yml 使用下列环境变量。凭据文件应放在受保护的部署目录，运行账号只需读取权限；不要把 JSON、.p12、密码或真实 token 提交到仓库、放进镜像公开层或写入日志。
| 设置 | 环境变量 | 默认/要求 |
|---|---|---|
| 通道 | BUSINESS_PUSH_MODE |
uni；可选 native，重启后生效 |
| APNs 环境 | BUSINESS_PUSH_APNS_ENVIRONMENT |
production；测试包用 development |
| 用户端 FCM 服务账号文件 | BUSINESS_PUSH_USER_FCM_CREDENTIALS_PATH |
原生模式必填 |
| 商家端 FCM 服务账号文件 | BUSINESS_PUSH_MERCHANT_FCM_CREDENTIALS_PATH |
原生模式必填 |
| 骑手端 FCM 服务账号文件 | BUSINESS_PUSH_RIDER_FCM_CREDENTIALS_PATH |
原生模式必填 |
用户、商家、骑手三端还分别需要 BUSINESS_PUSH_{USER|MERCHANT|RIDER}_APNS_CERTIFICATE_PATH、BUSINESS_PUSH_{USER|MERCHANT|RIDER}_APNS_CERTIFICATE_PASSWORD、BUSINESS_PUSH_{USER|MERCHANT|RIDER}_APNS_TOPIC。路径指向各 App 对应的普通推送 PKCS#12 (.p12) 证书；topic 为对应 App 的 Bundle ID，不是 VoIP topic。三端 Firebase 服务账号也必须分别属于对应 App 的 Firebase 项目。默认 uni 模式不需要这些凭据；native 模式启动时会校验三端配置并加载文件，缺失、不可读或证书无私钥/已过期时启动失败。
BUSINESS_PUSH_APNS_ENVIRONMENT=development 使用 APNs sandbox 网关，production 使用正式网关。所部署证书必须支持所选环境并与 topic 匹配；这两项对应关系仍需部署者核实，配置校验无法替代 Apple 端的实际发送验证。证书到期前应定期检查并更新三端证书，更新后重启服务，再做各端测试。
启用前条件
- App 端分别上报真实的 Android FCM token 或 iOS APNs device token 至
info_user.deviceToken，并把cidType设置为android或ios；cid只用于 uniPush，不能复制到deviceToken。本次交付不实现 App 端上报。 - 确认新手机登录后旧手机会话失效，数据库中账号只保留当前设备 token；原生发送时服务端重新读取该账号的当前
cidType/deviceToken。 - 在非生产环境配置六套凭据、对应 APNs 环境，设
BUSINESS_PUSH_MODE=native并重启。先检查服务启动，再用三端 Android/iOS 各一台真机触发订单、闪送和支付通知；核对通知栏、点击 payload、消息中心、语言与接收人。iOS 骑手使用pushsound.caf；Android 骑手 FCM 带qsRing通知渠道标识，须由 App 创建并配置该渠道才能保证自定义铃声，本次不修改 App。门店订单有可用分管账号时只通知分管账号，没有时才回退主账号。 - 重点覆盖 CID 为空而原生 token 有效、token 缺失/失效、账号换机、预约闪送进入可抢单窗口，以及发送失败但业务操作成功。某条原生通知失败时不会自动回退 uniPush；原路径已有的消息中心记录应保持一次。
切换与回退
生产切换须先完成 App 端配套和真机验收。部署受保护凭据后将 BUSINESS_PUSH_MODE 设为 native，按实例逐一重启并检查启动及推送错误日志；一条通知只会选择当前实例的一个通道，滚动重启期间不同实例可能短暂处于不同模式。若原生投递异常，改回 BUSINESS_PUSH_MODE=uni 并逐一重启；之后的新通知重新使用 cid，已失败的通知不会由服务端自动补发。回退时确认 App 仍维护有效的 uniPush CID。
自动化测试只验证路由、请求构造和错误隔离；真实 Firebase 项目、APNs 凭据、设备 token、通知展示与回退操作仍需部署环境验证。