企业官网建设流程全解析

实时消息推送这块，我前前后后做过好几版方案，从最早的HTTP轮询到短连接轮询，最后稳定用的是Netty + WebSocket这套组合。最近给一个订单实时大屏项目做后端支撑，需要把订单状态变化、库存预警、运营配置热更新三类消息推给前端，连接规模单机上万，延迟要求秒级。折腾下来最大的感受是：网上讲Netty WebSocket的教程不少，但真正到调参和排障的时候，文档里根本没写那么细。这篇文章就是我这次项目的完整复盘，覆盖选型、Pipeline设计、粘包问题、心跳机制、推送链路和三个我实际踩过的坑，想用Netty搭WebSocket推送服务的，或者准备Netty面试被问到实时推送细节的，都可以当一份实测笔记来看。

1. 选型复盘：从轮询到长连接，Netty做WebSocket推送强在哪

1.1 三类业务消息的实时性诉求

这个项目里需要推送的消息分三类。

第一类是订单状态变化。用户在下单之后，前端要实时看到"已支付、已出库、已发货、已签收"的状态流转，这类消息特点是频率高、格式统一、对顺序敏感。第二类是库存预警。当某个SKU的库存低于阈值时，运营后台要弹窗提醒，这类消息量少但非常重要，不允许丢。第三类是运营配置热更新。运营改了首页Banner或满减策略后，所有在线客户端要在几秒内拿到最新配置，这类消息本质上是全量广播。

这三类消息单独看都不复杂，但它们同时存在，就对推送系统的路由能力提出了要求：既要能单播给某个用户，又要能广播给全部在线客户端，还要能按业务分组下发。实时性方面，业务方的要求是秒级到达，实际上用Netty做本地推送时延迟通常在几十毫秒以内，大量时间反而是花在业务处理和网络IO上。

1.2 候选方案的横向对比

我把当时认真考虑过的方案整理成了表格。

单独看表格可能不够直观，我说几个实际对比中的关键点。HTTP短轮询在连接数少、消息频率低的时候是最省事的方案，但一旦达到秒级轮询，网关的请求量会膨胀好几倍，后端接口也被无效请求打满。SSE适合单向下推的场景，但我们的订阅、取消订阅、上行指令都需要从客户端发到服务端，SSE做双向交互很别扭。Spring WebSocket如果项目本身就跑在Spring生态里，用起来确实快，但它的线程模型依赖Servlet容器，在高连接数下会出现线程数爆炸、上下文切换开销大的问题，而且协议层、心跳这些细节被框架藏着，出问题反而不好查。

1.3 为什么最终选了Netty

选Netty，核心原因是它的线程模型和内存模型对整个推送场景足够可控。

Netty的Reactor模型里，boss线程负责accept连接，worker线程负责读写事件，每个Channel会被绑定到固定的EventLoop线程。这意味着同一个Channel的所有读写操作都在同一个线程内执行，天然没有并发竞争，不需要额外加锁保护会话状态，这也是实时推送场景里最看重的一点。另外Netty自己实现了ByteBuf内存池和零拷贝，在高频读写下能显著减少GC压力。

还有一个很实际的原因：我们不止做WebSocket推送，之后还有可能对接自定义TCP协议、MQTT网关，Netty这套Pipeline模型可以复用。与其在Spring的封装里挣扎，不如直接在Netty这一层把基础设施做扎实。当然，选Netty要付出的代价也很明确：所有协议细节都要自己处理，技术团队必须对Pipeline、解码器、ByteBuf有足够的理解。如果团队完全没有Netty经验，我建议还是先在Spring生态里跑通业务，再把底层换过来。

2. WebSocket握手原理与ChannelPipeline的初始化顺序

2.1 从HTTP升级到WebSocket的握手细节

WebSocket连接不是凭空建立的，它必须通过一次HTTP升级请求来转换协议。

客户端发的请求大致长这样：

GET /ws HTTP/1.1 Host: push.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13

