基于Netty与Spring Boot的在线客服系统实战：长连接、消息存储与高并发优化

1. 先想清楚一件事：在线客服系统到底在解决什么问题

我做过几个客服类项目，从最早的网页嵌入聊天窗，到后来带着工单、机器人、会话路由的完整平台，核心链路其实一直没变过：用户发起会话，客服接收并回复，双方维持一段实时双向通信，同时系统把聊天记录完整落库，供后续查询和质检。

这套基于Java + Spring Boot + Netty + MySQL的在线客服系统，本质上就是把这条链路落到工程实现上。Spring Boot负责业务接口、用户鉴权、REST API和后台管理，Netty负责承载长连接，处理高并发的消息推送，MySQL负责存储会话、消息、客服账号和访客信息。

这套技术栈选型的理由很直白：Java生态成熟，招人容易；Spring Boot省去大量Bean配置和依赖管理的心智负担，开发效率在Java阵营里是第一梯队；Netty是Java网络编程的事实标准，处理数万级长连接是它的舒适区，不用担心从零手写NIO多路复用踩出各种隐蔽Bug；MySQL则是绝大多数团队最熟悉的存储方案，做客服系统的消息存储完全够用，没必要为了一个中低并发场景硬上复杂的消息中间件或分布式数据库。

这篇文章面向两类人：一是刚接触Netty，想找一个真实的复合场景练手、搞懂长连接服务怎么和业务系统整合的同学；二是公司业务需要客服系统，想快速评估技术方案并踩坑避雷的开发者。我会把整个系统的核心设计、关键代码、数据库表结构、上线部署时容易翻车的点都过一遍，尽量做到拿过来就能照着落地。

在动手写代码之前，我建议先把在线客服系统拆成几个关键模块：接入层、路由层、业务层、存储层。接入层负责维持客户端和服务器之间的长连接，同时要处理客户端断线重连、心跳超时；路由层决定一条消息由哪个客服处理，简单方案是轮流分配，复杂方案是按技能组、负载、在线状态综合调度；业务层处理消息内容、敏感词过滤、会话状态流转、满意度评价；存储层把最终的消息和会话记录写进MySQL，供历史查询和统计报表使用。

2. Netty接入层设计：长连接服务不是启动一个ServerSocket那么简单

2.1 为什么不用Tomcat的WebSocket，非要单独搭一套Netty

很多人第一反应是：Spring Boot自带WebSocket支持，直接注解开发不就行了？确实，Spring的WebSocket基于Servlet容器实现，开发和部署都很方便。但这里有个前提——Spring Boot内嵌的Tomcat处理WebSocket连接时，每个连接最终是落在NIO线程池里，连接数一旦上千，线程和内存开销会迅速上涨，而且Tomcat的WebSocket是走Servlet规范的适配层，很多对网络栈底层的精细控制是做不到的。

我之前用一个Spring Boot WebSocket做过压测，2核4G的机器跑到2000个连接左右，CPU开始飙高，GC频繁，消息延迟明显抖动。换成Netty之后，同样的机器扛到8000连接还很平稳。原因在于Netty的Reactor模型，事件循环线程数可以按CPU核数弹性配置，一个线程能管理成千上万个Channel，消息处理完全走异步回调，不走Servlet的请求-响应阻塞模型。

在线客服系统的访问模型正好是“连接多、消息频率中等、单条消息数据量小”，这种长连接场景天然适合Netty来承载。Spring Boot这边只需要提供一个鉴权接口，给客户端颁发一个合法的token，然后让客户端拿token去连Netty服务，两个服务各司其职。

2.2 Netty服务的核心链路配置

接入Netty服务的第一步是配置ServerBootstrap的线程模型。我自己在项目里用的是双EventLoopGroup，boss线程池负责处理新的连接请求，worker线程池负责处理每个连接上的读写事件。生产环境建议这样设置：

