从 0 到 1 拆解一个 Netty IM 长连接服务:网关路由、在线路由与消息投递设计
本文详细解析了一个基于 Netty、WebSocket、Spring Cloud
前言
很多项目一开始做“实时消息”时,最容易把问题想简单:前端连一个 WebSocket,后端收到消息再转发出去,好像就完成了一个 IM 服务。
但真正落到微服务架构里,问题会立刻变多:
- 客户端长连接应该接到哪里?
- 网关怎么转发 WebSocket?
- 一个用户在多端在线时,服务端怎么找到他的连接?
- 多台 IM 服务实例部署后,消息服务怎么知道目标用户在哪台机器上?
- 心跳、断线、重连、踢下线、下行投递应该由谁负责?
- IM 服务到底应该只做连接,还是连消息落库、离线消息也一起做?
这篇文章就以我项目里的一个 IM 接入服务为案例,拆解一个“Netty + WebSocket + Spring Cloud Gateway + Redis 在线路由”的长连接服务是怎么设计的。
为了方便阅读,先说明一下本文里的项目名:
| 名称 | 在本文中的角色 | 可以类比成 |
|---|---|---|
s-gateway |
微服务统一网关,负责普通 HTTP 接口和 WebSocket 入口转发 | API Gateway |
s-im-server |
IM 长连接接入层,负责 WebSocket 连接、心跳、在线路由、本机投递 | Connection Gateway / IM Gateway |
s-auth |
认证服务,后续可用于校验 WebSocket token | Auth Service |
s-message |
规划中的消息业务服务,负责消息落库、离线、重试、分发 | Message Service |
| Redis | 保存用户、设备、房间和 IM 实例的在线路由 | Presence / Route Store |
| RabbitMQ | 承接上行业务消息,解耦连接层和消息业务层 | Message Queue |
所以,哪怕你不了解这个项目,也可以把它当成一个通用案例来看:s-im-server 不是一个完整聊天系统,而是一个“长连接接入层”。它的目标是先把连接、心跳、路由和投递这些底座打稳,至于消息落库、离线消息、已读未读、撤回、搜索,则交给后续独立的消息服务演进。
一、先从通用 IM 架构说起:为什么要拆出长连接接入层
1.1 一个 IM 系统最少要拆出哪些角色
从通用架构上看,一个 IM 或实时通信系统通常会拆成几层:
| 层次 | 负责什么 | 典型组件 |
|---|---|---|
| 接入层 | 维持客户端长连接,处理 WebSocket/TCP 心跳、断线、踢下线 | Netty、WebSocket Server |
| 路由层 | 记录用户在哪台接入节点、哪条连接上 | Redis、etcd、注册中心 |
| 消息层 | 处理消息落库、分发、重试、离线、幂等 | MQ、消息服务、数据库 |
| 业务层 | 群聊、客服、设备控制、AI 会话等业务语义 | 各业务服务 |
| 网关层 | 对外统一入口,处理 HTTP/WebSocket 转发、跨域、追踪 | Spring Cloud Gateway、Nginx |
本文里的 s-im-server 主要覆盖前两层:接入层和部分路由层。
它不是一个“大而全”的聊天服务,而是一个负责连接的基础设施服务。这样设计有一个很直接的好处:长连接服务可以专心处理高并发连接和低延迟投递,复杂业务逻辑不用挤进 Netty IO 线程。
1.2 本文案例的服务边界
s-im-server 主要负责这些事情:
- 接收客户端 WebSocket 长连接。
- 在握手阶段解析 token、userId、deviceId、clientType、roomId 等参数。
- 建立当前进程内的连接会话索引。
- 把用户、设备、房间、IM 实例信息注册到 Redis。
- 维护连接心跳,及时清理异常连接。
- 给内部服务提供本机下行投递接口。
- 给管理端提供连接统计、模拟投递、踢连接等调试能力。
它暂时不负责:
- 不负责聊天消息持久化。
- 不负责离线消息。
- 不负责复杂重试和死信。
- 不负责消息业务编排。
- 不在 IM 服务里写 MQ consumer。
这些能力更适合放到独立的消息服务里。本文为了方便表达,把这个规划中的消息业务服务叫做 s-message。读者可以把它理解成任意一个负责“消息落库、离线、重试、分发”的后台服务。
1.3 本文案例的系统架构图
这张图里有两个关键点:
- 网关转普通 HTTP 服务时走
lb://服务名,依赖 Nacos 服务发现。 - 网关转 IM WebSocket 时暂时走固定
ws://127.0.0.1:18111,因为 Nacos 注册的是 Spring Boot HTTP 管理端口18110,不是 Netty WebSocket 端口18111。
1.4 源码模块结构
本文案例的 IM 代码是一个 Maven 聚合模块:
xml
<modules>
<module>s-im-model</module>
<module>s-im-protocol</module>
<module>s-im-api</module>
<module>s-im-service</module>
</modules>
其中真正承载服务实现的是 s-im-service:
xml
<artifactId>s-im-service</artifactId>
<description>IM服务实现模块</description>
<dependencies>
<!-- 对外 API / facade 预留 -->
<dependency>
<groupId>com.salmon</groupId>
<artifactId>s-im-api</artifactId>
</dependency>
<!-- 注册中心和配置中心 -->
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
</dependency>
<!-- 健康检查、指标 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- 后续发布上行业务事件 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-amqp</artifactId>
</dependency>
<!-- WebSocket 长连接核心 -->
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-all</artifactId>
</dependency>
</dependencies>
<build>
<finalName>s-im-server-${project.version}</finalName>
</build>
虽然源码模块名叫 s-im-service,但最终包名是 s-im-server-0.0.1.jar。所以本文统一把这个长连接服务称为 s-im-server。
二、s-im-server 核心设计:为什么要这样拆
2.1 为什么 Spring Boot 和 Netty 各开一个端口
配置如下:
yaml
server:
port: 18110
servlet:
context-path: "/im"
spring:
application:
name: s-im-server
im:
server-id: ${IM_SERVER_ID:${spring.application.name}-${server.port}}
websocket:
port: 18111
path: /im/ws
test-path: /im/ws-test
boss-threads: 1
worker-threads: 4
max-frame-payload-length: 1048576
idle-reader-seconds: 90
idle-writer-seconds: 30
route:
heartbeat-seconds: 10
route-ttl-seconds: 45
这里有两个端口:
18110:Spring Boot HTTP 端口,承载/im/health、/im/admin/stats、/im/internal/deliver等 HTTP 接口。18111:Netty WebSocket 端口,承载真正的长连接/im/ws和测试连接/im/ws-test。
这样拆的好处:
- 长连接 IO 不和普通 HTTP 请求混在一起。
- WebSocket pipeline 可以完全按 Netty 的方式定制。
- Spring Boot 仍然负责配置、依赖注入、Actuator、内部 HTTP 接口。
- 后续 WebSocket 端口可以单独扩容、单独挂负载策略。
- 网关可以明确区分 HTTP 管理接口和 WebSocket 长连接入口。
2.2 为什么 IM 服务只做连接层,不做完整消息业务
IM 系统里最容易膨胀的是“消息业务”。如果把连接、鉴权、路由、投递、落库、离线、撤回、已读、漫游、搜索、通知全部写进一个服务,早期看起来快,后期会非常难维护。
当前设计把 s-im-server 定位为连接接入层:
这样的考虑主要有几个:
- 连接层要轻:长连接服务最怕业务逻辑阻塞 IO 线程。
- 消息层要稳:消息落库、重试、死信、幂等更适合独立服务维护。
- 扩容模型不同:连接层按连接数扩容,消息层按消息吞吐扩容。
- 故障影响更小:消息服务短暂异常时,连接层仍可维持连接和基础心跳。
- 后续跨语言方便:代码里已经提到 Go 侧统一 dispatch 格式,消息中心可以独立演进。
2.3 Netty 服务启动
ImNettyServer 只负责启动、绑定端口和优雅关闭,不承载业务逻辑:
java
@Slf4j
@Component
@RequiredArgsConstructor
public class ImNettyServer {
private final ImServerProperties properties;
private final ImChannelInitializer channelInitializer;
private EventLoopGroup bossGroup;
private EventLoopGroup workerGroup;
private Channel serverChannel;
private final AtomicBoolean running = new AtomicBoolean(false);
public void start() {
if (!running.compareAndSet(false, true)) {
return;
}
try {
// bossGroup 负责接收新连接
bossGroup = new NioEventLoopGroup(properties.getWebsocket().getBossThreads());
// workerGroup 负责处理已建立连接上的 IO 事件
workerGroup = new NioEventLoopGroup(properties.getWebsocket().getWorkerThreads());
ServerBootstrap bootstrap = new ServerBootstrap()
.group(bossGroup, workerGroup)
.channel(NioServerSocketChannel.class)
.childHandler(channelInitializer);
ChannelFuture future = bootstrap.bind(properties.getWebsocket().getPort()).sync();
serverChannel = future.channel();
log.info("IM Netty WebSocket 服务启动成功: port={}, path={}",
properties.getWebsocket().getPort(), properties.getWebsocket().getPath());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
running.set(false);
throw new IllegalStateException("启动 IM Netty 服务被中断", e);
} catch (Exception e) {
running.set(false);
shutdownGroups();
throw new IllegalStateException("启动 IM Netty 服务失败", e);
}
}
}
这里的设计重点是:
AtomicBoolean running保证启动和停止幂等。bossGroup和workerGroup分工明确。childHandler(channelInitializer)把连接处理细节交给 pipeline 初始化器。- 启动失败时主动关闭线程组,避免资源泄漏。
2.4 Spring 生命周期托管 Netty
NettyLifecycle 实现了 SmartLifecycle:
java
@Component
@RequiredArgsConstructor
public class NettyLifecycle implements SmartLifecycle {
private final ImNettyServer imNettyServer;
@Override
public void start() {
imNettyServer.start();
}
@Override
public void stop() {
imNettyServer.stop();
}
@Override
public boolean isAutoStartup() {
return true;
}
}
这样 Spring 容器启动完成后会自动启动 Netty,容器停止时也会自动关闭 Netty。它比在 main 方法里手动启动更适合微服务,因为生命周期和 Spring 应用保持一致。
三、Netty 类太多?按 pipeline 一条线看就清楚了
很多人第一次看 Netty 项目会觉得类很多,其实这套代码的 Netty 类是按职责拆的。只要沿着 pipeline 看,结构非常清楚。
3.1 Netty pipeline 流程图
3.2 ImChannelInitializer:每条连接的 handler 链
java
@Component
@RequiredArgsConstructor
public class ImChannelInitializer extends ChannelInitializer<SocketChannel> {
private final ImServerProperties properties;
private final ConnSessionManager sessionManager;
private final OnlineRouteRegistry routeRegistry;
private final ImPacketCodec packetCodec;
@Override
protected void initChannel(SocketChannel channel) {
channel.pipeline()
// HTTP 请求编解码,WebSocket 握手本质上先是 HTTP Upgrade
.addLast(new HttpServerCodec())
// 把 HTTP 请求聚合成 FullHttpRequest,方便握手处理器一次性读取 URI 和 query
.addLast(new HttpObjectAggregator(properties.getWebsocket().getMaxFramePayloadLength()))
// Netty 原生空闲检测,只产生事件,不直接处理业务
.addLast(new IdleStateHandler(
properties.getWebsocket().getIdleReaderSeconds(),
properties.getWebsocket().getIdleWriterSeconds(),
0,
TimeUnit.SECONDS))
// 自定义握手鉴权:校验路径、token,解析 userId/deviceId/clientType 等信息
.addLast(new HandshakeAuthHandler(properties))
// WebSocket 协议处理:完成 HTTP Upgrade,后续开始收 WebSocketFrame
.addLast(new WebSocketServerProtocolHandler(WebSocketServerProtocolConfig.newBuilder()
.websocketPath("/")
.checkStartsWith(true)
.allowExtensions(false)
.maxFramePayloadLength(properties.getWebsocket().getMaxFramePayloadLength())
.build()))
// 自定义心跳处理:写空闲发 ping,读空闲关闭连接
.addLast(new ImIdleStateHandler())
// 业务帧处理:文本消息、ping/pong、关闭帧、创建 session、刷新路由
.addLast(new ImWebSocketFrameHandler(sessionManager, routeRegistry, packetCodec))
// pipeline 末尾兜底异常处理
.addLast(new ChannelExceptionHandler());
}
}
这里几个细节值得注意:
WebSocketServerProtocolHandler的websocketPath("/")配合checkStartsWith(true),是因为前面的HandshakeAuthHandler已经严格限制只允许/im/ws和/im/ws-test。这样可以避免测试路径在协议 handler 的路径匹配处卡住。allowExtensions(false)是为了第一阶段不启用 permessage-deflate 等 WebSocket 扩展。浏览器可能默认请求压缩扩展,如果服务端没有配套压缩解码 handler,后续文本帧可能出问题。- 自定义 handler 都保持单一职责:握手的只做握手,心跳的只做心跳,帧处理的只做帧处理。
3.3 HandshakeAuthHandler:握手阶段做什么
WebSocket 握手本质上是一次 HTTP 请求,所以可以在升级前解析 URI 和 query 参数。
java
protected void channelRead0(ChannelHandlerContext ctx, FullHttpRequest request) {
QueryStringDecoder decoder = new QueryStringDecoder(request.uri());
String requestPath = decoder.path();
boolean normalPath = properties.getWebsocket().getPath().equals(requestPath);
boolean echoTest = properties.getWebsocket().getTestPath().equals(requestPath);
if (!normalPath && !echoTest) {
ReferenceCountUtil.release(request);
reject(ctx, "unsupported path: " + requestPath);
return;
}
Map<String, List<String>> params = decoder.parameters();
String token = first(params, "token");
if (!StringUtils.hasText(token)) {
ReferenceCountUtil.release(request);
reject(ctx, "missing token");
return;
}
HandshakePrincipal principal = HandshakePrincipal.builder()
.connId(UUID.randomUUID().toString().replace("-", ""))
.token(token)
.clientType(defaultIfBlank(first(params, "clientType"), "unknown"))
.userId(parseLong(first(params, "userId")))
.deviceId(first(params, "deviceId"))
.roomId(first(params, "roomId"))
.build();
// 先把握手身份放到 Channel 属性上,等 WebSocket 握手完成后再创建 ConnSession
ctx.channel().attr(ImChannelAttributes.CONN_ID).set(principal.getConnId());
ctx.channel().attr(ImChannelAttributes.TOKEN).set(principal.getToken());
ctx.channel().attr(ImChannelAttributes.CLIENT_TYPE).set(principal.getClientType());
ctx.channel().attr(ImChannelAttributes.USER_ID).set(principal.getUserId());
ctx.channel().attr(ImChannelAttributes.DEVICE_ID).set(principal.getDeviceId());
ctx.channel().attr(ImChannelAttributes.ROOM_ID).set(principal.getRoomId());
ctx.channel().attr(ImChannelAttributes.ECHO_TEST).set(echoTest);
// 放行给 WebSocketServerProtocolHandler,继续完成 HTTP Upgrade
ctx.fireChannelRead(request);
}
当前阶段只做 token 非空校验,代码注释里也写得很清楚:后续可以在这里调用 s-auth 或解析 JWT。这个设计是合理的,因为认证必须发生在握手升级之前,认证失败就不应该建立长连接。
握手 URL 大概长这样:
text
ws://localhost:18080/api/im/ws?token=xxx&userId=1001&clientType=web&deviceId=iphone-001
测试 echo 路径:
text
ws://localhost:18080/api/im/ws-test?token=dev-token&clientType=salmon-tools
3.4 ImChannelAttributes:为什么要把身份放在 Channel 上
ImChannelAttributes 定义了 Netty Channel 上的属性 key:
java
public final class ImChannelAttributes {
public static final AttributeKey<String> CONN_ID = AttributeKey.valueOf("im.connId");
public static final AttributeKey<String> TOKEN = AttributeKey.valueOf("im.token");
public static final AttributeKey<String> CLIENT_TYPE = AttributeKey.valueOf("im.clientType");
public static final AttributeKey<Long> USER_ID = AttributeKey.valueOf("im.userId");
public static final AttributeKey<String> DEVICE_ID = AttributeKey.valueOf("im.deviceId");
public static final AttributeKey<String> ROOM_ID = AttributeKey.valueOf("im.roomId");
public static final AttributeKey<Boolean> ECHO_TEST = AttributeKey.valueOf("im.echoTest");
}
这么做的原因是:
- 握手 handler 解析出来的信息,后面的 handler 也要用。
- Netty 的 Channel 生命周期和连接一致,把连接属性挂在 Channel 上很自然。
- 不需要靠 ThreadLocal,因为 Netty 事件可能由不同 event loop 调度。
- 握手完成后,可以从 Channel 属性构造正式的
ConnSession。
3.5 ImWebSocketFrameHandler:业务帧处理入口
ImWebSocketFrameHandler 处理 WebSocket 帧:
java
protected void channelRead0(ChannelHandlerContext ctx, WebSocketFrame frame) {
if (frame instanceof TextWebSocketFrame textFrame) {
handleTextFrame(ctx, textFrame);
return;
}
if (frame instanceof PingWebSocketFrame pingFrame) {
// 客户端 ping,服务端回 pong
ctx.writeAndFlush(new PongWebSocketFrame(pingFrame.content().retain()));
return;
}
if (frame instanceof PongWebSocketFrame) {
// 收到 pong,说明连接仍然活跃,刷新在线路由 TTL
sessionManager.get(ctx.channel().attr(ImChannelAttributes.CONN_ID).get())
.ifPresent(routeRegistry::refreshRoute);
return;
}
if (frame instanceof CloseWebSocketFrame) {
ctx.close();
return;
}
if (frame instanceof BinaryWebSocketFrame) {
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.error(
"UNSUPPORTED_FRAME",
"binary frame is not supported in first version",
null)));
return;
}
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.error("UNSUPPORTED_FRAME", "unsupported frame", null)));
}
当前版本只支持文本 JSON。二进制帧先明确拒绝,这很稳:先把协议边界说清楚,后续如果要支持音频流、二进制包,再专门设计 binary packet。
3.6 握手完成后创建本地 session
WebSocket 协议升级完成后,Netty 会触发握手完成事件。代码里对不同 Netty 版本可能触发的事件做了兼容:
java
@Override
public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
if (evt instanceof WebSocketServerProtocolHandler.ServerHandshakeStateEvent event
&& event == WebSocketServerProtocolHandler.ServerHandshakeStateEvent.HANDSHAKE_COMPLETE) {
createSessionIfAbsent(ctx);
return;
}
if (evt instanceof WebSocketServerProtocolHandler.HandshakeComplete) {
createSessionIfAbsent(ctx);
return;
}
super.userEventTriggered(ctx, evt);
}
private void createSessionIfAbsent(ChannelHandlerContext ctx) {
String connId = ctx.channel().attr(ImChannelAttributes.CONN_ID).get();
if (!StringUtils.hasText(connId) || sessionManager.get(connId).isPresent()) {
return;
}
ConnSession session = sessionManager.create(ctx.channel(), buildPrincipal(ctx));
routeRegistry.register(session);
}
这里还有一个很重要的幂等保护:
java
if (!StringUtils.hasText(connId) || sessionManager.get(connId).isPresent()) {
return;
}
因为不同 Netty 版本可能触发不同握手完成事件,如果不做幂等,可能重复创建 session、重复注册路由。
3.7 文本消息处理逻辑
java
private void handleTextFrame(ChannelHandlerContext ctx, TextWebSocketFrame textFrame) {
String connId = ctx.channel().attr(ImChannelAttributes.CONN_ID).get();
Boolean echoTest = ctx.channel().attr(ImChannelAttributes.ECHO_TEST).get();
if (Boolean.TRUE.equals(echoTest)) {
// 测试路径:客户端发什么,服务端原样返回什么
sessionManager.get(connId).ifPresent(routeRegistry::refreshRoute);
ctx.writeAndFlush(new TextWebSocketFrame(textFrame.text()));
return;
}
try {
ImPacket packet = packetCodec.decode(textFrame.text());
sessionManager.get(connId).ifPresent(routeRegistry::refreshRoute);
if (!StringUtils.hasText(packet.getType())) {
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.error(
"BAD_REQUEST", "missing packet type", packet.getTraceId())));
return;
}
if (ImPacketType.PING.equals(packet.getType())) {
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.pong(packet.getTraceId())));
return;
}
if (ImPacketType.CHAT.equals(packet.getType())
|| ImPacketType.CALL_SIGNAL.equals(packet.getType())
|| ImPacketType.DEVICE_EVENT.equals(packet.getType())
|| ImPacketType.VOICE_EVENT.equals(packet.getType())) {
// 第一阶段先 ack 和打日志;后续在这里接 MessageClient 或 MQ producer 转给 s-message
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.ack(packet)));
return;
}
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.error(
"UNKNOWN_TYPE", "unknown packet type", packet.getTraceId())));
} catch (Exception e) {
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.error("BAD_REQUEST", "invalid packet", null)));
}
}
这一段体现了当前阶段的取舍:
ping直接回pong。chat、call_signal、device_event、voice_event先回ack。- 后续可以在这里接
ImEventProducer,把上行业务消息投递到 MQ。 - 非法 JSON 或未知类型直接返回错误包。
3.8 协议包设计
统一协议对象是 ImPacket:
java
@Data
public class ImPacket {
/** 消息类型,例如 ping、pong、chat、ack、error、call_signal */
private String type;
/** 消息唯一 ID,由客户端或 s-message 生成 */
private String messageId;
/** 会话 ID,单聊、群聊、客服会话都可以使用 */
private String conversationId;
/** 发送方类型,例如 user、device、system、ai */
private String senderType;
/** 发送方 ID */
private String senderId;
/** 接收方类型,例如 user、device、room */
private String receiverType;
/** 接收方 ID */
private String receiverId;
/** 内容类型,例如 text、image、file、audio、video */
private String contentType;
/** 业务内容。第一阶段先用字符串,复杂结构可以放 ext */
private String content;
/** 客户端或服务端时间戳,毫秒 */
private Long timestamp;
/** 链路追踪 ID,便于排查一次消息流转 */
private String traceId;
/** 扩展字段,承载临时或业务特有参数 */
private Map<String, Object> ext = new HashMap<>();
}
示例消息:
json
{
"type": "chat",
"messageId": "msg-10001",
"conversationId": "c2c-1001-1002",
"senderType": "user",
"senderId": "1001",
"receiverType": "user",
"receiverId": "1002",
"contentType": "text",
"content": "你好,这是一条文本消息",
"timestamp": 1784131200000,
"traceId": "trace-abc"
}
ImPacketCodec 负责 JSON 编解码和通用响应构造:
java
@Component
@RequiredArgsConstructor
public class ImPacketCodec {
private final ObjectMapper objectMapper;
public ImPacket decode(String json) {
try {
return objectMapper.readValue(json, ImPacket.class);
} catch (JsonProcessingException e) {
throw new IllegalArgumentException("invalid packet json", e);
}
}
public String ack(ImPacket source) {
ImPacket packet = new ImPacket();
packet.setType(ImPacketType.ACK);
packet.setMessageId(source.getMessageId());
packet.setTraceId(source.getTraceId());
packet.setTimestamp(System.currentTimeMillis());
Map<String, Object> ext = new HashMap<>();
ext.put("status", "received");
packet.setExt(ext);
return encode(packet);
}
}
把编解码独立出来的好处是:Netty handler 不需要关心 JSON 细节,以后如果协议字段调整,也集中在 codec 和 packet 上改。
3.9 心跳设计:连接心跳和实例心跳不是一回事
连接心跳
IdleStateHandler 负责产生空闲事件,ImIdleStateHandler 负责处理事件:
java
public class ImIdleStateHandler extends ChannelInboundHandlerAdapter {
@Override
public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
if (evt instanceof IdleStateEvent idleStateEvent) {
String connId = ctx.channel().attr(ImChannelAttributes.CONN_ID).get();
if (idleStateEvent.state() == IdleState.WRITER_IDLE) {
// 服务端长时间没写数据,主动发 WebSocket ping 保活
ctx.writeAndFlush(new PingWebSocketFrame(
Unpooled.copiedBuffer(String.valueOf(System.currentTimeMillis()), StandardCharsets.UTF_8)));
return;
}
if (idleStateEvent.state() == IdleState.READER_IDLE) {
// 客户端长时间没有任何数据返回,关闭连接
ctx.writeAndFlush(new CloseWebSocketFrame(1000, "reader idle"))
.addListener(ChannelFutureListener.CLOSE);
return;
}
return;
}
super.userEventTriggered(ctx, evt);
}
}
配置上是:
idle-writer-seconds: 30:服务端 30 秒没写,发 ping。idle-reader-seconds: 90:服务端 90 秒没读到客户端任何数据,关闭连接。
这个配置意味着客户端最好能正常响应 WebSocket pong,或者主动发业务 ping。
实例心跳
ServerHeartbeatReporter 定时把当前 IM 实例信息写入 Redis:
java
@Scheduled(fixedDelayString = "#{${im.route.heartbeat-seconds:10} * 1000L}")
public void report() {
String key = RouteKeyBuilder.serverKey(properties.getServerId());
Map<String, String> value = new HashMap<>();
value.put("serverId", properties.getServerId());
value.put("host", resolveHost());
value.put("httpPort", String.valueOf(httpPort));
value.put("wsPort", String.valueOf(properties.getWebsocket().getPort()));
value.put("weight", "100");
value.put("connCount", String.valueOf(sessionManager.count()));
value.put("lastHeartbeat", LocalDateTime.now().toString());
redisTemplate.opsForHash().putAll(key, value);
redisTemplate.expire(key, Duration.ofSeconds(properties.getRoute().getRouteTtlSeconds()));
}
Redis key 类似:
text
im:server:s-im-server-18110
这个 key 告诉其他服务:当前有一台 IM 实例活着,它的 HTTP 端口、WebSocket 端口、连接数是多少。
心跳时序图
连接心跳解决“这个客户端还活着吗”;实例心跳解决“这台 IM 服务还活着吗”。两个问题不同,所以代码也分开。
3.10 连接断开与资源清理
当连接断开时:
java
@Override
public void channelInactive(ChannelHandlerContext ctx) throws Exception {
String connId = ctx.channel().attr(ImChannelAttributes.CONN_ID).get();
if (StringUtils.hasText(connId)) {
sessionManager.remove(connId).ifPresent(routeRegistry::unregister);
}
super.channelInactive(ctx);
}
这一步会做两件事:
- 从本机内存索引里删除连接。
- 从 Redis 在线路由里删除 user/device/room 相关 key。
如果进程异常宕机,没有机会执行 unregister,也没关系,因为 Redis 路由有 TTL,会自动过期。这就是 TTL 设计的价值。
四、会话、在线路由和下行投递
4.1 本机会话管理:ConnSessionManager
ConnSessionManager 维护当前 IM 实例内存中的连接索引:
java
@Component
@RequiredArgsConstructor
public class ConnSessionManager {
/** connId -> ConnSession */
private final ConcurrentHashMap<String, ConnSession> connIndex = new ConcurrentHashMap<>();
/** userId -> connId 集合,一个用户可多端在线 */
private final ConcurrentHashMap<Long, Set<String>> userIndex = new ConcurrentHashMap<>();
/** deviceId -> connId,第一阶段假设一个设备一条活跃连接 */
private final ConcurrentHashMap<String, String> deviceIndex = new ConcurrentHashMap<>();
/** roomId -> 本机 connId 集合 */
private final ConcurrentHashMap<String, Set<String>> roomIndex = new ConcurrentHashMap<>();
}
为什么要建这么多索引?
- 按
connId查:内部服务指定连接投递。 - 按
userId查:给某个用户的所有端发消息。 - 按
deviceId查:给某台设备发指令。 - 按
roomId查:后续房间、群聊、直播间广播可以用。
创建会话时会同时写入这些索引:
java
public ConnSession create(Channel channel, HandshakePrincipal principal) {
LocalDateTime now = LocalDateTime.now();
ConnSession session = ConnSession.builder()
.connId(principal.getConnId())
.channelId(channel.id().asShortText())
.userId(principal.getUserId())
.deviceId(principal.getDeviceId())
.roomId(principal.getRoomId())
.clientType(principal.getClientType())
.serverId(properties.getServerId())
.remoteAddress(String.valueOf(channel.remoteAddress()))
.connectedAt(now)
.lastActiveAt(now)
.channel(channel)
.build();
connIndex.put(session.getConnId(), session);
if (session.getUserId() != null) {
userIndex.computeIfAbsent(session.getUserId(), key -> ConcurrentHashMap.newKeySet())
.add(session.getConnId());
}
if (StringUtils.hasText(session.getDeviceId())) {
deviceIndex.put(session.getDeviceId(), session.getConnId());
}
if (StringUtils.hasText(session.getRoomId())) {
roomIndex.computeIfAbsent(session.getRoomId(), key -> ConcurrentHashMap.newKeySet())
.add(session.getConnId());
}
return session;
}
注意:这里的数据只代表“当前进程”的连接,不代表全局在线状态。所以还需要 Redis 在线路由。
4.2 Redis 在线路由:OnlineRouteRegistry
OnlineRouteRegistry 把当前实例上的连接写入 Redis:
java
public void register(ConnSession session) {
if (session.getUserId() != null) {
registerUserOnline(session);
}
if (StringUtils.hasText(session.getDeviceId())) {
registerDeviceOnline(session);
}
if (StringUtils.hasText(session.getRoomId())) {
redisTemplate.opsForSet().add(RouteKeyBuilder.roomServersKey(session.getRoomId()), session.getServerId());
redisTemplate.expire(RouteKeyBuilder.roomServersKey(session.getRoomId()), ttl());
}
}
public void refreshRoute(ConnSession session) {
session.touch();
register(session);
}
Redis key 由 RouteKeyBuilder 统一生成:
java
public final class RouteKeyBuilder {
public static String serverKey(String serverId) {
return "im:server:" + serverId;
}
public static String userOnlineKey(Long userId) {
return "im:online:user:" + userId;
}
public static String deviceOnlineKey(String deviceId) {
return "im:online:device:" + deviceId;
}
public static String roomServersKey(String roomId) {
return "im:room:" + roomId + ":servers";
}
}
路由内容是 OnlineRoute:
java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class OnlineRoute {
private String serverId;
private String connId;
private Long userId;
private String deviceId;
private String clientType;
private String transport;
private LocalDateTime loginAt;
private LocalDateTime lastActiveAt;
private LocalDateTime expireAt;
}
示例 Redis 值可以理解成这样:
json
{
"serverId": "s-im-server-18110",
"connId": "2f97bc7d2fe9407a8a66f2d350fd9b6c",
"userId": 1001,
"deviceId": "iphone-001",
"clientType": "web",
"transport": "websocket",
"loginAt": "2026-07-15T22:10:00",
"lastActiveAt": "2026-07-15T22:10:30",
"expireAt": "2026-07-15T22:11:15"
}
为什么 Redis 路由要有 TTL?
- 正常断开时,
channelInactive会删除路由。 - 异常宕机时,删除逻辑执行不到。
- TTL 可以兜底清理脏在线状态。
- 客户端活跃时会刷新 TTL,所以活连接不会误过期。
4.3 下行投递:LocalDeliveryService
LocalDeliveryService 只负责投递到“当前 IM 实例”的本机连接:
java
@Service
@RequiredArgsConstructor
public class LocalDeliveryService {
private final ConnSessionManager sessionManager;
private final ImPacketCodec packetCodec;
public DeliveryResult deliver(DownlinkMessage message) {
if (message == null || message.getPacket() == null) {
return DeliveryResult.nonRetryable("packet is required");
}
String payload = packetCodec.encode(message.getPacket());
// connId 优先,适合精确投递到某条连接
if (StringUtils.hasText(message.getConnId())) {
boolean ok = sessionManager.sendText(message.getConnId(), payload);
return ok ? DeliveryResult.success(1) : DeliveryResult.nonRetryable("connection not found");
}
// 按连接投递
if ("conn".equals(message.getTargetType())) {
boolean ok = sessionManager.sendText(message.getTargetId(), payload);
return ok ? DeliveryResult.success(1) : DeliveryResult.nonRetryable("connection not found");
}
// 按用户投递,给这个用户在本机的所有连接发
if ("user".equals(message.getTargetType())) {
Long userId = parseLong(message.getTargetId());
if (userId == null) {
return DeliveryResult.nonRetryable("invalid user targetId");
}
List<ConnSession> sessions = sessionManager.getByUserId(userId);
int count = 0;
for (ConnSession session : sessions) {
if (sessionManager.sendText(session.getConnId(), payload)) {
count++;
}
}
return count > 0 ? DeliveryResult.success(count) : DeliveryResult.nonRetryable("user offline on this server");
}
// 按设备投递
if ("device".equals(message.getTargetType())) {
return sessionManager.getByDeviceId(message.getTargetId())
.map(session -> sessionManager.sendText(session.getConnId(), payload)
? DeliveryResult.success(1)
: DeliveryResult.nonRetryable("device connection inactive"))
.orElseGet(() -> DeliveryResult.nonRetryable("device offline on this server"));
}
return DeliveryResult.nonRetryable("unsupported targetType");
}
}
这里的边界也很清楚:
- 它不查 Redis 全局路由。
- 它不做消息落库。
- 它不判断业务权限。
- 它只把消息写到本机 Netty Channel。
全局投递应该由消息业务服务来做。本文案例里把这个服务叫 s-message,你也可以把它替换成自己项目中的 message-service、chat-service 或 notification-service:
4.4 内部投递接口和管理接口
内部接口:
java
@RestController
@RequestMapping("/internal")
@RequiredArgsConstructor
public class ImInternalController {
private final LocalDeliveryService localDeliveryService;
@PostMapping("/deliver")
public DeliveryResult deliver(@RequestBody DownlinkMessage message) {
return localDeliveryService.deliver(message);
}
}
因为 Spring Boot 配置了:
yaml
server:
servlet:
context-path: "/im"
所以完整路径是:
text
POST /im/internal/deliver
管理接口:
java
@RestController
@RequestMapping("/admin")
@RequiredArgsConstructor
public class ImAdminController {
@GetMapping("/stats")
public Map<String, Object> stats() {
Map<String, Object> data = new LinkedHashMap<>();
data.put("serverId", properties.getServerId());
data.put("connCount", sessionManager.count());
data.put("userConnCount", sessionManager.userCount());
data.put("deviceConnCount", sessionManager.deviceCount());
data.put("time", LocalDateTime.now().toString());
return data;
}
@PostMapping("/deliver")
public DeliveryResult deliver(@RequestBody DownlinkMessage message) {
return localDeliveryService.deliver(message);
}
@PostMapping("/kick")
public Map<String, Object> kick(@RequestBody KickRequest request) {
boolean success = sessionManager.close(request.getConnId(), request.getReason());
Map<String, Object> data = new LinkedHashMap<>();
data.put("success", success);
data.put("connId", request.getConnId());
return data;
}
}
上线前需要注意:/admin/deliver、/admin/kick、/internal/deliver 这类接口不能裸露给公网,至少要做服务间鉴权、网关限制或内网访问控制。
五、s-gateway 路由转发:普通 HTTP 和 IM WebSocket 的差异
5.1 网关基础配置
s-gateway 服务端口:
yaml
server:
port: 18080
servlet:
context-path: "/api"
spring:
application:
name: s-gateway
也就是说外部访问统一从:
text
http://localhost:18080/api
进入。
Gateway 使用的是 WebFlux 版本:
xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
5.2 普通 HTTP 微服务路由
典型路由长这样:
java
.route("s-auth", r -> r.path("/api/auth/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/auth/(?<segment>.*)", "/auth/${segment}"))
.uri("lb://s-auth"))
含义:
- 外部请求
/api/auth/captcha。 - 网关匹配
/api/auth/**。 - 通过
rewritePath改写为/auth/captcha。 - 通过
lb://s-auth从注册中心找s-auth实例。 - 转发到目标服务。
其他服务类似:
java
.route("s-blog", r -> r.path("/api/blog/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/blog/(?<segment>.*)", "/blog/${segment}"))
.uri("lb://s-blog"))
.route("s-ai", r -> r.path("/api/ai/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/ai/(?<segment>.*)", "/ai/${segment}"))
.uri("lb://s-ai"))
.route("s-tool", r -> r.path("/api/tool/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/tool/(?<segment>.*)", "/tool/${segment}"))
.uri("lb://s-tool"))
5.3 IM WebSocket 路由
IM WebSocket 路由比较特殊:
java
@Value("${gateway.routes.im.ws-uri:ws://127.0.0.1:18111}")
private String imWebSocketUri;
测试路径:
java
.route("s-im-server-ws-test-api", r -> r.path("/api/im/ws-test", "/api/im/ws-test/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/im/ws-test(?<segment>/?.*)", "/im/ws-test${segment}"))
.uri(imWebSocketUri))
正式路径:
java
.route("s-im-server-ws-api", r -> r.path("/api/im/ws", "/api/im/ws/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/im/ws(?<segment>/?.*)", "/im/ws${segment}"))
.uri(imWebSocketUri))
HTTP 管理/内部接口:
java
.route("s-im-server-http", r -> r.path("/api/im/**")
.filters(f -> f.stripPrefix(0)
.rewritePath("/api/im/(?<segment>.*)", "/im/${segment}"))
.uri("lb://s-im-server"))
这三段的顺序很重要:WebSocket 的 /api/im/ws、/api/im/ws-test 要放在 /api/im/** 前面。否则更宽泛的 HTTP 路由可能先匹配到 /api/im/**,导致 WebSocket 请求走到 lb://s-im-server 的 HTTP 管理端口 18110,而不是 Netty 端口 18111。
5.4 为什么 WebSocket 暂时不用 lb://s-im-server
s-im-server 注册到 Nacos 的是 Spring Boot 应用,也就是 HTTP 端口 18110。但真正的 WebSocket 监听端口是 Netty 自己开的 18111。
如果直接这么写:
java
.uri("lb://s-im-server")
网关会把 WebSocket 请求转到 Nacos 里注册的服务端口,通常就是 18110。这不是 Netty 长连接端口,所以会连不上或行为不符合预期。
因此当前阶段先用:
java
ws://127.0.0.1:18111
后续更完整的做法可以有几个方向:
- 在 Nacos metadata 里注册
wsPort=18111,网关自定义路由选择器读取 metadata。 - 单独注册一个
s-im-ws服务名,端口就是 WebSocket 端口。 - 用 Nginx/OpenResty 在更外层做 WebSocket upstream。
- 如果部署到 K8s,用 Service 暴露多个 port,并为 WebSocket 单独配置路由。
5.5 Gateway 全局认证过滤器
GlobalAuthFilter 做了白名单、请求头校验和 IM WebSocket 放行:
java
private static final List<String> WHITE_LIST = Arrays.asList(
"/admin",
"/auth",
"/blog",
"/wallpaper",
"/ai",
"/pet",
"/actuator",
"/code-helper",
"/third",
"/tool",
"/im");
过滤逻辑:
java
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
String path = request.getURI().getPath();
if (!isWhiteList(path)) {
return badGateway(exchange.getResponse());
}
// WebSocket 握手不方便携带统一业务请求头,IM 连接先交给 s-im-server 用 token 单独校验
if (isImWebSocketRequest(request, path)) {
return chain.filter(exchange);
}
String version = getFirstValue(request, Constants.VERSION, Constants.VERSION);
String business = getFirstValue(request, Constants.BUSINESS, Constants.BUSINESS, "businessType");
boolean sseRequest = isSseRequest(request);
if ((!sseRequest && version == null) || business == null) {
ServerHttpResponse response = exchange.getResponse();
response.setStatusCode(HttpStatus.FORBIDDEN);
return response.setComplete();
}
if (version != null && !Constants.CURRENT_API_VERSION.equals(version)) {
ServerHttpResponse response = exchange.getResponse();
response.setStatusCode(HttpStatus.FORBIDDEN);
return response.setComplete();
}
if (!BusinessTypeEnum.exists(business)) {
ServerHttpResponse response = exchange.getResponse();
response.setStatusCode(HttpStatus.FORBIDDEN);
return response.setComplete();
}
return chain.filter(exchange);
}
IM WebSocket 特判:
java
private boolean isImWebSocketRequest(ServerHttpRequest request, String path) {
String upgrade = request.getHeaders().getUpgrade();
return isImWebSocketPath(path) && "websocket".equalsIgnoreCase(upgrade);
}
注意事项:
- WebSocket 握手由
Upgrade: websocket标识。 - WebSocket 客户端不一定方便带统一的
version、business请求头,所以网关放行,交给 IM 握手 token 校验。 - IM 的 HTTP 接口仍会走普通过滤逻辑。
- 当前
WHITE_LIST包含/im,如果上线后要加强控制,需要进一步区分公开 WebSocket 路径、内部路径、管理路径。
5.6 TraceId 过滤器
TraceIdGlobalFilter 会保证每个请求都有链路 ID:
java
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
String traceId = exchange.getRequest().getHeaders().getFirst(Constants.TRACE_ID_HEADER);
if (StrUtil.isBlank(traceId)) {
traceId = IdUtil.fastUUID();
}
ServerHttpRequest request = exchange.getRequest().mutate()
.header(Constants.TRACE_ID_HEADER, traceId)
.build();
MDC.put(Constants.TRACE_ID_MDC_KEY, traceId);
return chain.filter(exchange.mutate().request(request).build())
.doFinally(signalType -> MDC.remove(Constants.TRACE_ID_MDC_KEY));
}
这个对排查很有用:前端、网关、下游服务日志都能通过同一个 traceId 串起来。
5.7 日志过滤器
LoggingGlobalFilter 只在 dev、local、test 环境启用:
java
@Slf4j
@Component
@Profile({"dev", "local", "test"})
public class LoggingGlobalFilter implements GlobalFilter, Ordered {
private static final int MAX_LOG_BYTES = 4096;
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
log.info("[GW-REQ] {} {} query={} headers={}",
request.getMethod(), request.getURI(), request.getQueryParams(), sanitizeHeaders(request.getHeaders()));
// 包装响应,打印 JSON / 文本响应片段
// Authorization 会脱敏成 Bearer ***
return chain.filter(exchange.mutate().response(decoratedResponse).build());
}
}
注意它会打印请求和响应片段,所以只适合开发、测试环境。生产环境如果需要日志,也要考虑敏感字段脱敏、响应体大小、性能影响。
5.8 跨域和 JSON 字符集
跨域配置:
java
@Bean
public CorsWebFilter corsWebFilter() {
CorsConfiguration config = new CorsConfiguration();
config.addAllowedOriginPattern("*");
config.addAllowedHeader("*");
config.addAllowedMethod("*");
config.setAllowCredentials(true);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", config);
return new CorsWebFilter(source);
}
JSON 字符集补充:
java
@Bean
public GlobalFilter appendJsonCharsetFilter() {
return (exchange, chain) -> chain.filter(exchange).then(Mono.fromRunnable(() -> {
var headers = exchange.getResponse().getHeaders();
MediaType ct = headers.getContentType();
if (ct != null
&& "application".equals(ct.getType())
&& "json".equals(ct.getSubtype())
&& ct.getCharset() == null) {
headers.setContentType(new MediaType("application", "json", StandardCharsets.UTF_8));
}
}));
}
这个小配置能减少中文响应乱码、客户端解析不一致等问题。
5.9 网关转发完整流程图
5.10 IM WebSocket 握手时序图
六、注意事项和后续优化方向
6.1 路由顺序要注意
/api/im/ws 和 /api/im/ws-test 必须放在 /api/im/** 前面。
原因:
/api/im/**太宽泛。- WebSocket 需要转发到
18111。 - HTTP 管理接口需要转发到
lb://s-im-server,也就是18110。
顺序错了,就可能把 WebSocket 请求转到 HTTP 端口。
6.2 WebSocket 的鉴权要尽快补强
当前 HandshakeAuthHandler 只做 token 非空校验,方便本地联调。正式环境建议:
- 解析 JWT,校验签名和过期时间。
- 或调用
s-auth内部接口校验 token。 - 校验 userId 是否和 token 里的用户一致。
- 校验 deviceId 是否属于当前用户或可信设备。
- 对
/im/ws-test做环境隔离,生产环境关闭或加权限。
6.3 内部接口不能裸露
这些接口风险较高:
text
POST /im/internal/deliver
POST /im/admin/deliver
POST /im/admin/kick
建议:
- 只允许内网访问。
- 网关层禁止公网访问
/api/im/internal/**和/api/im/admin/**。 - 增加服务间签名,例如
X-Internal-Sign。 - 管理接口接入后台权限体系。
6.4 Redis 在线路由要考虑多端策略
当前 userOnlineKey(userId) 是一个 value,意味着一个用户的全局在线路由可能被后一次连接覆盖。虽然本机 userIndex 支持多连接,但 Redis 的用户路由如果要支持全局多端,需要继续优化。
可选方案:
im:online:user:{userId}改成 hash,field 是connId。- 或者使用 set 保存 connId,再用
im:conn:{connId}保存详情。 - 按客户端类型拆 key,例如
im:online:user:{userId}:web、im:online:user:{userId}:app。
6.5 上行业务消息还没有真正接 MQ
代码里已有 ImEventProducer:
java
public void publishUpstream(ImPacket packet) {
DispatchMessage message = DispatchMessage.builder()
.messageId(defaultMessageId(packet))
.consumerKey(CONSUMER_KEY_IM_UPSTREAM)
.bizKey(defaultBizKey(packet))
.consumerType("http")
.method("POST")
.traceId(packet.getTraceId())
.payload(objectMapper.valueToTree(packet))
.build();
rabbitTemplate.convertAndSend(DISPATCH_EXCHANGE, DISPATCH_ROUTING_KEY, message);
}
但当前 ImWebSocketFrameHandler 收到 chat 等业务消息后只是 ack 和打日志,还没有调用 publishUpstream。后续可以在业务消息分支里接上 MQ:
java
if (ImPacketType.CHAT.equals(packet.getType())
|| ImPacketType.CALL_SIGNAL.equals(packet.getType())
|| ImPacketType.DEVICE_EVENT.equals(packet.getType())
|| ImPacketType.VOICE_EVENT.equals(packet.getType())) {
imEventProducer.publishUpstream(packet);
ctx.writeAndFlush(new TextWebSocketFrame(packetCodec.ack(packet)));
return;
}
不过接之前最好先考虑:
- Netty handler 是否直接依赖 MQ producer,还是通过业务 service 间接依赖。
- MQ 发送失败时 ack 策略是什么。
- 是否要先落本地缓冲或返回错误。
- 是否要保证 messageId 幂等。
6.6 不要在 Netty IO 线程里做重活
Netty worker 线程主要负责 IO。后续如果加入这些逻辑,要特别小心:
- 数据库查询。
- RPC 调用。
- 大 JSON 解析。
- 文件处理。
- 音频转码。
- AI 调用。
这些操作会阻塞 IO 线程,影响同一个 worker 上的其他连接。正确做法是把重活丢给业务线程池、MQ 或独立服务。
6.7 生产环境 WebSocket 还要考虑负载均衡
如果未来多实例部署:
- 长连接一般需要四层负载或支持 WebSocket 的七层代理。
- 如果走网关,需要网关能识别每个 IM 实例的 WS 端口。
- 如果客户端直连 IM,需要有一个获取连接地址的接口。
- 如果用户在多台 IM 实例上在线,下行服务必须按 Redis 路由找准目标实例。
七、从一次消息流转看完整链路
7.1 客户端连接
text
客户端
-> s-gateway: /api/im/ws?token=xxx&userId=1001
-> s-im-server Netty: /im/ws
-> HandshakeAuthHandler: 校验 token 非空
-> ImWebSocketFrameHandler: 创建 session
-> Redis: 写在线路由
7.2 客户端发消息
text
客户端
-> s-im-server: TextWebSocketFrame(JSON)
-> ImPacketCodec: decode
-> ImWebSocketFrameHandler: 判断 type
-> 当前版本: 返回 ack
-> 完整版本: publish MQ 给消息业务服务
7.3 服务端下发消息
text
消息业务服务
-> Redis: 查询用户或设备在哪台 IM 实例
-> s-im-server: POST /im/internal/deliver
-> LocalDeliveryService: 找本机连接
-> ConnSessionManager: writeAndFlush TextWebSocketFrame
-> 客户端
7.4 完整时序图
八、如果你要把这套设计用到自己的项目
如果你不是这个项目的维护者,只是想借鉴这套设计,可以按下面的思路迁移。
第一步,先明确服务边界。长连接服务只负责连接、心跳、在线状态和本机投递,不要一开始就把消息落库、离线消息、会话列表、已读未读都塞进去。
第二步,确定入口方式。如果你的项目有统一网关,就让客户端从网关进入;如果没有网关,也可以让客户端先调用一个 HTTP 接口获取可连接的 WebSocket 地址,再直连 IM 节点。
第三步,设计在线路由。最简单可以用 Redis 保存:
text
im:server:{serverId} -> 当前 IM 实例心跳
im:online:user:{userId} -> 用户当前所在 IM 节点和 connId
im:online:device:{deviceId} -> 设备当前所在 IM 节点和 connId
im:room:{roomId}:servers -> 房间分布在哪些 IM 节点
第四步,设计下行投递。消息业务服务先查 Redis 在线路由,再调用目标 IM 实例的内部接口,由目标 IM 实例写自己的本机连接。
第五步,再补消息可靠性。等连接层稳定后,再逐步补 MQ、消息落库、幂等、离线消息、重试、死信和监控告警。
这也是本文案例的核心思路:先把“用户连得上、服务找得到、消息发得下去”这条链路跑通,再往上叠复杂业务。
九、总结
s-im-server 当前的架构核心是四个字:连接接入。
它用 Spring Boot 管理配置、注册中心、HTTP 内部接口和生命周期,用 Netty 承载 WebSocket 长连接,用本机内存索引保证连接写入足够快,用 Redis 保存全局在线路由和实例心跳,用 Gateway 统一入口转发外部请求。
这套设计最值得学习的地方不在于“用了 Netty”,而在于边界划得比较清楚:
ImNettyServer只负责启动和停止。ImChannelInitializer只负责组装 pipeline。HandshakeAuthHandler只负责握手校验和身份解析。ImWebSocketFrameHandler只负责 WebSocket 帧处理和 session 生命周期。ConnSessionManager只负责本机连接索引。OnlineRouteRegistry只负责 Redis 在线路由。LocalDeliveryService只负责本机下行投递。s-gateway只负责入口路由、统一过滤和 WebSocket 转发。
从后续演进看,下一步最重要的是三件事:
- 把 WebSocket token 鉴权补完整,和
s-auth或 JWT 打通。 - 把上行业务消息真正接入
ImEventProducer和后续s-message。 - 优化 Redis 在线路由结构,支持真正的全局多端在线和多实例投递。
等这些补上后,s-im-server 就能从“长连接骨架”进一步变成一个稳定、可扩展的实时通信接入层。