jw_JIAWEI WANGGitHub ↗
← 返回项目作品
02 / DISTRIBUTED SYSTEMS / CASE STUDY

RelayIM-Go

分布式实时消息后端

消息发出之后,
让投递与恢复有章可循。

使用 Go 与 go-zero 独立构建的即时通信后端。将接入、存储与投递解耦,重点处理长连接、多节点路由、幂等、离线恢复和故障接管。

ROLE个人项目 · 独立设计与开发
FOCUS分布式实时消息后端
SOURCEGitHub ↗
Gogo-zerogRPCWebSocketKafkaRedis StreamsMySQLetcd
01 / THE PROBLEM

为什么做这个项目

即时通信的复杂度,往往出现在一次发送之后:接收方连接可能在另一个节点,持久化和投递可能以不同速度完成,客户端会重试,消费者也可能在处理中断。RelayIM-Go 围绕这些具体故障场景构建多节点消息链路,将接入、业务事实和在线投递拆分处理。

01

在线通信

多节点 WebSocket 连接与跨节点消息路由。

02

离线恢复

按独立同步位置补拉消息,恢复送达及阅读状态。

03

故障排查

观察积压、投递和连接状态,验证消费者异常接管。

02 / HOW IT WORKS

从输入,到可检查的结果

  1. 01

    接入与寻址

    客户端通过 WebSocket 建立长连接,服务发现与在线路由租约共同确定节点和连接归属。

  2. 02

    进入消息总线

    消息进入 Kafka,存储与路由由不同 Consumer Group 分别消费。

  3. 03

    分支处理

    Store 分支写入 MySQL;Route 分支寻找接收节点,经对应 Redis Stream 进入在线投递链路。

  4. 04

    确认与恢复

    处理投递确认、Pending 与消费者接管;客户端重连后,按同步位置读取缓存及历史数据。

03 / SYSTEM DESIGN

架构与职责划分

把不同的职责放在明确的边界内,让每一步的输入、输出和失败方式都可以单独理解。

ARCHITECTURE MAPRelayIM-Go · 消息存储与投递
Kafka 的独立 Store 和 Route 消费组分别处理持久化与在线投递,目标节点通过 Redis Stream 消费消息。
蓝色:核心模块 · 虚线:辅助依赖 / 独立路径↔ 横向滑动查看完整架构

持久化、路由和最终送达是不同阶段,接收确认不等同于端到端送达。

分层职责速览

01 / 接入层Gateway / Realtime A / Realtime B
02 / 消息总线Kafka → 独立的 Store 与 Route Consumer Group
03 / 持久化分支Store → MySQL 业务事实
04 / 投递分支Route → 目标节点 Redis Stream → 客户端

核心工程实现

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 发布错误显式返回,数据库失败不提交消费进度,服务退出执行有界关闭;本页描述既有验证机制,不把测试结构转换成未经测量的容量数字。

04 / ENGINEERING DECISIONS

技术难点与设计取舍

01

为什么要拆分 Store 与 Route?

持久化和在线投递有不同的依赖与失败方式。独立 Consumer Group 让两个分支分别推进和恢复;同时也要求对持久化、路由和最终送达分别观测,不能将一次接收确认等同于完整投递。

02

为什么跨节点投递还需要 Redis Stream?

在线连接属于具体 Realtime 节点。目标节点的 Stream 为该节点提供待处理任务,并通过 Pending 与 XAUTOCLAIM 处理消费者异常后的接管。

03

如何处理重试与重复消费?

用客户端消息 ID 与 MySQL 唯一约束识别重复写入,同时处理投递链路中的重复与确认。系统的恢复和去重需要沿链路验证,不能仅依赖消息中间件。

04

为什么同步进度与阅读进度要分开?

设备收到消息,不代表用户已经阅读。分别保存同步和阅读状态,可以避免重连补拉覆盖阅读进度,也能让多次恢复使用稳定的游标语义。

06 / VERIFY & REFLECT

如何验证,以及做到哪里

01

并发与协议

Unit、Race 与 E2E 检查消息处理、连接状态和服务间协议行为。

02

故障场景

围绕重复消费、断线重连、节点故障与消费者接管验证恢复过程;分别核对遗漏和重复。

03

可观测性

Prometheus / Grafana 展示连接数、消息积压及投递状态,为故障定位提供观测入口。

CURRENT SCOPE

当前实现边界

项目当前聚焦 IM 核心消息链路。红包业务处于冻结状态,保留历史实现和回归测试。投递可靠性应以对应版本、场景和实验报告为依据,页面不宣称未经测量的吞吐量或端到端恰好一次语义。

继续阅读

架构设计 ↗运行与故障恢复 ↗内容依据当前项目 README 与架构文档整理;展示工程设计和验证方式,不将示意图或流程描述作为实时运行数据。
NEXT PROJECT / 03

WatchOps-Lite

证据驱动的 OnCall 排障 Agent

↗