java复制EventLoopGroup bossGroup = new NioEventLoopGroup(1);
EventLoopGroup workerGroup = new NioEventLoopGroup(Runtime.getRuntime().availableProcessors() * 2);

boss线程数设置为1足够，因为对于单个端口来说，同时到达的连接请求由一个线程串行accept是最高效的，避免多线程竞争同一个ServerSocketChannel。worker线程数则按CPU核数和业务复杂度来调，一般取CPU核数的两倍。如果机器是4核，就配置8个worker线程，这样既能保证每个线程有足够的CPU时间片，又不会因为线程过多导致上下文切换开销过大。

ChannelPipeline里加载哪些Handler，直接决定了你的服务能否稳定运行。我建议的最小配置如下：

• IdleStateHandler：用于检测连接空闲超时，超过规定时间没有读写，就触发心跳事件。
• DelimiterBasedFrameDecoder：按自定义分隔符拆包，解决TCP粘包/拆包问题。
• MessageToMessageDecoder：将字节流解码为业务消息对象。
• MessageToMessageEncoder：将业务消息对象编码为字节流。
• 自定义MessageHandler：处理具体的业务逻辑。

粘包半包问题必须在解码阶段解决，越快越好。客服系统是典型的短消息场景，一条消息就几十几百字节，我用的是自定义分隔符方案，每条消息末尾加一个特殊的结束标记，比如\r\n。Netty的DelimiterBasedFrameDecoder会把每个完整帧切割出来再交给后续Handler处理。如果消息类型更复杂，可以考虑用LengthFieldBasedFrameDecoder，在消息头放一个长度字段，按长度解码，这种方式更适合协议扩展性要求高的场景。

2.3 在线状态管理与心跳维持

客服系统的在线状态非常重要。客服离线了，系统就不能再把用户分配到TA身上；用户刷新了页面，服务端要能及时感知旧连接失效。我用一个ChannelGroup来管理所有在线连接，每个Channel绑定一个全局唯一标识，标识就是用户ID拼接一个随机字符串，比如10001_a3f9d2。用户上线时把Channel加入ChannelGroup，下线时移除。

客户端和服务端的心跳机制，我采用的是双向心跳：客户端每隔30秒发送一个Ping消息，Netty服务端收到后回复Pong；服务端同时用IdleStateHandler设置读空闲超时时间为60秒，如果60秒内没有收到客户端的任何数据，就判定连接已失效，主动关闭Channel。这里有个细节经验：读空闲超时时间最好设置为心跳间隔的两倍以上，避免网络抖动导致的误判。

java复制public class HeartbeatHandler extends ChannelInboundHandlerAdapter {
    
    private static final int MAX_MISSED_PING = 3;
    private int missedPingCount = 0;

    @Override
    public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
        if (evt instanceof IdleStateEvent) {
            IdleStateEvent event = (IdleStateEvent) evt;
            if (event.state() == IdleState.READER_IDLE) {
                missedPingCount++;
                if (missedPingCount >= MAX_MISSED_PING) {
                    // 连续多次未收到心跳，认为连接已死
                    ctx.close();
                }
            }
        } else {
            super.userEventTriggered(ctx, evt);
        }
    }
}

这段代码处理了一个常见的边界情况：网络偶发抖动时，客户端可能只是迟到了一个心跳包，但连接本身是正常的。如果服务端收到一次空闲事件就直接断开连接，会导致大量误杀。我采用三次连续心跳超时才关闭连接，同时客户端只要成功发送下一个心跳包，服务端就会把missedPingCount清零，这样既保证了连接的及时清理，又不会因为网络抖动影响正常用户。

2.4 双端接入：浏览器端用WebSocket，客服端用统一协议

在线客服系统通常有两类客户端：用户端是浏览器网页，客服端是运营人员使用的后台。浏览器的WebSocket协议和自定义TCP协议在握手阶段有本质区别，WebSocket需要完成HTTP升级握手，而自定义TCP协议直接连上就能收发消息。

