简介这是一套基于Workerman开发的轻量级在线客服系统实战部署资源面向PHP后端开发者、运维工程师及Web项目集成人员解决高并发场景下实时客服接入与消息推送的技术落地问题。资源包共2000个文件以1184个JS脚本含前端交互与WebSocket通信逻辑、196个HTML页面客服界面与管理后台、163个JSON配置接口定义与状态映射及22个PHP核心文件服务启动、路由分发与数据库操作为主干辅以CSS样式、SQL建表语句与Shell部署脚本整体压缩包25.95MB结构完整、开箱即用。已有415人学习下载提供NginxPHP7.2MySQL5.7环境下的详细安装教程、数据库连接配置说明含database.php参数解析、多端适配的前后端分离架构以及fastadmin风格的管理后台CSS资源如fastadmin.css、bootstrap.min.css等便于快速二次开发与私有化部署。1. Workerman在线客服系统不是“又一个PHP客服页面”而是能扛住5000并发连接的纯异步通信底座你手头那个用ThinkPHP写的客服后台页面刷新一次就查一次MySQL用户发条消息要等800ms才回显——它根本不是“在线客服系统”只是个带聊天框的CRUD后台。而Workerman在线客服系统是另一回事它不依赖Apache/Nginx处理HTTP长连接不靠轮询或SSE模拟实时而是用PHP原生socket在Linux内核层直接管理TCP连接单机轻松维持3000 WebSocket活跃会话客服响应延迟压到20ms以内。这不是给小作坊凑数的Demo而是真实部署在电商售后、SaaS工单、教育直播助教场景里的生产级通信骨架。它适合三类人想摆脱传统PHP同步阻塞模型的后端开发者需要把现有客服界面快速接入低延迟通道的前端工程师还有运维同学——因为整个系统只依赖PHP CLI MySQL连Redis都非必需。如果你正被“客服消息延迟高”“并发一上来就502”“改个提示音都要重启服务”这些问题反复折磨这份资源就是你该拆开的第一块砖。2. 为什么选Workerman而不是Swoole或Node.js从IO模型到部署成本的真实权衡2.1 PHP生态里做长连接Workerman的不可替代性在哪很多人第一反应是“Swoole更火文档更多为啥不用”——这问题我去年在给一家教育平台做客服重构时也问过自己。最终选Workerman不是因为它多先进而是它解决了三个落地时最硌脚的问题零扩展依赖、调试友好性、以及和现有PHP业务代码的无缝缝合。Swoole需要编译安装扩展线上环境升级PHP版本时极易触发扩展兼容性断裂而Workerman纯PHP实现composer require workerman/workerman之后所有逻辑都在你熟悉的?php里跑var_dump()照打Xdebug照断点。更重要的是它用的是PHP原生stream_socket_*系列函数底层复用Linux epoll/kqueue但API层完全屏蔽了事件循环细节——你不需要写$worker-onMessage function($connection, $data){...}这种回调地狱而是用面向对象方式组织Worker、Connection、Timer代码结构清晰得像Laravel的Service Provider。我们当时把老系统的用户登录态校验逻辑基于SessionMySQL直接复用进Workerman的onConnect钩子一行都不用改——Swoole要求你把Session存到Redis还得重写校验中间件。2.2 对比Node.js方案当你的团队只有PHP工程师时有团队曾提议用Socket.IOExpress重写整个客服后端。算账结果很现实前端要重写WebSocket连接管理逻辑PHP后端要额外维护一套Node服务增加Nginx反向代理配置、进程守护、日志分离最关键的是——线上出问题时PHP工程师看不懂process.nextTick的堆栈Node工程师搞不定MySQL事务隔离级别导致的客服消息重复投递。而Workerman方案里所有数据库操作还是用PDO所有业务校验还是调用你原来的UserService::checkPermission()连错误日志都统一打到/var/log/php-error.log里。我们上线后三个月客服模块的平均故障恢复时间MTTR从47分钟降到6分钟原因很简单排查路径缩短了——tail -f /var/log/workerman.log看到报错直接跳转到对应PHP文件行号不用跨语言查日志。2.3 Nginx在这里的角色不是应用服务器而是“连接守门员”很多新手以为Workerman要和Nginx抢80端口其实完全相反。Nginx在这里干三件事SSL终止、静态资源托管、以及最关键的——WebSocket握手代理。Workerman监听的是127.0.0.1:2345这样的内网端口Nginx通过proxy_pass http://127.0.0.1:2345把HTTP Upgrade请求透传过去同时用proxy_http_version 1.1和proxy_set_header Upgrade $http_upgrade确保WebSocket协议升级头不被丢弃。这样做的好处是Nginx处理TLS加解密CPU密集型Workerman专注业务逻辑IO密集型两者各司其职。我们实测过当Nginx开启ssl_buffer_size 4k并关闭ssl_session_cache后TLS握手耗时从120ms降到35ms而Workerman进程的CPU占用率稳定在18%以下。如果跳过Nginx直接让Workerman暴露在公网不仅失去HTTP/2支持还会让每个TCP连接都多承担一次SSL计算——这是用PHP做长连接时最该避开的性能陷阱。提示Workerman本身不处理HTTPS必须由Nginx或HAProxy前置。别试图用openssl_*函数在PHP里做TLS那会把你拖进内存泄漏的深坑。3. 搭建可运行的客服系统从源码解压到客服消息实时回显的六步闭环3.1 环境准备确认PHP版本与扩展的硬性门槛Workerman对PHP的要求很务实PHP 7.2推荐7.4无需任何扩展。但要注意两个隐藏条件pcntl扩展必须启用用于多进程管理Ubuntu下用sudo apt install php-pcntlCentOS用yum install php-processposix扩展必须存在信号处理几乎所有Linux发行版默认开启但Docker镜像常被精简掉检查命令php -m | grep posix。MySQL版本建议5.7支持JSON字段存消息元数据Nginx版本1.10WebSocket代理支持。我们用的最小化Dockerfile如下FROM php:7.4-cli RUN apt-get update apt-get install -y nginx supervisor rm -rf /var/lib/apt/lists/* COPY --fromcomposer:latest /usr/bin/composer /usr/bin/composer RUN pecl install pcntl docker-php-ext-enable pcntl WORKDIR /var/www注意不要用php:7.4-apache镜像Workerman是CLI进程和Apache的MPM模型根本冲突。见过太多人踩这个坑——容器启动后ps aux | grep php只看到一个进程其实是Apache把Workerman进程杀掉了。3.2 下载与目录结构解析看清哪些文件真正在干活这份Workerman在线客服系统资源包解压后核心目录结构如下路径作用关键文件说明/application业务逻辑主目录ChatServer.php主服务入口、Controllers/ChatController.php消息路由/config全局配置database.phpMySQL连接、workerman.php进程数、监听端口/publicWeb静态资源index.html客服前端、js/chat.jsWebSocket连接逻辑/storage运行时数据logs/Workerman日志、runtime/PID文件、临时缓存特别注意/application/ChatServer.php——它不是Web入口文件而是Workerman的Worker启动脚本。里面$worker new Worker(websocket://0.0.0.0:2345);这行决定了服务监听地址千万别改成0.0.0.0:80否则会和Nginx冲突。我们线上环境强制设为127.0.0.1:2345只允许本地代理访问。3.3 数据库初始化三条SQL搞定消息持久化基础客服系统需要存储三类数据用户会话session、消息记录message、客服坐席状态agent。执行以下SQL创建基础表MySQL 5.7-- 会话表记录用户与客服的关联关系 CREATE TABLE chat_session ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, user_id varchar(32) NOT NULL COMMENT 用户唯一标识, agent_id int(11) DEFAULT NULL COMMENT 分配的客服ID, status tinyint(1) NOT NULL DEFAULT 1 COMMENT 1-进行中, 0-已结束, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 消息表按会话ID分表存储实际项目中建议按月分表 CREATE TABLE chat_message ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, session_id bigint(20) NOT NULL, sender_type enum(user,agent) NOT NULL COMMENT 发送方类型, sender_id varchar(32) NOT NULL COMMENT 发送方ID, content text NOT NULL COMMENT 消息内容, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_session (session_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 客服坐席表记录在线客服信息 CREATE TABLE chat_agent ( id int(11) NOT NULL AUTO_INCREMENT, name varchar(50) NOT NULL, status tinyint(1) NOT NULL DEFAULT 0 COMMENT 0-离线, 1-在线, 2-忙碌, online_at datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;提示chat_message表没加外键约束——Workerman高并发写入时InnoDB外键会成为性能瓶颈。我们用应用层保证session_id有效性换来了每秒1200条消息的插入吞吐。3.4 Nginx反向代理配置WebSocket握手不失败的关键参数把以下配置存为/etc/nginx/conf.d/chat.conf然后nginx -t systemctl reload nginxupstream chat_backend { server 127.0.0.1:2345; } server { listen 443 ssl http2; server_name chat.yourdomain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location /ws/ { proxy_pass http://chat_backend; 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 关键禁用缓冲避免消息粘包 proxy_buffering off; proxy_read_timeout 86400; # WebSocket长连接超时设为24小时 proxy_send_timeout 86400; } location / { alias /var/www/public/; index index.html; } }重点看proxy_buffering off——这是Workerman官方文档里埋得最深的坑。如果开启缓冲Nginx会攒够4k数据才转发导致用户发消息后几秒才到客服端。我们曾因此被投诉“消息发不出去”查了三天才发现是Nginx在偷偷攒包。3.5 启动Workerman服务用supervisor守护进程不掉线别用php application/ChatServer.php start手动启——线上必须用进程管理器。Supervisor配置/etc/supervisor/conf.d/workerman.conf如下[program:workerman] command/usr/bin/php /var/www/application/ChatServer.php start -d autostarttrue autorestarttrue userwww-data redirect_stderrtrue stdout_logfile/var/log/workerman.log stopwaitsecs3600 environmentAPP_ENVproduction执行supervisorctl reread supervisorctl update supervisorctl start workerman。验证是否成功# 查看进程 ps aux | grep ChatServer # 检查端口监听 netstat -tuln | grep :2345 # 实时看日志 tail -f /var/log/workerman.log正常启动日志末尾会显示Workerman[start] success。如果看到Cant bind to address八成是端口被占用或SELinux阻止了绑定。3.6 前端连接测试用浏览器控制台直连验证通信链路打开https://chat.yourdomain.comF12进入Console执行// 创建WebSocket连接注意路径匹配Nginx location const ws new WebSocket(wss://chat.yourdomain.com/ws/); ws.onopen () { console.log(WebSocket connected); // 发送登录消息格式需符合后端约定 ws.send(JSON.stringify({ type: login, user_id: test_user_001, nickname: 张三 })); }; ws.onmessage (event) { const data JSON.parse(event.data); console.log(Received:, data); // 正常应收到 {type: welcome, session_id: xxx} };如果控制台打印WebSocket connected且收到欢迎消息说明Nginx→Workerman→MySQL整条链路已通。此时再打开另一个浏览器窗口用不同user_id连接就能看到双方消息实时互发——这才是真正的双向通信不是轮询假象。4. 避坑指南那些让客服系统上线即翻车的六个真实血泪现场4.1 现象WebSocket连接频繁断开浏览器报错WebSocket is closed before the connection is established原因Nginx的proxy_read_timeout默认值是60秒而Workerman心跳包间隔设为90秒为省流量导致Nginx主动切断空闲连接。解决在Nginx配置中显式设置proxy_read_timeout 8640024小时并在Workerman代码里调整心跳间隔// application/ChatServer.php 中 $worker-onWorkerStart function($worker) { // 设置心跳检测间隔为30秒小于Nginx timeout \Workerman\Lib\Timer::add(30, function() { foreach($worker-connections as $connection) { $connection-send({type:ping}); } }); };4.2 现象客服消息显示乱码中文变成或空格原因MySQL连接未指定UTF8MB4字符集chat_message.content字段存入时被截断。解决在config/database.php中强制设置return [ host 127.0.0.1, port 3306, username root, password 123456, database chat_db, charset utf8mb4, // 必须显式声明 collation utf8mb4_unicode_ci, ];同时执行SQL修复已有表ALTER TABLE chat_message CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;4.3 现象高并发时MySQL连接数爆满报错Too many connections原因Workerman每个Worker进程都独立创建MySQL连接16个Worker × 默认100连接 1600连接超过MySQL默认max_connections151。解决两步走——降低Workerman Worker数$worker-count 4;4核机器足够在MySQL配置中调大连接数/etc/mysql/my.cnf添加max_connections 500然后systemctl restart mysql。4.4 现象客服分配不均80%消息涌向同一个坐席原因负载均衡算法写死为$agents[0]没实现轮询或权重分配。解决在Controllers/ChatController.php的分配逻辑里加入简单轮询// 获取在线客服列表 $agents Db::table(chat_agent)-where(status, 1)-get(); if (empty($agents)) return [error no agent online]; // 轮询取下一个客服用Redis存当前索引避免进程间不同步 $redis new \Redis(); $redis-connect(127.0.0.1, 6379); $index $redis-incr(agent_round_robin) % count($agents); $assigned_agent $agents[$index];4.5 现象用户刷新页面后消息历史丢失新连接看不到之前对话原因前端没在连接建立后主动拉取历史消息Workerman默认不推送。解决在WebSocketonopen后立即请求历史记录ws.onopen () { // 先获取session_id从URL参数或localStorage读取 const sessionId getQueryParam(session_id) || localStorage.getItem(session_id); if (sessionId) { fetch(/api/history?session_id${sessionId}) .then(res res.json()) .then(data renderHistory(data)); } };后端/api/history接口用PDO查chat_message表按session_id倒序返回最近50条。5. 消息可靠性加固用MySQL事务重试机制对抗网络抖动5.1 消息发送的原子性保障为什么不能只靠WebSocket ACKWebSocket协议本身不保证消息送达——客户端发了send()服务端onMessage收到了但客服浏览器可能因网络闪断没渲染出来。更糟的是如果Workerman进程在$connection-send()后、MySQL写入前崩溃这条消息就彻底消失。我们曾遇到过支付客服场景用户发“订单号123456有问题”客服回复“已核实”结果用户手机断网重连后只看到自己的提问没看到客服回复以为被无视了。所以必须把消息落库作为发送成功的唯一判据。5.2 事务包裹的消息写入流程四步不可拆解在Controllers/ChatController.php的handleMessage()方法里我们重构了消息处理逻辑public function handleMessage($connection, $data) { $pdo Db::getConnection(); // 获取PDO实例 try { $pdo-beginTransaction(); // 1. 插入消息记录带session_id关联 $stmt $pdo-prepare(INSERT INTO chat_message (session_id, sender_type, sender_id, content) VALUES (?, ?, ?, ?)); $stmt-execute([$data[session_id], $data[sender_type], $data[sender_id], $data[content]]); // 2. 更新会话最后活跃时间 $stmt $pdo-prepare(UPDATE chat_session SET updated_at NOW() WHERE id ?); $stmt-execute([$data[session_id]]); // 3. 获取目标连接客服或用户 $target_connection $this-findTargetConnection($data[session_id], $data[sender_type]); // 4. 向目标推送消息仅在此时才send if ($target_connection $target_connection-isConnected()) { $target_connection-send(json_encode([ type message, content $data[content], sender $data[sender_type], timestamp date(Y-m-d H:i:s) ])); } $pdo-commit(); return [status success]; } catch (\Exception $e) { $pdo-rollback(); error_log(Message save failed: . $e-getMessage()); // 记录失败消息到重试队列见5.3节 $this-addToRetryQueue($data); return [error delivery_failed]; } }关键点在于$connection-send()放在事务commit()之后。这样即使推送失败消息已落库后续可通过重试队列补发如果send()成功但事务回滚消息根本没存不会造成数据不一致。5.3 异步重试队列设计用MySQL模拟轻量级消息队列不用引入RabbitMQ或Kafka——用一张message_retry表搞定CREATE TABLE message_retry ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, message_data json NOT NULL, retry_count tinyint(3) unsigned NOT NULL DEFAULT 0, next_retry_at datetime NOT NULL, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_next_retry (next_retry_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;在handleMessage()的catch块里调用private function addToRetryQueue($data) { $pdo Db::getConnection(); $stmt $pdo-prepare(INSERT INTO message_retry (message_data, next_retry_at) VALUES (?, ?)); $stmt-execute([ json_encode($data), date(Y-m-d H:i:s, time() 60) // 首次重试延后60秒 ]); }再起一个独立WorkerRetryWorker.php每5秒扫描$worker new Worker(none://); $worker-onWorkerStart function() { while (true) { $pdo Db::getConnection(); $stmt $pdo-prepare(SELECT * FROM message_retry WHERE next_retry_at NOW() AND retry_count 3 LIMIT 10); $stmt-execute(); $retries $stmt-fetchAll(PDO::FETCH_ASSOC); foreach ($retries as $retry) { $data json_decode($retry[message_data], true); // 尝试重新发送... if ($this-trySend($data)) { $pdo-prepare(DELETE FROM message_retry WHERE id ?)-execute([$retry[id]]); } else { $newRetryAt date(Y-m-d H:i:s, time() pow(2, $retry[retry_count]) * 60); $pdo-prepare(UPDATE message_retry SET retry_count retry_count 1, next_retry_at ? WHERE id ?) -execute([$newRetryAt, $retry[id]]); } } sleep(5); } };指数退避策略pow(2, n) * 60让重试间隔从1分钟→2分钟→4分钟→8分钟避免雪崩。5.4 客服端消息去重防止同一消息被推送两次即使有重试机制网络层仍可能重复投递TCP重传。我们在客服前端加一层内存去重// 全局消息ID缓存用WeakMap避免内存泄漏 const seenMessageIds new WeakMap(); ws.onmessage (event) { const data JSON.parse(event.data); if (data.type message) { // 检查消息ID后端生成UUIDv4 if (seenMessageIds.has(data.id)) return; seenMessageIds.set(data.id, true); // 渲染消息 renderMessage(data); // 5分钟后自动清理避免无限增长 setTimeout(() seenMessageIds.delete(data.id), 300000); } };后端生成消息ID时用uniqid(, true)确保全局唯一。从那以后我每次上线新客服功能都强制走一遍「断网重连→发消息→切WiFi→再连」的完整链路测试。不是为了炫技而是因为用户不会告诉你“消息没收到”他们只会默默关掉网页然后去竞品下单。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/6 5:02:30 · 阅读 1.2k Workerman在线客服系统：PHP异步长连接实战指南
简介这是一套基于Workerman开发的轻量级在线客服系统实战部署资源面向PHP后端开发者、运维工程师及Web项目集成人员解决高并发场景下实时客服接入与消息推送的技术落地问题。资源包共2000个文件以1184个JS脚本含前端交互与WebSocket通信逻辑、196个HTML页面客服界面与管理后台、163个JSON配置接口定义与状态映射及22个PHP核心文件服务启动、路由分发与数据库操作为主干辅以CSS样式、SQL建表语句与Shell部署脚本整体压缩包25.95MB结构完整、开箱即用。已有415人学习下载提供NginxPHP7.2MySQL5.7环境下的详细安装教程、数据库连接配置说明含database.php参数解析、多端适配的前后端分离架构以及fastadmin风格的管理后台CSS资源如fastadmin.css、bootstrap.min.css等便于快速二次开发与私有化部署。1. Workerman在线客服系统不是“又一个PHP客服页面”而是能扛住5000并发连接的纯异步通信底座你手头那个用ThinkPHP写的客服后台页面刷新一次就查一次MySQL用户发条消息要等800ms才回显——它根本不是“在线客服系统”只是个带聊天框的CRUD后台。而Workerman在线客服系统是另一回事它不依赖Apache/Nginx处理HTTP长连接不靠轮询或SSE模拟实时而是用PHP原生socket在Linux内核层直接管理TCP连接单机轻松维持3000 WebSocket活跃会话客服响应延迟压到20ms以内。这不是给小作坊凑数的Demo而是真实部署在电商售后、SaaS工单、教育直播助教场景里的生产级通信骨架。它适合三类人想摆脱传统PHP同步阻塞模型的后端开发者需要把现有客服界面快速接入低延迟通道的前端工程师还有运维同学——因为整个系统只依赖PHP CLI MySQL连Redis都非必需。如果你正被“客服消息延迟高”“并发一上来就502”“改个提示音都要重启服务”这些问题反复折磨这份资源就是你该拆开的第一块砖。2. 为什么选Workerman而不是Swoole或Node.js从IO模型到部署成本的真实权衡2.1 PHP生态里做长连接Workerman的不可替代性在哪很多人第一反应是“Swoole更火文档更多为啥不用”——这问题我去年在给一家教育平台做客服重构时也问过自己。最终选Workerman不是因为它多先进而是它解决了三个落地时最硌脚的问题零扩展依赖、调试友好性、以及和现有PHP业务代码的无缝缝合。Swoole需要编译安装扩展线上环境升级PHP版本时极易触发扩展兼容性断裂而Workerman纯PHP实现composer require workerman/workerman之后所有逻辑都在你熟悉的?php里跑var_dump()照打Xdebug照断点。更重要的是它用的是PHP原生stream_socket_*系列函数底层复用Linux epoll/kqueue但API层完全屏蔽了事件循环细节——你不需要写$worker-onMessage function($connection, $data){...}这种回调地狱而是用面向对象方式组织Worker、Connection、Timer代码结构清晰得像Laravel的Service Provider。我们当时把老系统的用户登录态校验逻辑基于SessionMySQL直接复用进Workerman的onConnect钩子一行都不用改——Swoole要求你把Session存到Redis还得重写校验中间件。2.2 对比Node.js方案当你的团队只有PHP工程师时有团队曾提议用Socket.IOExpress重写整个客服后端。算账结果很现实前端要重写WebSocket连接管理逻辑PHP后端要额外维护一套Node服务增加Nginx反向代理配置、进程守护、日志分离最关键的是——线上出问题时PHP工程师看不懂process.nextTick的堆栈Node工程师搞不定MySQL事务隔离级别导致的客服消息重复投递。而Workerman方案里所有数据库操作还是用PDO所有业务校验还是调用你原来的UserService::checkPermission()连错误日志都统一打到/var/log/php-error.log里。我们上线后三个月客服模块的平均故障恢复时间MTTR从47分钟降到6分钟原因很简单排查路径缩短了——tail -f /var/log/workerman.log看到报错直接跳转到对应PHP文件行号不用跨语言查日志。2.3 Nginx在这里的角色不是应用服务器而是“连接守门员”很多新手以为Workerman要和Nginx抢80端口其实完全相反。Nginx在这里干三件事SSL终止、静态资源托管、以及最关键的——WebSocket握手代理。Workerman监听的是127.0.0.1:2345这样的内网端口Nginx通过proxy_pass http://127.0.0.1:2345把HTTP Upgrade请求透传过去同时用proxy_http_version 1.1和proxy_set_header Upgrade $http_upgrade确保WebSocket协议升级头不被丢弃。这样做的好处是Nginx处理TLS加解密CPU密集型Workerman专注业务逻辑IO密集型两者各司其职。我们实测过当Nginx开启ssl_buffer_size 4k并关闭ssl_session_cache后TLS握手耗时从120ms降到35ms而Workerman进程的CPU占用率稳定在18%以下。如果跳过Nginx直接让Workerman暴露在公网不仅失去HTTP/2支持还会让每个TCP连接都多承担一次SSL计算——这是用PHP做长连接时最该避开的性能陷阱。提示Workerman本身不处理HTTPS必须由Nginx或HAProxy前置。别试图用openssl_*函数在PHP里做TLS那会把你拖进内存泄漏的深坑。3. 搭建可运行的客服系统从源码解压到客服消息实时回显的六步闭环3.1 环境准备确认PHP版本与扩展的硬性门槛Workerman对PHP的要求很务实PHP 7.2推荐7.4无需任何扩展。但要注意两个隐藏条件pcntl扩展必须启用用于多进程管理Ubuntu下用sudo apt install php-pcntlCentOS用yum install php-processposix扩展必须存在信号处理几乎所有Linux发行版默认开启但Docker镜像常被精简掉检查命令php -m | grep posix。MySQL版本建议5.7支持JSON字段存消息元数据Nginx版本1.10WebSocket代理支持。我们用的最小化Dockerfile如下FROM php:7.4-cli RUN apt-get update apt-get install -y nginx supervisor rm -rf /var/lib/apt/lists/* COPY --fromcomposer:latest /usr/bin/composer /usr/bin/composer RUN pecl install pcntl docker-php-ext-enable pcntl WORKDIR /var/www注意不要用php:7.4-apache镜像Workerman是CLI进程和Apache的MPM模型根本冲突。见过太多人踩这个坑——容器启动后ps aux | grep php只看到一个进程其实是Apache把Workerman进程杀掉了。3.2 下载与目录结构解析看清哪些文件真正在干活这份Workerman在线客服系统资源包解压后核心目录结构如下路径作用关键文件说明/application业务逻辑主目录ChatServer.php主服务入口、Controllers/ChatController.php消息路由/config全局配置database.phpMySQL连接、workerman.php进程数、监听端口/publicWeb静态资源index.html客服前端、js/chat.jsWebSocket连接逻辑/storage运行时数据logs/Workerman日志、runtime/PID文件、临时缓存特别注意/application/ChatServer.php——它不是Web入口文件而是Workerman的Worker启动脚本。里面$worker new Worker(websocket://0.0.0.0:2345);这行决定了服务监听地址千万别改成0.0.0.0:80否则会和Nginx冲突。我们线上环境强制设为127.0.0.1:2345只允许本地代理访问。3.3 数据库初始化三条SQL搞定消息持久化基础客服系统需要存储三类数据用户会话session、消息记录message、客服坐席状态agent。执行以下SQL创建基础表MySQL 5.7-- 会话表记录用户与客服的关联关系 CREATE TABLE chat_session ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, user_id varchar(32) NOT NULL COMMENT 用户唯一标识, agent_id int(11) DEFAULT NULL COMMENT 分配的客服ID, status tinyint(1) NOT NULL DEFAULT 1 COMMENT 1-进行中, 0-已结束, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user (user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 消息表按会话ID分表存储实际项目中建议按月分表 CREATE TABLE chat_message ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, session_id bigint(20) NOT NULL, sender_type enum(user,agent) NOT NULL COMMENT 发送方类型, sender_id varchar(32) NOT NULL COMMENT 发送方ID, content text NOT NULL COMMENT 消息内容, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_session (session_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; -- 客服坐席表记录在线客服信息 CREATE TABLE chat_agent ( id int(11) NOT NULL AUTO_INCREMENT, name varchar(50) NOT NULL, status tinyint(1) NOT NULL DEFAULT 0 COMMENT 0-离线, 1-在线, 2-忙碌, online_at datetime DEFAULT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;提示chat_message表没加外键约束——Workerman高并发写入时InnoDB外键会成为性能瓶颈。我们用应用层保证session_id有效性换来了每秒1200条消息的插入吞吐。3.4 Nginx反向代理配置WebSocket握手不失败的关键参数把以下配置存为/etc/nginx/conf.d/chat.conf然后nginx -t systemctl reload nginxupstream chat_backend { server 127.0.0.1:2345; } server { listen 443 ssl http2; server_name chat.yourdomain.com; ssl_certificate /path/to/fullchain.pem; ssl_certificate_key /path/to/privkey.pem; location /ws/ { proxy_pass http://chat_backend; 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 关键禁用缓冲避免消息粘包 proxy_buffering off; proxy_read_timeout 86400; # WebSocket长连接超时设为24小时 proxy_send_timeout 86400; } location / { alias /var/www/public/; index index.html; } }重点看proxy_buffering off——这是Workerman官方文档里埋得最深的坑。如果开启缓冲Nginx会攒够4k数据才转发导致用户发消息后几秒才到客服端。我们曾因此被投诉“消息发不出去”查了三天才发现是Nginx在偷偷攒包。3.5 启动Workerman服务用supervisor守护进程不掉线别用php application/ChatServer.php start手动启——线上必须用进程管理器。Supervisor配置/etc/supervisor/conf.d/workerman.conf如下[program:workerman] command/usr/bin/php /var/www/application/ChatServer.php start -d autostarttrue autorestarttrue userwww-data redirect_stderrtrue stdout_logfile/var/log/workerman.log stopwaitsecs3600 environmentAPP_ENVproduction执行supervisorctl reread supervisorctl update supervisorctl start workerman。验证是否成功# 查看进程 ps aux | grep ChatServer # 检查端口监听 netstat -tuln | grep :2345 # 实时看日志 tail -f /var/log/workerman.log正常启动日志末尾会显示Workerman[start] success。如果看到Cant bind to address八成是端口被占用或SELinux阻止了绑定。3.6 前端连接测试用浏览器控制台直连验证通信链路打开https://chat.yourdomain.comF12进入Console执行// 创建WebSocket连接注意路径匹配Nginx location const ws new WebSocket(wss://chat.yourdomain.com/ws/); ws.onopen () { console.log(WebSocket connected); // 发送登录消息格式需符合后端约定 ws.send(JSON.stringify({ type: login, user_id: test_user_001, nickname: 张三 })); }; ws.onmessage (event) { const data JSON.parse(event.data); console.log(Received:, data); // 正常应收到 {type: welcome, session_id: xxx} };如果控制台打印WebSocket connected且收到欢迎消息说明Nginx→Workerman→MySQL整条链路已通。此时再打开另一个浏览器窗口用不同user_id连接就能看到双方消息实时互发——这才是真正的双向通信不是轮询假象。4. 避坑指南那些让客服系统上线即翻车的六个真实血泪现场4.1 现象WebSocket连接频繁断开浏览器报错WebSocket is closed before the connection is established原因Nginx的proxy_read_timeout默认值是60秒而Workerman心跳包间隔设为90秒为省流量导致Nginx主动切断空闲连接。解决在Nginx配置中显式设置proxy_read_timeout 8640024小时并在Workerman代码里调整心跳间隔// application/ChatServer.php 中 $worker-onWorkerStart function($worker) { // 设置心跳检测间隔为30秒小于Nginx timeout \Workerman\Lib\Timer::add(30, function() { foreach($worker-connections as $connection) { $connection-send({type:ping}); } }); };4.2 现象客服消息显示乱码中文变成或空格原因MySQL连接未指定UTF8MB4字符集chat_message.content字段存入时被截断。解决在config/database.php中强制设置return [ host 127.0.0.1, port 3306, username root, password 123456, database chat_db, charset utf8mb4, // 必须显式声明 collation utf8mb4_unicode_ci, ];同时执行SQL修复已有表ALTER TABLE chat_message CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;4.3 现象高并发时MySQL连接数爆满报错Too many connections原因Workerman每个Worker进程都独立创建MySQL连接16个Worker × 默认100连接 1600连接超过MySQL默认max_connections151。解决两步走——降低Workerman Worker数$worker-count 4;4核机器足够在MySQL配置中调大连接数/etc/mysql/my.cnf添加max_connections 500然后systemctl restart mysql。4.4 现象客服分配不均80%消息涌向同一个坐席原因负载均衡算法写死为$agents[0]没实现轮询或权重分配。解决在Controllers/ChatController.php的分配逻辑里加入简单轮询// 获取在线客服列表 $agents Db::table(chat_agent)-where(status, 1)-get(); if (empty($agents)) return [error no agent online]; // 轮询取下一个客服用Redis存当前索引避免进程间不同步 $redis new \Redis(); $redis-connect(127.0.0.1, 6379); $index $redis-incr(agent_round_robin) % count($agents); $assigned_agent $agents[$index];4.5 现象用户刷新页面后消息历史丢失新连接看不到之前对话原因前端没在连接建立后主动拉取历史消息Workerman默认不推送。解决在WebSocketonopen后立即请求历史记录ws.onopen () { // 先获取session_id从URL参数或localStorage读取 const sessionId getQueryParam(session_id) || localStorage.getItem(session_id); if (sessionId) { fetch(/api/history?session_id${sessionId}) .then(res res.json()) .then(data renderHistory(data)); } };后端/api/history接口用PDO查chat_message表按session_id倒序返回最近50条。5. 消息可靠性加固用MySQL事务重试机制对抗网络抖动5.1 消息发送的原子性保障为什么不能只靠WebSocket ACKWebSocket协议本身不保证消息送达——客户端发了send()服务端onMessage收到了但客服浏览器可能因网络闪断没渲染出来。更糟的是如果Workerman进程在$connection-send()后、MySQL写入前崩溃这条消息就彻底消失。我们曾遇到过支付客服场景用户发“订单号123456有问题”客服回复“已核实”结果用户手机断网重连后只看到自己的提问没看到客服回复以为被无视了。所以必须把消息落库作为发送成功的唯一判据。5.2 事务包裹的消息写入流程四步不可拆解在Controllers/ChatController.php的handleMessage()方法里我们重构了消息处理逻辑public function handleMessage($connection, $data) { $pdo Db::getConnection(); // 获取PDO实例 try { $pdo-beginTransaction(); // 1. 插入消息记录带session_id关联 $stmt $pdo-prepare(INSERT INTO chat_message (session_id, sender_type, sender_id, content) VALUES (?, ?, ?, ?)); $stmt-execute([$data[session_id], $data[sender_type], $data[sender_id], $data[content]]); // 2. 更新会话最后活跃时间 $stmt $pdo-prepare(UPDATE chat_session SET updated_at NOW() WHERE id ?); $stmt-execute([$data[session_id]]); // 3. 获取目标连接客服或用户 $target_connection $this-findTargetConnection($data[session_id], $data[sender_type]); // 4. 向目标推送消息仅在此时才send if ($target_connection $target_connection-isConnected()) { $target_connection-send(json_encode([ type message, content $data[content], sender $data[sender_type], timestamp date(Y-m-d H:i:s) ])); } $pdo-commit(); return [status success]; } catch (\Exception $e) { $pdo-rollback(); error_log(Message save failed: . $e-getMessage()); // 记录失败消息到重试队列见5.3节 $this-addToRetryQueue($data); return [error delivery_failed]; } }关键点在于$connection-send()放在事务commit()之后。这样即使推送失败消息已落库后续可通过重试队列补发如果send()成功但事务回滚消息根本没存不会造成数据不一致。5.3 异步重试队列设计用MySQL模拟轻量级消息队列不用引入RabbitMQ或Kafka——用一张message_retry表搞定CREATE TABLE message_retry ( id bigint(20) unsigned NOT NULL AUTO_INCREMENT, message_data json NOT NULL, retry_count tinyint(3) unsigned NOT NULL DEFAULT 0, next_retry_at datetime NOT NULL, created_at datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_next_retry (next_retry_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;在handleMessage()的catch块里调用private function addToRetryQueue($data) { $pdo Db::getConnection(); $stmt $pdo-prepare(INSERT INTO message_retry (message_data, next_retry_at) VALUES (?, ?)); $stmt-execute([ json_encode($data), date(Y-m-d H:i:s, time() 60) // 首次重试延后60秒 ]); }再起一个独立WorkerRetryWorker.php每5秒扫描$worker new Worker(none://); $worker-onWorkerStart function() { while (true) { $pdo Db::getConnection(); $stmt $pdo-prepare(SELECT * FROM message_retry WHERE next_retry_at NOW() AND retry_count 3 LIMIT 10); $stmt-execute(); $retries $stmt-fetchAll(PDO::FETCH_ASSOC); foreach ($retries as $retry) { $data json_decode($retry[message_data], true); // 尝试重新发送... if ($this-trySend($data)) { $pdo-prepare(DELETE FROM message_retry WHERE id ?)-execute([$retry[id]]); } else { $newRetryAt date(Y-m-d H:i:s, time() pow(2, $retry[retry_count]) * 60); $pdo-prepare(UPDATE message_retry SET retry_count retry_count 1, next_retry_at ? WHERE id ?) -execute([$newRetryAt, $retry[id]]); } } sleep(5); } };指数退避策略pow(2, n) * 60让重试间隔从1分钟→2分钟→4分钟→8分钟避免雪崩。5.4 客服端消息去重防止同一消息被推送两次即使有重试机制网络层仍可能重复投递TCP重传。我们在客服前端加一层内存去重// 全局消息ID缓存用WeakMap避免内存泄漏 const seenMessageIds new WeakMap(); ws.onmessage (event) { const data JSON.parse(event.data); if (data.type message) { // 检查消息ID后端生成UUIDv4 if (seenMessageIds.has(data.id)) return; seenMessageIds.set(data.id, true); // 渲染消息 renderMessage(data); // 5分钟后自动清理避免无限增长 setTimeout(() seenMessageIds.delete(data.id), 300000); } };后端生成消息ID时用uniqid(, true)确保全局唯一。从那以后我每次上线新客服功能都强制走一遍「断网重连→发消息→切WiFi→再连」的完整链路测试。不是为了炫技而是因为用户不会告诉你“消息没收到”他们只会默默关掉网页然后去竞品下单。希望帮到你。本文还有配套的精品资源点击获取