Flash Push

A message push platform for microservice architectures

Jupiter Push 是一个基于 Spring Boot / Spring Cloud 的消息推送中台项目，目标是把微服务场景下分散的消息触达逻辑统一沉淀为可复用的基础能力，重点解决 接入解耦、削峰缓冲、业务聚合、在线分发、离线持久化、多端一致性 等问题。

它不是单一的 WebSocket Demo，而是一套按职责拆分的多模块推送平台，覆盖社交互动通知、系统通知、营销任务、聊天消息、短信验证码，以及认证与控制面能力。

一句话介绍 / One-line Summary

在微服务架构下，Jupiter Push 通过“接入层 + 处理层 + 分发层 + 控制面”的分层设计，把点赞、评论、关注、聊天、营销、短信等消息能力沉淀为统一的推送中台。

项目背景 / Why This Project

在业务快速增长的微服务系统中，消息推送逻辑往往散落在不同服务中：

• 每条业务线都要自己处理消息接入、鉴权、限流、聚合、离线补发
• 实时消息与非实时消息的处理语义不同，重复建设成本高
• 营销任务、社交互动通知、聊天消息的投递策略完全不同，但底层链路可以复用

Jupiter Push 的目标，就是把这些能力沉淀成统一中台，让业务系统只关注“发生了什么事件”，而把“如何可靠、可控地触达用户”交给平台完成。

核心能力 / Key Features

• Push API 接入能力：对外接收点赞、评论、关注、系统通知、聊天消息等推送事件
• Kafka 解耦与削峰：API 写入 Kafka，core 异步消费并进入后续处理链路
• 社交消息聚合：点赞 / 评论 / 关注支持分阶段聚合、阈值提醒、静默摘要
• 多端在线投递：根据在线连接状态精准路由到指定 Gateway / WebSocket 连接
• 用户级离线持久化：通知类消息支持离线 inbox、跨设备去重、过期清理
• 聊天消息专属策略：聊天消息始终持久化、在线实时推送、两年保留
• 营销批量任务：支持文件输入、分片、分批、截止时间、夜间禁发、断点续跑
• 短信验证码通道：支持独立 API、限流、黑名单、异步发送、provider 抽象
• 调用方鉴权与后台登录：auth 提供 HMAC 签名鉴权与后台 JWT 登录
• 控制面第一版：admin 提供模板、策略、频控、快照发布，并驱动 core/task 轮询生效

整体架构 / Architecture

flowchart LR
    A["Business Systems<br/>Like / Comment / Follow / Marketing / Chat"] --> B["API"]
    B --> C["Kafka"]
    C --> D["Core"]
    D --> E["Task"]
    D --> F["Router"]
    F --> G["Gateway"]
    F --> H["Offline Inbox / DB"]
    I["Admin"] --> D
    I --> E
    J["Auth"] --> B
    J --> E
    J --> I

Loading

架构说明：

• api 负责消息接入、请求校验、写入 Kafka
• core 负责 Kafka 消费、聚合、分发决策、DLT 与投递命令生成
• task 负责营销任务、短信异步发送与批量调度
• router/gateway 负责在线路由、WebSocket 触达与离线补拉
• admin 提供模板、策略、频控与配置快照
• auth 提供调用方鉴权和后台管理员登录

模块说明 / Modules

模块	说明
jupiter-push-common	公共 DTO、枚举、通用协议与共享模型
jupiter-push-api	对外 HTTP 接入层，完成校验、规范化并写入 Kafka
jupiter-push-core	核心处理层，负责消费、聚合、重试、DLT、分发
jupiter-push-task	任务调度层，负责营销任务、短信发送、批量分片与限流
jupiter-push-router	路由层，维护在线状态、离线 inbox、离线 claim / ack
jupiter-push-gateway	网关层，负责 WebSocket 长连接与最终消息写出
jupiter-push-auth	认证中心，负责调用方签名鉴权与后台用户 JWT 登录
jupiter-push-admin	控制面第一版，负责模板、策略、频控与快照发布

关键链路 / Core Flows

1. 社交互动通知

1. 业务系统调用 Push API 提交点赞 / 评论 / 关注事件
2. API 完成参数校验后，将 PushMessageDTO 直接写入 Kafka
3. core 消费 Kafka，进行有限重试、手动 ACK 与 DLT 兜底
4. 点赞 / 评论 / 关注进入 Redis 状态机聚合
5. 生成最终通知语义后进入分发层
6. router 查询在线状态，gateway 向在线连接推送；离线则持久化到 inbox

2. 聊天消息

1. 聊天消息到达 core 后不做聚合
2. 始终先写入用户级离线 inbox
3. 再向当前在线设备实时 fanout
4. 同设备已实时收到的聊天消息，后续重连不再重复补拉