我可以选择在Netty里同时监听两个端口：一个端口专门处理WebSocket连接，另一个端口处理客服客户端的自定义TCP连接。也可以用同一个端口，通过判断首个字节的协议版本号来分发到不同的Handler链。前者实现更简单，两个端口的逻辑分离，故障隔离性也更好，我倾向于前者。

浏览器端接入Netty的WebSocket代码，核心Pipeline配置是这样的：

java复制ch.pipeline().addLast(new HttpServerCodec());
ch.pipeline().addLast(new HttpObjectAggregator(65536));
ch.pipeline().addLast(new WebSocketServerProtocolHandler("/ws"));
ch.pipeline().addLast(new WebSocketFrameHandler());

HttpServerCodec负责HTTP协议的编解码，HttpObjectAggregator把HTTP请求组装成完整消息，WebSocketServerProtocolHandler处理WebSocket握手、帧解码和关闭控制帧。如果用户是通过网页访问的，走这个端口；客服端则是直接TCP连接，走另一个端口，两条链路共享同一个消息处理Handler，便于统一维护业务逻辑。

3. MySQL数据层设计：聊天记录不是简单插一条记录那么简单

3.1 核心表结构与字段设计

在线客服系统涉及的核心数据表有这么几张：访客表、客服账号表、会话表、消息表、评价表。我重点展开会话表和消息表，因为这两个表的设计直接关系到系统的性能和扩展性。

会话表（chat_session）用于记录一次完整的服务过程。一次会话从用户发起咨询开始，到客服关闭或用户主动结束为止，包含访客ID、客服ID、开始时间、结束时间、状态等字段。关键字段如下：

sql复制CREATE TABLE `chat_session` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `session_no` varchar(32) NOT NULL COMMENT '会话编号，业务标识',
  `visitor_id` bigint(20) NOT NULL COMMENT '访客ID',
  `agent_id` bigint(20) DEFAULT NULL COMMENT '客服ID',
  `status` tinyint(4) NOT NULL DEFAULT '1' COMMENT '1-进行中 2-已结束 3-已转接',
  `queue_start_time` datetime DEFAULT NULL COMMENT '排队开始时间',
  `agent_accept_time` datetime DEFAULT NULL COMMENT '客服接起时间',
  `end_time` datetime DEFAULT NULL COMMENT '结束时间',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_visitor_time` (`visitor_id`, `create_time`),
  KEY `idx_agent_status` (`agent_id`, `status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会话表';

注意这里的索引设计。对访客查询历史会话列表，高频查询条件是“某个访客最近和哪些客服聊过天”，所以建的联合索引是(visitor_id, create_time)，这样能快速定位某个访客的会话记录并按时间倒序。对于客服端，高频操作是查看“我当前待处理或处理中的会话”，所以加了一个(agent_id, status)的联合索引。

消息表（chat_message）是数据量增长最快的表，设计时一定要想清楚消息怎么读、怎么删、怎么归档：

sql复制CREATE TABLE `chat_message` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `session_id` bigint(20) NOT NULL COMMENT '关联会话ID',
  `sender_type` tinyint(4) NOT NULL COMMENT '1-访客 2-客服 3-系统',
  `sender_id` bigint(20) NOT NULL COMMENT '发送者ID',
  `msg_type` tinyint(4) NOT NULL COMMENT '1-文本 2-图片 3-商品卡 4-系统提示',
  `content` text NOT NULL COMMENT '消息内容',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_session_time` (`session_id`, `create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='聊天消息表';

消息表最常用的查询是“拉取某次会话的所有消息”，所以索引落在(session_id, create_time)上。另外一个容易被忽略的点是消息表的排序和ID生成，统一用自增主键，业务上消息展示也按这个自增ID排，因为时间字段存在相同毫秒的情况，但自增ID不会重复。

3.2 消息落库的异步优化