这里的核心是Sec-WebSocket-Key，一个客户端随机生成的Base64字符串。服务端拿到它之后，会拼接一个固定的魔数：

258EAFA5-E914-47DA-95CA-C5AB0DC85B11

然后计算SHA1，再做一次Base64，得到Sec-WebSocket-Accept返回给客户端，同时回复HTTP 101状态码，整个握手就完成了。这个魔数是RFC 6455里写死的，网上很多教程会直接复制，但建议还是搞清楚它的来历。

从握手开始，连接就变成了WebSocket全双工通道，后续的HTTP解析器基本退场。客户端发来的数据以WebSocket帧的形式到达，服务端下发的数据也要封装成WebSocket帧。帧格式里最容易被新手忽略的一点是掩码规则：客户端发给服务端的帧必须带掩码，服务端发给客户端的帧不能带掩码，这是协议强制要求。Netty的WebSocketServerProtocolHandler已经封装了这些细节，但你心里得有数，不然自己写解码器的时候很容易在这一步栽跟头。

2.2 Pipeline的Handler装配顺序与职责

Netty的一切工作都在ChannelPipeline里发生，WebSocket服务端的Pipeline装配是整套系统的基础。

我最终使用的装配逻辑如下：

ServerBootstrap bootstrap = new ServerBootstrap(); bootstrap.group(bossGroup, workerGroup) .channel(NioServerSocketChannel.class) .childHandler(new ChannelInitializer<SocketChannel>() { @Override protected void initChannel(SocketChannel ch) { ChannelPipeline pipeline = ch.pipeline(); // 1. HTTP编解码 pipeline.addLast(new HttpServerCodec()); // 2. 聚合HTTP请求，避免收到不完整的HTTP消息 pipeline.addLast(new HttpObjectAggregator(65536)); // 3. 实现WebSocket升级与帧解码 pipeline.addLast(new WebSocketServerProtocolHandler("/ws")); // 4. 业务处理器 pipeline.addLast(new PushMessageHandler()); } });

每个Handler的位置都有讲究。HttpServerCodec负责HTTP请求的编解码；HttpObjectAggregator把分块的HTTP请求聚合为完整消息，避免半包问题；WebSocketServerProtocolHandler是这个Pipeline里最关键的一环，它会在收到HTTP升级请求时自动完成101握手，升级成功后自动把TCP流解码为WebSocketFrame；PushMessageHandler里再处理业务消息和推送逻辑。

网上很多新手代码把业务Handler放在WebSocketServerProtocolHandler之前，导致收到的是HTTP消息而不是WebSocketFrame，handler里拿不到完整数据。这是最常见的问题之一。

2.3 连接注册与用户映射管理

连接管理是推送系统的地基。最简单的做法是用Netty自带的ChannelGroup来维护所有连接：

public class ConnectionManager { public static final ChannelGroup channels = new DefaultChannelGroup(GlobalEventExecutor.INSTANCE); }

但实际项目里只有ChannelGroup不够，因为推送要按用户、按分组定位。我的做法是用Channel的attr属性来保存用户标识：

AttributeKey<String> USER_KEY = AttributeKey.valueOf("userId"); channel.attr(USER_KEY).set(userId);

同时维护一个userId到Channel列表的映射，因为同一个用户可能在PC端、手机端、大屏端同时登录。写入映射时要考虑并发，Netty的EventLoop模型保证了同一个Channel没有并发问题，但不同线程调用业务代码时可能同时操作映射，所以我用了ConcurrentHashMap，并在连接断开时从映射中清理对应Channel，防止僵尸会话。

连接断开的清理非常关键。如果清理不及时，映射里会堆积大量失效连接，推送时writeAndFlush不会报错但消息全部丢失，连接数看起来还在涨。我就是最初漏了这一步，上线两天后连接数虚高，排查半天才找到根因。后续会在channelInactive回调里统一执行映射清理。

3. 粘包与半包：藏在帧边界下的业务边界问题

3.1 TCP流与WebSocket帧的关系

先澄清一个概念：TCP是面向字节流的协议，不保证一次write对应一次read。你以为发了一个完整的WebSocket帧，对端可能分两次收到；你以为发了两个帧，对端可能一次全部收到。这就是"半包"和"粘包"的由来。

引入WebSocket之后，协议层在帧头里规定了payload长度，所以Netty的WebSocket解码器可以按帧长度精确地把每个帧切出来。只要你的Handler收到的是WebSocketFrame类型，就不存在"一个文本帧被切成两个不完整的TextWebSocketFrame"的问题。很多人问Netty WebSocket怎么处理粘包，实际上框架已经替你解决了协议帧层面的边界问题。

但协议帧边界解决了，业务消息边界却不一定会自动解决。这时候最容易踩坑。

3.2 业务层粘包的实测案例

我在项目里还真踩过一次。前端用的某个WebSocket客户端封装库，底层做的是批量合并写入，一次flush把三条JSON消息塞进了同一个WebSocket帧。服务端Handler收到完整的TextWebSocketFrame之后，直接拿content()里的字节去做JSON反序列化，结果解析失败，日志里全是JsonParseException。

一开始我完全不理解，明明协议层处理正确，为什么还会解析失败？后来把收到的原始内容打出来才明白，一整个帧里是拼接在一起的三个JSON对象，中间没有任何分隔符。这就回到了TCP时代的老问题：多个业务消息共享同一个传输单元。

除了这种"多业务消息塞一帧"的场景，还有一个容易被忽略的情况就是WebSocket分片帧。协议里允许把一条大消息拆成多个帧发送，frame的FIN标志位表示是否是最后一个分片。如果客户端发送分片消息，服务端默认会按照分片逐个收到，业务层如果不去聚合，就会看到一条消息被拆成多段。Netty提供了一个现成的聚合器WebSocketFrameAggregator，可以在Pipeline里加上：

pipeline.addLast(new WebSocketFrameAggregator(1024 * 1024));

这样分片帧会被自动合成一个完整的帧再交给业务Handler。

3.3 业务消息边界的设计建议

既然粘包可能发生在业务层，那业务协议就要显式定义边界。建议的做法是：业务消息统一走自己的报文头，结构为"业务长度字段 + 消息体"。

举例说明，比如每条业务消息都这样组装：

+--------+-----------------+ | length | payload | | 4 byte | JSON bytes | +--------+-----------------+

在服务端收到一个完整的TextWebSocketFrame后，从content里先读取4字节长度，再根据长度切分出一条条完整的业务消息依次处理。这个过程其实就是模仿LengthFieldBasedFrameDecoder的思路，只是把解码的层级从TCP层挪到了业务层。

如果你的业务消息确实是"一帧一条"，那客户端库的flush行为必须受控，不能搞批量合并。这要靠前后端联调时拉齐规范，我后来在接口文档里明确写了"一个WebSocket帧只能包含一条完整的业务消息"，从那之后业务层粘包问题基本绝迹。

所以面试被问"Netty怎么处理粘包"时，标准答题路径是：先说明TCP流没有消息边界，然后说解决办法是定义协议边界，最后说Netty的ByteToMessageDecoder通过累积缓存和循环解码自动解决半包。如果问题背景是WebSocket，还要补一句：协议帧边界由WebSocket长度头解决，业务消息边界得靠业务协议自己解决。

4. 心跳机制设计：参数、实现与半开连接检测

4.1 心跳参数怎么定才能不误杀

TCP自带keepalive机制，默认探测周期是两个小时，这个粒度对实时推送来说完全不够。中间还有Nginx、SLB这类组件，它们会默默回收空闲连接，客户端可能早就不知道服务端已经断开，服务端却还傻等数据。所以应用层必须自己维护心跳。

心跳参数怎么定，我实际踩过"心跳周期太短导致误杀长任务连接"的坑。当时我把心跳定为15秒，服务端读空闲判定30秒。结果运营同事在后台执行一个耗时超过30秒的批量导出操作，期间客户端没发任何数据，服务端直接判定死链，把连接踢了。虽然业务上可以容忍秒级推送延迟，但误杀一个还在正常工作的连接是不可接受的。

我后来定的参数是：客户端心跳周期60秒，服务端读空闲判定180秒。也就是允许客户端三个心跳周期内完全不发任何数据才判定死链，误杀概率大大降低。

4.2 服务端与客户端的心跳配合

服务端用Netty自带的IdleStateHandler实现，装配在Pipeline里：

pipeline.addLast(new IdleStateHandler(180, 0, 0, TimeUnit.SECONDS));

参数顺序是readerIdleTime、writerIdleTime、allIdleTime。我这里只关心读空闲，所以把写空闲和全空闲设为0，表示不启用。如果配置了写空闲，通常是用在服务端主动探活场景，这个下一小节说。

然后在业务Handler里重写userEventTriggered：

@Override public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception { if (evt instanceof IdleStateEvent) { IdleStateEvent event = (IdleStateEvent) evt; if (event.state() == IdleState.READER_IDLE) { ctx.close(); } } else { super.userEventTriggered(ctx, evt); } }

提示：这里把readerIdleTime设为180秒，意思是180秒内读不到任何数据才触发事件，包括业务消息、Ping、Pong等所有帧类型。只要客户端有任意数据进来，计时器都会重置。

服务端侧的心跳策略是：客户端必须周期性地发送数据，任何类型的WebSocket帧都可以，包括业务消息、Ping帧或者Pong帧。客户端配套逻辑：每60秒发送一个WebSocket的Ping帧，服务端收到后由WebSocketServerProtocolHandler自动回Pong帧。之所以选协议层Ping帧而不是自定义JSON心跳消息，是因为Ping帧载荷极小、语义标准、不占业务带宽。业务上也可以顺带把当前在线状态作为心跳消息的payload，但我不建议把两件事混在一起，拆开更容易排查问题。

4.3 半开连接的主动探活

半开连接指的就是TCP连接在双方看来还活着，但实际数据链路已经断了。比如手机从电梯里出来切换网络，或者笔记本睡眠唤醒，这类场景下客户端不会发FIN包，服务端只在真正尝试写数据时才会发现对端不可达。

针对半开连接，服务端需要主动探活。具体做法有两种。第一种是配置IdleStateHandler的ALL_IDLE，比如每60秒触发一次AllIdle事件，服务端向客户端发送一个Ping帧，如果连续N次没有收到Pong帧，就判定连接已死并关闭。第二种是维护一个独立的定时任务，周期性扫描所有Channel的最近活跃时间，超过阈值就主动关闭。第一种方案实现成本最低，因为Netty已经帮你把定时器做了。

这里要特别提醒：Ping帧的发送频率不能太激进，否则大量Ping/Pong帧在网络里空跑，白白消耗带宽和CPU。我的经验是探活周期和客户端心跳周期保持一致，60秒一次Ping，连续3次无响应就断连。这样在小规模连接下几乎无感，又能在真实断网场景下及时释放资源。

5. 消息推送链路：协议、路由与可靠投递

5.1 下行消息协议设计

推送系统里，服务端下发的消息必须有统一的协议结构，否则客户端没法区分这是业务消息、ACK、心跳还是错误提示。

我用的下行消息协议是一个JSON对象：

{ "cmd": "push", "msgId": "3f2a1b8e-6c4d-4e5a-9f0c-1b2a3c4d5e6f", "type": "order.update", "timestamp": 1693232000000, "data": {} }

字段含义说清楚：cmd是命令类型，push表示业务推送；msgId是消息唯一ID，用于去重和ACK确认；type是业务类型，客户端用它决定如何渲染；data是业务载荷。除了push之外，还有ack、heartbeat、error等命令，统一放在cmd里。

设计这套协议时，最需要注意的一点是msgId必须有。实时推送最常见的故障就是消息重复或丢失，没有msgId，客户端就无法去重，服务端也无法做重推。即使你的业务当前不要求高可靠，也建议从一开始就把msgId加上，否则后面想补就很难了。

5.2 广播、单播与分组路由

有了连接管理和协议后，推送路由就是调用关系了。

单播是最直接的，通过userId找到对应的Channel列表然后逐个writeAndFlush：

List<Channel> channels = userChannels.get(userId); if (channels != null) { for (Channel channel : channels) { if (channel.isActive() && channel.isWritable()) { channel.writeAndFlush(buildTextFrame(message)); } } }

广播用ChannelGroup把所有在线连接一次性推出去：

ChannelGroup channels = ConnectionManager.channels; channels.writeAndFlush(new TextWebSocketFrame(JSON.toJSONString(message)));

分组广播需要自己维护分组和Channel的对应关系，可以用ConcurrentHashMap<groupId, ChannelGroup>，推送时按groupId取到对应的ChannelGroup再writeAndFlush。

这里有一个容易忽略的性能点：writeAndFlush是异步的，它把消息写入Channel的出站缓冲区就返回，并不会等待真正发到对端。调用量大时，如果完全不检查Channel的可写状态，消息会全部积压在ChannelOutboundBuffer里，最终导致内存上升和推送延迟。所以上面的代码里我特意加了isWritable()判断。要启用写水位线监控，可以在Pipeline里设置：

pipeline.addLast(new WriteBufferWaterMark(32 * 1024, 64 * 1024));

一旦Channel的写缓冲区超过高水位，isWritable()会返回false，业务侧就应该停止向该Channel投递，并把消息临时落库，等水位恢复后再投。

5.3 ACK确认、重推与离线补偿

纯实时推送系统可以接受部分消息丢失，但订单预警类消息不能丢。我在项目里给重要消息加了一套ACK确认与补偿机制。

客户端每收到一条push消息，都要回一条ACK帧：

{ "cmd": "ack", "msgId": "3f2a1b8e-6c4d-4e5a-9f0c-1b2a3c4d5e6f" }

服务端发出消息时，把msgId和对应的Channel记到待确认集合里，然后用指定延时器在3秒后检测是否收到ACK。Netty自带的HashedWheelTimer比较适合干这个，它本质是一个时间轮，能以较低的CPU开销处理大量定时任务。如果超时未ACK，就重推，最多3次，仍然失败就把消息写入Redis中的离线消息队列，等客户端下次上线时做补偿拉取。

这里要控制待确认集合的大小，避免消息拥塞时内存暴涨。我做了两个限制：对每个Channel最多允许N条未确认消息，超过则阻塞推送，并触发告警；对整体待确认消息数做了上限，超过时优先保证最新消息，丢弃最老的未确认消息并记录日志。

做这套ACK机制时还有个经验：ACK处理要尽可能轻量，只需要从集合中移除msgId即可，不要在ACK链路里做复杂的业务判断，否则ACK消息本身也会成为性能瓶颈。

6. 线上故障排查实录：三个典型问题定位全过程

6.1 连接成功但消息双向不通

最诡异的故障是：浏览器显示WebSocket连接成功，服务端也接受了连接，但服务端推给客户端的数据客户端完全收不到，客户端发的业务消息服务端也不触发channelRead。

我最初的定位思路是先确认升级是否真的成功。在业务Handler里打印了channelActive和channelRead0的日志，结果发现channelActive打了，channelRead0只有HTTP消息进来时才有日志，WebSocket文本消息进来没有任何输出。这就把问题缩小到了Pipeline顺序上。

检查后发现，我的自定义Handler继承了SimpleChannelInboundHandler，但泛型写成了Object。由于SimpleChannelInboundHandler会去匹配传入消息的类型，泛型Object会匹配一切消息，包括HttpObjectAggregator聚合出来的HTTP消息。升级前消息被它消费了一部分，升级后WebSocketFrame被它消费了但又被丢弃，业务Handler永远拿不到。解决方案是让Handler的泛型精确匹配WebSocketFrame，或者把业务Handler放在WebSocketServerProtocolHandler之后并严格限定消息类型。同时也检查了WebSocketServerProtocolHandler的路径参数，必须和前端连接的路径一致，这个细节也容易踩。

还有一个隐蔽的坑：如果WebSocketServerProtocolHandler放在了业务Handler后面，升级完成后业务Handler根本不在帧处理路径上，逻辑上就完全失效了。所以Pipeline顺序一定遵守"HTTP编解码 -> HTTP聚合 -> WebSocket升级 -> 业务Handler"这个基本次序。

6.2 空闲误判：长任务连接被踢

这个问题的现象是：客户端在长时间执行任务时，连接会被服务端莫名其妙断开，断开前没有报错，客户端重连后又能正常工作。

我直接怀疑是心跳参数太激进。当时读空闲阈值设的是30秒，而客户端的心跳周期是15秒，理论上两个心跳周期内不会有问题，但实际出现了部分客户端在长任务期间完全停止发心跳，代码里确实有在某个定时任务执行期间暂停心跳的逻辑。结果30秒一到，服务端就踢连接。

定位过程不难，难的是要不要把心跳和业务行为解耦。我当时上线了三个优化：一是把读空闲阈值放宽到180秒，让正常连接不易被误杀；二是把客户端心跳从业务线程里独立出来，无论业务任务多长，心跳线程都稳定运行；三是在业务消息的频率和心跳频率之间做了协调，业务消息越多，心跳可以适当放宽，但不能完全没有。这个组合调整之后，长任务断连的问题再也没有出现过。

6.3 ByteBuf泄漏与GC压力

压测过程中出现过一个典型的ByteBuf泄漏，表现为持续运行几小时后，服务端内存占用不断上升，最终触发Full GC导致推送延迟飙升，连接也开始被断开。

我先启动了Netty的泄漏检测：

-Dio.netty.leakDetection.level=paranoid

日志里很快定位到是某个自定义Outbound处理器在writeAndFlush之前对消息做了转换，但转换过程中创建的ByteBuf没有正确释放。原因是我继承了ChannelOutboundHandlerAdapter，手动构建ByteBuf后，原消息没有被释放，新ByteBuf也没有在写完时释放。

注意：如果你用的是SimpleChannelInboundHandler，它会在处理完成后自动释放传入的msg；如果继承了ChannelInboundHandlerAdapter，就必须在finally块里调用ReferenceCountUtil.release(msg)。Netty对引用计数的要求很严格：谁创建的ByteBuf谁负责释放。

压测时泄漏不明显，是因为内存池撑得住，但跑上几个小时就会暴露。另外，推送高频场景下，每条消息都创建新的TextWebSocketFrame和JSON字符串，GC压力不可避免地会上升。我做的优化是尽量复用ByteBuf，少做无谓的字符串拼接，能用字节数组就用字节数组；同时调整了堆外内存和堆内内存的分配策略，让Netty优先使用池化的DirectByteBuf。压测数据跑下来，同样的推送量下GC次数明显下降。

最后分享一个小经验：Netty做WebSocket推送，功能跑通只是开始，真正考验人在线上。我给服务加了四个基础监控指标：当前连接数、每秒接收和推送消息数、Channel不可写次数、心跳超时断开数。尤其是"心跳超时断开数"这个指标，曲线一旦异常，往往意味着网络环境在恶化或者客户端批量掉线，它比平均延迟更能反映系统健康度。这套系统上线到现在，大的故障没再出过，偶尔冒出来的问题也都能靠日志和指标快速定位。如果你也在搭类似系统，建议从一开始就把这些埋点做进去，省下来的排查时间远比开发成本多。