RelayIM-Go
分布式实时消息后端
消息发出之后,
让投递与恢复有章可循。
使用 Go 与 go-zero 独立构建的即时通信后端。将接入、存储与投递解耦,重点处理长连接、多节点路由、幂等、离线恢复和故障接管。
为什么做这个项目
即时通信的复杂度,往往出现在一次发送之后:接收方连接可能在另一个节点,持久化和投递可能以不同速度完成,客户端会重试,消费者也可能在处理中断。RelayIM-Go 围绕这些具体故障场景构建多节点消息链路,将接入、业务事实和在线投递拆分处理。
在线通信
多节点 WebSocket 连接与跨节点消息路由。
离线恢复
按独立同步位置补拉消息,恢复送达及阅读状态。
故障排查
观察积压、投递和连接状态,验证消费者异常接管。
从输入,到可检查的结果
- 01
接入与寻址
客户端通过 WebSocket 建立长连接,服务发现与在线路由租约共同确定节点和连接归属。
- 02
进入消息总线
消息进入 Kafka,存储与路由由不同 Consumer Group 分别消费。
- 03
分支处理
Store 分支写入 MySQL;Route 分支寻找接收节点,经对应 Redis Stream 进入在线投递链路。
- 04
确认与恢复
处理投递确认、Pending 与消费者接管;客户端重连后,按同步位置读取缓存及历史数据。
架构与职责划分
把不同的职责放在明确的边界内,让每一步的输入、输出和失败方式都可以单独理解。
持久化、路由和最终送达是不同阶段,接收确认不等同于端到端送达。
分层职责速览
核心工程实现
WebSocket 生命周期与连接归属
每条连接保持一个 reader 和一个 writer,通过有界发送队列隔离消息生产与网络写入。心跳负责连接存活检测,慢客户端不能无限占用队列;etcd 负责节点发现,Redis 路由租约记录用户当前所属的 Realtime 节点。
连接替换和离线清理使用 connectionId 条件删除,防止旧连接退出时删除新连接的路由。路由记录解决“连接在哪里”,节点内连接注册表解决“该交给哪条连接”,两者共同支撑跨节点消息发送。
Kafka Store / Route 独立消费与业务幂等
Realtime 完成会话与业务权限检查后发布标准消息事件。Kafka Store Group 负责写入 MySQL,Route Group 负责在线路由,两条分支独立消费、独立推进,不要求消息先落库再开始路由。Kafka 发布成功后返回发送 ACK。
系统采用 At-least-once processing,以 messageId、clientMessageId 和数据库唯一约束吸收网络重试及重复消费。MySQL 写入失败时不提前提交对应消费进度,依赖恢复后重试;这提供幂等业务效果,而非端到端 Exactly Once。
节点专属 Redis Stream 与 Pending 接管
Route Worker 根据 Redis 在线租约找到目标节点,将消息写入该节点专属 Stream。目标 Realtime 消费任务,在成功放入对应连接的 writePump 发送队列后执行 XACK;Pending 保留尚未确认的工作,XAUTOCLAIM 支持消费者异常后的认领恢复。
Stream 确认的边界是节点内发送队列接收成功,实际网络发送在之后异步发生。因此 Stream XACK 不能代替客户端确认;在线失败和重试仍需结合消息去重、连接状态及离线补拉进行恢复。
五类 ACK:接收、排队、送达、阅读与同步
SendAck 表示 Kafka 发布成功;Stream XACK 表示消息已进入目标连接发送队列;DeliverAck 由单聊接收客户端确认收到;ReadAck 表示用户读到经过校验的会话位置;Offline ACK 表示客户端已同步或持久化的位置。五种状态分别建模,不能互相替代。
阅读状态按 (userId, sessionId) 保存 (createdTime, messageId) 复合游标,在数据库行锁内单调推进,不读写离线同步游标。接收 ACK 事件进入 Kafka 后先返回受理状态,Store 持久化校验后再异步返回处理结果。群聊阅读维护当前成员游标,不执行逐成员送达 fan-out。
离线 Pull / ACK 与 Redis、MySQL 冷热归并
Pull 只读取消息,不因一次响应发出就推进同步位置。客户端本地保存成功后再 ACK,服务端按用户和会话推进游标,使响应丢失、重复 Pull 和重复 ACK 均可重试。同步进度与已读进度独立,补拉不会把“设备收到”改写为“用户看过”。
历史分页使用 (createdTime, messageId) 复合游标,处理同一时间戳的多条消息;Redis 热数据与 MySQL 历史按 messageId 去重归并。Redis 是近期加速层,缓存缺失或 Canal 投影落后时由 MySQL 完整历史承担事实来源。
故障恢复与消息链路观测
Prometheus / Grafana 覆盖 received、publish、store、route、delivery 各阶段,以及 Kafka Lag、Stream Pending / Claim、WebSocket 连接和 Offline Pull / ACK。通过分别观察各阶段,区分接入成功、持久化完成与最终送达。
仓库的 Unit、Contract、Race 与 E2E 覆盖权限、事务、幂等、游标和连接并发,并通过 Kafka、Redis、MySQL、Canal 及服务重启场景验证恢复。Kafka 发布错误显式返回,数据库失败不提交消费进度,服务退出执行有界关闭;本页描述既有验证机制,不把测试结构转换成未经测量的容量数字。
技术难点与设计取舍
为什么要拆分 Store 与 Route?
持久化和在线投递有不同的依赖与失败方式。独立 Consumer Group 让两个分支分别推进和恢复;同时也要求对持久化、路由和最终送达分别观测,不能将一次接收确认等同于完整投递。
为什么跨节点投递还需要 Redis Stream?
在线连接属于具体 Realtime 节点。目标节点的 Stream 为该节点提供待处理任务,并通过 Pending 与 XAUTOCLAIM 处理消费者异常后的接管。
如何处理重试与重复消费?
用客户端消息 ID 与 MySQL 唯一约束识别重复写入,同时处理投递链路中的重复与确认。系统的恢复和去重需要沿链路验证,不能仅依赖消息中间件。
为什么同步进度与阅读进度要分开?
设备收到消息,不代表用户已经阅读。分别保存同步和阅读状态,可以避免重连补拉覆盖阅读进度,也能让多次恢复使用稳定的游标语义。
消息链路架构实景
架构图来自项目文档。点击图片可打开原图查看细节。
如何验证,以及做到哪里
并发与协议
Unit、Race 与 E2E 检查消息处理、连接状态和服务间协议行为。
故障场景
围绕重复消费、断线重连、节点故障与消费者接管验证恢复过程;分别核对遗漏和重复。
可观测性
Prometheus / Grafana 展示连接数、消息积压及投递状态,为故障定位提供观测入口。
当前实现边界
项目当前聚焦 IM 核心消息链路。红包业务处于冻结状态,保留历史实现和回归测试。投递可靠性应以对应版本、场景和实验报告为依据,页面不宣称未经测量的吞吐量或端到端恰好一次语义。
WatchOps-Lite
证据驱动的 OnCall 排障 Agent