刚开始做这个系统时我犯过一个错误：在Netty的业务Handler里直接同步执行消息插入MySQL。后来压测发现，当消息并发量上来后，Netty的worker线程被数据库IO阻塞，整个服务端的吞吐量急转直下。原因是MySQL写入一次正常需要几毫秒，而高并发下这些几毫秒的阻塞会让Netty的线程池很快耗尽。

正确做法是引入异步落库机制。我用的方案是在Spring Boot服务里维护一个双端队列，Netty的Handler处理完一条消息后，把消息对象扔进队列就返回，专门的消费者线程从队列里批量取出消息，攒够50条或每隔500毫秒批量插入一次，这样能极大减少数据库交互次数。

java复制@Component
public class MessagePersistService {

    private static final int BATCH_SIZE = 50;
    private static final long FLUSH_INTERVAL_MS = 500L;
    
    private final BlockingQueue<ChatMessage> queue = new LinkedBlockingQueue<>(2048);
    private final ChatMessageMapper messageMapper;

    public MessagePersistService(ChatMessageMapper messageMapper) {
        this.messageMapper = messageMapper;
        this.startConsumer();
    }

    private void startConsumer() {
        ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor();
        executor.scheduleWithFixedDelay(() -> {
            List<ChatMessage> batch = new ArrayList<>();
            queue.drainTo(batch, BATCH_SIZE);
            if (!batch.isEmpty()) {
                messageMapper.batchInsert(batch);
            }
        }, 0, FLUSH_INTERVAL_MS, TimeUnit.MILLISECONDS);
    }
}

这里有几个工程细节值得说明。队列容量设置了2048的上限，防止消息积压导致内存溢出，如果队列满了，发送线程可以选择丢弃消息并记录日志，或者启动快速降级策略，直接写入日志文件等待后续补偿。批量插入用的MyBatis的foreach动态SQL，一次insert语句插入50条记录，实测比单条插入性能提升十倍以上。

3.3 历史消息查询：分页方案别用OFFSET大跳

客服后台要查看历史消息，常见做法是打开一个会话记录，往下滚动加载更多。数据量小的时候用LIMIT offset, size没什么问题，但消息表到百万级以后，OFFSET越大查询越慢，因为数据库要扫描并丢弃前面所有行。我切换到游标分页方案，用create_time + id作为游标条件：

sql复制SELECT * FROM chat_message 
WHERE session_id = #{sessionId} 
  AND (create_time < #{lastTime} OR (create_time = #{lastTime} AND id < #{lastId}))
ORDER BY create_time DESC, id DESC
LIMIT 20;

这种方式每次查询只走联合索引的区间扫描，性能非常稳定，不会随着翻页深入而下降。前端再通过消息体的has_more字段判断是否还有更多数据可加载。

3.4 老数据归档：别让核心表无限膨胀

运行一年后，消息表的数据量可能达到几千万甚至上亿条。这时候即使索引建得很好，也会因为索引过大而影响写入性能。我建议在系统设计之初就预留归档机制：消息表按月份分表，比如chat_message_202501、chat_message_202502，每月一张。业务查询先根据时间定位到对应分表，再执行SQL。旧表数据可以定期转移到归档库或者冷存储，核心库只保留近半年的热数据。

如果不想动分表逻辑，另一种常用方案是原文JSON存储，把一次会话的所有消息打包成JSON存到一张独立的会话详情表。这样查询历史会话时只查一次大字段，避免了海量消息行的扫描。缺点是单条会话消息量特别大时，MySQL的单行存储压力会增大，需要根据业务实际情况权衡。

4. Spring Boot业务层落地：鉴权、路由、消息转发

4.1 连接鉴权：Netty也要做登录校验

很多初学Netty的人把服务搭好后就只关注收发消息，忽略了鉴权。在客服系统里，如果任何人都能随意连接到Netty端口并发送消息，后果不只是垃圾消息，而是信息泄露——攻击者可以伪造客服身份给用户发送钓鱼消息。

我采用的鉴权方案是：客户端先调用Spring Boot的登录接口，登录成功后拿到一个token，这个token包含用户ID、角色、过期时间，并用JWT签名。客户端建立Netty连接后，发送的第一条消息必须是AUTH类型，携带token。Netty的Handler把token解析出来，验证签名和有效期，再通过RPC调用或者共享Redis查询用户信息，验证通过才把连接标记为已认证，否则直接关闭连接。

java复制public class AuthHandler extends ChannelInboundHandlerAdapter {

    @Override
    public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
        if (!(msg instanceof AuthMessage)) {
            // 未认证只能发AUTH消息，其他消息直接拒绝
            ctx.close();
            return;
        }
        AuthMessage authMsg = (AuthMessage) msg;
        Long userId = JwtUtil.parseToken(authMsg.getToken());
        if (userId == null) {
            ctx.close();
            return;
        }
        ctx.channel().attr(AttributeKey.valueOf("userId")).set(userId);
        // 认证通过后移除AuthHandler，后续消息直接进入业务Handler
        ctx.pipeline().remove(this);
    }
}

