简介这是一套基于ThinkPHP 6与Swoole 4构建的企业级开源客服系统面向电商、SaaS服务商及中大型企业技术团队解决多渠道客户接入难、客服响应慢、跨端管理割裂等实际运营痛点。系统完整支持微信网页、H5、PC端用户接入商家侧覆盖PC管理后台、H5轻量接待页及App端实时会话具备用户标签化分组、会话状态跟踪、消息持久化等核心能力适用于需快速部署、灵活定制的客服中台场景。压缩包含2000个文件主体为294个PHP后端逻辑文件、171个Vue前端组件、347个JS交互脚本、104个CSS样式资源及188个Markdown文档含部署指南、API说明与二次开发规范整体90.77MB结构清晰前后端分离明确便于学习架构设计与高并发优化实践。已有261人下载学习可直接运行调试获取完整可商用的客服系统源码、数据库脚本及全链路通信实现细节。1. 项目缘起从传统轮询到长连接我们为什么选择重构客服系统几年前我们团队维护着一个基于ThinkPHP5.1开发的客服系统。那是一个典型的“请求-响应”式架构用户发送消息客服刷新页面才能看到。为了模拟“实时”效果我们不得不在前端用JavaScript写了一个笨重的轮询Polling脚本每隔几秒就去服务器“问”一次“有新消息吗” 这种方案在用户量少的时候还能勉强应付但随着业务增长问题接踵而至服务器压力巨大大量无意义的请求、消息延迟严重最坏情况要等一个轮询周期、资源浪费多数请求返回空数据。更头疼的是当客服同时接待多个用户时频繁的页面刷新和请求让后台管理页面卡顿不堪体验极差。痛定思痛我们决定彻底重构。核心目标就一个实现真正的双向实时通信。在技术选型上我们很快锁定了Swoole。它作为PHP的异步、并行、高性能网络通信引擎能让我们用熟悉的PHP语言构建常驻内存的WebSocket服务彻底告别轮询。框架层面我们选择了当时较新的ThinkPHP 6.0TP6它更现代、更规范对Swoole的集成支持也更好。于是“TP6 Swoole4”就成了我们新客服系统的技术基石。这个组合让我们能用一套PHP代码同时处理HTTP请求和WebSocket长连接不仅实现了消息的即时推送还为后续支持多端微信网页、H5、PC接入打下了坚实的基础。2. 核心架构解析TP6与Swoole4如何协同工作很多人会把Swoole简单理解为一个“加速器”或“插件”这是不准确的。在我们的架构里TP6和Swoole4扮演着截然不同又紧密协作的角色。2.1 职责分离TP6管业务Swoole管通信ThinkPHP 6.0 在这里主要承担了传统的Web MVC职责。所有需要渲染页面、处理表单提交、提供API接口的逻辑都由TP6通过HTTP协议来处理。例如客服登录/登出通过TP6的路由、控制器、验证器完成。历史消息查询TP6的模型Model操作MySQL数据库返回JSON数据。知识库管理、用户管理这些后台CRUD操作完全由TP6的标准MVC流程处理。Swoole 4.x 则作为独立的WebSocket服务器运行。它启动后会监听一个特定的端口例如9501。它的核心职责是维持长连接当用户打开客服聊天窗口前端会通过WebSocket协议连接到这个Swoole服务器建立一个持久的双向通道。实时消息转发当用户A发送消息消息首先通过WebSocket到达Swoole服务器。Swoole服务器能立刻知道用户A连接在哪个fd文件描述符Swoole中连接的标识上也能通过我们维护的“关系映射表”找到正在接待用户A的客服B的fd然后将消息实时推送给客服B的浏览器。连接状态管理管理所有在线用户的连接处理连接建立、断开、心跳检测等网络层事件。2.2 关键问题HTTP的TP6如何与WebSocket的Swoole通信这是整个架构最精妙也最容易出问题的地方。TP6HTTP和SwooleWebSocket是两个独立的进程数据如何互通我们采用了“内部API调用”结合“共享存储”的方案。场景一客服在TP6后台发送消息给用户客服在TP6渲染的页面点击发送一个HTTP请求发送到TP6的控制器。TP6控制器处理业务逻辑如保存消息到数据库然后需要通知Swoole服务器推送这条消息。TP6通过Swoole\Coroutine\Http\Client协程HTTP客户端向本地运行的Swoole WebSocket服务的一个特定HTTP接口例如http://127.0.0.1:9501/push发起一个内部请求。Swoole服务内有一个专门处理这个/push接口的代码逻辑它接收到来自TP6的请求和数据包含目标用户ID和消息内容便在其内存中查找对应用户的WebSocket连接fd然后执行$server-push($fd, $message)完成实时推送。场景二用户上下线状态同步客服需要在后台看到用户是否在线。这个状态存在于Swoole服务器的内存中。我们通过Redis作为“共享存储”来解决当用户通过WebSocket连接成功Swoole服务器除了在自身内存的fd映射表中记录还会向Redis写入一条记录user_online:{user_id}并设置一个较短的过期时间如60秒。TP6后台需要判断用户是否在线时不去直接问Swoole因为进程隔离无法直接访问内存而是去查询Redis中这个键是否存在。同时Swoole服务内会运行一个定时器定期如每30秒要求所有连接的前端回复一个“心跳包”。前端回复后Swoole就刷新Redis中对应键的过期时间。如果某个连接断了或没有心跳Redis的键会自动过期表示用户离线。注意这里有一个大坑。TP6默认是同步阻塞的而直接使用Swoole\Coroutine\Http\Client是协程化的。在TP6的普通控制器中调用协程客户端需要确保你的TP6运行在Swoole的HTTP服务器模式下或者使用\Swoole\Runtime::enableCoroutine()将Socket函数切换为协程否则可能无法生效。在我们的生产部署中我们通常将TP6也通过Swoole运行使整个应用协程化这样内部通信更顺畅。3. 多端接入实战微信网页、H5与PC的兼容性处理客服系统的价值在于触达用户而用户分布在不同的终端。让一套系统适配微信内网页、普通手机浏览器H5和PC网页是本次开发的重点和难点。3.1 微信网页端接入的“特殊待遇”微信浏览器特别是安卓端的X5内核是一个需要特别关照的环境。它对于WebSocket的支持有时会有“脾气”。首先WebSocket连接地址必须是wss://加密。在微信中非加密的ws://连接会被直接阻断。这意味着你必须为你的服务端配置SSL证书。我们的做法是使用Nginx作为反向代理。# Nginx 配置片段 server { listen 443 ssl; server_name your.domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location /websocket { proxy_pass http://127.0.0.1:9501; # 代理到Swoole WS服务 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 这两行是关键确保长连接不被Nginx超时断开 proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }前端连接的地址就是wss://your.domain.com/websocket。其次注意“企业微信应用程序将要访问外部网页”的提示。如果你的客服链接需要从企业微信中打开且域名与企业微信备案的不一致就会弹出这个安全警告。对于正式项目最好的解决方案是将客服系统域名加入企业微信的可信网页列表。对于快速测试或演示一个临时的办法是提醒用户“点击继续访问”但这很影响体验。绝对不要尝试引导用户关闭安全设置这既不专业也不安全。关于音频视频自动播放微信浏览器为了省流和防骚扰严格限制了音视频的自动播放。我们的“新消息提示音”功能就栽过跟头。解决方案是将音频播放的触发绑定在用户与页面的首次交互上。例如在连接建立后我们会在页面显示一个“点击开启提示音”的按钮用户点击后我们才用代码audio.play()来播放一个极短的无声音频文件以此“解锁”音频上下文。之后再由JavaScript动态替换audio元素的src为真正的提示音文件这样后续通过audio.play()触发播放才能成功。3.2 H5与PC端的统一与差异对于普通的手机浏览器H5和PC浏览器环境限制少很多主要考虑响应式设计和连接稳定性。前端库的选择我们放弃了早期自己封装原生WebSocket的做法转而使用Socket.io-client。虽然Swoole原生支持WebSocket协议但Socket.io提供了更强大的功能自动重连、心跳检测、回退机制在不支持WS时降级为长轮询。这大大增强了在弱网络环境下的用户体验。需要注意的是服务端也需要使用对应的Socket.io协议实现我们使用了wokerman/socket.io这个PHP适配库来与Swoole配合。响应式设计聊天界面的UI我们基于Vue.js Element UI (PC) / Vant (H5) 开发。核心是让消息气泡、输入框、按钮等组件能自适应不同屏幕宽度。一个细节是在PC端我们采用左右分栏左侧会话列表右侧聊天窗口在H5端则切换为上下结构顶部为会话标题栏中间为聊天区域底部为输入框。连接保活与断线重连这是实时系统的生命线。除了Socket.io自带的重连逻辑我们在前端还额外做了两层保护页面可见性Page Visibility监听当用户切换到其他浏览器标签或最小化窗口时我们降低心跳频率当用户切回来时立即检查连接状态如果断开则快速重连。网络状态Online/Offline监听监听浏览器的网络在线事件在网络恢复时主动尝试重连。4. 商家端多终端接待的实现与数据同步客服系统另一半的核心是商家端客服坐席端。我们支持客服通过PC后台、独立的H5页面以及App使用Uni-app打包来接待用户。这带来了新的挑战同一客服账号如何在多个设备上安全登录并同步消息状态4.1 多端登录的互斥与协同策略首先我们定义了两种模式互斥登录一个客服账号同一时间只允许在一个地方登录。新登录会踢掉旧登录。这适用于对会话状态一致性要求极高的场景防止同一个客服在两个地方回复同一个用户造成混乱。实现方式是在用户登录时在Redis生成一个唯一的login_token并记录设备信息。每次请求都校验此token。当同一账号在新设备登录时生成新token并使旧token立即失效同时通过旧设备的WebSocket连接发送一条“您已在别处登录”的指令强制其前端跳转到登录页。协同登录允许同一账号在多个设备同时在线并同步消息。这更复杂但更灵活。我们采用了“发布-订阅”模式。对于协同登录具体实现如下客服A在PC和手机App同时登录。两个设备都会建立独立的WebSocket连接到Swoole服务器获得各自的fd_A_pc和fd_A_app。在Swoole服务器内存中我们维护一个“客服-连接组”的映射agent_connections[A] [fd_A_pc, fd_A_app]。当有用户消息需要推送给客服A时Swoole服务器会遍历agent_connections[A]这个数组向其中的每一个fd执行push操作。这样客服A的PC和手机都能同时收到消息提醒。当客服A在PC端回复了用户这条消息除了会推送给用户也会通过同样的“组播”机制推送到客服A自己的手机App上确保两侧的聊天记录实时同步。4.2 会话状态同步的细节处理消息内容同步相对简单但“会话状态”同步更需要精细设计。状态包括当前正在接待的会话、会话的未读消息数、会话的折叠/展开状态等。我们设计了一个轻量级的“状态同步指令”协议。当客服在设备A上进行某个操作时例如点击某个会话将其设为“正在接待”前端除了执行本地UI更新还会通过WebSocket发送一个特定的状态同步指令到服务器指令中包含操作类型和会话ID。{ type: switch_session, session_id: 12345, timestamp: 1629981123456 }Swoole服务器收到后会做两件事更新该会话在数据库或Redis中的“最后接待客服”和“最后活动时间”等核心状态。向该客服其他所有在线设备通过agent_connections查找广播这个指令。其他设备的前端收到指令后根据type更新本地UI状态例如高亮显示会话ID为12345的聊天窗口。这样无论客服在哪个设备上操作其他设备都能在毫秒级内保持界面状态一致。4.3 App端的技术选型Uni-app的考量我们选择Uni-app来构建App端核心原因是开发效率和与H5端的代码复用。客服接待App的功能相对标准消息列表、聊天窗口、用户信息查看。使用Uni-app我们可以用Vue语法编写一套代码同时发布到iOS和Android应用商店以及生成H5页面。在Uni-app中连接我们的Swoole WebSocket服务需要注意平台差异。在App端我们使用uni.connectSocket API。在调试时如果遇到连接失败首先要检查手机网络是否能访问到服务器的wss地址。一个常见的坑是在开发阶段手机和电脑可能不在同一局域网需要确保服务器地址是公网可访问的或者使用内网穿透工具如ngrok进行调试。消息推送提醒方面在App端我们可以利用uni-app的原生推送插件如UniPush当App在后台时通过厂商通道华为、小米、OPPO、vivo等或苹果APNs进行系统级推送确保消息送达率。这与H5端依赖浏览器通知需要用户授权且不稳定有本质区别体验好得多。5. 用户添加与管理从邀请链接到智能分配“支持用户添加”这个功能点看似简单实则是一个完整的用户生命周期管理入口。我们将其设计为一个可配置的流程。5.1 多种用户添加途径的实现邀请链接/二维码这是最通用的方式。在客服系统后台可以为某个客服或某个客服组生成一个唯一的邀请链接或二维码。该链接包含一个加密的参数如sourceinviteagent_idxxx。当用户点击此链接进入客服页面时后端TP6在创建用户会话时就能识别出这个“来源”并自动将会话分配给指定的客服或客服组。二维码本质上就是链接的图形化使用endroid/qr-code这类库可以轻松生成。网页插件/浮动窗口在商城的商品页、帮助中心等位置嵌入一段JavaScript代码。这段代码会在页面右下角生成一个浮动聊天图标。用户点击后弹出客服窗口。这里的关键点是要能在插件初始化时就携带当前网页的上下文信息。例如我们会在代码中注入window.ChatWidgetConfig { product_id: 12345, page_title: XXX商品详情页, visitor_name: 已登录用户的昵称 // 如果商城已登录 };当插件初始化并与Swoole建立连接后会将这些信息作为“用户元数据”发送到服务器方便客服了解用户来自哪个页面正在看什么商品从而实现更精准的服务。API接口导入对于已有用户体系的企业他们可能希望将CRM中的用户直接导入客服系统。我们提供了一个RESTful API允许对方服务器通过调用我们的接口需验证API密钥来创建或更新用户信息并即时发起一个客服会话。这常用于订单投诉、售后跟进等主动服务场景。5.2 用户分配策略轮询、负载与技能组当用户通过任何渠道进入系统需要决定“该由哪位客服来接待”。我们实现了三种分配策略可在后台灵活配置轮流分配Round Robin将所有在线且未达到接待上限的客服排成一个队列新用户会话依次分配给队列中的下一位客服。这是最公平的策略保证每个客服的工作量大致均衡。实现上我们在Redis中使用一个列表来维护这个队列分配一次就旋转一次列表。最少会话优先实时计算每个在线客服的当前接待会话数将新会话分配给会话数最少的那位。这比轮询更动态能更精细地平衡负载。我们需要在Swoole服务器的内存或Redis中为每个客服维护一个计数器并在会话开始和结束时更新它。技能组路由这是更专业的模式。在后台可以为客服打上标签如“售前”、“售后-技术”、“售后-退款”。同时在生成用户入口时如不同的邀请链接、不同的网页插件配置可以指定其需要的“技能组”。用户进入时系统只会将会话分配给拥有对应技能标签且在线、未满负荷的客服。如果匹配的客服有多位再结合“最少会话优先”策略进行分配。实操心得分配逻辑绝对不能放在WebSocket服务器的主事件循环中执行。因为分配可能涉及数据库查询、复杂的计算如果处理时间过长会阻塞其他消息的接收。我们的做法是当需要分配时Swoole服务器会向一个Redis队列如queue:assign_session投递一个分配任务。由TP6框架下运行的独立命令行进程消费者从队列中取出任务执行复杂的分配逻辑确定客服后再通过内部HTTP调用通知Swoole服务器建立具体的连接绑定关系。这样实现了逻辑解耦和异步处理保证了WebSocket服务的高性能。6. 性能优化与稳定性保障Swoole服务的生产级部署基于Swoole开发服务开发只是第一步如何让它稳定、高效地跑在生产环境才是真正的挑战。6.1 进程模型与配置调优Swoole默认使用多进程模型。以我们的WebSocket服务为例在server-start()后会创建1个Master进程负责管理Worker和Task进程。N个Worker进程由worker_num配置它们才是真正处理业务逻辑如onMessage事件的进程。每个Worker进程内部是异步非阻塞的可以处理大量并发连接。worker_num通常设置为CPU核数的1-2倍。M个Task进程由task_worker_num配置专门处理耗时任务如消息持久化到数据库、发送邮件通知等。Worker进程可以通过$server-task()投递任务到Task进程自己则继续处理新请求避免阻塞。我们的生产配置大致如下$server new Swoole\WebSocket\Server(0.0.0.0, 9501); $server-set([ worker_num 4, // 根据4核CPU设置 task_worker_num 2, // 用于异步任务 daemonize true, // 以守护进程运行 log_file /var/log/swoole_websocket.log, // 记录日志 pid_file /var/run/swoole_websocket.pid, // 记录PID max_request 1000, // 防止内存泄漏每处理1000个请求Worker重启一次 heartbeat_check_interval 60, // 60秒检测一次 heartbeat_idle_time 600, // 连接最大允许空闲600秒 buffer_output_size 32 * 1024 * 1024, // 调大输出缓冲区应对大消息 ]);关键参数解释daemonize必须设为true让服务在后台运行。log_file和pid_file方便运维和监控。max_request这是一个重要的防御性参数。PHP代码在长期运行后可能会有少量内存累积定期重启Worker可以释放内存。但设置太小会导致频繁重启开销需要根据实际情况调整。heartbeat_idle_time用于清理“死连接”。如果客户端异常断开如直接关闭浏览器服务器可能无法立刻感知。通过心跳机制服务器定期检查超过此时间未通信的连接会被主动关闭。6.2 连接资源管理与内存泄漏排查Swoole服务常驻内存任何资源泄露都会被放大。最常见的问题是全局变量或静态变量不当引用导致的内存增长。我们踩过的坑早期我们在onOpen事件中将用户连接fd和用户ID的映射关系保存在一个类的静态属性public static $fdMap []中。随着时间推移这个数组越来越大即使连接断开我们也只是在onClose中从数组里删除了fd但用户ID作为数组的键可能还被其他地方的代码引用着导致无法被PHP垃圾回收。最终表现为Worker进程内存占用持续缓慢上升。解决方案使用Swoole自带的TableSwoole提供了Swoole\Table这是一个高性能的、共享内存的、并发安全的数据结构。我们将fd和用户ID的映射关系存于Table中生命周期由我们完全控制且在不同Worker间共享。$table new Swoole\Table(1024); $table-column(user_id, Swoole\Table::TYPE_INT); $table-column(agent_id, Swoole\Table::TYPE_INT); $table-create(); $server-fd_table $table; // 可以附加到server对象上在onClose中彻底清理除了从Table中删除记录还要清理任何与此fd或用户ID相关的Redis键、其他内存缓存等。定期监控我们使用Swoole\Timer::tick设置一个每10分钟执行一次的定时器输出每个Worker进程的内存使用量memory_get_usage(true)和连接数到日志。一旦发现某个Worker内存异常增长且不回落就发出告警。6.3 高可用与平滑重启方案单点Swoole服务是危险的。我们通过以下方式实现高可用多实例部署在两台或更多服务器上部署完全相同的Swoole服务实例监听不同端口。前端如Nginx通过负载均衡轮询或最少连接将WebSocket连接请求分发到不同实例。这样即使一台服务器宕机服务也不会中断。状态共享多实例带来的核心问题是状态不同步。用户A连接到实例1其客服B连接到实例2消息就无法直接推送了。因此所有连接状态必须集中存储。我们彻底放弃了在Swoole进程内存中维护fd映射转而全部使用Redis。每个实例在onOpen时将fd、用户ID、实例IP等信息写入Redis的一个有序集合或Hash中。当需要推送消息时先查询Redis找到目标用户所在的实例和fd如果不在当前实例则通过实例间的一个轻量级RPC如基于Redis Pub/Sub或一个简单的HTTP接口将消息转发到对应实例去执行推送。平滑重启Hot Reload当需要更新业务代码时不能直接kill进程。Swoole提供了平滑重启机制向Master进程发送SIGUSR1信号它会逐个重启所有Worker进程等Worker处理完当前请求后退出再拉起新的Worker。但要注意平滑重启只对Worker进程有效对Master进程和Task进程无效。更新了server-set的配置或Master进程的代码仍需完全重启服务。我们的做法是在深夜低峰期通过部署脚本先启动一个新的Swoole服务实例让Nginx将流量逐步切到新实例再关闭旧实例实现真正的零停机更新。7. 测试策略从单元测试到全链路压测一个实时通信系统测试必须覆盖从底层逻辑到高并发场景的全链路。7.1 TP6单元测试与HTTP接口测试对于TP6部分的业务逻辑如用户管理、权限验证、历史消息查询API我们严格按照TP6的测试文档编写单元测试和HTTP接口测试。这能保证核心业务逻辑的正确性。我们使用PHPUnit并配置了一个独立的测试数据库。7.2 Swoole WebSocket服务的集成测试测试WebSocket服务更复杂。我们构建了一个基于PHPUnit和Swoole\Coroutine\Http\Client的测试套件。启动测试服务在setUpBeforeClass方法中启动一个专用于测试的Swoole WebSocket服务器端口与生产环境不同。模拟连接与消息在每个测试方法中使用协程客户端模拟多个用户连接、发送消息、接收回复并断言收到的消息是否符合预期。测试并发行为利用Swoole的协程我们可以轻松模拟数百个用户同时连接和发送消息的场景验证服务器的并发处理能力和内存稳定性。7.3 全链路压测与混沌工程在上线前我们进行了全链路压测。使用压测工具如wrk或jmeter模拟海量用户同时建立WebSocket连接、发送消息。观察指标包括服务器CPU、内存、网络IO、Swoole各进程状态。数据库/RedisQPS、连接数、慢查询。前端页面响应时间、消息延迟。压测让我们发现了几个瓶颈一是MySQL在批量写入消息时出现慢查询我们通过优化索引和引入消息队列异步落库解决了二是Redis在存储大量在线状态时某个大Key查询拖慢了速度我们通过将数据拆分到多个Hash结构进行了优化。此外我们还实践了简单的“混沌工程”在测试环境中随机断开网络、杀死Swoole Worker进程、让Redis短暂不可用以观察系统的容错和自恢复能力。例如我们验证了当Redis临时宕机时前端会因为心跳失败而尝试重连新的连接会在Redis恢复后重新建立而不会导致整个服务雪崩。整个“TP6Swoole4开源客服系统”从重构到稳定运行是一个不断踩坑和填坑的过程。技术选型只是起点真正的挑战在于如何让这些技术组件在复杂的多端、实时、高并发场景下协同工作并保持稳定和可维护。这套架构目前支撑了我们日均数十万的活跃会话其核心思想——HTTP处理业务、WebSocket负责实时、中间件解耦、状态外部化——对于其他需要实时功能的PHP应用也有很好的参考价值。本文还有配套的精品资源点击获取