从 0 到 1 拆解一个 Netty IM 长连接服务:网关路由、在线路由与消息投递设计

2026-07-16后端24 分钟140 次阅读
AI 摘要salmon-ai

本文详细解析了一个基于 Netty、WebSocket、Spring Cloud

前言

很多项目一开始做“实时消息”时,最容易把问题想简单:前端连一个 WebSocket,后端收到消息再转发出去,好像就完成了一个 IM 服务。

但真正落到微服务架构里,问题会立刻变多:

  1. 客户端长连接应该接到哪里?
  2. 网关怎么转发 WebSocket?
  3. 一个用户在多端在线时,服务端怎么找到他的连接?
  4. 多台 IM 服务实例部署后,消息服务怎么知道目标用户在哪台机器上?
  5. 心跳、断线、重连、踢下线、下行投递应该由谁负责?
  6. 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 主要负责这些事情:

  1. 接收客户端 WebSocket 长连接。
  2. 在握手阶段解析 token、userId、deviceId、clientType、roomId 等参数。
  3. 建立当前进程内的连接会话索引。
  4. 把用户、设备、房间、IM 实例信息注册到 Redis。
  5. 维护连接心跳,及时清理异常连接。
  6. 给内部服务提供本机下行投递接口。
  7. 给管理端提供连接统计、模拟投递、踢连接等调试能力。

它暂时不负责:

  1. 不负责聊天消息持久化。
  2. 不负责离线消息。
  3. 不负责复杂重试和死信。
  4. 不负责消息业务编排。
  5. 不在 IM 服务里写 MQ consumer。

这些能力更适合放到独立的消息服务里。本文为了方便表达,把这个规划中的消息业务服务叫做 s-message。读者可以把它理解成任意一个负责“消息落库、离线、重试、分发”的后台服务。

1.3 本文案例的系统架构图

flowchart TB Client["客户端<br/>Web / App / 小程序 / 设备"] --> Gateway["s-gateway<br/>统一入口"] Gateway -->|HTTP API<br/>lb://服务名| Auth["s-auth"] Gateway -->|HTTP API<br/>lb://服务名| Blog["s-blog"] Gateway -->|HTTP API<br/>lb://服务名| Ai["s-ai"] Gateway -->|HTTP API<br/>lb://服务名| Pet["s-pet"] Gateway -->|WebSocket<br/>ws://127.0.0.1:18111| Im["s-im-server<br/>Netty WebSocket"] Im --> LocalSession["本机连接索引<br/>conn / user / device / room"] Im --> Redis["Redis<br/>在线路由与实例心跳"] Im --> RabbitMQ["RabbitMQ<br/>上行业务事件预留"] Message["s-message<br/>消息业务服务<br/>可独立演进"] -->|读取在线路由| Redis Message -->|HTTP 内部投递<br/>/im/internal/deliver| Im Message --> DB["MySQL<br/>消息落库 / 离线消息"]

这张图里有两个关键点:

  • 网关转普通 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。

这样拆的好处:

  1. 长连接 IO 不和普通 HTTP 请求混在一起。
  2. WebSocket pipeline 可以完全按 Netty 的方式定制。
  3. Spring Boot 仍然负责配置、依赖注入、Actuator、内部 HTTP 接口。
  4. 后续 WebSocket 端口可以单独扩容、单独挂负载策略。
  5. 网关可以明确区分 HTTP 管理接口和 WebSocket 长连接入口。

2.2 为什么 IM 服务只做连接层,不做完整消息业务

IM 系统里最容易膨胀的是“消息业务”。如果把连接、鉴权、路由、投递、落库、离线、撤回、已读、漫游、搜索、通知全部写进一个服务,早期看起来快,后期会非常难维护。

当前设计把 s-im-server 定位为连接接入层:

flowchart LR U["客户端"] --> IM["s-im-server<br/>连接接入层"] IM -->|上行业务消息| MQ["RabbitMQ / Dispatch"] MQ --> MSG["s-message<br/>消息业务层"] MSG --> DB["MySQL / Redis"] MSG -->|下行投递| IM IM --> U

这样的考虑主要有几个:

  1. 连接层要轻:长连接服务最怕业务逻辑阻塞 IO 线程。
  2. 消息层要稳:消息落库、重试、死信、幂等更适合独立服务维护。
  3. 扩容模型不同:连接层按连接数扩容,消息层按消息吞吐扩容。
  4. 故障影响更小:消息服务短暂异常时,连接层仍可维持连接和基础心跳。
  5. 后续跨语言方便:代码里已经提到 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 流程图

flowchart TD A["SocketChannel 建立"] --> B["HttpServerCodec<br/>HTTP 编解码"] B --> C["HttpObjectAggregator<br/>聚合 FullHttpRequest"] C --> D["IdleStateHandler<br/>产生读写空闲事件"] D --> E["HandshakeAuthHandler<br/>路径校验 + token 非空校验 + 写 Channel 属性"] E --> F["WebSocketServerProtocolHandler<br/>HTTP 升级 WebSocket"] F --> G["ImIdleStateHandler<br/>写空闲 ping / 读空闲关闭"] G --> H["ImWebSocketFrameHandler<br/>文本帧 / ping / pong / close / session"] H --> I["ChannelExceptionHandler<br/>统一异常关闭"]

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());
    }
}