这里有两个细节容易踩坑。一是用户断线重连时，会因为忘记预先认证而收到服务端的关闭指令，所以客户端重连逻辑里一定要先发AUTH再发业务消息；二是Channel上的用户信息不能只放在ChannelHandlerContext里，因为后续做消息转发时可能要从别的Channel上下文拿到目标用户的ID，我统一用Channel的Attribute来存。

4.2 消息路由：一条消息如何找到目标客户端

在线客服的消息路由，核心问题是维护一张“用户ID到Channel的映射表”。我们用ConcurrentHashMap存这份映射，key为Long类型的用户ID，value为Channel。因为一个用户同一个时间只有一个连接，这里不用考虑多端登录的问题。

java复制public class ChannelRegistry {
    
    private static final Map<Long, Channel> CHANNEL_MAP = new ConcurrentHashMap<>();
    
    public static void add(Long userId, Channel channel) {
        CHANNEL_MAP.put(userId, channel);
    }
    
    public static Channel get(Long userId) {
        return CHANNEL_MAP.get(userId);
    }
    
    public static void remove(Long userId, Channel channel) {
        CHANNEL_MAP.remove(userId, channel);
    }
}

用户发消息给客服时，消息先到达Netty服务端，Netty把消息投递到Spring Boot的消息处理接口，业务层根据消息里的目标客服ID去ChannelRegistry查目标Channel，然后通过该Channel把消息写出去。这个过程中要注意共享变量并发可见性，ConcurrentHashMap没问题，但Channel的写操作本身是线程安全的，可以直接调用channel.writeAndFlush()。

4.3 会话分配：简单的轮询还是带权分配

当用户发来咨询时，系统需要从当前在线的客服里选一个分配。最简方案是维护一个在线客服队列，每次从队列头取一个人分配，再将这个人放到队尾，典型的轮询策略。这个方案实现简单，但缺陷明显：没有考虑客服当前正在接待的会话数量，可能出现一个客服已经被塞了10个会话，另一个客服空闲的情况。

我做了一个轻量的加权算法：每个客服维护一个当前接待人数，用户在排队等待时，后台每3秒扫描一次所有在线客服，找出接待人数最少的客服作为候选，分配给用户。如果所有客服都达到最大接待上限，用户进入排队队列，并向用户推送一条排队提示消息。

java复制public AgentInfo pickBestAgent(List<AgentInfo> onlineAgents, int maxLoad) {
    return onlineAgents.stream()
        .filter(agent -> agent.getCurrentSessionCount() < maxLoad)
        .min(Comparator.comparingInt(AgentInfo::getCurrentSessionCount))
        .orElse(null);
}

