feat: add jpush push handler

2026-09-05 17:06:59 +08:00
parent efbfb7556a
commit 9e290b76b3
10 changed files with 1715 additions and 2 deletions
@@ -446,6 +446,138 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 消息过大 | `{"ctrl":{"id":"pub-1","code":413,"text":"message too large","params":{"reason":"MESSAGE_TOO_LARGE","max_size":4194304}}}` | 禁止重试，提示压缩或拆分 |
 | 断线 | WebSocket close | 指数退避重连，重新 `hi -> token login -> sub me -> sub topics`，按最后完整 `seq + 1` 增量拉取 |

+##### 0.5.4.9 极光离线 Push 与重连补偿
+
+离线 Push 只承担提醒和唤醒 App，不作为消息正文或业务状态真源。客户端收到极光 Push 后，必须重新登录 IM，通过 `topic + seq`、`call_id` 或系统通知 ID 拉取服务端状态。普通聊天、群 @、系统通知、好友/群审批、音视频来电都复用同一套 extras 分发协议。
+
+客户端侧要求：
+
+- App 集成 JPush SDK，初始化使用极光 `AppKey`，不接触 `MasterSecret`。
+- 登录 IM 后将极光 alias 绑定为当前 `user_id`，例如 `usr...`；同一用户多设备允许绑定同一个 alias。
+- SDK 返回 `registration_id` 后调用 `PUT /v1/im/devices/{device_id}/push-token` 上报，`provider` 固定传 `jpush`。
+- 点击 Push 后按 `extras.type` 跳转，再按服务端数据补偿，不能只凭 Push payload 渲染最终状态。
+
+服务端侧要求：
+
+- `jpush_master_secret` 只保存在后台配置 `im_jpush` 分组，IM Server 通过内部配置接口读取并调用极光 REST API。
+- 用户在线时优先 WebSocket 实时投递；用户离线、后台或不可投递时生成 Push 任务。
+- 万人大群实时 fanout 不靠 Push；离线只对需要提醒的成员生成极光 Push，客户端重连后按 Topic seq 拉取补偿。
+- Push payload 默认不带敏感正文，通知栏文案按用户隐私设置降级。
+
+极光 Push extras 统一格式：
+
+```json
+{
+  "type": "im_message",
+  "tenant_code": "default",
+  "topic": "p2p...",
+  "seq": "128",
+  "sender_id": "usr_sender",
+  "message_type": "text"
+}
+```
+
+| `extras.type` | 必填字段 | 客户端动作 |
+| --- | --- | --- |
+| `im_message` | `tenant_code,topic,seq` | 打开会话，按本地最后 seq 补齐消息并定位。 |
+| `group_mention` | `tenant_code,topic,seq,sender_id` | 打开群会话并定位被 @ 消息。 |
+| `call_invite` | `tenant_code,topic,seq,call_id,call_type,caller_id` | 打开来电页前先登录 IM 并确认通话仍为有效来电。 |
+| `call_missed` | `tenant_code,topic,call_id` | 打开通话记录或对应会话。 |
+| `system_notification` | `tenant_code,notification_id` | 打开系统消息列表并刷新详情。 |
+| `friend_request` | `tenant_code,request_id` | 打开新朋友列表并刷新未处理数。 |
+| `group_request` | `tenant_code,topic,request_id` | 打开群审批入口并刷新列表。 |
+
+普通离线消息极光 payload 示例：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_target"]
+  },
+  "notification": {
+    "alert": "你收到一条新消息",
+    "android": {
+      "title": "MeetingIM",
+      "alert": "你收到一条新消息",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "MeetingIM",
+        "body": "你收到一条新消息"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 86400,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+音视频来电极光 payload 示例：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_callee"]
+  },
+  "notification": {
+    "alert": "收到一通语音通话",
+    "android": {
+      "title": "语音通话",
+      "alert": "张三邀请你语音通话",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "语音通话",
+        "body": "张三邀请你语音通话"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 60,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```

 #### 0.5.5 Long Polling 与文件基础示例

@@ -0,0 +1,317 @@
+# IM 极光推送前后端对接文档
+
+更新时间：2026-09-04
+
+## 1. 对接边界
+
+极光 JPush 接入分三段：
+
+| 边界 | 责任 |
+| --- | --- |
+| 客户端和极光 SDK | 初始化 SDK、申请通知权限、获取 `registration_id`、绑定 alias、接收和点击 Push。 |
+| 客户端和 IM Server | 登录后上报设备 Push Token，收到 Push 后按 `topic/seq/call_id` 回 IM 拉取补偿。 |
+| IM Server 和极光 REST API | 保存 `master_secret`，生成 Push 任务，调用 `POST /v3/push`，记录 `msg_id` 和失败原因。 |
+
+客户端不需要知道 `master_secret`，也不直接调用极光 REST API。
+
+## 2. 客户端接入
+
+### 2.1 SDK 初始化
+
+客户端按平台集成 JPush SDK：
+
+- Android：初始化 JPush SDK，创建通知 Channel，按厂商通道要求配置包名、签名、Channel ID。
+- iOS：配置 APNs 证书或 Token Authentication，申请通知权限。
+- HarmonyOS：按鸿蒙 SDK 文档初始化并配置通知分类。
+
+客户端启动后取得 `registration_id`，登录 IM 后把 alias 绑定为当前 `user_id`。同一用户多设备允许绑定同一个 alias。
+
+### 2.2 上报 Push Token
+
+```http
+PUT /v1/im/devices/{device_id}/push-token
+Authorization: Bearer <IM token>
+X-MeetingIM-APIKey: <api_key>
+X-IM-Schema: 1
+X-Tenant-Code: <tenant_code>
+X-Request-ID: <request_id>
+Idempotency-Key: <idempotency_key>
+Content-Type: application/json
+```
+
+请求：
+
+```json
+{
+  "provider": "jpush",
+  "token": "registration_id",
+  "platform": "ios",
+  "app_version": "1.0.0",
+  "push_env": "test",
+  "sdk_version": "5.0.0",
+  "notification_permission": "granted"
+}
+```
+
+响应 `data`：
+
+```json
+{
+  "device_id": "ios_device_1",
+  "provider": "jpush",
+  "platform": "ios",
+  "app_version": "1.0.0",
+  "updated_at": "2026-09-04T10:00:00Z"
+}
+```
+
+字段说明：
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `provider` | 是 | 固定传 `jpush`。后续保留 `fcm`、`apns` 等兼容值。 |
+| `token` | 是 | 极光 SDK 返回的 `registration_id`。 |
+| `platform` | 是 | `android`、`ios`、`hmos`。 |
+| `app_version` | 否 | 客户端版本，用于排查。 |
+| `push_env` | 否 | `test` 或 `production`，用于 iOS APNs 环境核对。 |
+| `sdk_version` | 否 | JPush SDK 版本。 |
+| `notification_permission` | 否 | `granted`、`denied`、`unknown`。 |
+
+### 2.3 点击 Push 后处理
+
+客户端统一读取 `extras`：
+
+```json
+{
+  "type": "im_message",
+  "tenant_code": "default",
+  "topic": "p2p...",
+  "seq": "128",
+  "sender_id": "usr_sender",
+  "message_type": "text"
+}
+```
+
+处理规则：
+
+1. 如果未登录，先进入登录或静默登录。
+2. 如果租户不一致，先切换到 `tenant_code`。
+3. 按 `type` 跳转目标页面。
+4. 按 `topic` 和本地游标拉取消息补偿。
+5. 按 `seq` 定位消息；若消息已撤回，展示撤回占位。
+6. 对通话类 Push，必须向 IM Server 查询当前通话状态，不能只凭 Push 打开通话中页面。
+
+## 3. 后端接入
+
+### 3.1 配置读取
+
+IM Server 从后台配置读取 `im_jpush` 分组：
+
+```json
+{
+  "jpush_enabled": "true",
+  "jpush_app_key": "app_key",
+  "jpush_master_secret": "******",
+  "jpush_api_domain": "https://api.jpush.cn",
+  "jpush_apns_production": "false",
+  "jpush_default_ttl_seconds": "86400",
+  "jpush_call_ttl_seconds": "60",
+  "jpush_use_alias": "true",
+  "jpush_test_model": "false",
+  "jpush_classification": "1"
+}
+```
+
+### 3.2 设备记录
+
+设备表建议至少支持：
+
+| 字段 | 说明 |
+| --- | --- |
+| `user_id` | IM 用户 ID。 |
+| `device_id` | 客户端设备 ID。 |
+| `provider` | `jpush`。 |
+| `push_token` | 极光 `registration_id`。 |
+| `platform` | `android/ios/hmos`。 |
+| `app_version` | App 版本。 |
+| `push_env` | `test/production`。 |
+| `enabled` | 是否有效。 |
+| `last_seen_at` | 最近上报时间。 |
+| `disabled_reason` | 禁用原因。 |
+
+同一 `user_id + device_id + provider` 覆盖更新；同一 token 换绑账号时，以最后一次登录上报为准并禁用旧绑定。
+
+### 3.3 Push 任务
+
+服务端生成任务时推荐数据结构：
+
+```json
+{
+  "task_id": "push_01K...",
+  "tenant_code": "default",
+  "target_user_id": "usr_target",
+  "push_type": "im_message",
+  "topic": "p2p...",
+  "seq": 128,
+  "call_id": "",
+  "dedupe_key": "default:usr_target:p2p...:128:im_message",
+  "status": "pending",
+  "retry_count": 0,
+  "next_retry_at": "2026-09-04T10:00:00Z"
+}
+```
+
+任务落库或投 Kafka 后由 worker 发送。极光成功返回后记录 `msg_id`；失败按错误类型重试、跳过或禁用设备。
+
+## 4. IM Server 调极光
+
+### 4.1 请求
+
+```http
+POST https://api.jpush.cn/v3/push
+Authorization: Basic base64(app_key + ":" + master_secret)
+Content-Type: application/json
+```
+
+普通消息：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_target"]
+  },
+  "notification": {
+    "alert": "你收到一条新消息",
+    "android": {
+      "title": "MeetingIM",
+      "alert": "你收到一条新消息",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "MeetingIM",
+        "body": "你收到一条新消息"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 86400,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+来电提醒：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_callee"]
+  },
+  "notification": {
+    "alert": "收到一通视频通话",
+    "android": {
+      "title": "视频通话",
+      "alert": "张三邀请你视频通话",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "video",
+        "caller_id": "usr_caller"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "视频通话",
+        "body": "张三邀请你视频通话"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "video",
+        "caller_id": "usr_caller"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 60,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+### 4.2 响应处理
+
+成功响应示例：
+
+```json
+{
+  "sendno": "0",
+  "msg_id": "18100287008546343"
+}
+```
+
+处理规则：
+
+- HTTP 200 且返回 `msg_id`：任务置为 `sent`。
+- 网络超时、5xx、限流：任务置为 `retry_wait`，按退避重试。
+- 鉴权失败或配置错误：任务置为 `failed`，告警并停止继续重试同配置。
+- registration_id 无效：禁用对应设备 token。
+- 用户关闭通知权限：记录设备能力，后续可跳过普通提醒。
+
+## 5. Push extras 规范
+
+所有 extras 值建议使用字符串，避免不同平台 SDK 对数字类型解析不一致。
+
+| 字段 | 必填 | 说明 |
+| --- | --- | --- |
+| `type` | 是 | `im_message`、`group_mention`、`call_invite`、`call_missed`、`system_notification`、`friend_request`、`group_request`。 |
+| `tenant_code` | 是 | 租户编码。 |
+| `topic` | 条件 | 会话或群 Topic。消息、群、通话类必填。 |
+| `seq` | 条件 | Topic 消息序号。消息、群、通话类建议必填。 |
+| `call_id` | 条件 | 通话类必填。 |
+| `call_type` | 条件 | `audio` 或 `video`。 |
+| `sender_id` | 否 | 消息发送人。 |
+| `caller_id` | 条件 | 来电类必填。 |
+| `notification_id` | 条件 | 系统通知类必填。 |
+| `route` | 否 | 客户端白名单路由，不允许外部 URL。 |
+
+## 6. 前后端联调清单
+
+| 步骤 | 操作 | 验证 |
+| --- | --- | --- |
+| 1 | 客户端初始化 JPush SDK | 能拿到 `registration_id`。 |
+| 2 | 登录 IM 并绑定 alias=`user_id` | 极光控制台能查到别名或设备。 |
+| 3 | 调用设备上报接口 | 服务端设备记录 provider=`jpush`。 |
+| 4 | 目标用户退出或断网 | IM 判断为离线或不可 WS 投递。 |
+| 5 | 发送 P2P 消息 | 离线用户收到 Push。 |
+| 6 | 点击 Push | App 打开对应会话并补齐 `seq`。 |
+| 7 | 发起语音/视频通话 | 离线被叫收到短 TTL 来电 Push。 |
+| 8 | 通话取消后点击旧 Push | 客户端查询后显示已取消或未接，不进入通话中。 |
+| 9 | 关闭会话免打扰 | 普通消息不发 Push，@提醒按策略执行。 |
+| 10 | 极光返回无效 token | 后端禁用设备 token，重新上报后恢复。 |
@@ -0,0 +1,368 @@
+# IM 极光推送完整调用流程
+
+更新时间：2026-09-04
+
+## 1. 流程目标
+
+本文用于说明 IM 系统接入极光 JPush 后，离线消息、离线来电、系统通知和业务红点提醒从客户端注册设备、后端保存设备、服务端生成 Push 任务、调用极光 REST API 到客户端点击补偿拉取的完整链路。
+
+官方参考：
+
+- 极光快速开始：https://docs.jiguang.cn/jpush/quickstart/
+- 极光 REST API 概述：https://docs.jiguang.cn/jpush/server/push/server_overview
+- 极光创建推送 API：https://docs.jiguang.cn/jpush/server/push/rest_api_v3_push
+
+## 2. 整体链路
+
+```text
+后台配置极光参数
+-> 客户端集成 JPush SDK
+-> 客户端获得 registration_id
+-> 客户端登录 IM 后上报设备 Push Token
+-> IM Server 保存 user_id/device_id/provider/registration_id/platform
+-> 用户离线或目标设备不在线
+-> IM Server 生成离线 Push 任务
+-> Push worker 调用极光 POST /v3/push
+-> 极光下发通知到 Android/iOS/HarmonyOS
+-> 用户点击通知打开 App
+-> 客户端按 extras 中的 topic/seq/call_id 跳转并补偿拉取
+```
+
+## 3. 后台配置流程
+
+配置建议存放在 HotGo 后台 `hg_sys_config`，分组建议使用 `im_jpush`。IM Server 通过 Admin 内部配置接口读取并缓存，配置变更后通过 Kafka 配置事件或进程内缓存过期生效。
+
+| 配置项 | 示例 | 说明 |
+| --- | --- | --- |
+| `jpush_enabled` | `true` | 是否启用极光推送。 |
+| `jpush_app_key` | `xxxxxxxx` | 极光应用 AppKey。客户端 SDK 初始化也会用到，允许给客户端配置使用。 |
+| `jpush_master_secret` | `******` | 极光 REST API 密钥，只能后端保存和使用，不允许返回客户端。 |
+| `jpush_api_domain` | `https://api.jpush.cn` | 极光 REST API 域名。 |
+| `jpush_push_path` | `/v3/push` | 创建推送 API 路径。 |
+| `jpush_apns_production` | `false/true` | iOS APNs 环境，测试包用 false，生产包用 true。 |
+| `jpush_default_ttl_seconds` | `86400` | 离线 Push 默认保留时长。 |
+| `jpush_call_ttl_seconds` | `60` | 来电 Push 保留时长，建议短一些。 |
+| `jpush_use_alias` | `true` | 是否优先使用 alias=user_id 投递。 |
+| `jpush_test_model` | `false` | 极光测试模式，仅联调测试设备时开启。 |
+| `jpush_classification` | `1` | 重要业务通知建议按系统消息分类处理，需结合厂商通道规则确认。 |
+| `jpush_log_payload` | `false` | 生产关闭 payload 明文日志，避免敏感信息进入日志。 |
+
+## 4. 客户端初始化流程
+
+### 4.1 获取极光配置
+
+客户端安装包通常内置对应环境的 `AppKey`，也可以从 App 配置接口获取非敏感配置。`MasterSecret` 不允许下发。
+
+客户端需要完成：
+
+1. 集成 JPush SDK。
+2. 初始化 SDK 使用 `jpush_app_key`。
+3. 申请系统通知权限。
+4. 取得 `registration_id`。
+5. 登录 IM 后绑定 alias，建议 alias 使用当前 IM `user_id`，例如 `usr...`。
+6. 调用 IM 后端设备接口上报 Push Token。
+
+### 4.2 设备上报
+
+```http
+PUT /v1/im/devices/{device_id}/push-token
+Authorization: Bearer <IM token>
+X-MeetingIM-APIKey: <api_key>
+X-IM-Schema: 1
+X-Tenant-Code: <tenant_code>
+X-Request-ID: <request_id>
+Idempotency-Key: <idempotency_key>
+Content-Type: application/json
+```
+
+请求 Body：
+
+```json
+{
+  "provider": "jpush",
+  "token": "registration_id_from_jpush",
+  "platform": "android",
+  "app_version": "1.0.0",
+  "push_env": "test",
+  "sdk_version": "5.0.0",
+  "notification_permission": "granted"
+}
+```
+
+成功响应：
+
+```json
+{
+  "code": 0,
+  "data": {
+    "device_id": "device_1",
+    "provider": "jpush",
+    "platform": "android",
+    "app_version": "1.0.0",
+    "updated_at": "2026-09-04T10:00:00Z"
+  },
+  "request_id": "req_01K...",
+  "server_time": "2026-09-04T10:00:00Z"
+}
+```
+
+### 4.3 设备解绑
+
+退出登录、删除设备、切换账号或 SDK 返回 registration_id 失效时，客户端应调用设备解绑接口或覆盖上报为空状态。后端要把该设备 token 标记为 disabled，避免继续推送到错误账号。
+
+## 5. 服务端 Push 任务生成
+
+### 5.1 触发场景
+
+| 场景 | 触发条件 | Push 目标 |
+| --- | --- | --- |
+| P2P 离线消息 | 接收方当前无在线可投递设备，或需要离线提醒 | 接收方 user_id。 |
+| 群离线消息 | 成员离线且未免打扰，按 Topic seq 补偿 | 被提醒成员 user_id，不对万人群逐条广播无差别 Push。 |
+| @提醒 | 被 @ 用户离线或后台 | 被 @ 用户 user_id，高优先级。 |
+| 好友申请/审批 | 目标用户离线 | 目标用户 user_id。 |
+| 群申请/邀请/审批 | 审批人或目标成员离线 | 对应用户 user_id。 |
+| 系统通知 | 已写入系统通知表且用户离线 | 通知目标 user_id。 |
+| 语音/视频来电 | 被叫方当前无在线可响铃设备或 App 后台 | 被叫 user_id，短 TTL。 |
+| 未接来电 | 通话超时、取消或未接 | 被叫 user_id。 |
+
+### 5.2 在线与离线判断
+
+在线实时消息仍走 WebSocket。Push 不是消息正文真源，只负责提醒。客户端重连后必须按 Topic `seq` 或业务 ID 从 IM Server 拉取补偿，不能只依赖 Push payload 展示最终状态。
+
+推荐判断：
+
+- 当前用户存在可投递在线会话：优先 WS，下发 Push 可按用户设置降级或不发。
+- 用户全离线：生成 Push 任务。
+- 用户在线但 App 后台状态不可判定：可生成低干扰 Push，客户端本地去重。
+- 群万人场景：实时 fanout 走 Redis/Kafka/Topic 路由，离线只对需要提醒的成员生成 Push。
+
+### 5.3 任务状态机
+
+```text
+pending -> sending -> sent
+pending -> sending -> retry_wait -> sending
+pending -> sending -> failed
+pending -> skipped
+```
+
+| 状态 | 说明 |
+| --- | --- |
+| `pending` | 已生成，等待 worker 发送。 |
+| `sending` | worker 已领取，正在请求极光。 |
+| `sent` | 极光 API 返回成功并记录 `msg_id`。 |
+| `retry_wait` | 临时错误，等待退避重试。 |
+| `failed` | 永久失败或超过最大重试次数。 |
+| `skipped` | 用户免打扰、无有效设备、消息已过期或策略不允许发送。 |
+
+任务需保存 `dedupe_key`，例如 `tenant_code:user_id:topic:seq:push_type`，避免重复生成离线提醒。
+
+## 6. 服务端调用极光 REST API
+
+极光创建推送 API：
+
+```http
+POST https://api.jpush.cn/v3/push
+Authorization: Basic base64(app_key + ":" + master_secret)
+Content-Type: application/json
+```
+
+官方说明中，创建推送 API 使用 HTTPS、HTTP Basic Authentication 和 JSON 请求体；推送目标支持 `alias`、`registration_id`、`tag` 等方式，`alias` 单次最多 1000 个，`registration_id` 单次最多 1000 个；返回成功时包含 `sendno` 和 `msg_id`。
+
+### 6.1 普通离线消息 Push
+
+```json
+{
+  "platform": ["android", "ios", "hmos"],
+  "audience": {
+    "alias": ["usr_target"]
+  },
+  "notification": {
+    "alert": "你收到一条新消息",
+    "android": {
+      "title": "MeetingIM",
+      "alert": "你收到一条新消息",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128",
+        "sender_id": "usr_sender",
+        "message_type": "text"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "MeetingIM",
+        "body": "你收到一条新消息"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128",
+        "sender_id": "usr_sender",
+        "message_type": "text"
+      }
+    },
+    "hmos": {
+      "title": "MeetingIM",
+      "alert": "你收到一条新消息",
+      "category": "IM",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128",
+        "sender_id": "usr_sender",
+        "message_type": "text"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 86400,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+### 6.2 群消息 Push
+
+群消息 Push 只提醒，不携带完整消息正文。万人群不建议按群全员同步投递，只对离线且需要提醒的人生成任务，例如被 @、特别关注、管理员公告、未免打扰小群等。
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_mentioned"]
+  },
+  "notification": {
+    "alert": "群里有人提到了你",
+    "android": {
+      "title": "项目群",
+      "alert": "群里有人提到了你",
+      "extras": {
+        "type": "group_mention",
+        "tenant_code": "default",
+        "topic": "grp...",
+        "seq": "56001",
+        "sender_id": "usr_sender",
+        "mention": "1"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "项目群",
+        "body": "群里有人提到了你"
+      },
+      "badge": "+1",
+      "sound": "default",
+      "extras": {
+        "type": "group_mention",
+        "tenant_code": "default",
+        "topic": "grp...",
+        "seq": "56001",
+        "sender_id": "usr_sender",
+        "mention": "1"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 86400,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+### 6.3 来电 Push
+
+语音/视频来电需要短 TTL。普通离线 Push 只做提醒；如后续要实现系统级强提醒、VoIP 样式或厂商 VoIP，需要额外开通并按平台单独配置。
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_callee"]
+  },
+  "notification": {
+    "alert": "收到一通语音通话",
+    "android": {
+      "title": "语音通话",
+      "alert": "张三邀请你语音通话",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "语音通话",
+        "body": "张三邀请你语音通话"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 60,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+## 7. 客户端点击与补偿拉取
+
+客户端收到或点击 Push 后按 `extras.type` 分发：
+
+| `extras.type` | 客户端动作 |
+| --- | --- |
+| `im_message` | 打开 `topic` 对应会话，按本地最后 `seq + 1` 拉取消息。 |
+| `group_mention` | 打开群会话并定位到 `seq`，若本地无该消息先拉取。 |
+| `call_invite` | 如果通话仍有效，打开来电页；同时通过 IM 登录和会话补偿确认通话状态。 |
+| `call_missed` | 打开通话记录或对应会话。 |
+| `system_notification` | 打开系统消息列表或 `action` 指定页面，再调用 HTTP 拉取详情。 |
+| `friend_request` | 打开新朋友列表并刷新未处理数。 |
+| `group_request` | 打开群审批入口并刷新列表。 |
+
+Push 中的 `topic`、`seq`、`call_id` 只用于定位和补偿，不作为业务真源。客户端必须重新登录 IM 并拉取服务端数据确认状态，例如通话是否已取消、消息是否已撤回、系统通知是否已读。
+
+## 8. 隐私与安全
+
+1. `jpush_master_secret` 只在后端配置和请求极光时使用，不返回客户端。
+2. Push 通知栏默认不展示敏感正文，可按用户隐私设置决定是否展示摘要。
+3. `extras` 不放身份证号、手机号、文件直链、完整消息正文、审核原因明细等敏感数据。
+4. 日志只记录 `task_id/user_id/provider/status/msg_id/error_code`，不记录完整 Push payload。
+5. 推送失败后按错误类型禁用无效 registration_id，避免持续打失败请求。
+6. 多租户场景下 `tenant_code` 必须进入任务、payload、dedupe_key 和日志，禁止跨租户复用设备 token。
+
+## 9. 联调验收
+
+| 验收项 | 期望结果 |
+| --- | --- |
+| 客户端初始化 | SDK 返回 registration_id，alias 绑定为当前 `usr...`。 |
+| 设备上报 | `PUT /v1/im/devices/{device_id}/push-token` 返回成功，服务端记录 provider=`jpush`。 |
+| 普通离线消息 | 用户离线后收到 Push，点击后进入会话并补齐 Topic seq。 |
+| 群 @ 提醒 | 被 @ 用户离线时只收到一次提醒，重连后定位到对应消息。 |
+| 语音来电 | 被叫离线时收到短 TTL 来电 Push，通话取消后点击不会进入过期通话。 |
+| 免打扰 | 免打扰会话不产生普通 Push，@ 或强提醒按策略例外。 |
+| 幂等重试 | 同一 `dedupe_key` 不重复发，极光临时失败可重试。 |
+| 无效设备 | 极光返回无效 token 后设备记录被禁用或待清理。 |
+| iOS 环境 | 测试包 `apns_production=false`，生产包为 true。 |
@@ -5853,15 +5853,36 @@ func (a *adapter) TenantDevicePushTokenUpsert(id t.TenantID, token *t.DevicePush
 }

 func (a *adapter) TenantDevicePushTokenGetAll(id t.TenantID, uids ...t.Uid) (map[t.Uid][]t.DeviceDef, int, error) {
+	return a.tenantDevicePushTokenGetAllByProviders(id, []string{"fcm", "firebase"}, uids...)
+}
+
+func (a *adapter) TenantDevicePushTokenGetAllByProvider(id t.TenantID, provider string, uids ...t.Uid) (map[t.Uid][]t.DeviceDef, int, error) {
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	if provider == "" {
+		return map[t.Uid][]t.DeviceDef{}, 0, nil
+	}
+	return a.tenantDevicePushTokenGetAllByProviders(id, []string{provider}, uids...)
+}
+
+func (a *adapter) tenantDevicePushTokenGetAllByProviders(id t.TenantID, providers []string, uids ...t.Uid) (map[t.Uid][]t.DeviceDef, int, error) {
 	if !a.tenantScopedDB {
 		tenantAdp, err := a.routedTenantAdapter(id)
 		if err != nil {
 			return nil, 0, err
 		}
 		if tenantAdp != a {
-			return tenantAdp.TenantDevicePushTokenGetAll(id, uids...)
+			return tenantAdp.tenantDevicePushTokenGetAllByProviders(id, providers, uids...)
 		}
 	}
+	normalizedProviders := make([]any, 0, len(providers))
+	for _, provider := range providers {
+		if provider = strings.ToLower(strings.TrimSpace(provider)); provider != "" {
+			normalizedProviders = append(normalizedProviders, provider)
+		}
+	}
+	if len(normalizedProviders) == 0 {
+		return map[t.Uid][]t.DeviceDef{}, 0, nil
+	}
 	decoded := make([]any, 0, len(uids))
 	for _, uid := range uids {
 		if !uid.IsZero() {
@@ -5872,7 +5893,7 @@ func (a *adapter) TenantDevicePushTokenGetAll(id t.TenantID, uids ...t.Uid) (map
 		return map[t.Uid][]t.DeviceDef{}, 0, nil
 	}
 	query, args, err := sqlx.In(`SELECT user_id,token,platform,updated_at FROM im_device_push_tokens
-		WHERE provider IN ('fcm','firebase') AND user_id IN (?)`, decoded)
+		WHERE provider IN (?) AND user_id IN (?)`, normalizedProviders, decoded)
 	if err != nil {
 		return nil, 0, err
 	}
@@ -46,6 +46,7 @@ import (
 	// Push notifications
 	"github.com/tinode/chat/server/push"
 	_ "github.com/tinode/chat/server/push/fcm"
+	_ "github.com/tinode/chat/server/push/jpush"
 	_ "github.com/tinode/chat/server/push/stdout"
 	_ "github.com/tinode/chat/server/push/tnpg"

@@ -207,6 +207,19 @@
      "config": {
        "enabled": false
      }
+    },
+    {
+      "name": "jpush",
+      "config": {
+        "enabled": false,
+        "api_domain": "https://api.jpush.cn",
+        "push_path": "/v3/push",
+        "default_ttl_seconds": 86400,
+        "call_ttl_seconds": 60,
+        "apns_production": false,
+        "use_alias": true,
+        "classification": 1
+      }
    }
  ],

@@ -0,0 +1,617 @@
+// Package jpush implements push notification plugin for JPush.
+package jpush
+
+import (
+	"bytes"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/tinode/chat/server/logs"
+	"github.com/tinode/chat/server/push"
+	"github.com/tinode/chat/server/store"
+	t "github.com/tinode/chat/server/store/types"
+)
+
+const (
+	defaultBufferSize = 1024
+	defaultAPIDomain  = "https://api.jpush.cn"
+	defaultPushPath   = "/v3/push"
+	defaultTTL        = 86400
+	defaultCallTTL    = 60
+)
+
+var handler Handler
+
+type Handler struct {
+	input   chan *push.Receipt
+	channel chan *push.ChannelReq
+	stop    chan bool
+	client  *http.Client
+	config  configType
+}
+
+type configType struct {
+	Enabled           bool   `json:"enabled"`
+	DryRun            bool   `json:"dry_run"`
+	AppKey            string `json:"app_key"`
+	MasterSecret      string `json:"master_secret"`
+	APIDomain         string `json:"api_domain"`
+	PushPath          string `json:"push_path"`
+	Buffer            int    `json:"buffer"`
+	DefaultTTLSeconds int    `json:"default_ttl_seconds"`
+	CallTTLSeconds    int    `json:"call_ttl_seconds"`
+	APNsProduction    bool   `json:"apns_production"`
+	UseAlias          *bool  `json:"use_alias"`
+	Classification    int    `json:"classification"`
+	Title             string `json:"title"`
+}
+
+type jpushPayload struct {
+	Platform     any                 `json:"platform"`
+	Audience     map[string][]string `json:"audience,omitempty"`
+	Notification *jpushNotification  `json:"notification,omitempty"`
+	Message      *jpushMessage       `json:"message,omitempty"`
+	Options      jpushOptions        `json:"options"`
+	CID          string              `json:"cid,omitempty"`
+}
+
+type jpushNotification struct {
+	Alert   string          `json:"alert,omitempty"`
+	Android *androidPayload `json:"android,omitempty"`
+	IOS     *iosPayload     `json:"ios,omitempty"`
+	HMOS    *hmosPayload    `json:"hmos,omitempty"`
+}
+
+type androidPayload struct {
+	Alert    string            `json:"alert"`
+	Title    string            `json:"title,omitempty"`
+	Extras   map[string]string `json:"extras,omitempty"`
+	Priority int               `json:"priority,omitempty"`
+}
+
+type iosPayload struct {
+	Alert  iosAlert          `json:"alert"`
+	Sound  string            `json:"sound,omitempty"`
+	Badge  string            `json:"badge,omitempty"`
+	Extras map[string]string `json:"extras,omitempty"`
+}
+
+type iosAlert struct {
+	Title string `json:"title,omitempty"`
+	Body  string `json:"body,omitempty"`
+}
+
+type hmosPayload struct {
+	Alert    string            `json:"alert"`
+	Title    string            `json:"title,omitempty"`
+	Category string            `json:"category,omitempty"`
+	Extras   map[string]string `json:"extras,omitempty"`
+}
+
+type jpushMessage struct {
+	MsgContent string            `json:"msg_content"`
+	Title      string            `json:"title,omitempty"`
+	Extras     map[string]string `json:"extras,omitempty"`
+}
+
+type jpushOptions struct {
+	TimeToLive     int  `json:"time_to_live"`
+	APNsProduction bool `json:"apns_production"`
+	Classification int  `json:"classification,omitempty"`
+}
+
+type jpushResponse struct {
+	SendNo any `json:"sendno"`
+	MsgID  any `json:"msg_id"`
+	Error  *struct {
+		Code    int    `json:"code"`
+		Message string `json:"message"`
+	} `json:"error,omitempty"`
+}
+
+func (Handler) Init(jsonconf json.RawMessage) (bool, error) {
+	if handler.input != nil {
+		return false, errors.New("already initialized")
+	}
+	var config configType
+	if err := json.Unmarshal(jsonconf, &config); err != nil {
+		return false, errors.New("failed to parse config: " + err.Error())
+	}
+	loadThirdPartyConfig(&config)
+	if v := strings.TrimSpace(os.Getenv("IM_JPUSH_APP_KEY")); v != "" {
+		config.AppKey = v
+		config.Enabled = true
+	}
+	if v := strings.TrimSpace(os.Getenv("IM_JPUSH_MASTER_SECRET")); v != "" {
+		config.MasterSecret = v
+		config.Enabled = true
+	}
+	if v := strings.TrimSpace(os.Getenv("IM_JPUSH_API_DOMAIN")); v != "" {
+		config.APIDomain = v
+	}
+	if !config.Enabled {
+		return false, nil
+	}
+	normalized, err := normalizeConfig(config)
+	if err != nil {
+		return false, err
+	}
+	handler.input = make(chan *push.Receipt, normalized.Buffer)
+	handler.channel = make(chan *push.ChannelReq, normalized.Buffer)
+	handler.stop = make(chan bool, 1)
+	handler.client = &http.Client{Timeout: 10 * time.Second}
+	handler.config = normalized
+
+	go func() {
+		for {
+			select {
+			case rcpt := <-handler.input:
+				go sendReceipt(rcpt, &handler.config, handler.client)
+			case req := <-handler.channel:
+				logs.Info.Println("jpush: channel subscription ignored", req.Uid.UserId(), req.Channel)
+			case <-handler.stop:
+				return
+			}
+		}
+	}()
+	return true, nil
+}
+
+func normalizeConfig(config configType) (configType, error) {
+	config.AppKey = strings.TrimSpace(config.AppKey)
+	config.MasterSecret = strings.TrimSpace(config.MasterSecret)
+	config.APIDomain = strings.TrimRight(strings.TrimSpace(config.APIDomain), "/")
+	config.PushPath = strings.TrimSpace(config.PushPath)
+	config.Title = strings.TrimSpace(config.Title)
+	if config.APIDomain == "" {
+		config.APIDomain = defaultAPIDomain
+	}
+	if config.PushPath == "" {
+		config.PushPath = defaultPushPath
+	}
+	if !strings.HasPrefix(config.PushPath, "/") {
+		config.PushPath = "/" + config.PushPath
+	}
+	if config.Buffer <= 0 {
+		config.Buffer = defaultBufferSize
+	}
+	if config.DefaultTTLSeconds <= 0 {
+		config.DefaultTTLSeconds = defaultTTL
+	}
+	if config.CallTTLSeconds <= 0 {
+		config.CallTTLSeconds = defaultCallTTL
+	}
+	if config.Title == "" {
+		config.Title = "MeetingIM"
+	}
+	if config.AppKey == "" || config.MasterSecret == "" {
+		return config, errors.New("jpush: missing app_key or master_secret")
+	}
+	return config, nil
+}
+
+func sendReceipt(rcpt *push.Receipt, config *configType, client *http.Client) {
+	payloads, uids := preparePayloads(rcpt, config)
+	for i := range payloads {
+		if config.DryRun {
+			logs.Info.Println("jpush dry run:", uids[i].UserId(), payloads[i].CID)
+			continue
+		}
+		if err := sendPayload(payloads[i], config, client); err != nil {
+			logs.Warn.Println("jpush push failed:", uids[i].UserId(), err)
+			return
+		}
+	}
+}
+
+func sendPayload(payload *jpushPayload, config *configType, client *http.Client) error {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return err
+	}
+	req, err := http.NewRequest(http.MethodPost, config.APIDomain+config.PushPath, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Basic "+base64.StdEncoding.EncodeToString([]byte(config.AppKey+":"+config.MasterSecret)))
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("http %d: %s", resp.StatusCode, strings.TrimSpace(string(respBody)))
+	}
+	var parsed jpushResponse
+	if len(respBody) > 0 {
+		if err = json.Unmarshal(respBody, &parsed); err != nil {
+			return fmt.Errorf("decode response: %w", err)
+		}
+	}
+	if parsed.Error != nil {
+		return fmt.Errorf("jpush error %d: %s", parsed.Error.Code, parsed.Error.Message)
+	}
+	if parsed.MsgID != nil && logs.Info != nil {
+		logs.Info.Println("jpush sent:", parsed.MsgID)
+	}
+	return nil
+}
+
+func loadThirdPartyConfig(config *configType) {
+	if config == nil || store.ThirdPartyConfig == nil {
+		return
+	}
+	values, err := store.ThirdPartyConfig.Get("im_jpush",
+		"jpush_enabled",
+		"jpush_app_key",
+		"jpush_master_secret",
+		"jpush_api_domain",
+		"jpush_push_path",
+		"jpush_default_ttl_seconds",
+		"jpush_call_ttl_seconds",
+		"jpush_apns_production",
+		"jpush_use_alias",
+		"jpush_classification",
+		"jpush_title",
+	)
+	if err != nil || len(values) == 0 {
+		return
+	}
+	if v, ok := parseConfigBool(values["jpush_enabled"]); ok {
+		config.Enabled = v
+	}
+	if v := strings.TrimSpace(values["jpush_app_key"]); v != "" {
+		config.AppKey = v
+	}
+	if v := strings.TrimSpace(values["jpush_master_secret"]); v != "" {
+		config.MasterSecret = v
+	}
+	if v := strings.TrimSpace(values["jpush_api_domain"]); v != "" {
+		config.APIDomain = v
+	}
+	if v := strings.TrimSpace(values["jpush_push_path"]); v != "" {
+		config.PushPath = v
+	}
+	if v, ok := parseConfigInt(values["jpush_default_ttl_seconds"]); ok {
+		config.DefaultTTLSeconds = v
+	}
+	if v, ok := parseConfigInt(values["jpush_call_ttl_seconds"]); ok {
+		config.CallTTLSeconds = v
+	}
+	if v, ok := parseConfigBool(values["jpush_apns_production"]); ok {
+		config.APNsProduction = v
+	}
+	if v, ok := parseConfigBool(values["jpush_use_alias"]); ok {
+		config.UseAlias = &v
+	}
+	if v, ok := parseConfigInt(values["jpush_classification"]); ok {
+		config.Classification = v
+	}
+	if v := strings.TrimSpace(values["jpush_title"]); v != "" {
+		config.Title = v
+	}
+}
+
+func parseConfigBool(value string) (bool, bool) {
+	switch strings.ToLower(strings.TrimSpace(value)) {
+	case "1", "true", "yes", "on", "enabled":
+		return true, true
+	case "0", "false", "no", "off", "disabled":
+		return false, true
+	default:
+		return false, false
+	}
+}
+
+func parseConfigInt(value string) (int, bool) {
+	parsed, err := strconv.Atoi(strings.TrimSpace(value))
+	return parsed, err == nil
+}
+
+func preparePayloads(rcpt *push.Receipt, config *configType) ([]*jpushPayload, []t.Uid) {
+	if rcpt == nil || config == nil {
+		return nil, nil
+	}
+	data, err := pushData(rcpt.Payload)
+	if err != nil {
+		logs.Warn.Println("jpush: could not build payload:", err)
+		return nil, nil
+	}
+	useAlias := true
+	if config.UseAlias != nil {
+		useAlias = *config.UseAlias
+	}
+	uids := sortedRecipients(rcpt.To)
+	if len(uids) == 0 {
+		return nil, nil
+	}
+	var devices map[t.Uid][]t.DeviceDef
+	if !useAlias {
+		devices, _, err = providerDevicesForUsers(rcpt.TenantID, "jpush", uids...)
+		if err != nil {
+			logs.Warn.Println("jpush: db error", err)
+			return nil, nil
+		}
+	}
+	var payloads []*jpushPayload
+	var targets []t.Uid
+	for _, uid := range uids {
+		recipient := rcpt.To[uid]
+		if recipient.Delivered > 0 {
+			continue
+		}
+		userData := cloneData(data)
+		topic := rcpt.Payload.Topic
+		if t.GetTopicCat(topic) == t.TopicCatP2P {
+			if alias, err := t.P2PNameForUser(uid, topic); err == nil {
+				topic = alias
+				userData["topic"] = alias
+			}
+		}
+		var audience map[string][]string
+		if useAlias {
+			audience = map[string][]string{"alias": {uid.UserId()}}
+		} else {
+			var registrationIDs []string
+			for _, device := range devices[uid] {
+				if device.DeviceId != "" && !containsString(recipient.Devices, device.DeviceId) {
+					registrationIDs = append(registrationIDs, device.DeviceId)
+				}
+			}
+			if len(registrationIDs) == 0 {
+				continue
+			}
+			audience = map[string][]string{"registration_id": registrationIDs}
+		}
+		payloads = append(payloads, buildPayload(audience, topic, userData, recipient.Unread, config))
+		targets = append(targets, uid)
+	}
+	return payloads, targets
+}
+
+func pushData(pl push.Payload) (map[string]string, error) {
+	data := map[string]string{
+		"what":  pl.What,
+		"type":  "im_message",
+		"topic": pl.Topic,
+		"ts":    pl.Timestamp.Format(time.RFC3339Nano),
+	}
+	if pl.From != "" {
+		data["sender_id"] = pl.From
+		data["xfrom"] = pl.From
+	}
+	if pl.Silent {
+		data["silent"] = "true"
+	}
+	switch pl.What {
+	case push.ActMsg:
+		data["seq"] = strconv.FormatInt(pl.SeqId, 10)
+		if pl.ContentType != "" {
+			data["mime"] = pl.ContentType
+			data["message_type"] = messageTypeFromMime(pl.ContentType)
+		}
+		if text := payloadContentString(pl.Content, "text"); text != "" {
+			data["content"] = truncateRunes(text, push.MaxPayloadLength)
+		}
+		if pl.Webrtc != "" {
+			data["webrtc"] = pl.Webrtc
+			if callID := payloadContentString(pl.Content, "callId"); callID != "" {
+				data["call_id"] = callID
+			}
+			if callType := payloadContentString(pl.Content, "callType"); callType == "audio" || callType == "video" {
+				data["call_type"] = callType
+			}
+			data["type"] = "call_invite"
+			if pl.Webrtc != "started" {
+				data["type"] = "call_missed"
+			}
+			if pl.AudioOnly || data["call_type"] == "audio" {
+				data["call_type"] = "audio"
+				data["aonly"] = "true"
+			} else if data["call_type"] == "" {
+				data["call_type"] = "video"
+			}
+			if pl.From != "" {
+				data["caller_id"] = pl.From
+			}
+		}
+		if pl.Replace != "" {
+			data["replace"] = pl.Replace
+			data["silent"] = "true"
+		}
+	case push.ActSub:
+		data["type"] = "system_notification"
+		data["modeWant"] = pl.ModeWant.String()
+		data["modeGiven"] = pl.ModeGiven.String()
+	case push.ActRead:
+		data["type"] = "read"
+		data["seq"] = strconv.FormatInt(pl.SeqId, 10)
+		data["silent"] = "true"
+	default:
+		return nil, errors.New("unknown push type")
+	}
+	return data, nil
+}
+
+func buildPayload(audience map[string][]string, topic string, data map[string]string, unread int, config *configType) *jpushPayload {
+	alert, title := alertText(data, config)
+	ttl := config.DefaultTTLSeconds
+	if data["type"] == "call_invite" {
+		ttl = config.CallTTLSeconds
+	}
+	payload := &jpushPayload{
+		Platform: "all",
+		Audience: audience,
+		Options: jpushOptions{
+			TimeToLive:     ttl,
+			APNsProduction: config.APNsProduction,
+			Classification: config.Classification,
+		},
+		CID: cidFor(topic, data),
+	}
+	if data["silent"] == "true" || data["type"] == "read" {
+		payload.Message = &jpushMessage{MsgContent: alert, Title: title, Extras: data}
+		return payload
+	}
+	badge := "+1"
+	if unread > 0 {
+		badge = strconv.Itoa(unread)
+	}
+	payload.Notification = &jpushNotification{
+		Alert: alert,
+		Android: &androidPayload{
+			Title:    title,
+			Alert:    alert,
+			Extras:   data,
+			Priority: 1,
+		},
+		IOS: &iosPayload{
+			Alert:  iosAlert{Title: title, Body: alert},
+			Sound:  "default",
+			Badge:  badge,
+			Extras: data,
+		},
+		HMOS: &hmosPayload{
+			Title:    title,
+			Alert:    alert,
+			Category: "IM",
+			Extras:   data,
+		},
+	}
+	return payload
+}
+
+func alertText(data map[string]string, config *configType) (string, string) {
+	title := config.Title
+	switch data["type"] {
+	case "call_invite":
+		if data["call_type"] == "audio" {
+			return "收到一通语音通话", "语音通话"
+		}
+		return "收到一通视频通话", "视频通话"
+	case "call_missed":
+		return "你有一通未接来电", "未接来电"
+	case "system_notification":
+		return "你收到一条系统通知", title
+	default:
+		return "你收到一条新消息", title
+	}
+}
+
+func cidFor(topic string, data map[string]string) string {
+	parts := []string{data["type"], topic, data["seq"], data["replace"]}
+	return strings.Trim(strings.Join(parts, "_"), "_")
+}
+
+func messageTypeFromMime(mime string) string {
+	switch {
+	case strings.Contains(mime, "image"):
+		return "image"
+	case strings.Contains(mime, "audio"):
+		return "voice"
+	case strings.Contains(mime, "video"):
+		return "video"
+	default:
+		return "text"
+	}
+}
+
+func payloadContentString(content any, key string) string {
+	if content == nil {
+		return ""
+	}
+	if values, ok := content.(map[string]any); ok {
+		if value, ok := values[key].(string); ok {
+			return strings.TrimSpace(value)
+		}
+	}
+	if values, ok := content.(map[string]string); ok {
+		return strings.TrimSpace(values[key])
+	}
+	return ""
+}
+
+func truncateRunes(value string, limit int) string {
+	if limit <= 0 || len(value) <= limit {
+		return value
+	}
+	runes := []rune(value)
+	if len(runes) <= limit {
+		return value
+	}
+	return string(runes[:limit]) + "…"
+}
+
+func sortedRecipients(recipients map[t.Uid]push.Recipient) []t.Uid {
+	uids := make([]t.Uid, 0, len(recipients))
+	for uid := range recipients {
+		if !uid.IsZero() {
+			uids = append(uids, uid)
+		}
+	}
+	for i := 1; i < len(uids); i++ {
+		for j := i; j > 0 && uids[j].String() < uids[j-1].String(); j-- {
+			uids[j], uids[j-1] = uids[j-1], uids[j]
+		}
+	}
+	return uids
+}
+
+func cloneData(src map[string]string) map[string]string {
+	dst := make(map[string]string, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}
+
+func containsString(values []string, target string) bool {
+	for _, value := range values {
+		if value == target {
+			return true
+		}
+	}
+	return false
+}
+
+func providerDevicesForUsers(tenantID t.TenantID, provider string, uids ...t.Uid) (map[t.Uid][]t.DeviceDef, int, error) {
+	if tokens, ok := store.DevicePushTokens.(store.DevicePushTokenProviderQueryInterface); ok {
+		return tokens.GetAllByProvider(tenantID, provider, uids...)
+	}
+	return map[t.Uid][]t.DeviceDef{}, 0, nil
+}
+
+func (Handler) IsReady() bool {
+	return handler.input != nil
+}
+
+func (Handler) Push() chan<- *push.Receipt {
+	return handler.input
+}
+
+func (Handler) Channel() chan<- *push.ChannelReq {
+	return handler.channel
+}
+
+func (Handler) Stop() {
+	if handler.stop != nil {
+		handler.stop <- true
+	}
+	handler.input = nil
+	handler.channel = nil
+	handler.stop = nil
+}
+
+func init() {
+	push.Register("jpush", &handler)
+}
@@ -0,0 +1,209 @@
+package jpush
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/tinode/chat/server/push"
+	"github.com/tinode/chat/server/store"
+	"github.com/tinode/chat/server/store/types"
+)
+
+type testThirdPartyConfigStore map[string]string
+
+func (s testThirdPartyConfigStore) Get(_ string, keys ...string) (map[string]string, error) {
+	result := make(map[string]string, len(keys))
+	for _, key := range keys {
+		if value, ok := s[key]; ok {
+			result[key] = value
+		}
+	}
+	return result, nil
+}
+
+type testDevicePushTokenStore struct {
+	devices map[types.Uid][]types.DeviceDef
+}
+
+func (s *testDevicePushTokenStore) Upsert(types.TenantID, *types.DevicePushToken) (*types.DevicePushToken, error) {
+	return nil, nil
+}
+
+func (s *testDevicePushTokenStore) GetAllByProvider(types.TenantID, string, ...types.Uid) (map[types.Uid][]types.DeviceDef, int, error) {
+	count := 0
+	for _, devices := range s.devices {
+		count += len(devices)
+	}
+	return s.devices, count, nil
+}
+
+func TestNormalizeConfigLoadsThirdPartyConfig(t *testing.T) {
+	oldConfig := store.ThirdPartyConfig
+	store.ThirdPartyConfig = testThirdPartyConfigStore{
+		"jpush_enabled":             "1",
+		"jpush_app_key":             "app-key",
+		"jpush_master_secret":       "master",
+		"jpush_api_domain":          "https://push.example.com/",
+		"jpush_push_path":           "v3/push",
+		"jpush_default_ttl_seconds": "123",
+		"jpush_call_ttl_seconds":    "45",
+		"jpush_use_alias":           "false",
+		"jpush_classification":      "1",
+	}
+	defer func() { store.ThirdPartyConfig = oldConfig }()
+
+	var config configType
+	loadThirdPartyConfig(&config)
+	config, err := normalizeConfig(config)
+	if err != nil {
+		t.Fatalf("normalize config: %v", err)
+	}
+	if !config.Enabled || config.AppKey != "app-key" || config.MasterSecret != "master" {
+		t.Fatalf("unexpected credentials: %#v", config)
+	}
+	if config.APIDomain != "https://push.example.com" || config.PushPath != "/v3/push" {
+		t.Fatalf("unexpected endpoint: %#v", config)
+	}
+	if config.DefaultTTLSeconds != 123 || config.CallTTLSeconds != 45 || config.UseAlias == nil || *config.UseAlias {
+		t.Fatalf("unexpected ttl/use_alias: %#v", config)
+	}
+}
+
+func TestPreparePayloadsUsesAliasAndNormalizesP2PTopic(t *testing.T) {
+	caller := types.Uid(42)
+	callee := types.Uid(43)
+	topic := caller.P2PName(callee)
+	config := &configType{Title: "MeetingIM", DefaultTTLSeconds: 86400, CallTTLSeconds: 60}
+	payloads, uids := preparePayloads(&push.Receipt{
+		TenantID: 7,
+		To: map[types.Uid]push.Recipient{
+			callee: {Unread: 3},
+		},
+		Payload: push.Payload{
+			What:        push.ActMsg,
+			Topic:       topic,
+			From:        caller.UserId(),
+			SeqId:       12,
+			ContentType: "text/plain",
+			Content:     map[string]any{"text": "hello"},
+			Timestamp:   time.Date(2026, 9, 4, 10, 0, 0, 0, time.UTC),
+		},
+	}, config)
+	if len(payloads) != 1 || len(uids) != 1 || uids[0] != callee {
+		t.Fatalf("unexpected payload count: %d %#v", len(payloads), uids)
+	}
+	payload := payloads[0]
+	if got := payload.Audience["alias"][0]; got != callee.UserId() {
+		t.Fatalf("unexpected alias: %s", got)
+	}
+	userTopic, _ := types.P2PNameForUser(callee, topic)
+	if got := payload.Notification.Android.Extras["topic"]; got != userTopic {
+		t.Fatalf("topic was not normalized for callee: got %s want %s", got, userTopic)
+	}
+	if payload.Notification.IOS.Badge != "3" {
+		t.Fatalf("unexpected badge: %s", payload.Notification.IOS.Badge)
+	}
+}
+
+func TestPreparePayloadsCanUseRegistrationID(t *testing.T) {
+	oldTokens := store.DevicePushTokens
+	uid := types.Uid(42)
+	store.DevicePushTokens = &testDevicePushTokenStore{devices: map[types.Uid][]types.DeviceDef{
+		uid: {
+			{DeviceId: "online-token", Platform: "ios"},
+			{DeviceId: "offline-token", Platform: "android"},
+		},
+	}}
+	defer func() { store.DevicePushTokens = oldTokens }()
+	useAlias := false
+	config := &configType{Title: "MeetingIM", DefaultTTLSeconds: 86400, CallTTLSeconds: 60, UseAlias: &useAlias}
+	payloads, _ := preparePayloads(&push.Receipt{
+		TenantID: 7,
+		To: map[types.Uid]push.Recipient{
+			uid: {Devices: []string{"online-token"}},
+		},
+		Payload: push.Payload{What: push.ActMsg, Topic: "grpTopic", SeqId: 9, Timestamp: time.Now()},
+	}, config)
+	if len(payloads) != 1 {
+		t.Fatalf("unexpected payload count: %d", len(payloads))
+	}
+	got := payloads[0].Audience["registration_id"]
+	if len(got) != 1 || got[0] != "offline-token" {
+		t.Fatalf("unexpected registration ids: %#v", got)
+	}
+}
+
+func TestBuildPayloadUsesShortTTLForCalls(t *testing.T) {
+	config := &configType{Title: "MeetingIM", DefaultTTLSeconds: 86400, CallTTLSeconds: 60}
+	payload := buildPayload(map[string][]string{"alias": {"usr1"}}, "p2pTopic", map[string]string{
+		"type":      "call_invite",
+		"topic":     "p2pTopic",
+		"seq":       "30",
+		"call_type": "audio",
+	}, 0, config)
+	if payload.Options.TimeToLive != 60 {
+		t.Fatalf("unexpected ttl: %d", payload.Options.TimeToLive)
+	}
+	if payload.Notification.Android.Title != "语音通话" {
+		t.Fatalf("unexpected title: %s", payload.Notification.Android.Title)
+	}
+}
+
+func TestPushDataExtractsCallFields(t *testing.T) {
+	data, err := pushData(push.Payload{
+		What:   push.ActMsg,
+		Topic:  "p2pTopic",
+		From:   "usrCaller",
+		SeqId:  30,
+		Webrtc: "started",
+		Content: map[string]any{
+			"callId":   "call_1",
+			"callType": "audio",
+		},
+		Timestamp: time.Date(2026, 9, 4, 10, 0, 0, 0, time.UTC),
+	})
+	if err != nil {
+		t.Fatalf("push data: %v", err)
+	}
+	if data["type"] != "call_invite" || data["call_id"] != "call_1" || data["call_type"] != "audio" || data["caller_id"] != "usrCaller" {
+		t.Fatalf("unexpected call data: %#v", data)
+	}
+}
+
+func TestSendPayloadUsesBasicAuth(t *testing.T) {
+	var gotAuth string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		if r.URL.Path != "/v3/push" {
+			t.Fatalf("unexpected path: %s", r.URL.Path)
+		}
+		var payload jpushPayload
+		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+			t.Fatalf("decode payload: %v", err)
+		}
+		if payload.Audience["alias"][0] != "usr1" {
+			t.Fatalf("unexpected audience: %#v", payload.Audience)
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"sendno":"0","msg_id":"1"}`))
+	}))
+	defer srv.Close()
+	config := &configType{AppKey: "key", MasterSecret: "secret", APIDomain: srv.URL, PushPath: "/v3/push"}
+	err := sendPayload(&jpushPayload{
+		Platform: "all",
+		Audience: map[string][]string{"alias": {"usr1"}},
+		Message:  &jpushMessage{MsgContent: "hello"},
+		Options:  jpushOptions{TimeToLive: 60},
+	}, config, srv.Client())
+	if err != nil {
+		t.Fatalf("send payload: %v", err)
+	}
+	wantAuth := "Basic " + base64.StdEncoding.EncodeToString([]byte("key:secret"))
+	if gotAuth != wantAuth {
+		t.Fatalf("unexpected auth: got %s want %s", gotAuth, wantAuth)
+	}
+}
@@ -2606,6 +2606,10 @@ type DevicePushTokenQueryInterface interface {
 	GetAll(tenantID types.TenantID, uid ...types.Uid) (map[types.Uid][]types.DeviceDef, int, error)
 }

+type DevicePushTokenProviderQueryInterface interface {
+	GetAllByProvider(tenantID types.TenantID, provider string, uid ...types.Uid) (map[types.Uid][]types.DeviceDef, int, error)
+}
+
 type devicePushTokenMapper struct{}

 var DevicePushTokens DevicePushTokenPersistenceInterface
@@ -2636,6 +2640,24 @@ func (devicePushTokenMapper) GetAll(tenantID types.TenantID, uids ...types.Uid)
 	return reader.TenantDevicePushTokenGetAll(tenantID, uids...)
 }

+func (devicePushTokenMapper) GetAllByProvider(tenantID types.TenantID, provider string, uids ...types.Uid) (map[types.Uid][]types.DeviceDef, int, error) {
+	provider = strings.ToLower(strings.TrimSpace(provider))
+	if provider == "" {
+		return map[types.Uid][]types.DeviceDef{}, 0, nil
+	}
+	tenantAdp, err := tenantBusinessAdapter(tenantID)
+	if err != nil {
+		return nil, 0, err
+	}
+	reader, ok := tenantAdp.(interface {
+		TenantDevicePushTokenGetAllByProvider(types.TenantID, string, ...types.Uid) (map[types.Uid][]types.DeviceDef, int, error)
+	})
+	if !ok {
+		return map[types.Uid][]types.DeviceDef{}, 0, nil
+	}
+	return reader.TenantDevicePushTokenGetAllByProvider(tenantID, provider, uids...)
+}
+
 type SafetyPersistenceInterface interface {
 	CreateRiskChallenge(tenantID types.TenantID, challenge *types.RiskChallenge) (*types.RiskChallenge, error)
 	ConfirmRiskChallenge(tenantID types.TenantID, uid types.Uid, challengeID, decision, actionTokenID string, now time.Time) (*types.RiskChallenge, error)
@@ -207,6 +207,19 @@
      "config": {
        "enabled": false
      }
+    },
+    {
+      "name": "jpush",
+      "config": {
+        "enabled": false,
+        "api_domain": "https://api.jpush.cn",
+        "push_path": "/v3/push",
+        "default_ttl_seconds": 86400,
+        "call_ttl_seconds": 60,
+        "apns_production": false,
+        "use_alias": true,
+        "classification": 1
+      }
    }
  ],