夜雨聆风
飞享IM完整架构设计文档——架构师视角的系统设计全解析
二、需求分析与约束条件
（一）功能性需求
（二）非功能性需求（质量属性目标）
（三）技术约束
三、系统整体架构设计
（一）逻辑架构（4 层分层）
（二）核心消息流转时序
四、模块设计与接口规范
（一）push-connector 职责边界
（二）push-group 服务层次
（三）Dubbo 接口契约（push-stub）
（四）REST API 规范
-
通用响应结构：
-
错误码体系：
-
核心 API 列表：
五、通信协议设计
（一）TCP 二进制协议头（10 字节）
（二）SubSignal 枚举表
六、数据架构设计
（一）消息分表策略
运维注意事项：
-
时钟回拨可能导致路由到错误分表，需处理（见 ADR-002） -
跨月查询最多跨 3 张表 - 3 年后同月复用：须在运维计划中安排历史数据归档，否则数据混淆
（二）Hazelcast 内存数据结构
七、AI 融合架构设计
对应岗位要求第 7 条「（特别重要）懂 AI，具备新型 AI 架构工程师能力」
（一）当前 AI 接入方案（SAI 协议）
（二）SAI 数据包格式（当前 JSON）
（三）AI 架构特别关注点
（四）AI 架构演进路线
八、高可用与容灾设计
（一）各层可用性分析
（二）幽灵 Session 解决方案
问题： connector 进程 kill -9 时，断线回调不触发，online=true 的 Session 残留，其他节点向死连接投递消息后静默丢失。
解决方案：Hazelcast Entry TTL + 心跳续期
九、安全架构设计
（一）认证流程
（二）传输安全状态
（三）分布式限流（改进方案）
当前问题：限流计数存在 JVM 内存中，多节点时实际限额 = 配置值 × 节点数。
改进：Redis Lua 滑动窗口分布式限流：
十、性能容量规划
（一）单节点容量（16GB 机器）
（二）集群扩容规划
（三）OS 调优清单（运维）
十一、技术决策记录（ADR）
（一）ADR-001：选择 t-io 作为 NIO 框架
背景： 需要支持 TCP + WebSocket 双协议，同时支撑 100 万级长连接。
决策理由： t-io 内置 IM 场景封装（心跳、群组、广播），开发效率高；110 万连接/节点满足业务需求。后续评估： 若需超过 200 万连接/节点，迁移至 Netty。
（二）ADR-002：消息 ID 使用类 Snowflake 算法
决策： 43bit 时间戳 + 6bit nodeId + 15bit 序号
-
时钟回拨未处理（改进：回拨 > 5ms 拒绝服务，等时钟追上） -
nodeId 手动配置（改进：Redis 自动分配） -
nodeId 上限 63（最多 64 节点）
（三）ADR-003：Hazelcast 作为 Session 存储（部分场景建议改 Redis）
背景： 需要分布式 Session 存储，支持多节点查询。
决策： Hazelcast IMap 存 Session + MySQL 冷备份
后续改进方向：
userMessages.lock(user)
INCR 原子操作-
Session TTL 管理 → 推荐 Redis（原生 TTL 支持更稳定）
（四）ADR-004：AI 流式输出使用新增 SAI SubSignal
-
背景： AI Agent 流式 token 需实时推送，MN → Pull 模式延迟过高（多一个 RTT）。
-
决策：新增
SubSignal.SAI，旁路推送不入离线库；流结束后完整答案通过saveAndPublish正常落库。 -
权衡： 流中途断线 → token 丢失，仅通过 MN 拉取完整答案恢复（可接受，AI 回复不是核心消息路径）。
十二、技术演进路线图
十三、架构评审检查单
架构师在每次重大版本发布前须对照评审：
（一）功能完整性
-
所有 P0 功能用例已覆盖（私聊/群聊/登录）
-
离线消息在断线重连后可完整恢复 -
多端消息同步（Android + Web）一致 -
AI 流式输出与普通消息互不干扰 （二）非功能性验证
-
AUTH token 验证已开启（不可绕过）
-
Dubbo 服务间鉴权 token 已配置（非空） -
生产环境 WebSocket 使用 wss://（TLS） -
SQL 注入防护（MyBatis 参数绑定，无拼接 SQL） -
敏感信息不出现在日志中
（三）可运维性
-
每个服务有健康检查端点（Actuator /health）
-
关键日志有 traceId（消息 ID 可追踪全链路） -
JVM 参数已设置 HeapDump（OOM 时自动 dump） -
数据库迁移脚本在 Flyway 中管理（有版本号） （四）AI 架构专项
-
AI 请求超时已配置（防 Agent 服务慢响应阻塞线程）
-
AI 线程池有界（防 OOM） -
Agent 服务不可用时有降级（友好提示而非异常）
AI 上下文记忆按 userId 隔离（不同用户不串话）
总结
-
接入层无状态可水平扩展，业务层可从单实例演进到集群清晰的接口契约 -
Dubbo 接口、REST 规范、protobuf IDL，让各团队并行开发量化的质量目标 -
110 万连接/节点、5,000 TPS，不是模糊描述透明的技术决策 -
每个关键选型都有 ADR 记录背景、候选方案、决策理由可操作的改进路径 -
从当前版本到近期、中期的演进步骤清晰AI 原生思维 -
SAI 协议旁路推送、多 Agent 路由、本地 LLM 集成路线