这个方案虽然是全量扫描，但在客服数量规模为几十人的场景下完全没有性能压力。如果客服团队扩展到上千人，就需要引入Redis的有序集合来维护在线客服列表，按当前负载排序，这样选人的时间复杂度能从O(n)降到O(log n)。

4.4 消息流转的完整时序

理清时序对排查问题非常重要。我画过一张完整的消息流转图，用文字描述一下：用户在浏览器页面输入内容，前端通过WebSocket把消息发给Netty服务端，Netty的WebSocketFrameHandler解码出消息对象，将消息推送到Spring Boot的MessageController接口，MessageController校验消息合法性后调用MessageService保存消息，同时调用DispatchService查找目标客服的Channel，找到后把消息编码成客户端协议格式，通过Netty写回客服端。客服端收到消息后回执ACK，Netty收到ACK后更新消息的投递状态。

如果目标客服不在线，消息不能直接丢弃，要存入离线消息表。客服上线后，系统自动把离线期间未读的消息推送过去。这个逻辑在客服系统里几乎是必须的，否则客服休息回来后发现自己漏掉了很多用户的咨询。

5. 上线前必须做的性能优化与压测

5.1 JVM参数和Netty线程调优

我之前有个项目上线初期没有做JVM参数配置，用的默认设置，结果在流量高峰期频繁触发Full GC，最高的一次停顿了2秒，直接导致一批WebSocket连接心跳超时被断开。客服系统对GC停顿非常敏感，因为长连接服务一旦短暂无响应，客户端的心跳检测失败就可能主动断开连接，用户感知就是“聊天断开需要刷新页面”。

我建议上线前至少调整这几个JVM参数：-Xms和-Xmx设为相同的值，防止堆动态扩容导致性能抖动；-XX:+UseG1GC在JDK 11以后默认开启，但如果用JDK 8需要手动指定；-XX:MaxGCPauseMillis=200设定G1的目标停顿时间。对于8G内存的机器，堆内存设置4G到5G比较合理，剩下的内存留给Netty的堆外内存和操作系统缓存。

Netty本身也涉及堆外内存管理。默认的PooledByteBufAllocator会维护一组内存池，这里有一个常见问题：如果堆外内存被耗尽，Netty会抛出OutOfDirectMemoryError。出现这个错误时，先看Netty的-Dio.netty.maxDirectMemory配置，如果手动设置过，要确保它小于JVM的MaxDirectMemorySize；如果没设置过，检查是否有忘记释放的ByteBuf，把-Dio.netty.leakDetection.level=advanced打开抓内存泄漏。

5.2 压测方案与结果分析

我在压测时用的工具是JMeter加WebSocket插件，配合一个自研的模拟客户端脚本。这里推荐一个压测思路：不要只测单纯的消息吞吐量，要模拟真实场景——一定比例的连接在发消息，一定比例的连接在空闲心跳，一定比例的连接在频繁连接/断开。

我实测的一个数据供参考：4核8G的云主机，部署Netty服务单节点，每个连接每5秒发一条心跳消息，每30秒发一条业务消息，没有消息落库，纯网络转发。连接数从2000逐步加到6000，CPU利用率稳定在60%~70%，消息延迟P99在80ms以内。如果开启MySQL异步落库，同样场景下连接数在4000以内时性能没有明显退化，超过4000后数据库批量写入成为瓶颈，需要把落库消费者独立部署成单独服务。

压测时最常踩的坑是操作系统层限制。Linux系统默认的文件描述符上限是1024，如果你不修改就直接压测，连接数到1000多就会报Too many open files。要先执行ulimit -n 65535修改当前会话的限制，同时在/etc/security/limits.conf里添加持久化配置。另外，TCP的time_wait状态积压也会导致新连接建立失败，需要调整内核参数：

bash复制net.ipv4.tcp_tw_reuse = 1
net.ipv4.ip_local_port_range = 1024 65000
net.core.somaxconn = 4096

