做在线客服系统这件事，我前前后后折腾了不少年。市面上现成的客服产品要么重得要命，部署一台机器都嫌挤；要么是商业SaaS，功能是齐全，但想改个欢迎语、接个内部工单系统，处处受限制。所以我一直很推崇那种“轻量高效、源码开放、适合学习和二次开发”的客服聊天系统，它不追求大而全，而是把核心链路做扎实，让开发者能看懂、能改动、能快速落地到自己的业务里。
这篇文章要聊的系统，正是这样一个方向：一套基于PHP/MySQL/WebSocket技术栈的在线客服聊天源码系统。它的核心价值不在于界面多华丽、功能多花哨，而在于“轻”和“可改”。对于想学习实时通信原理、想给自家网站加客服功能、或者想在这个基础上做企业级二次开发的团队，这套系统都是一个非常合适的起点。我的建议是，先顺着这篇文章把整体架构和核心代码逻辑捋清楚，再动手去改，会比直接拿到源码瞎改高效得多。
1. 整体设计思路：为什么说“轻量”才是核心竞争力
1.1 轻量化架构背后的取舍
我见过很多团队一上来就喊微服务、消息队列、分布式缓存，结果一个日活几千的客服功能，部署了六个节点，维护成本比功能本身还高。真正合适的方案，是回到业务的本质：客服系统的核心就是“访客发消息、客服回消息、双方都能实时收到”，把这个链路搞清楚，其他的都是锦上添花。
这个系统采用了非常务实的组合方案：
| 层级 | 选型 | 说明 |
|---|---|---|
| 后端语言 | PHP 7.4+ | 上手门槛低，二次开发劳动力充足 |
| 通信方案 | WebSocket (Workerman) | 真正实现服务端主动推送，实时性有保障 |
| 数据存储 | MySQL 5.7+ | 结构化数据天然友好，索引合理即可 |
| 前端 | 原生HTML/JavaScript | 不依赖重型框架，打开即用，改起来直观 |
| 部署 | Nginx + PHP-FPM | 经典组合，运维资料多，出问题容易排查 |
选PHP不是因为它性能最好，而是因为它在“二次开发”这个维度上有着独到的优势。国内大量开发者的第一门后端语言就是PHP，你找一个能改Java的人可能得等一周，但找一个能改PHP的人当天就能上手。轻量系统的核心逻辑是“让使用者能在这个代码库上快速工作”，而不是“让代码库在技术上显得很酷”。
WebSocket的选型也同理。很多人问为什么不用轮询、不用SSE。轮询的问题是延迟高且浪费资源，访客每两秒刷一次接口，服务器得白白扛一堆无效请求。SSE能做到服务器推流，但它是单向的，访客给客服发消息还得另外走HTTP接口，链路就劈成两半了。WebSocket是一次握手、双向通信，访客发消息和客服收消息在同一条连接上完成，代码逻辑连贯，实时性也最好。这个系统的核心通信就建立在这个机制上。
1.2 模块划分与目录结构：二次开发的第一印象
拿到源码后，第一件事就是看目录结构。一个适合二次开发的系统，目录结构必须“一眼就能看懂”，而不是把所有逻辑都堆在一个几百KB的index.php里。
online-chat-system/ ├── public/ # Web根目录（唯一对外暴露的目录） │ ├── index.php # 入口文件，路由分发 │ ├── visitor.html # 访客端页面 │ └── agent.html # 客服端页面 ├── app/ │ ├── Controllers/ # 控制器层（HTTP请求处理） │ │ ├── VisitorController.php │ │ └── AgentController.php │ ├── Models/ # 数据模型层（数据库操作） │ │ ├── SessionModel.php │ │ └── MessageModel.php │ └── Services/ # 业务逻辑层（核心规则） │ └── ChatService.php ├── socket/ │ └── server.php # WebSocket服务端（Workerman） ├── config/ │ └── config.php # 数据库、端口等配置 └── sql/ └── install.sql # 初始化建表脚本这个结构最重要的特点，是把“业务规则”和“页面展示”分开。Controllers只负责接收请求、调用Service、返回结果，不写任何业务逻辑；Models只负责和数据库打交道；真正的状态判断、会话分配、消息记录这些核心规则，全部收拢在ChatService里。二次开发的时候，改数据表就动Models，改业务规则就动Services，改页面就动HTML文件，互不干扰。
我见过很多“教不会”的源码，本质问题就是三层混在一起，想加个敏感词过滤，得在十几个文件里各插一段代码。而这套系统的分层，说白了就是让开发者知道“我该去哪里改”。对于一个以学习为目的的项目来说，这种清晰度的价值，远大于某些炫技的架构设计。
1.3 为什么轻量系统反而更适合做“地基”
很多团队问我，既然要做二次开发，为什么不直接买一套商业系统，或者用那种功能全部拉满的开源项目？我的回答是：要看你的目标是什么。如果你的目标是“上线一个能用的客服系统”，那商业SaaS确实省心；但如果你的目标是“做一套符合自身业务形态的客服系统”，那么一个清爽简洁的代码库，远比功能繁多但逻辑缠绕的巨型系统有价值。
轻量系统适合做地基，有三个原因。第一，复杂度可控。整个系统的代码量可能只有几千行，一个开发者一两天就能通读完成，这意味着后续任何修改都在你的掌控范围内。第二，问题可追踪。出bug的时候，你能很快定位到是通信问题、数据问题还是业务逻辑问题，而不是在一个庞然大物里面大海捞针。第三，扩展有空间。地基越是规整，往上加盖楼层就越轻松。加机器人、加工单、加数据统计，本质上都是在已有的“会话—消息”模型上做延伸，而不是推翻重来。
2. 核心功能与数据模型：聊天系统的地基
2.1 四张核心表的精妙设计
在线客服系统的本质是“会话上下文中的消息流”。整个数据库设计，其实就围绕着一个核心：把“一次服务过程”抽象成“一条会话记录”，再在会话下面挂上若干条消息。这个系统只用了四张核心表，就把整个业务模型撑起来了，非常值得学习。
第一张表是访客表。访客第一次打开聊天窗口，系统会给浏览器分配一个唯一ID，通过Cookie存下来。这张表记录访客的基础信息，最基本的两个字段是visitor_id和create_time。不要小看这张表，它是后面所有统计功能的基础——你今天接待了多少新访客、多少老访客回访，全靠它。
第二张表是客服表。客服表里有个关键字段是status，标识客服当前是“离线”“在线空闲”还是“在线忙碌”状态。这个字段更新非常频繁，客服登录后置为在线，接入会话后置为忙碌，挂断后恢复空闲。轻量系统的做法是直接用数据库字段标记状态，而不去搞独立的在线状态服务，因为客服数量通常远小于访客数量，数据库的读写压力完全扛得住。
第三张表是会话表。每次服务事件产生一条记录，包括访客ID、接待客服ID、会话状态、创建时间、关闭时间。这张表的精髓在于source字段，它标明会话是从哪个页面发起的。很多公司做二次开发，第一件事就是扩展这个字段，因为通过它就能知道“携程过来的客户”和“App内来的客户”在服务质量上有没有差异。
第四张表是消息表。这是整个系统数据量最大的表，每一条聊天记录都落在这里。核心字段包括会话ID、发送方类型（访客/客服/系统）、发送方ID、消息类型（文本/图片/系统通知）、消息内容、发送时间以及是否已读。
我在改这个系统的时候，给消息表加过两个很有用的字段：client_msg_id和read_at。前者是客户端生成的消息ID，用来做消息去重；后者记录客服“已读”的具体时间，用来算首次响应时长。这两个字段虽然原版系统没有，但加起来的改动量极小，对于做服务质检来说价值非常大——这就是轻量系统二次开发的典型体验，改动都在明处，不绕弯子。
建表SQL大致如下：
CREATE TABLE `visitor` ( `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, `visit_code` VARCHAR(32) NOT NULL COMMENT '访客唯一标识CID', `nickname` VARCHAR(50) DEFAULT '', `create_time` DATETIME NOT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `agent` ( `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, `username` VARCHAR(50) NOT NULL, `password` VARCHAR(64) NOT NULL, `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0离线 1空闲 2忙碌', `last_login_time` DATETIME DEFAULT NULL ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `chat_session` ( `id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, `visitor_id` INT UNSIGNED NOT NULL, `agent_id` INT UNSIGNED DEFAULT 0, `status` TINYINT NOT NULL DEFAULT 0 COMMENT '0排队中 1服务中 2已结束', `channel` VARCHAR(20) DEFAULT '', `create_time` DATETIME NOT NULL, `close_time` DATETIME DEFAULT NULL, KEY idx_visitor (visitor_id), KEY idx_agent_status (agent_id, status) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `chat_message` ( `id` BIGINT AUTO_INCREMENT PRIMARY KEY, `session_id` INT UNSIGNED NOT NULL, `sender_type` TINYINT NOT NULL COMMENT '0访客 1客服 2系统', `sender_id` INT UNSIGNED NOT NULL, `message_type` TINYINT DEFAULT 0 COMMENT '0文本 1图片 2系统提示', `content` TEXT NOT NULL, `client_msg_id` VARCHAR(36) NOT NULL, `is_read` TINYINT DEFAULT 0, `create_time` DATETIME NOT NULL, KEY idx_session_time (session_id, create_time), KEY idx_client_msg (client_msg_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;你说它简单吗？确实简单。但四张表已经能完整回答在线客服系统最核心的几类问题：现在有多少访客在等待？每个客服手里挂了几个会话？某次服务过程聊了哪些内容？响应速度怎么样？这些数据都是从这四张表里出来的。做二次开发的时候，先别急着加一堆华丽字段，把这几张表的索引和字段设计研究透彻，反而更重要。
2.2 会话状态机：从排队到结束的完整流转
在线客服和普通微信聊天的最大区别，在于客服系统有“接待”的概念。访客发消息不是简单地发给某个固定的人，而是需要被分配到合适的客服；客服也不是同时和几百个人高频聊天，而是一个一个处理。这就需要一个清晰的状态机来控制会话的流转。
这套系统的会话流转，用三个状态就够了：排队中、服务中、已结束。规则如下。
访客第一次打开聊天窗口发起第一条消息时，系统创建一个新会话，状态为“排队中”，同时触发分配逻辑。分配逻辑有两种策略：如果当前有状态为“空闲”的客服，直接把会话分配给最早空闲的那位，状态改为“服务中”；如果没有空闲客服，会话保持排队状态，等有客服空闲时再自动分配。
客服端获得新会话提示后，点击“接入”按钮，才算正式进入服务状态。接入后，客服状态从“空闲”改为“忙碌”。这里有个细节很重要：访客发消息时系统自动分配客服，但客服真正接手，有两种模式——自动接入和手动接入。自动接入适合消息量大的场景，客服不需要任何操作，会话直接弹出来；手动接入适合客服需要准备时间的场景，避免被突然弹出来的会话打断手头工作。两种模式就是一行配置的区别，但对于使用体验的影响非常大，二次开发时值得重点调整。
结束会话有两种方式。客服点击“结束会话”，或者访客直接关闭聊天窗口并触发断开事件。结束之后，会话状态变为“已结束”，同时系统往消息表写一条系统消息——“客服XXX已结束会话”或“访客已离开会话”。还有一条容易被忽略但实际上很关键的规则：如果访客在会话结束后又发来新消息，那么系统应该创建一个新会话，而不是去复用那个已结束的旧会话。很多客服系统的体验很奇怪，聊着聊着没反应，其实就是复用了死会话导致的。逻辑上，旧会话已经归档，新问题就应该开新档来记录。
这个状态机的核心价值在于“可预测”。无论发生什么情况——客服掉线、访客关闭浏览器、消息发送失败——会话总能落在这三个状态之一，不会出现“既排队中又服务中”这种逻辑死角。二次开发和排障的时候，只要盯着状态字段看，就能推演出系统当前处于什么阶段。
3. 实操过程与核心实现
3.1 从零搭建运行环境
纸上谈兵到此为止，下面进入真正动手的阶段。我在本机用Linux虚拟机完整过了一遍从拉取源码到跑通的流程，整个过程中最耗时间的其实不是写代码，而是环境配置里那些细枝末节的问题。这里把完整的步骤和踩坑点一起放出来。
环境准备其实很标准：一台Linux服务器或者虚拟机，装好PHP 7.4及以上、MySQL 5.7及以上、Nginx、Composer。PHP需要安装pcntl和posix扩展，这是Workerman跑起来的前置条件。
初始化步骤分五步走：
第一步，把源码放到Nginx的网站目录，比如/var/www/online-chat，设置public为网站根目录。这一步的目的是隔离文件访问范围，让外部只能触达入口文件和静态资源，后端代码和配置目录都藏在Web根目录之外。
第二步，导入数据库。执行sql/install.sql，生成四张核心表。然后用文本编辑器打开config/config.php，把数据库地址、用户名、密码、库名改掉。
第三步，安装Composer依赖。在项目根目录执行：
composer install这一步会拉取Workerman等依赖包，如果没装Composer，先通过官方脚本装好。
第四步，启动WebSocket服务端：
php socket/server.php start出现“Workerman started successfully”字样，说明服务端已经监听在0.0.0.0:2346端口。
第五步，启动Nginx和PHP-FPM，然后访问http://你的服务器IP/visitor.html，打开访客端页面；再打开http://你的服务器IP/agent.html，跳转到客服登录页，用初始账号登录客服端。
到这里系统就能用了。但这里有个关键的坑：默认情况下，访客端的ws连接地址是写死在配置里的ws://你的IP:2346，如果IP不对或者端口没放行，前端就会一直显示“正在连接”。这是新手第一次部署最容易卡住的地方，建议先把服务器防火墙的2346端口放行，再确认前端配置文件里的地址和实际IP一致。
3.2 WebSocket连接与心跳保活：看似简单但最要命的部分
既然叫“实时聊天系统”，通信就是命脉所在。这套系统用Workerman做WebSocket服务端，前端的连接代码用原生JavaScript实现，把这个通信链路彻底打通，整个聊天系统就活了。
先看服务端核心代码。Workerman提供了一个事件驱动的WebSocket服务器，开发者注册几个回调函数即可：
<?php require_once __DIR__ . '/../vendor/autoload.php'; use Workerman\Worker; use Workerman\Connection\TcpConnection; $ws_worker = new Worker("websocket://0.0.0.0:2346"); $ws_worker->count = 4; // 开启4个进程处理连接 // 连接建立时，每个连接保存一个clientId用于标识 $ws_worker->onConnect = function (TcpConnection $connection) { $connection->clientId = uniqid(); }; // 收到消息：消息统一为JSON格式 $ws_worker->onMessage = function (TcpConnection $connection, $data) { $msg = json_decode($data, true); if (!$msg || empty($msg['type'])) { return; } // 分发消息，这里将业务处理交给ChatService \App\Services\ChatService::handleMessage($connection, $msg); }; // 连接关闭时，需要告诉ChatService清理在线状态 $ws_worker->onClose = function (TcpConnection $connection) { if (isset($connection->clientId)) { \App\Services\ChatService::disconnect($connection->clientId); } }; Worker::runAll();前端的连接逻辑也很直接：
const ws = new WebSocket("ws://你的服务器IP:2346"); ws.onopen = function() { // 登录成功后给服务端发一条init消息，绑定访客身份 ws.send(JSON.stringify({ type: "init", visitorCode: getVisitorCode(), role: "visitor" })); }; ws.onmessage = function(event) { const data = JSON.parse(event.data); if (data.type === "chat") { appendMessage(data); } else if (data.type === "system") { showSystemMessage(data.content); } };这里有个非常关键的设计——消息层就只做转发，业务逻辑全在ChatService里。服务端收到消息后，先根据type字段判断是初始化、聊天还是心跳，然后调用Service里的方法处理。这种设计避免了把业务代码塞在回调里，否则二次开发的时候，改成机器人对接、敏感词过滤，全得在回调里层层叠加，代码很快变成一锅粥。
连接建立之后，最核心的问题就来了：WebSocket连接是长连接，但网络环境并不总是稳定的。客户端掉线、服务器重启、Nginx空闲超时，都可能导致连接悄无声息地断开。如果没有心跳机制，服务端会一直认为某个访客还“在线”，直到下次发消息才发现连接已经死了。这时候访客体验就是：打开页面显示在线，但发消息毫无反应。
这套系统用心跳机制来解决：客户端每30秒发送一个ping，服务端收到后返回pong，如果连续三次没收到客户端心跳，服务端主动断开该连接并清理在线状态。
let heartbeatCount = 0; let heartbeatTimer = null; function startHeartbeat() { heartbeatTimer = setInterval(() => { ws.send(JSON.stringify({ type: "ping" })); heartbeatCount++; if (heartbeatCount >= 3) { ws.close(); reconnectWebSocket(); } }, 30000); } ws.onmessage = function(event) { const data = JSON.parse(event.data); if (data.type === "pong") { heartbeatCount = 0; // 收到pong，重置计数 } // 处理其他类型消息... };心跳机制的经验总结起来就三个字：别偷懒。我见过有人把心跳间隔设置成5分钟，理由是“省资源”，结果一遇到运营商NAT超时就大量断线。更好的做法是缩短心跳周期，同时配合客户端的自动重连逻辑。断线不可怕，可怕的是断线了双方都不知道。对于在线客服这种实时性要求高的系统，每30秒一次心跳是值得的。
3.3 消息收发的完整链路：从访客输入到客服端展示
把通信链路搭好之后，就要看消息在系统里是怎么流转的。我画了条线，访客发一条消息，背后发生的事比看着的要复杂一些。
访客在输入框按回车，前端把消息内容包装成JSON通过WebSocket发送到服务端。JSON格式是统一的规范，这个规范在二次开发时最好不要轻易改动：
{ "type": "chat", "sessionId": "10001", "clientMsgId": "a3f2e8f1-5c1b-4d7b-9bf3-8b3ff1bd3e21", "content": "我想咨询一下你们的会员价格" }这里的clientMsgId是我的建议字段。原版系统里可能没有，但加上它几乎零成本，却能让消息去重、消息追踪变得无比轻松。服务端收到这条消息后，按以下步骤处理：
第一步，查会话表，确认当前会话是否有效。如果会话状态是“排队中”或“服务中”，继续下一步；如果是“已结束”，则创建新会话。
第二步，把消息写入消息表。写入时把clientMsgId原样保存，这样万一客户端因为断线重发同一条消息，服务端可以通过SELECT * FROM chat_message WHERE client_msg_id = ?查出已经存在，直接返回成功，而不重复入库。
第三步，通过WebSocket把这条消息推送给客服端。这里就有个“连接映射”的问题：服务端怎么知道这条消息要发给哪个客服？答案是通过会话表里的agent_id字段找到对应客服，再在服务端维护的“客服ID到WebSocket连接”的映射表里找到连接对象。
第四步，如果客服当前不在线——注意，这里说的是“WebSocket连接不存在”，不是“客服账号未登录”——则把消息标记为离线消息。客服下次上线时，系统自动把离线消息批量推送过去。
整个链路看起来简单，真正容易出错的是第三步的“推送对象”判定。很多初学者会犯一个错误：往会话里所有连接都推一遍消息，导致访客收到自己发送的消息、客服收到重复消息。正确做法是在ChatService里维护一张在线连接映射表，每个会话只推给对应的两个角色。
这套系统的消息链路，把“写入数据库”和“推送给对方”两个动作做成原子操作——先入库，再推送。如果推送失败无非就是对方稍后刷新能看到；但如果你先推送、再入库，推送成功而数据库写入失败了，那这条消息就彻底丢了，怎么都找不回来。这个顺序在二次开发时一定要保持住。
4. 二次开发的几个方向与实操建议
4.1 最容易见效的三个扩展点
很多做二次开发的同行，一开始不知道从哪里下手。我的建议是：先做那些“改动小、见效快、能直观感受到系统在变化”的功能，建立信心之后再碰底层的架构改动。这套系统有这三个扩展点值得优先做。
第一个是自动欢迎语。访客打开聊天窗口时，系统自动推送一条欢迎语。实现方式非常简单，在访客建立WebSocket连接并完成init握手后，调用一次消息发送接口，往会话里写入一条类型为system的消息。这段代码不会动底层逻辑，只是在你现有的“会话创建”流程上挂一个钩子。
第二个是快捷回复。客服端维护一个快捷回复模板列表，客服点击模板，系统把模板内容填入输入框，或者直接发送。这个功能特别适合客服话术标准化的业务场景。实现上只需要在客服端页面加一个侧边栏，从数据库读取模板列表，点击后把内容回填到输入框即可，服务端不用改一行代码。
第三个是敏感词过滤，这个功能每个商业客服系统都有，但自己做起来也只是一层过滤逻辑。在ChatService::handleMessage()入口处，对消息内容做一次字符串匹配，命中敏感词就直接拦截，返回一条系统提示给访客，不进入消息表。
注意：敏感词过滤一定是“进系统的第一道关卡”，而不是在客服端展示时才过滤。如果只在展示端过滤，敏感词已经落库了，排查的时候怎么都说不清。我调过很多客服系统的敏感词功能，这个教训是反复被验证的。
这三个扩展点的共同特征是：都在原有模型上“加一层”，不影响底层架构。做完这些，你基本就对系统运行机制有了感觉，可以有底气去做更复杂的改动。
4.2 进阶改造：机器人接入、多租户改造、数据统计
当基础扩展做完后，就可以挑战真正的“大活”了。这里聊三个我做过并且验证过的进阶方向，任何一个都会让这套轻量系统具备商业级的能力。
第一个是机器人接入。现在的客服系统如果不带机器人，人力成本很难控制。但机器人的接入，实际上不是“人工智能”的问题，而是“事件分发”的问题。做法不复杂：在消息处理链路里加一个钩子，当消息的发送方是访客时，先把消息复制一份发给机器人接口，然后设定一个超时时间，比如3秒。如果机器人返回了回复内容，就把回复内容作为客服角色的消息写入并推送给访客；如果机器人没回，或者返回“转人工”指令，则该消息的正常分配逻辑继续执行，转给人工客服处理。
这个改造里最容易出问题的是“超时控制”。机器人接口如果响应慢，访客会以为系统卡了。我的建议是：机器人回复的主导权交给前端。前端收到访客消息后，先展示“AI正在输入...”的占位效果，同时并行请求机器人接口，3秒内没回就自动切换为人工排队提示。这个体验比让访客干等好得多。
第二个是多租户改造，这是把一套系统变成SaaS平台的关键一步。说白了就是给原有的表都加一个tenant_id字段，然后在数据操作层统一加上租户过滤条件。听起来简单，但会碰到一个绕不开的问题：WebSocket的连接映射表也要按租户隔离。不然A公司的客服，可能会收到B公司访客的消息推送请求。
具体做法是，在WebSocket连接初始化的时候，把tenant_id作为连接的一个属性存下来，消息路由时先校验会话所属租户和连接所属租户是否一致，不一致直接拒绝。这个校验代码量不大，但逻辑位置非常关键——必须在路由分发的最前面，而不是到了ChatService内部才判断。越早拦截，越不容易漏。
第三个是数据统计。聊天数据是客服系统的金矿，但光有数据没有统计，金矿就是一堆沙子。我建议从最简单的指标做起：每日会话数、平均首次响应时长、平均会话时长、满意度评价。这些指标不需要复杂的分析模型，几条SQL就能跑出来。会话数就是COUNT(*)加GROUP BY date；首次响应时长就用该会话第一条客服消息时间减去会话创建时间；满意度评价则需要在会话结束前加一个评价入口，把评分存到会话表里。
说到多租户改造，顺带提一嘴：现在很多团队做二次开发喜欢先上复杂的东西，比如对接大模型、做智能分配，但基础的数据隔离和服务质量统计没跟上，最后系统跑起来了，业务方一问“今天哪条渠道咨询量最高”“哪个客服响应最慢”，拿不出数据，这个系统就很难真正落地。先把数据底座打好，后面任何智能化改造都有了判断依据。
4.3 二次开发中容易被忽略的细节
做二次开发的过程中，有两个细节我强烈建议多花一点时间处理，不然上线后会很痛苦。
第一个是消息内容的HTML转义。聊天消息在客户端展示时，如果直接拼接HTML，访客发一条<img src=x onerror=alert(1)>，那就是标准的存储型XSS漏洞，客服端一打开页面就会中招。做在线客服系统，这个防线必须要设。最简单的做法，前端展示消息时全部用textContent而不是innerHTML，需要支持图片的话，对内容做白名单校验，只允许特定的标签格式。
第二个是操作日志。客服系统每天会产生大量的操作行为：登录、接入会话、转接、结束会话、快捷回复。这些行为如果完全没有日志，出了问题连“这个客服到底有没有接过这个客户”都说不清。轻量系统考虑到精简，日志功能往往很薄，但我的建议是至少记录两类：登录日志和会话操作日志。前者记录谁在什么时间登录过，后者记录会话的完整流转过程。不需要额外建很多表，在现有表上增加日志字段或者一个简单的操作流水表就够了。
5. 常见问题与排查技巧实录
5.1 部署和运行中的高频问题速查
我在部署和调试这套系统的过程中，遇到了不少问题，很多问题其实是同一个根源的不同表现。这里整理成一张速查表，按“现象—原因—解法”的方式，方便大家直接对标自己的情况。
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 访客端一直显示“正在连接”，连接不上WebSocket | 服务器防火墙未放行2346端口；前端ws地址IP写错 | 用firewall-cmd --list-ports检查端口，用telnet IP 2346测试连通性 |
| 连接正常，但聊天消息收不到 | Nginx反向代理未开启WebSocket升级；消息路由被并发进程打乱 | 配置Nginx代理头Upgrade: websocket；确认Workerman启动的数个进程的连接映射同步正常 |
| 客服端显示在线，但访客发消息没有反应 | 客服的WebSocket连接已断开但未感知；会话分配逻辑未触发 | 检查客服端心跳，断开时重新拉取会话列表；检查ChatService分配逻辑 |
| 消息重复显示 | 缺少有效的去重机制；客户端断线重连后重发了未确认的消息 | 启用client_msg_id去重，前端加载历史消息时跳过已存在的ID |
| 一段时间没操作后，连接自动断开 | Nginx的proxy_read_timeout默认60秒，长连接被掐断 | 调整proxy_read_timeout 300s，客户端心跳周期保持在30秒以内 |
| 消息写入数据库失败，但界面没有任何错误提示 | 消息接口返回值被前端忽略；SQL字段长度超限 | 前端统一处理错误返回，显示“发送失败，点击重试”；调整消息表字段长度 |
| 客服端页面白屏或卡死 | 浏览器控制台有JS报错；图片或特殊字符导致渲染异常 | 打开开发者工具看Console报错，检查消息渲染代码是否对特殊内容做了转义 |
| 多开几个客服端后，消息串线 | 连接映射表按agent_id维护，但多个标签页共用了同一个客服身份 | 客户端连接时给每个标签页生成独立连接ID，服务端以连接ID作为映射主键 |
这里面最值得单独说的，是“消息路由”那个问题。Workerman启动多进程后，不同进程维护各自的连接映射表，如果访客的连接和客服的连接落在不同进程，消息就没法直接转发。解决办法有两种：要么改成单进程模式（适合学习阶段，代码简单），要么引入一个共享的内存通道（生产环境必须做）。很多二次开发的人在这个问题上卡了很久，是因为他们以为问题出在“消息格式”上，实际是进程隔离问题。
5.2 性能、安全与底线的把握
在线客服系统的性能压力相对可控，但这不意味着可以完全不管性能。明确说一下底线在哪里。
消息表的增长速度是最快的，一个活跃的客服系统，一天几千条消息很正常。如果不做任何归档策略，一两年后消息表就会有几百万行，导致查询越来越慢。轻量系统常用的策略是“冷热数据分离”：热数据保留最近90天，老数据定期导出归档到历史表或文件里。实现上就是一条定时任务，把90天前的消息从主表搬到归档表，改动量不大。
安全方面，有三道底线要守。第一道是SQL注入防线，所有数据库操作必须走参数绑定，不允许字符串拼接SQL。第二道是消息内容过滤，入库之前做统一的过滤和转义，防止存储型XSS。第三道是权限控制，前后端都要做。前端隐藏按钮只是体验优化，真正的权限校验必须放在服务端，否则任何人构造一个请求就能冒充客服调用接口。
压力测试这块，我实测过这套系统在单台2核4G的云主机上，开启4个Workerman进程，保持500个WebSocket长连接同时在线，消息延迟能控制在100毫秒以内。这台机器的配置在云服务商那儿是最低档位的，因此作为学习用和中小业务场景已经足够。如果并发再往上走，那就需要考虑负载均衡、多机部署方案，属于另一个话题了。
5.3 调试工具与日常运维心得
最后分享几个调试这套系统时很有用的工具和心法。
浏览器开发者工具是调试WebSocket的第一利器。打开Network面板，找到WS标签，可以看到建立连接、发送帧、接收帧的完整记录。前端发送了什么、服务端返回了什么，在这上面一目了然。我调试消息重复、断线重连这类问题，几乎全靠它。
Workerman本身带了日志和状态查看功能。启动后在命令行执行：
php socket/server.php status能看到当前连接数、消息收发总数、进程状态。如果发现连接数一直在涨而不回落，那多半是有连接没被正确关闭，结合心跳机制检查一下。线上出问题先跑这个命令，信息量比看一堆日志都要大。
还有一个运维细节，改代码之后重启Workerman：
php socket/server.php restart这个命令会重启所有进程，加载新代码。如果是新增了数据库表字段，记得先执行对应的ALTER语句再重启，否则新逻辑查到不存在的字段会直接报错。
关于调试时效性，我的体会是：在线客服系统出问题，最怕的是“复现不了”。因为涉及实时连接和多端交互，很多问题在测试环境根本复现不出来。所以一定要在生产环境保留前端的错误日志和服务端的消息日志。前端把WebSocket的收发记录发送到日志接口，服务端把每条收到和发出的消息记录到日志文件，一旦出问题，两边日志一对比，问题在哪边立刻就清楚了。这套系统原版可能日志很薄，但做二次开发时把它补上，绝对是性价比最高的一笔投入。