这里几个细节值得注意:

  1. WebSocketServerProtocolHandler 的 websocketPath("/") 配合 checkStartsWith(true),是因为前面的 HandshakeAuthHandler 已经严格限制只允许 /im/ws 和 /im/ws-test。这样可以避免测试路径在协议 handler 的路径匹配处卡住。
  2. allowExtensions(false) 是为了第一阶段不启用 permessage-deflate 等 WebSocket 扩展。浏览器可能默认请求压缩扩展,如果服务端没有配套压缩解码 handler,后续文本帧可能出问题。
  3. 自定义 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");
}

这么做的原因是:

  1. 握手 handler 解析出来的信息,后面的 handler 也要用。
  2. Netty 的 Channel 生命周期和连接一致,把连接属性挂在 Channel 上很自然。
  3. 不需要靠 ThreadLocal,因为 Netty 事件可能由不同 event loop 调度。
  4. 握手完成后,可以从 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 端口、连接数是多少。

心跳时序图

sequenceDiagram participant C as 客户端 participant IM as s-im-server Netty participant Redis as Redis loop 连接级心跳 IM->>C: WebSocket Ping C-->>IM: WebSocket Pong IM->>Redis: 刷新用户/设备在线路由 TTL end loop 实例级心跳 IM->>Redis: 写 im:server:{serverId} Redis-->>IM: 设置 TTL end

连接心跳解决“这个客户端还活着吗”;实例心跳解决“这台 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);
}

这一步会做两件事:

  1. 从本机内存索引里删除连接。
  2. 从 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?

  1. 正常断开时,channelInactive 会删除路由。
  2. 异常宕机时,删除逻辑执行不到。
  3. TTL 可以兜底清理脏在线状态。
  4. 客户端活跃时会刷新 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:

sequenceDiagram participant MSG as s-message participant Redis as Redis participant IM as 目标 s-im-server participant C as 客户端 MSG->>Redis: 查询 im:online:user:{userId} Redis-->>MSG: 返回 serverId / connId / httpPort MSG->>IM: POST /im/internal/deliver IM->>IM: ConnSessionManager 查本机连接 IM->>C: WebSocket TextFrame IM-->>MSG: DeliveryResult

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"))