5.3 Netty的内存泄漏排查

Netty的内存泄漏是项目上线的最大隐患之一，因为很多情况下不是立刻出问题，而是随着运行时间增长慢慢耗尽内存。最常见的原因是开发者在自定义Handler里拿了ByteBuf的数据，但忘记释放。

如果你在Handler里处理消息时用了msg instanceof ByteBuf的写法，处理完必须调用ReferenceCountUtil.release(msg)或ByteBufUtil.release(msg)。使用DelimiterBasedFrameDecoder这类解码器时，解码产出的ByteBuf已经是被Netty管理的，业务Handler在消费完数据后要负责释放。

java复制@Override
public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception {
    if (msg instanceof ByteBuf) {
        ByteBuf buf = (ByteBuf) msg;
        try {
            byte[] data = new byte[buf.readableBytes()];
            buf.readBytes(data);
            // 处理数据
        } finally {
            ReferenceCountUtil.release(buf);
        }
    } else {
        // 其它消息类型，业务对象，Netty会负责回收
        ctx.fireChannelRead(msg);
    }
}

我用过Netty自带的泄露检测器，-Dio.netty.leakDetection.level=paranoid，它能精确到字节码级别，但性能开销较大，只适合本地测试。线上环境建议改成advanced级别，它能在日志里打印出疑似泄漏点的分配位置。如果线上实在查不出，就把堆内存dump下来，配合MAT分析ByteBuf对象分布，一般能定位到异常增长的Class。

6. 常见问题与排查技巧实录

实际维护这个系统的过程中，我遇到并解决过不少问题，挑几个典型的写下来，大家遇到类似问题可以直接对照排查。

6.1 Netty服务启动后，客户端连接不上

最常见的原因有三类：一是Spring Boot的端口和Netty的端口冲突，比如Spring Boot配置了8080，Netty服务也默认监听8080，启动时后一个组件会报Address already in use。检查方式很简单，lsof -i:端口号看哪个进程占用了端口。

二是云服务器的安全组没有放行Netty端口。这种情况在本地测试正常，部署到云服务器后连不上。排查顺序：先在本机执行telnet 服务器IP 端口，超时说明防火墙或安全组拦截。三是客户端连接时用的IP地址是内网IP，但服务端实际监听的是公网IP，这种情况在NAT环境下经常出现，建议Netty服务端监听0.0.0.0，让所有网络接口都能接收连接。

6.2 Spring Boot后台拿到了消息，但前端收不到

这个问题的定位路径比较固定。先看Netty服务端日志，确认消息是否已经成功写入Channel。如果写入了，再看Channel是哪种类型的连接，WebSocket连接必须通过WebSocketFrame发送数据，如果误用了普通的ByteBuf发送，浏览器收到的是无法解析的二进制帧，前端表现就是收不到消息。

还有一次我排查了很久的问题：客服端能收到消息但消息内容全是乱码。最后发现是消息编码时用了本地字符集，而客户端解码用的是UTF-8。这里提醒不要依赖系统默认字符集，编解码必须显式指定UTF-8。

java复制// 正确做法，编码时显式指定字符集
Unpooled.copiedBuffer(messageJson, CharsetUtil.UTF_8);
// 而不是
Unpooled.copiedBuffer(messageJson);
// 后者会使用平台默认字符集，一旦服务器和客户端字符集不一致就出乱码

6.3 数据库连接池被占满

在线客服系统的消息写入是高频操作，如果每个消息都单独从连接池取一个连接，高并发下连接数很容易被打满。我换成了前面说的批量异步落库方案后，这个问题就解决了，但批量操作本身又引入了新问题：如果池子大小设置太小，批量插入时可能因为获取不到连接而失败。我调整了HikariCP的配置：

yaml复制spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000
      max-lifetime: 1800000

