Files

richarjiang cc83b84c80 feat(push): 新增设备推送和测试功能

- 新增基于设备令牌的推送通知接口
- 添加推送测试服务，支持应用启动时自动测试
- 新增推送测试文档说明
- 更新 APNS 配置和日志记录
- 迁移至 apns2 库的 PushType 枚举
- 替换订阅密钥文件
- 添加项目规则文档

2025-10-15 19:09:51 +08:00

3.3 KiB

Raw Blame History

推送测试功能

本文档介绍如何使用推送测试功能，该功能可以在应用程序启动时自动获取表中的已有 token 进行消息推送。

功能概述

推送测试功能包括以下特性：

自动测试：应用程序启动时自动执行推送测试（可通过环境变量控制）
手动触发：通过 API 接口手动触发推送测试
统计信息：获取推送令牌的统计信息
可配置内容：可以自定义测试推送的标题和内容

环境变量配置

在 .env 文件中添加以下配置：

# 推送测试配置
# 启用/禁用应用启动时的推送测试
ENABLE_PUSH_TEST=false

# 测试推送消息内容（可选，如果不提供将使用默认值）
PUSH_TEST_TITLE=测试推送
PUSH_TEST_BODY=这是一条测试推送消息，用于验证推送功能是否正常工作。

环境变量说明

ENABLE_PUSH_TEST: 设置为 true 启用应用启动时的推送测试，设置为 false 禁用（默认为 false）
PUSH_TEST_TITLE: 测试推送的标题（可选）
PUSH_TEST_BODY: 测试推送的内容（可选）

API 接口

1. 手动触发推送测试

请求方式: POST 请求路径: /api/push-test/trigger

响应示例:

{
  "code": 0,
  "message": "Push test completed",
  "data": {
    "success": true,
    "message": "Push test completed"
  }
}

2. 获取推送令牌统计信息

请求方式: GET 请求路径: /api/push-test/stats

响应示例:

{
  "code": 0,
  "message": "获取推送令牌统计信息成功",
  "data": {
    "totalTokens": 100,
    "activeTokens": 85,
    "inactiveTokens": 15,
    "recentlyActiveTokens": 60
  }
}

工作原理

自动测试流程:
- 应用启动时，PushTestService 会检查 ENABLE_PUSH_TEST 环境变量
- 如果启用，服务会在应用完全启动后 5 秒执行推送测试
- 测试会获取最多 10 个活跃的推送令牌
- 向这些令牌发送测试推送消息
手动测试流程:
- 通过调用 /api/push-test/trigger 接口手动触发测试
- 测试流程与自动测试相同
统计信息:
- totalTokens: 总令牌数
- activeTokens: 活跃令牌数
- inactiveTokens: 非活跃令牌数
- recentlyActiveTokens: 最近 7 天活跃的令牌数

注意事项

生产环境使用:
- 在生产环境中使用前，请确保测试推送内容不会对用户造成困扰
- 建议在非高峰时段进行测试
令牌限制:
- 自动测试每次最多获取 10 个令牌，避免发送过多推送
- 只会向标记为 isActive=true 的令牌发送推送
错误处理:
- 如果推送失败，服务会记录详细的错误日志
- 无效的令牌会被自动标记为非活跃状态

日志记录

推送测试功能会记录以下日志：

测试开始和结束
发送成功和失败的统计
每个令牌的推送结果
错误详情

这些日志可以帮助排查推送问题。

示例用法

启用自动测试

在 .env 文件中设置 ENABLE_PUSH_TEST=true
重启应用程序
查看日志确认测试是否成功执行

手动触发测试

curl -X POST http://localhost:3002/api/push-test/trigger

查看统计信息

curl -X GET http://localhost:3002/api/push-test/stats

3.3 KiB Raw Blame History Unescape Escape