3. 营销任务

1. 营销模块提供排序后的用户文件
2. task 将文件切分为 shard，再在 shard 内分 batch 顺序发送
3. 每个 batch 前检查发送时间窗与截止时间
4. 超过时效的后续用户直接跳过，不跨期发送

4. 短信验证码

1. 业务系统调用短信发送 API
2. task 模块完成黑名单、限流、幂等检查
3. 请求入库为 PENDING
4. 后台 worker 异步调 SmsProvider
5. 成功/失败状态与发送日志统一落库

技术栈 / Tech Stack

核心框架与基础设施

• Java 17
• Spring Boot 3.2.5
• Spring Cloud 2023.0.2
• Spring Cloud Alibaba 2023.0.1.2
• Apache Kafka
• Redis
• PostgreSQL
• Nacos

开发与测试工具

• Maven
• Lombok
• H2 Database
• JUnit / Spring Boot Test

快速开始 / Quick Start

环境要求

• JDK 17
• Maven 3.9+
• Kafka
• Redis
• PostgreSQL
• Nacos（可选）

说明：

• 这是一个多模块微服务工程，推荐按模块单独启动
• 本地开发时，部分模块/测试支持 H2
• 若本地未接入 Nacos，启动或测试时可能出现连接告警日志，但不一定影响本地开发验证

构建

mvn -q -DskipTests package

推荐启动顺序

auth -> admin -> router -> gateway -> core -> task -> api

示例启动方式

mvn -pl jupiter-push-auth spring-boot:run
mvn -pl jupiter-push-admin spring-boot:run
mvn -pl jupiter-push-router spring-boot:run
mvn -pl jupiter-push-gateway spring-boot:run
mvn -pl jupiter-push-core spring-boot:run
mvn -pl jupiter-push-task spring-boot:run
mvn -pl jupiter-push-api spring-boot:run

当前完成度 / Current Status

已完成 / Implemented

• API 到 Kafka 的生产链路已打通
• core 已具备 Kafka 消费、有限重试、DLT、手动 ACK
• 点赞 / 评论 / 关注的分阶段聚合策略已实现
• 聊天消息已实现“实时推送 + 持久化 + 两年保留”
• 用户离线消息支持用户级 inbox、跨设备去重、30 天过期清理
• 营销任务支持文件输入、分片、分批、截止时间、夜间禁发
• 短信验证码支持独立 API、限流、黑名单、异步发送、provider 抽象
• auth 已具备调用方签名鉴权与后台用户 JWT 登录
• admin 第一版已具备模板、策略、频控、快照发布与 core/task 运行时轮询生效

当前边界 / Current Boundaries

• 控制面前端页面尚未建设，当前以后台 API 为主
• 黑白名单后台、灰度发布、监控告警、死信补偿、任务回放尚未完整落地
• router/gateway 暂未接入控制面动态配置
• 短信真实供应商尚未接入，当前默认使用 mock provider
• 更高规模下的多实例调度、流量隔离、热点 key 深化治理仍有演进空间

Roadmap / Next Steps

• 完成控制面前端页面与更完整的运营后台能力
• 补齐黑白名单、灰度、监控告警、死信补偿、任务回放
• 将控制面动态配置逐步扩展到 router/gateway
• 接入真实短信供应商，完善短信回执链路
• 继续优化大规模场景下的多实例调度、流量隔离与热点治理能力

对外能力入口 / Public Entry Points

• Push API：接收点赞 / 评论 / 关注 / 系统通知 / 聊天消息
• Marketing Task API：创建批量营销任务
• SMS API：提交验证码短信发送请求
• Auth API：后台登录与内部鉴权
• Admin API：模板、策略、频控、快照发布

README 仅做能力级介绍，具体字段与协议请参考各模块实现。

Acknowledgements / 致谢

本项目的实现离不开优秀的开源生态支持。在这里，向项目中重点使用的开源项目致谢。

核心框架与基础设施

• Spring Boot：提供统一、成熟的应用启动与工程基础设施
• Spring Cloud：支持微服务治理、服务间协作与模块化扩展
• Spring Cloud Alibaba / Nacos：用于服务发现与配置管理（service discovery / config management）
• Spring Kafka：支撑事件流、异步解耦与消费链路处理（event streaming / asynchronous decoupling）
• Redis：承载聚合状态、幂等、在线路由辅助与去重能力（stateful aggregation / dedup / online routing support）
• PostgreSQL：承载离线 inbox、营销任务、短信请求与控制面配置数据

开发与测试工具

• H2 Database：支撑本地测试与轻量化集成验证
• Lombok：减少样板代码，提升实体与 DTO 开发效率
• Maven：负责多模块构建、依赖管理与工程组织

感谢这些开源项目为本项目提供稳定、可靠的工程基础。