connection-timeout设置成3秒，避免批量插入时线程无限等待。maximum-pool-size对于单机客服系统20个连接足够，不需要调的很大，因为MySQL对并发连接数也有上限，过多的连接反而增加数据库端的上下文切换开销。

6.4 SQL执行超时的真相：谁在管SQL的10秒超时

有同学问过一个问题：“JVM或者Spring Boot会设置一个SQL执行10秒自动关闭吗？”这个问题背后往往对应一个真实场景：某条慢SQL执行很久，最后报了一个TimeoutException或CommunicationsException。

我实际排查后发现，Spring Boot本身不会给你的SQL设置统一的10秒超时，10秒这个数字很可能来自三个地方：一是MySQL本身的net_read_timeout和net_write_timeout默认不是10秒，而是30秒；二是HikariCP的connection-timeout默认值是30秒，如果你设置了10秒，那可能是自定义配置；三是MyBatis或JDBC驱动层面的socketTimeout设置。

要定位真正的超时来源，要看完整的异常堆栈：如果是java.sql.SQLTimeoutException，多半是JDBC的queryTimeout或statementTimeout；如果是CommunicationsException: The last packet successfully received from the server was...，大概率是MySQL服务端的wait_timeout把空闲连接断了，连接池里的旧连接还在用，导致第一次操作时连接已失效。建议启动参数加上autoReconnect=true，或者连接池开启connection-test-query检测连接有效性。

6.5 客服端Web页面偶发断连

这个现象排查起来有点折磨人，因为断连不是持续性的，而是偶发性的。后来我抓了客户端日志，发现每次断连前都有一段较长的空闲时间，超过60秒没有消息和心跳。问题出在浏览器的WebSocket机制上：浏览器页面在后台Tab时，JS定时器会被浏览器节流，心跳发送间隔被拉长到几十秒，超过了服务端的空闲检测阈值，服务端判定连接超时并关闭。

解决思路是让服务端的心跳检测策略更宽容一些，把读空闲超时从60秒调整到90秒或120秒，同时客户端监听页面可见性变化，页面切换到后台时立即补发一个心跳包，页面回到前台时主动检测WebSocket状态并重新连接。做好这些之后，断连频率明显下降。

7. 一些过来人的经验和建议

最后聊几点运维和迭代层面的体会。

第一，客服系统上线后，一定要做好消息日志的可观测性。每条消息在Netty入站、Spring Boot处理、MySQL落库、出站推送几个关键节点都打印一条带消息ID的日志。这样用户说“我发的消息客服没收到”时，你可以直接根据消息ID在日志链路里定位是哪一步丢了，而不是靠猜。我见过太多团队上线客服系统后连日志都懒得打，出了问题只能重启服务，这对用户体验伤害非常大。

第二，消息内容和敏感信息审计要提前规划。客服会话内容会涉及用户隐私、订单信息甚至支付信息，系统上线前就要考虑敏感数据脱敏和操作审计。数据库里的聊天记录，具备访问权限的人能直接看到明文，这是一个安全隐患。我建议对消息表的content字段做数据库字段级加密，查询时再解密，对客服后台导出聊天记录的功能做权限审批和操作留痕。

第三，如果业务量增长到一定规模，可以考虑把Netty服务独立成集群，通过Nginx的TCP代理做负载均衡，再用Redis的Pub/Sub做跨节点的消息转发。因为单机Netty的承载能力再强也有上限，而客服系统的在线用户量往往在搞一次活动、一个促销节点突然暴涨。提前规划好水平扩展方案，比到时候手忙脚乱重新设计要好得多。

这套系统的设计和实现，覆盖了从实时通信、消息存储到业务路由的完整链路，技术栈本身不算前沿，但足够解决真实业务问题。拿到源码后，我建议你从Netty的接入层开始读，理解每一条Handler的作用，再顺着消息流转路径看业务层如何配合，最后研究MySQL表结构和异步落库的细节。把这条链路跑通、跑稳，在线客服系统的核心能力也就掌握了。