含义:

  1. 外部请求 /api/auth/captcha。
  2. 网关匹配 /api/auth/**。
  3. 通过 rewritePath 改写为 /auth/captcha。
  4. 通过 lb://s-auth 从注册中心找 s-auth 实例。
  5. 转发到目标服务。

其他服务类似:

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

后续更完整的做法可以有几个方向:

  1. 在 Nacos metadata 里注册 wsPort=18111,网关自定义路由选择器读取 metadata。
  2. 单独注册一个 s-im-ws 服务名,端口就是 WebSocket 端口。
  3. 用 Nginx/OpenResty 在更外层做 WebSocket upstream。
  4. 如果部署到 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);
}

注意事项:

  1. WebSocket 握手由 Upgrade: websocket 标识。
  2. WebSocket 客户端不一定方便带统一的 version、business 请求头,所以网关放行,交给 IM 握手 token 校验。
  3. IM 的 HTTP 接口仍会走普通过滤逻辑。
  4. 当前 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 网关转发完整流程图

flowchart TD A["客户端请求<br/>/api/xxx"] --> B["s-gateway"] B --> C["TraceIdGlobalFilter<br/>生成或透传 Trace-Id"] C --> D["GlobalAuthFilter<br/>白名单 / version / business"] D -->|普通 HTTP| E["RouteLocator<br/>匹配 /api/auth /api/blog 等"] E --> F["rewritePath<br/>/api/blog/a -> /blog/a"] F --> G["lb://服务名<br/>Nacos 负载均衡"] G --> H["目标 HTTP 微服务"] D -->|IM WebSocket| I["匹配 /api/im/ws"] I --> J["rewritePath<br/>/api/im/ws -> /im/ws"] J --> K["ws://127.0.0.1:18111"] K --> L["s-im-server Netty"]

5.10 IM WebSocket 握手时序图

sequenceDiagram participant C as 客户端 participant GW as s-gateway participant H as HandshakeAuthHandler participant W as WebSocketServerProtocolHandler participant F as ImWebSocketFrameHandler participant R as Redis C->>GW: GET /api/im/ws?token=xxx&userId=1001<br/>Upgrade: websocket GW->>GW: TraceId / AuthFilter<br/>识别 WebSocket 放行 GW->>H: 转发到 ws://127.0.0.1:18111/im/ws H->>H: 校验 path / token<br/>解析 userId、deviceId、clientType H->>W: fireChannelRead(request) W-->>C: 101 Switching Protocols W->>F: 触发 HANDSHAKE_COMPLETE F->>F: 创建 ConnSession F->>R: 写 im:online:user:{userId}<br/>设置 TTL F->>R: 写 im:online:device:{deviceId}<br/>设置 TTL

六、注意事项和后续优化方向

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 非空校验,方便本地联调。正式环境建议:

  1. 解析 JWT,校验签名和过期时间。
  2. 或调用 s-auth 内部接口校验 token。
  3. 校验 userId 是否和 token 里的用户一致。
  4. 校验 deviceId 是否属于当前用户或可信设备。
  5. 对 /im/ws-test 做环境隔离,生产环境关闭或加权限。

6.3 内部接口不能裸露

这些接口风险较高:

text 复制代码
POST /im/internal/deliver
POST /im/admin/deliver
POST /im/admin/kick

建议:

  1. 只允许内网访问。
  2. 网关层禁止公网访问 /api/im/internal/** 和 /api/im/admin/**。
  3. 增加服务间签名,例如 X-Internal-Sign。
  4. 管理接口接入后台权限体系。

6.4 Redis 在线路由要考虑多端策略

当前 userOnlineKey(userId) 是一个 value,意味着一个用户的全局在线路由可能被后一次连接覆盖。虽然本机 userIndex 支持多连接,但 Redis 的用户路由如果要支持全局多端,需要继续优化。

可选方案:

  1. im:online:user:{userId} 改成 hash,field 是 connId。
  2. 或者使用 set 保存 connId,再用 im:conn:{connId} 保存详情。
  3. 按客户端类型拆 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;
}

不过接之前最好先考虑:

  1. Netty handler 是否直接依赖 MQ producer,还是通过业务 service 间接依赖。
  2. MQ 发送失败时 ack 策略是什么。
  3. 是否要先落本地缓冲或返回错误。
  4. 是否要保证 messageId 幂等。

6.6 不要在 Netty IO 线程里做重活

Netty worker 线程主要负责 IO。后续如果加入这些逻辑,要特别小心:

  • 数据库查询。
  • RPC 调用。
  • 大 JSON 解析。
  • 文件处理。
  • 音频转码。
  • AI 调用。

这些操作会阻塞 IO 线程,影响同一个 worker 上的其他连接。正确做法是把重活丢给业务线程池、MQ 或独立服务。

6.7 生产环境 WebSocket 还要考虑负载均衡

如果未来多实例部署:

  1. 长连接一般需要四层负载或支持 WebSocket 的七层代理。
  2. 如果走网关,需要网关能识别每个 IM 实例的 WS 端口。
  3. 如果客户端直连 IM,需要有一个获取连接地址的接口。
  4. 如果用户在多台 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 完整时序图

sequenceDiagram participant C as 客户端 participant GW as s-gateway participant IM as s-im-server participant Redis as Redis participant MQ as RabbitMQ participant MSG as s-message C->>GW: WebSocket 握手 /api/im/ws GW->>IM: 转发 /im/ws 到 18111 IM->>IM: 握手鉴权 + 创建 ConnSession IM->>Redis: 注册在线路由 IM-->>C: 握手成功 C->>IM: chat 消息 IM-->>C: ack IM->>MQ: 后续版本投递 im.upstream MQ->>MSG: 消费上行业务消息 MSG->>MSG: 落库 / 生成下行消息 MSG->>Redis: 查询接收方在线路由 MSG->>IM: POST /im/internal/deliver IM->>C: WebSocket 下行消息

八、如果你要把这套设计用到自己的项目

如果你不是这个项目的维护者,只是想借鉴这套设计,可以按下面的思路迁移。

第一步,先明确服务边界。长连接服务只负责连接、心跳、在线状态和本机投递,不要一开始就把消息落库、离线消息、会话列表、已读未读都塞进去。

第二步,确定入口方式。如果你的项目有统一网关,就让客户端从网关进入;如果没有网关,也可以让客户端先调用一个 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”,而在于边界划得比较清楚:

  1. ImNettyServer 只负责启动和停止。
  2. ImChannelInitializer 只负责组装 pipeline。
  3. HandshakeAuthHandler 只负责握手校验和身份解析。
  4. ImWebSocketFrameHandler 只负责 WebSocket 帧处理和 session 生命周期。
  5. ConnSessionManager 只负责本机连接索引。
  6. OnlineRouteRegistry 只负责 Redis 在线路由。
  7. LocalDeliveryService 只负责本机下行投递。
  8. s-gateway 只负责入口路由、统一过滤和 WebSocket 转发。

从后续演进看,下一步最重要的是三件事:

  1. 把 WebSocket token 鉴权补完整,和 s-auth 或 JWT 打通。
  2. 把上行业务消息真正接入 ImEventProducer 和后续 s-message。
  3. 优化 Redis 在线路由结构,支持真正的全局多端在线和多实例投递。

等这些补上后,s-im-server 就能从“长连接骨架”进一步变成一个稳定、可扩展的实时通信接入层。

觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句