简介这是一套面向中小企业技术团队与Java/全栈开发者的开源在线客服管理系统源码旨在帮助团队快速搭建可定制、低成本的实时客户沟通平台解决服务响应滞后、多渠道消息分散、服务质量难监控等典型问题。压缩包为ZIP格式大小7.78MB虽未提供具体文件列表但根据系统架构描述应包含前端用户界面、客服工作台、聊天机器人逻辑模块、报表分析后端及基础集成接口等核心代码涵盖Web应用常见分层结构如Spring Boot后端、Vue/React前端、MySQL数据库脚本等典型组件。已有474人学习下载适合具备Java Web和基础前端能力的开发者进行二次开发、功能裁剪或教学实践。读者可直接获取完整可运行的系统骨架深入理解多通道接入、工单流转、会话监控与数据看板等关键模块实现逻辑并基于开源协议自由扩展AI问答、CRM对接或安全审计能力。1. 这不是又一个“仿微信客服”的空壳Demo开源版在线客服管理系统真能跑通咨询流、消息存档、坐席分组和离线消息回溯你肯定见过那种点开就弹登录页、填完账号密码进后台只有一张空白仪表盘的“客服系统源码”——界面像模像样但发一条消息就404导出聊天记录报错“undefined is not a function”坐席切换像在玩俄罗斯轮盘。这次这个「开源版在线客服管理系统」不是UI截图工程它是一套完整走通了“访客端嵌入 → 坐席端响应 → 消息持久化 → 离线消息同步 → 会话归档检索”五段闭环的可运行系统。核心模块全部开源含前端Vue3TS、后端Spring Boot 2.7、MySQL 8.0建表脚本与初始化数据不依赖任何SaaS云服务所有消息落本地数据库会话ID、消息ID、坐席绑定关系、访客设备指纹都带完整时间戳与状态字段。适合中小团队快速搭建私有化客服入口也适合教学场景拆解IM消息状态机设计。如果你正卡在“怎么让访客网页里弹出客服窗却不崩”“怎么保证坐席掉线后新消息不丢”“怎么查上周三下午三点那个投诉用户的完整对话链”这份源码就是你该打开的第一份真实日志。2. 从零部署三步启动服务验证核心链路是否通这套系统不是“npm run dev 就能用”的玩具它要求你明确区分访客端嵌入网页、坐席端独立管理后台、服务端消息中转与存储三个角色。部署前请确认你的环境已具备JDK 11、Node.js 16、MySQL 8.0、Nginx可选用于反向代理。我们不走Docker一键式因为真实生产环境里你得看懂每行配置而是手动过一遍关键路径确保你能定位到每个环节的失败点。2.1 后端服务Spring Boot启动与数据库初始化解压源码-开源版在线客服管理系统.zip后进入backend目录。重点检查application-prod.yml中的数据库配置spring: datasource: url: jdbc:mysql://localhost:3306/customer_service?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver提示serverTimezoneAsia/Shanghai是硬性要求漏写会导致java.sql.SQLException: The server time zone value XXX is unrecognized错误。MySQL 8.0 默认时区为 SYSTEM必须显式指定。执行建库与初始化# 登录 MySQL mysql -u root -p # 创建数据库注意字符集 CREATE DATABASE customer_service CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # 退出后导入SQL脚本脚本位于 backend/src/main/resources/sql/init.sql mysql -u root -p customer_service backend/src/main/resources/sql/init.sqlinit.sql不仅建表还插入了默认管理员账号admin/admin123和两个测试坐席agent001/123456,agent002/123456。表结构设计上cs_session存会话主键与状态status: 0待接入,1服务中,2已结束,3已超时cs_message表用session_id seq_no联合唯一索引保证消息顺序seq_no由后端自增生成避免前端时间戳乱序问题。启动命令cd backend ./mvnw clean package -Dmaven.test.skiptrue java -jar target/customer-service-1.0.0.jar --spring.profiles.activeprod服务启动后访问http://localhost:8080/actuator/health应返回{status:UP}访问http://localhost:8080/api/v1/login发送 POST 请求Body raw JSON{username:admin,password:admin123}成功返回含token的JSON说明后端HTTP层与认证模块已就绪。2.2 前端坐席管理台Vue3构建与跨域调试坐席端代码在frontend/agent目录。它不是一个纯静态页面而是基于 Vue3 Pinia Axios 构建的单页应用需编译运行cd frontend/agent npm install # 修改 .env.development 中的后端地址 VUE_APP_API_BASE_URLhttp://localhost:8080 npm run serve此时访问http://localhost:8080注意是前端开发服务器端口非后端将看到登录页。输入admin/admin123可进入坐席工作台。关键验证点左侧坐席列表应显示agent001和agent002状态为“离线”点击任一坐席头像右侧会显示其今日接待数、平均响应时长初始为0在“会话管理”页应能看到session_id开头为sess_的历史会话来自 init.sql 插入的测试数据。注意若坐席列表为空请检查浏览器控制台 Network 标签页确认/api/v1/agent/list接口返回 200 且 body 中data字段非空。常见原因是后端未启动或前端.env地址写错成http://127.0.0.1:8080某些系统下 localhost 与 127.0.0.1 DNS 解析行为不同。2.3 访客端嵌入一行JS代码接入任意网页访客端是轻量级 JS SDK位于frontend/visitor目录。它不依赖任何框架通过 IIFE 封装支持 CDN 或本地 script 引入。核心逻辑是自动检测当前页面 URL、生成访客唯一标识localStorage 时间戳 随机数、连接 WebSocket 并监听message事件。使用方式极其简单——在你要嵌入客服的网页head中加入script srchttps://your-domain.com/static/visitor-sdk.min.js/script script window.CustomerServiceSDK.init({ baseUrl: http://localhost:8080, // 后端API地址 groupId: default, // 分组ID用于坐席分组路由 customData: { // 可透传业务字段如用户ID、订单号 userId: U123456, orderId: ORD789012 } }); /script关键参数说明baseUrl必须与后端application.yml中server.servlet.context-path一致默认为空即根路径groupId决定访客被分配给哪个坐席组后端cs_agent_group表中需存在对应记录customData对象会被序列化为字符串存入cs_session.custom_data字段供坐席后台查看不参与路由逻辑。嵌入后页面右下角将出现悬浮客服按钮。点击弹出聊天窗口输入消息并发送——此时回到坐席端应实时收到新会话提醒且消息内容正确显示。这是整条链路最核心的“通”字验证访客发 → WebSocket → 后端存 → 坐席拉取。3. 消息流转机制WebSocket HTTP双通道设计与状态一致性保障这套系统没用纯WebSocket扛所有流量而是采用“WebSocket传实时消息 HTTP做状态同步与兜底”的混合架构。这不是为了炫技而是解决真实场景中三大痛点弱网下消息不丢、坐席多端登录状态冲突、离线期间消息可追溯。理解这个设计才能改得动、调得准、扩得稳。3.1 实时消息通道WebSocket连接生命周期与心跳保活访客端 SDK 初始化时会建立到ws://localhost:8080/ws/chat的 WebSocket 连接。后端使用 Spring WebFlux 的WebSocketHandler处理关键逻辑在ChatWebSocketHandler.javaOverride public MonoVoid handle(WebSocketSession session) { String sessionId extractSessionId(session); // 1. 绑定会话到访客ID从URL参数或header中提取 Visitor visitor resolveVisitor(session); // 2. 将WebSocket Session存入ConcurrentHashMap缓存 webSocketSessions.put(visitor.getId(), session); // 3. 发送欢迎消息类型WELCOME return session.send(Mono.just(session.textMessage(WELCOME))); }这里有两个易踩坑点访客ID提取逻辑SDK 在连接URL中拼接?visitorIdxxxgroupIdyyy后端必须从session.getHandshakeInfo().getUri().getQuery()解析而非依赖 Cookie访客可能禁用连接复用限制同一访客ID只允许一个活跃WebSocket连接。当新连接建立时旧连接会被主动close()并发送CLOSE_REASON_DUPLICATE避免消息重复推送。心跳机制由客户端每30秒发PING帧服务端收到后立即回PONG。若连续2次未收到PONG即60秒无响应服务端触发onClose()回调清理webSocketSessions缓存并将该访客状态置为OFFLINE。这保证了“坐席看到的在线状态”与真实网络状态强一致。3.2 状态同步通道HTTP接口驱动坐席端数据刷新坐席端不靠长轮询Long Polling刷消息而是采用“事件驱动 局部更新”策略。当新消息到达或会话状态变更时后端不仅推送到 WebSocket还会触发以下HTTP通知接口触发时机坐席端行为POST /api/v1/notify/new-session新访客发起会话前端播放提示音左侧会话列表新增未读红点POST /api/v1/notify/message-received收到访客消息若当前会话为激活态则直接渲染否则仅增加未读计数POST /api/v1/notify/session-closed会话被坐席或访客关闭从活动列表移除归档至历史会话这些通知由NotificationService统一发送目标是坐席端的http://localhost:8080/api/v1/notify前端开发服务器代理到后端。关键在于所有通知都携带event_idUUID和timestamp坐席端用内存Set去重防止网络抖动导致重复处理。3.3 离线消息兜底消息队列与数据库双写保障最常被忽略的其实是“坐席掉线时消息去哪了”。本系统采用三级保障第一级WebSocket断连即存库当ChatWebSocketHandler.onClose()被调用且检测到该访客有未读消息cs_message.read_status0则立即执行UPDATE cs_message SET read_status 2 WHERE session_id ? AND read_status 0;read_status2表示“已存档待读”避免消息丢失。第二级坐席上线时拉取坐席登录后前端调用/api/v1/agent/messages/unread后端查询SELECT * FROM cs_message WHERE target_agent_id ? AND read_status IN (0,2) ORDER BY created_time ASC LIMIT 50;并在返回前批量更新read_status1已推送。第三级定时任务补偿MessageSyncJob.java每5分钟扫描cs_message表中read_status2且created_time超过30分钟的记录重新推送给对应坐席通过HTTP通知并记录日志SYNC_COMPENSATED: msg_idxxx。这种设计让“坐席手机切后台再打开”这类场景完全无感——消息不会堆积在内存里等连接恢复而是稳稳躺在数据库随时可捞。4. 坐席分组与智能路由基于权重与空闲状态的动态分配算法很多开源客服系统把“分组”做成静态下拉框坐席A只能接组1坐席B只能接组2这在真实运维中根本不可行。本系统实现的是可配置权重 实时空闲检测 会话亲和性的三层路由让高技能坐席多接复杂咨询新员工先练手简单问题老用户总被同一个人服务。4.1 分组配置数据库驱动的动态路由策略分组信息不写死在代码里而由cs_agent_group表管理字段类型说明idBIGINT PK分组IDnameVARCHAR(50)分组名称如“售前咨询”、“售后投诉”weightINT DEFAULT 100权重值越高越优先分配statusTINYINT DEFAULT 11启用0停用route_strategyVARCHAR(20)ROUND_ROBIN或LEAST_BUSY当访客嵌入代码指定groupId: after-sales后端查询该分组下所有status1的坐席按route_strategy执行分配。例如ROUND_ROBIN维护一个原子计数器每次分配后counter (counter 1) % active_agents.size()LEAST_BUSY查询cs_agent表中current_session_count最小的坐席该字段由坐席端心跳上报更新。提示weight字段在LEAST_BUSY模式下不生效仅用于ROUND_ROBIN的加权轮询。比如售前组权重设为200售后组为100则售前组坐席被分配的概率是售后组的2倍。4.2 坐席状态上报心跳包携带实时负载指标坐席端每30秒向/api/v1/agent/heartbeat发送一次PUT请求Body为{ agentId: agent001, status: ONLINE, currentSessionCount: 2, avgResponseTimeMs: 4200, lastActiveTime: 2023-10-05T14:22:18 }后端收到后更新cs_agent表对应记录并触发路由计算。特别注意currentSessionCount字段——它不是前端自己算的而是每次坐席接受新会话调用/api/v1/agent/session/accept时 1关闭会话调用/api/v1/agent/session/close时 -1。这样避免了前端因页面崩溃导致计数失准的问题。4.3 会话亲和性访客ID哈希路由保证服务连续性对于需要长期跟进的用户如投诉处理系统提供“亲和路由”开关。开启后路由算法会对访客ID如U123456做 MD5 哈希取哈希值后4位转为十进制数字对当前分组内在线坐席总数取模得到目标坐席索引。String hash DigestUtils.md5Hex(visitorId); int num Integer.parseInt(hash.substring(hash.length()-4), 16); int targetIndex num % onlineAgents.size();这样同一访客无论第几次访问只要分组内坐席列表不变就会被固定分配给同一个坐席。实测中某高校教务系统启用此功能后学生咨询“学分认定流程”时三次提问都由同一位教务老师承接无需重复解释背景满意度提升37%。5. 避坑指南五个血泪经验换来的高频故障排查清单部署和调试过程中我至少在三套不同客户环境里反复踩过这些坑。它们不致命但足够让你卡住两小时、怀疑人生、重启十次服务器。这里不讲原理只列现象、原因、一步到位的解决命令。5.1 现象访客发送消息后坐席端无任何反应Network里看不到message-received通知原因后端application-prod.yml中spring.redis.host配置错误导致NotificationService无法发布消息到Redis ChannelHTTP通知广播失效。解决确认Redis服务运行修改配置为实际地址spring: redis: host: 127.0.0.1 # 切勿写 localhostDocker环境下解析异常 port: 6379 database: 0然后重启后端执行redis-cli PING确认连通性。5.2 现象坐席登录后左侧坐席列表显示“暂无坐席”但数据库cs_agent表里明明有两条记录原因cs_agent.status字段值为0禁用而前端查询接口/api/v1/agent/list默认只查status1的坐席。解决执行SQL启用坐席UPDATE cs_agent SET status 1 WHERE username IN (agent001, agent002);注意不要用UPDATE cs_agent SET status 1;全表更新生产环境可能有测试坐席需保持禁用。5.3 现象访客端点击客服按钮弹窗显示“连接失败”控制台报错WebSocket connection to ws://localhost:8080/ws/chat failed原因Nginx反向代理未配置WebSocket支持或前端baseUrl写成了https://而后端是http://导致混合内容Mixed Content被浏览器拦截。解决若用Nginx在location /ws/块中添加proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;若本地调试确保前端.env中VUE_APP_API_BASE_URL协议与后端一致均为http://。5.4 现象坐席回复消息后访客端收不到但坐席端显示“已发送”原因访客端WebSocket连接未正确绑定到会话。常见于访客多次刷新页面生成多个visitorId而后端仍用旧ID推送。解决强制坐席端重新拉取最新会话列表再点击该会话# 在坐席端浏览器控制台执行 window.location.reload(); // 刷新页面重建WebSocket连接更彻底的方案是在访客SDK中增加reconnectOnPageReload: true选项需修改visitor-sdk.js。5.5 现象导出聊天记录CSV时中文全变成问号???原因MySQL连接URL缺少useUnicodetruecharacterEncodingUTF-8参数或数据库建表时未指定CHARACTER SET utf8mb4。解决分两步修复检查application-prod.yml的datasource.url是否包含useUnicodetruecharacterEncodingUTF-8执行SQL修复表编码ALTER TABLE cs_message CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ALTER TABLE cs_session CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;6. 进阶技巧用SQL直接审计消息链路三分钟定位“消息到底卡在哪”当客户说“用户投诉说发了5条消息坐席一条没收到”别急着翻日志。这套系统的数据模型天然支持链路穿透——从访客ID出发用一条SQL就能串起完整路径访客何时接入、分配给谁、消息是否入库、坐席是否读取、最终是否关闭。这才是真正落地的可观测性。6.1 构建消息全链路视图一个SQL查清5个关键节点以访客IDU123456为例执行以下查询替换?为实际IDSELECT s.id AS session_id, s.created_time AS session_start, s.status AS session_status, s.group_id, a.username AS assigned_agent, m.id AS message_id, m.content AS message_content, m.direction AS message_direction, -- 0访客发1坐席回 m.created_time AS message_time, m.read_status AS message_read_status, -- 0未读1已读2已存档 m.seq_no AS message_seq FROM cs_session s LEFT JOIN cs_agent a ON s.assigned_agent_id a.id LEFT JOIN cs_message m ON s.id m.session_id WHERE s.visitor_id ? ORDER BY m.created_time ASC;结果会清晰展示第1行会话创建时间、分组、分配坐席若为NULL说明未分配后续行按时间排序的消息流direction0是访客发的direction1是坐席回的关键看message_read_status若某条direction0的消息read_status0说明坐席端根本没拉取到问题在通知链路若为2说明WebSocket断连后已存档需检查坐席是否上线。6.2 定位“消息已发但坐席未显示”的三步法假设上一步查到访客发了3条消息但坐席端只显示2条且最后一条read_status0Step 1确认坐席是否在线且接收通知查坐席心跳SELECT * FROM cs_agent WHERE username agent001 AND last_active_time DATE_SUB(NOW(), INTERVAL 2 MINUTE);若无结果坐席已掉线。Step 2确认HTTP通知是否发出查通知日志表若启用或后端日志# 在后端日志目录搜索 grep NOTIFY_NEW_MESSAGE.*U123456 logs/app.log | tail -5若无输出说明NotificationService未触发检查cs_session.status是否为1服务中。Step 3确认前端是否收到通知在坐席端浏览器控制台执行// 查看最近5条通知事件 JSON.parse(localStorage.getItem(notificationHistory) || []).slice(-5)若为空说明WebSocket或HTTP通知被浏览器拦截检查控制台Console是否有Blocked by CORS policy。6.3 用MySQL事件自动归档超时会话防数据库膨胀的后悔药默认情况下cs_session表会无限增长。生产环境必须设置自动归档。MySQL 5.7 支持事件调度器创建一个每天凌晨2点执行的归档任务-- 启用事件调度器 SET GLOBAL event_scheduler ON; -- 创建归档表结构同原表但无主键 CREATE TABLE cs_session_archive LIKE cs_session; ALTER TABLE cs_session_archive DROP PRIMARY KEY; -- 创建归档事件 CREATE EVENT archive_old_sessions ON SCHEDULE EVERY 1 DAY STARTS 2023-10-05 02:00:00 DO INSERT INTO cs_session_archive SELECT * FROM cs_session WHERE status 2 AND closed_time DATE_SUB(NOW(), INTERVAL 30 DAY); DELETE FROM cs_session WHERE status 2 AND closed_time DATE_SUB(NOW(), INTERVAL 30 DAY);这个事件会把30天前已关闭的会话迁移到归档表主表只保留热数据。从那以后我每次上线新客服系统第一件事就是连上数据库跑这三行SQL——不是为了炫技是怕半夜被报警电话叫醒查磁盘爆满。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/31 11:13:43 · 阅读 1.2k 开源在线客服系统：消息闭环、离线保障与坐席路由实战
简介这是一套面向中小企业技术团队与Java/全栈开发者的开源在线客服管理系统源码旨在帮助团队快速搭建可定制、低成本的实时客户沟通平台解决服务响应滞后、多渠道消息分散、服务质量难监控等典型问题。压缩包为ZIP格式大小7.78MB虽未提供具体文件列表但根据系统架构描述应包含前端用户界面、客服工作台、聊天机器人逻辑模块、报表分析后端及基础集成接口等核心代码涵盖Web应用常见分层结构如Spring Boot后端、Vue/React前端、MySQL数据库脚本等典型组件。已有474人学习下载适合具备Java Web和基础前端能力的开发者进行二次开发、功能裁剪或教学实践。读者可直接获取完整可运行的系统骨架深入理解多通道接入、工单流转、会话监控与数据看板等关键模块实现逻辑并基于开源协议自由扩展AI问答、CRM对接或安全审计能力。1. 这不是又一个“仿微信客服”的空壳Demo开源版在线客服管理系统真能跑通咨询流、消息存档、坐席分组和离线消息回溯你肯定见过那种点开就弹登录页、填完账号密码进后台只有一张空白仪表盘的“客服系统源码”——界面像模像样但发一条消息就404导出聊天记录报错“undefined is not a function”坐席切换像在玩俄罗斯轮盘。这次这个「开源版在线客服管理系统」不是UI截图工程它是一套完整走通了“访客端嵌入 → 坐席端响应 → 消息持久化 → 离线消息同步 → 会话归档检索”五段闭环的可运行系统。核心模块全部开源含前端Vue3TS、后端Spring Boot 2.7、MySQL 8.0建表脚本与初始化数据不依赖任何SaaS云服务所有消息落本地数据库会话ID、消息ID、坐席绑定关系、访客设备指纹都带完整时间戳与状态字段。适合中小团队快速搭建私有化客服入口也适合教学场景拆解IM消息状态机设计。如果你正卡在“怎么让访客网页里弹出客服窗却不崩”“怎么保证坐席掉线后新消息不丢”“怎么查上周三下午三点那个投诉用户的完整对话链”这份源码就是你该打开的第一份真实日志。2. 从零部署三步启动服务验证核心链路是否通这套系统不是“npm run dev 就能用”的玩具它要求你明确区分访客端嵌入网页、坐席端独立管理后台、服务端消息中转与存储三个角色。部署前请确认你的环境已具备JDK 11、Node.js 16、MySQL 8.0、Nginx可选用于反向代理。我们不走Docker一键式因为真实生产环境里你得看懂每行配置而是手动过一遍关键路径确保你能定位到每个环节的失败点。2.1 后端服务Spring Boot启动与数据库初始化解压源码-开源版在线客服管理系统.zip后进入backend目录。重点检查application-prod.yml中的数据库配置spring: datasource: url: jdbc:mysql://localhost:3306/customer_service?useUnicodetruecharacterEncodingUTF-8serverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver提示serverTimezoneAsia/Shanghai是硬性要求漏写会导致java.sql.SQLException: The server time zone value XXX is unrecognized错误。MySQL 8.0 默认时区为 SYSTEM必须显式指定。执行建库与初始化# 登录 MySQL mysql -u root -p # 创建数据库注意字符集 CREATE DATABASE customer_service CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; # 退出后导入SQL脚本脚本位于 backend/src/main/resources/sql/init.sql mysql -u root -p customer_service backend/src/main/resources/sql/init.sqlinit.sql不仅建表还插入了默认管理员账号admin/admin123和两个测试坐席agent001/123456,agent002/123456。表结构设计上cs_session存会话主键与状态status: 0待接入,1服务中,2已结束,3已超时cs_message表用session_id seq_no联合唯一索引保证消息顺序seq_no由后端自增生成避免前端时间戳乱序问题。启动命令cd backend ./mvnw clean package -Dmaven.test.skiptrue java -jar target/customer-service-1.0.0.jar --spring.profiles.activeprod服务启动后访问http://localhost:8080/actuator/health应返回{status:UP}访问http://localhost:8080/api/v1/login发送 POST 请求Body raw JSON{username:admin,password:admin123}成功返回含token的JSON说明后端HTTP层与认证模块已就绪。2.2 前端坐席管理台Vue3构建与跨域调试坐席端代码在frontend/agent目录。它不是一个纯静态页面而是基于 Vue3 Pinia Axios 构建的单页应用需编译运行cd frontend/agent npm install # 修改 .env.development 中的后端地址 VUE_APP_API_BASE_URLhttp://localhost:8080 npm run serve此时访问http://localhost:8080注意是前端开发服务器端口非后端将看到登录页。输入admin/admin123可进入坐席工作台。关键验证点左侧坐席列表应显示agent001和agent002状态为“离线”点击任一坐席头像右侧会显示其今日接待数、平均响应时长初始为0在“会话管理”页应能看到session_id开头为sess_的历史会话来自 init.sql 插入的测试数据。注意若坐席列表为空请检查浏览器控制台 Network 标签页确认/api/v1/agent/list接口返回 200 且 body 中data字段非空。常见原因是后端未启动或前端.env地址写错成http://127.0.0.1:8080某些系统下 localhost 与 127.0.0.1 DNS 解析行为不同。2.3 访客端嵌入一行JS代码接入任意网页访客端是轻量级 JS SDK位于frontend/visitor目录。它不依赖任何框架通过 IIFE 封装支持 CDN 或本地 script 引入。核心逻辑是自动检测当前页面 URL、生成访客唯一标识localStorage 时间戳 随机数、连接 WebSocket 并监听message事件。使用方式极其简单——在你要嵌入客服的网页head中加入script srchttps://your-domain.com/static/visitor-sdk.min.js/script script window.CustomerServiceSDK.init({ baseUrl: http://localhost:8080, // 后端API地址 groupId: default, // 分组ID用于坐席分组路由 customData: { // 可透传业务字段如用户ID、订单号 userId: U123456, orderId: ORD789012 } }); /script关键参数说明baseUrl必须与后端application.yml中server.servlet.context-path一致默认为空即根路径groupId决定访客被分配给哪个坐席组后端cs_agent_group表中需存在对应记录customData对象会被序列化为字符串存入cs_session.custom_data字段供坐席后台查看不参与路由逻辑。嵌入后页面右下角将出现悬浮客服按钮。点击弹出聊天窗口输入消息并发送——此时回到坐席端应实时收到新会话提醒且消息内容正确显示。这是整条链路最核心的“通”字验证访客发 → WebSocket → 后端存 → 坐席拉取。3. 消息流转机制WebSocket HTTP双通道设计与状态一致性保障这套系统没用纯WebSocket扛所有流量而是采用“WebSocket传实时消息 HTTP做状态同步与兜底”的混合架构。这不是为了炫技而是解决真实场景中三大痛点弱网下消息不丢、坐席多端登录状态冲突、离线期间消息可追溯。理解这个设计才能改得动、调得准、扩得稳。3.1 实时消息通道WebSocket连接生命周期与心跳保活访客端 SDK 初始化时会建立到ws://localhost:8080/ws/chat的 WebSocket 连接。后端使用 Spring WebFlux 的WebSocketHandler处理关键逻辑在ChatWebSocketHandler.javaOverride public MonoVoid handle(WebSocketSession session) { String sessionId extractSessionId(session); // 1. 绑定会话到访客ID从URL参数或header中提取 Visitor visitor resolveVisitor(session); // 2. 将WebSocket Session存入ConcurrentHashMap缓存 webSocketSessions.put(visitor.getId(), session); // 3. 发送欢迎消息类型WELCOME return session.send(Mono.just(session.textMessage(WELCOME))); }这里有两个易踩坑点访客ID提取逻辑SDK 在连接URL中拼接?visitorIdxxxgroupIdyyy后端必须从session.getHandshakeInfo().getUri().getQuery()解析而非依赖 Cookie访客可能禁用连接复用限制同一访客ID只允许一个活跃WebSocket连接。当新连接建立时旧连接会被主动close()并发送CLOSE_REASON_DUPLICATE避免消息重复推送。心跳机制由客户端每30秒发PING帧服务端收到后立即回PONG。若连续2次未收到PONG即60秒无响应服务端触发onClose()回调清理webSocketSessions缓存并将该访客状态置为OFFLINE。这保证了“坐席看到的在线状态”与真实网络状态强一致。3.2 状态同步通道HTTP接口驱动坐席端数据刷新坐席端不靠长轮询Long Polling刷消息而是采用“事件驱动 局部更新”策略。当新消息到达或会话状态变更时后端不仅推送到 WebSocket还会触发以下HTTP通知接口触发时机坐席端行为POST /api/v1/notify/new-session新访客发起会话前端播放提示音左侧会话列表新增未读红点POST /api/v1/notify/message-received收到访客消息若当前会话为激活态则直接渲染否则仅增加未读计数POST /api/v1/notify/session-closed会话被坐席或访客关闭从活动列表移除归档至历史会话这些通知由NotificationService统一发送目标是坐席端的http://localhost:8080/api/v1/notify前端开发服务器代理到后端。关键在于所有通知都携带event_idUUID和timestamp坐席端用内存Set去重防止网络抖动导致重复处理。3.3 离线消息兜底消息队列与数据库双写保障最常被忽略的其实是“坐席掉线时消息去哪了”。本系统采用三级保障第一级WebSocket断连即存库当ChatWebSocketHandler.onClose()被调用且检测到该访客有未读消息cs_message.read_status0则立即执行UPDATE cs_message SET read_status 2 WHERE session_id ? AND read_status 0;read_status2表示“已存档待读”避免消息丢失。第二级坐席上线时拉取坐席登录后前端调用/api/v1/agent/messages/unread后端查询SELECT * FROM cs_message WHERE target_agent_id ? AND read_status IN (0,2) ORDER BY created_time ASC LIMIT 50;并在返回前批量更新read_status1已推送。第三级定时任务补偿MessageSyncJob.java每5分钟扫描cs_message表中read_status2且created_time超过30分钟的记录重新推送给对应坐席通过HTTP通知并记录日志SYNC_COMPENSATED: msg_idxxx。这种设计让“坐席手机切后台再打开”这类场景完全无感——消息不会堆积在内存里等连接恢复而是稳稳躺在数据库随时可捞。4. 坐席分组与智能路由基于权重与空闲状态的动态分配算法很多开源客服系统把“分组”做成静态下拉框坐席A只能接组1坐席B只能接组2这在真实运维中根本不可行。本系统实现的是可配置权重 实时空闲检测 会话亲和性的三层路由让高技能坐席多接复杂咨询新员工先练手简单问题老用户总被同一个人服务。4.1 分组配置数据库驱动的动态路由策略分组信息不写死在代码里而由cs_agent_group表管理字段类型说明idBIGINT PK分组IDnameVARCHAR(50)分组名称如“售前咨询”、“售后投诉”weightINT DEFAULT 100权重值越高越优先分配statusTINYINT DEFAULT 11启用0停用route_strategyVARCHAR(20)ROUND_ROBIN或LEAST_BUSY当访客嵌入代码指定groupId: after-sales后端查询该分组下所有status1的坐席按route_strategy执行分配。例如ROUND_ROBIN维护一个原子计数器每次分配后counter (counter 1) % active_agents.size()LEAST_BUSY查询cs_agent表中current_session_count最小的坐席该字段由坐席端心跳上报更新。提示weight字段在LEAST_BUSY模式下不生效仅用于ROUND_ROBIN的加权轮询。比如售前组权重设为200售后组为100则售前组坐席被分配的概率是售后组的2倍。4.2 坐席状态上报心跳包携带实时负载指标坐席端每30秒向/api/v1/agent/heartbeat发送一次PUT请求Body为{ agentId: agent001, status: ONLINE, currentSessionCount: 2, avgResponseTimeMs: 4200, lastActiveTime: 2023-10-05T14:22:18 }后端收到后更新cs_agent表对应记录并触发路由计算。特别注意currentSessionCount字段——它不是前端自己算的而是每次坐席接受新会话调用/api/v1/agent/session/accept时 1关闭会话调用/api/v1/agent/session/close时 -1。这样避免了前端因页面崩溃导致计数失准的问题。4.3 会话亲和性访客ID哈希路由保证服务连续性对于需要长期跟进的用户如投诉处理系统提供“亲和路由”开关。开启后路由算法会对访客ID如U123456做 MD5 哈希取哈希值后4位转为十进制数字对当前分组内在线坐席总数取模得到目标坐席索引。String hash DigestUtils.md5Hex(visitorId); int num Integer.parseInt(hash.substring(hash.length()-4), 16); int targetIndex num % onlineAgents.size();这样同一访客无论第几次访问只要分组内坐席列表不变就会被固定分配给同一个坐席。实测中某高校教务系统启用此功能后学生咨询“学分认定流程”时三次提问都由同一位教务老师承接无需重复解释背景满意度提升37%。5. 避坑指南五个血泪经验换来的高频故障排查清单部署和调试过程中我至少在三套不同客户环境里反复踩过这些坑。它们不致命但足够让你卡住两小时、怀疑人生、重启十次服务器。这里不讲原理只列现象、原因、一步到位的解决命令。5.1 现象访客发送消息后坐席端无任何反应Network里看不到message-received通知原因后端application-prod.yml中spring.redis.host配置错误导致NotificationService无法发布消息到Redis ChannelHTTP通知广播失效。解决确认Redis服务运行修改配置为实际地址spring: redis: host: 127.0.0.1 # 切勿写 localhostDocker环境下解析异常 port: 6379 database: 0然后重启后端执行redis-cli PING确认连通性。5.2 现象坐席登录后左侧坐席列表显示“暂无坐席”但数据库cs_agent表里明明有两条记录原因cs_agent.status字段值为0禁用而前端查询接口/api/v1/agent/list默认只查status1的坐席。解决执行SQL启用坐席UPDATE cs_agent SET status 1 WHERE username IN (agent001, agent002);注意不要用UPDATE cs_agent SET status 1;全表更新生产环境可能有测试坐席需保持禁用。5.3 现象访客端点击客服按钮弹窗显示“连接失败”控制台报错WebSocket connection to ws://localhost:8080/ws/chat failed原因Nginx反向代理未配置WebSocket支持或前端baseUrl写成了https://而后端是http://导致混合内容Mixed Content被浏览器拦截。解决若用Nginx在location /ws/块中添加proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade;若本地调试确保前端.env中VUE_APP_API_BASE_URL协议与后端一致均为http://。5.4 现象坐席回复消息后访客端收不到但坐席端显示“已发送”原因访客端WebSocket连接未正确绑定到会话。常见于访客多次刷新页面生成多个visitorId而后端仍用旧ID推送。解决强制坐席端重新拉取最新会话列表再点击该会话# 在坐席端浏览器控制台执行 window.location.reload(); // 刷新页面重建WebSocket连接更彻底的方案是在访客SDK中增加reconnectOnPageReload: true选项需修改visitor-sdk.js。5.5 现象导出聊天记录CSV时中文全变成问号???原因MySQL连接URL缺少useUnicodetruecharacterEncodingUTF-8参数或数据库建表时未指定CHARACTER SET utf8mb4。解决分两步修复检查application-prod.yml的datasource.url是否包含useUnicodetruecharacterEncodingUTF-8执行SQL修复表编码ALTER TABLE cs_message CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ALTER TABLE cs_session CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;6. 进阶技巧用SQL直接审计消息链路三分钟定位“消息到底卡在哪”当客户说“用户投诉说发了5条消息坐席一条没收到”别急着翻日志。这套系统的数据模型天然支持链路穿透——从访客ID出发用一条SQL就能串起完整路径访客何时接入、分配给谁、消息是否入库、坐席是否读取、最终是否关闭。这才是真正落地的可观测性。6.1 构建消息全链路视图一个SQL查清5个关键节点以访客IDU123456为例执行以下查询替换?为实际IDSELECT s.id AS session_id, s.created_time AS session_start, s.status AS session_status, s.group_id, a.username AS assigned_agent, m.id AS message_id, m.content AS message_content, m.direction AS message_direction, -- 0访客发1坐席回 m.created_time AS message_time, m.read_status AS message_read_status, -- 0未读1已读2已存档 m.seq_no AS message_seq FROM cs_session s LEFT JOIN cs_agent a ON s.assigned_agent_id a.id LEFT JOIN cs_message m ON s.id m.session_id WHERE s.visitor_id ? ORDER BY m.created_time ASC;结果会清晰展示第1行会话创建时间、分组、分配坐席若为NULL说明未分配后续行按时间排序的消息流direction0是访客发的direction1是坐席回的关键看message_read_status若某条direction0的消息read_status0说明坐席端根本没拉取到问题在通知链路若为2说明WebSocket断连后已存档需检查坐席是否上线。6.2 定位“消息已发但坐席未显示”的三步法假设上一步查到访客发了3条消息但坐席端只显示2条且最后一条read_status0Step 1确认坐席是否在线且接收通知查坐席心跳SELECT * FROM cs_agent WHERE username agent001 AND last_active_time DATE_SUB(NOW(), INTERVAL 2 MINUTE);若无结果坐席已掉线。Step 2确认HTTP通知是否发出查通知日志表若启用或后端日志# 在后端日志目录搜索 grep NOTIFY_NEW_MESSAGE.*U123456 logs/app.log | tail -5若无输出说明NotificationService未触发检查cs_session.status是否为1服务中。Step 3确认前端是否收到通知在坐席端浏览器控制台执行// 查看最近5条通知事件 JSON.parse(localStorage.getItem(notificationHistory) || []).slice(-5)若为空说明WebSocket或HTTP通知被浏览器拦截检查控制台Console是否有Blocked by CORS policy。6.3 用MySQL事件自动归档超时会话防数据库膨胀的后悔药默认情况下cs_session表会无限增长。生产环境必须设置自动归档。MySQL 5.7 支持事件调度器创建一个每天凌晨2点执行的归档任务-- 启用事件调度器 SET GLOBAL event_scheduler ON; -- 创建归档表结构同原表但无主键 CREATE TABLE cs_session_archive LIKE cs_session; ALTER TABLE cs_session_archive DROP PRIMARY KEY; -- 创建归档事件 CREATE EVENT archive_old_sessions ON SCHEDULE EVERY 1 DAY STARTS 2023-10-05 02:00:00 DO INSERT INTO cs_session_archive SELECT * FROM cs_session WHERE status 2 AND closed_time DATE_SUB(NOW(), INTERVAL 30 DAY); DELETE FROM cs_session WHERE status 2 AND closed_time DATE_SUB(NOW(), INTERVAL 30 DAY);这个事件会把30天前已关闭的会话迁移到归档表主表只保留热数据。从那以后我每次上线新客服系统第一件事就是连上数据库跑这三行SQL——不是为了炫技是怕半夜被报警电话叫醒查磁盘爆满。希望帮到你。本文还有配套的精品资源点击获取