简介这是一套基于Workerman的在线客服系统源码面向需要搭建实时客服功能的PHP开发者与运维人员尤其适合已掌握Nginx、PHP、MySQL基础、希望快速部署一套可用客服系统的中初级技术人员。资源包共约2000个文件以1184个js脚本、196个html页面、163个json配置、106个css样式及22个php后端文件为主另含sql建库脚本、md说明文档与少量vue组件压缩包整体约25.95MB结构完整、前后端资源齐备。安装教程覆盖环境搭建Nginx 1.21.4、PHP 7.2、MySQL 5.7.40、源码上传解压及数据库连接配置重点说明application/database.php中数据库名、用户名与密码的填写方式读者可据此完成从环境准备到系统跑通的完整流程。目前已有415人学习下载适合作为在线客服类项目的部署参考与二次开发起点。1. 从一次客服消息丢失说起Workerman 在线客服系统到底解决什么问题很多团队做在线客服第一反应是上 HTTP 轮询前端每 3 秒问一次服务器「有没有新消息」。用户少的时候没问题一旦同时在线破千服务器就被大量空请求拖垮消息延迟还忽高忽低。更尴尬的是「正在输入」状态、访客实时轨迹、坐席转接这类功能轮询根本做不优雅。Workerman 在线客服系统要解决的就是把这套「请求-响应」模型换成常驻内存的长连接模型用 PHP 起一个常驻进程客户端和坐席都通过 WebSocket 挂上来消息由服务端主动推送。它适合谁适合已经用 PHP 做业务、又不想为了一个客服模块单独引入 Java 或 Go 技术栈的中小团队。你不需要额外学一门语言用熟悉的 PHP 就能把连接管理、消息路由、心跳保活全部握在手里。这一篇不讲空概念从进程模型讲到消息协议、从单机跑通讲到多进程排错最后落到几个能直接抄的参数和排查手法。2. Workerman 的进程模型与在线客服的选型理由2.1 为什么是常驻进程而不是 PHP-FPM传统 PHP-FPM 的生命周期是「请求进来 → 初始化 → 执行 → 销毁」每个请求都要重新加载框架、重建数据库连接。在线客服的核心诉求是「连接一直挂着、消息随时能推」这跟 FPM 的短生命周期天然冲突。Workerman 把 PHP 跑成一个常驻的 Master Worker 进程组Master 负责监听和拉起 WorkerWorker 常驻内存处理连接和业务。连接对象、在线坐席表、房间关系都放在内存里推送一条消息不需要查库、不需要走 HTTP直接遍历连接对象写回 socket。代价是你要自己管内存。常驻进程里一个没释放的数组、一个没断开的定时器跑几天就会把内存吃满。这是选型时必须接受的交换用「手动管理生命周期」换「实时推送能力」。2.2 四种进程角色怎么分工一个能上生产的客服系统进程不是随便起的常见做法是按职责拆成四类进程角色职责常见数量关键点Gateway维持客户端 WebSocket 连接按连接数扩只做收发不碰业务BusinessWorker处理消息逻辑、路由按 CPU 核数无状态可水平扩Register内部服务注册与发现1Gateway 和 Worker 靠它互相找到定时/推送进程心跳检测、离线消息补发12避免和业务 Worker 抢资源Gateway 和 BusinessWorker 分离是 Workerman 生态里很关键的一步。Gateway 只管连接BusinessWorker 只管逻辑两者通过内部协议通信。好处是坐席逻辑改崩了不会把连接层带崩扩容时也能分别扩。新手最容易犯的错是把所有逻辑塞进一个 Worker连接一多业务一卡整个服务全挂。2.3 最小可跑通的目录与启动脚本先不接数据库把「客户端连上、发消息、服务端回显」跑通这是后面所有功能的地基。# 目录结构纯手工建不依赖任何框架 workerman-kefu/ ├── start.php # 入口注册所有 Worker ├── app/ │ ├── Gateway.php # 连接层 │ └── Business.php # 业务层 └── composer.json# 安装 workerman用 composer版本以你本地拉到的为准 composer require workerman/workerman?php // start.php —— 入口文件只做进程注册不写业务 require_once __DIR__ . /vendor/autoload.php; use Workerman\Worker; // 1. 连接层对外暴露 WebSocket $gateway new Worker(websocket://0.0.0.0:8282); $gateway-name Gateway; $gateway-count 2; // 连接层进程数按并发调 $gateway-reusePort true; // 多进程共享端口减少惊群 // 2. 业务层处理消息逻辑 $business new Worker(); $business-name BusinessWorker; $business-count 4; // 一般等于 CPU 核数 $business-onWorkerStart function ($worker) { // 这里注册消息处理回调见下一章 }; // 3. 内部注册中心 $register new Worker(text://0.0.0.0:1236); $register-name Register; Worker::runAll();逻辑说明reusePort true让多个 Gateway 进程各自持有同一个端口的监听内核层面做负载比单进程 accept 再分发要平滑。count不是越大越好Gateway 进程数超过 CPU 核数太多上下文切换反而拖慢。参数上websocket://0.0.0.0:8282的 8282 是示例端口生产环境记得在防火墙只放行必要来源。启动用php start.php start调试用start后台跑用start -d改完代码要restart而不是reloadreload 不会重载入口文件里的进程定义。3. 消息协议设计与坐席路由的落地实现3.1 自定义 JSON 协议字段怎么定WebSocket 只负责传字节传什么格式是你自己定的。客服场景消息类型多文本、图片、转接、已读回执、正在输入。常见做法是统一一个 JSON 信封用type区分避免每种消息一套解析逻辑。{ type: chat.message, msg_id: c-20240101-0001, from: visitor_8821, to: agent_007, ts: 1704067200, payload: { content: 你好订单还没发货, content_type: text } }字段设计有几个血泪经验msg_id必须客户端生成并回传服务端用它做去重和回执关联否则弱网重发会出现重复消息ts用秒级时间戳别用毫秒字符串排序时容易踩坑type用「域.动作」两段式后面加类型不会和旧类型撞名。payload单独一层是为了让文本、图片、订单卡片共用外层路由字段解析时先看type再决定怎么读payload。3.2 坐席分配轮询、最少连接还是技能组访客进来要分给哪个坐席是客服系统最核心的一段逻辑。三种常见策略轮询实现最简单但坐席忙闲不均一个坐席手上压 20 个会话另一个闲着。最少连接按当前会话数排序取最小均衡性好实现也不复杂是多数团队的首选。技能组按业务线售前/售后/技术先分组组内再按最少连接分适合业务复杂的团队。下面是最少连接的落地写法坐席在线状态和会话数都放内存?php // app/Business.php 片段坐席分配 class AgentPool { // agent_id [conn 连接对象, sessions 当前会话数, group 技能组] public static $agents []; // 为一个访客挑选坐席 public static function pick($group default) { $best null; foreach (self::$agents as $id $info) { if ($info[group] ! $group) { continue; // 技能组不匹配直接跳过 } if ($best null || $info[sessions] $best[sessions]) { $best [id $id] $info; } } return $best; // 返回 null 表示无可用坐席 } // 会话结束时务必调用否则 sessions 只增不减 public static function release($agentId) { if (isset(self::$agents[$agentId])) { self::$agents[$agentId][sessions]--; } } }逻辑说明pick遍历所有在线坐席按sessions取最小。参数$group是技能组标识默认组兜底。这里有个必须强调的点sessions的增减必须成对分配时加一、会话关闭时减一。我见过线上坐席数明明够却一直提示「无可用坐席」排查半天发现是会话关闭的回调里漏了release计数只涨不跌坐席全被「假占满」。所以release一定要挂在连接断开和会话主动结束两个地方。3.3 心跳保活与断线重连长连接最怕「假死」网络断了但两端都没察觉消息发出去石沉大海。Workerman 自带onClose但移动网络下连接可能既不报错也不关闭。常见做法是应用层心跳客户端每 30 秒发一个ping服务端回pong服务端超过 90 秒没收到任何数据就主动断开。?php // 服务端心跳检测挂在 BusinessWorker 的 onWorkerStart 里 use Workerman\Timer; $business-onWorkerStart function ($worker) { Timer::add(30, function () { $now time(); foreach (AgentPool::$agents as $id $info) { // last_active 在每次收到该连接消息时更新 if ($now - $info[last_active] 90) { $info[conn]-close(); // 触发 onClose走清理逻辑 } } }); };参数说明检测周期 30 秒、超时阈值 90 秒是「3 次心跳丢失判定离线」的常见配比。周期太短浪费流量太长断线感知迟钝。客户端侧要配指数退避重连第一次 1 秒、第二次 2 秒、依次翻倍到 30 秒封顶避免服务端刚重启就被海量重连打垮。重连成功后第一件事是重新拉取未读消息而不是假设本地状态还对。4. 避坑与排查上线后最容易翻车的五个点4.1 消息重复现象是访客收到两条一样的回复现象弱网或客户端重连后同一条消息被处理两次访客看到重复回复。原因客户端超时重发服务端没有幂等判断msg_id形同虚设。解决服务端维护一个近期msg_id集合用 Redis 或内存 LRU处理前先查命中就直接丢弃并回一个已处理的回执。集合要设过期时间否则内存无限涨。4.2 内存只涨不降跑三天进程被 OOM 杀掉现象php start.php status看到某个 Worker 内存持续上涨几天后被系统杀掉。原因常驻进程里往静态数组塞数据却从不清理比如把每条历史消息都存进$allMessages。解决所有「按会话/按用户」累积的结构都要有清理时机会话结束就删排查时用status命令看各进程内存定位到具体 Worker 再回代码里找全局变量。4.3 坐席收不到转接消息跨进程连接找不到现象访客被转接给坐席 B但 B 的客户端没反应。原因Gateway 是多进程的访客连在进程 1、坐席 B 连在进程 2业务代码只在当前进程的连接表里找自然找不到。解决连接寻址必须走 Gateway 提供的跨进程发送接口按 client_id 发不要自己维护「进程内连接数组」然后直接遍历。这是 Gateway/Worker 分离架构里最经典的坑。4.4 定时器重复注册一条消息被推了 N 次现象某个提醒消息被推送了多次次数正好等于 Worker 进程数。原因Timer::add写在了onWorkerStart里而 Worker 有 4 个进程每个进程都注册了一遍定时器。解决定时任务要么只在一个进程里注册用进程 id 判断要么把定时逻辑独立成一个count 1的 Worker。凡是「全局只该跑一次」的逻辑都要显式限制进程数。4.5 平滑重启丢消息reload 期间连接被断现象发版reload时部分在线访客的连接被断开正在输入的内容丢失。原因reload 会平滑重启 Worker连接会短暂中断如果客户端没做重连和消息补发用户就感知到掉线。解决发版尽量选低峰期客户端必须实现重连 未读补拉服务端在断开前可以给客户端发一个「服务维护中」的提示帧让前端给出友好提示而不是白屏。5. 把客服系统做稳的三个进阶习惯第一个习惯是给消息加「可观测性」。别等用户投诉才发现问题在消息进出两个关键点打结构化日志msg_id、from、to、type、耗时。出问题时用msg_id一路 grep能快速判断是没收到、没路由还是没推送。日志别写进常驻进程的标准输出就完事要落到文件或日志服务否则进程一重启全没了。第二个习惯是把「在线状态」当成有生命周期的资源来管。坐席上线写进AgentPool下线、断线、超时三种情况都要触发清理且清理逻辑要幂等——重复清理不能把计数减成负数。我一般会在清理函数入口先判断这个坐席是否还在池子里不在就直接返回。这个判断看着多余但线上真能挡住不少重复回调引发的脏数据。第三个习惯是压测要压「连接数」而不是只压「消息量」。客服系统的瓶颈往往在同时挂着的连接数上而不是每秒消息条数。用脚本模拟几千个 WebSocket 连接挂着不发消息观察内存和文件描述符再模拟一部分连接高频发消息观察 BusinessWorker 的 CPU。两个维度分开压才能知道该扩 Gateway 还是扩 BusinessWorker。文件描述符上限ulimit -n是新手最容易忽略的连接一多就报「too many open files」改完系统限制记得重启进程才生效。最后说个我自己的教训早期我图省事把坐席分配、消息存储、推送全塞进一个 Worker本地测几十个连接一切正常上线到几百连接就开始随机卡顿排查了两天才意识到是单进程里一个慢查询把整个消息循环堵住了。后来拆成 Gateway BusinessWorker慢查询只影响业务层连接层照常收发问题立刻可控。做这类常驻服务职责分离不是架构洁癖是保命手段。希望帮到你。本文还有配套的精品资源点击获取
简介这是一套基于Workerman的在线客服系统源码面向需要搭建实时客服功能的PHP开发者与运维人员尤其适合已掌握Nginx、PHP、MySQL基础、希望快速部署一套可用客服系统的中初级技术人员。资源包共约2000个文件以1184个js脚本、196个html页面、163个json配置、106个css样式及22个php后端文件为主另含sql建库脚本、md说明文档与少量vue组件压缩包整体约25.95MB结构完整、前后端资源齐备。安装教程覆盖环境搭建Nginx 1.21.4、PHP 7.2、MySQL 5.7.40、源码上传解压及数据库连接配置重点说明application/database.php中数据库名、用户名与密码的填写方式读者可据此完成从环境准备到系统跑通的完整流程。目前已有415人学习下载适合作为在线客服类项目的部署参考与二次开发起点。1. 从一次客服消息丢失说起Workerman 在线客服系统到底解决什么问题很多团队做在线客服第一反应是上 HTTP 轮询前端每 3 秒问一次服务器「有没有新消息」。用户少的时候没问题一旦同时在线破千服务器就被大量空请求拖垮消息延迟还忽高忽低。更尴尬的是「正在输入」状态、访客实时轨迹、坐席转接这类功能轮询根本做不优雅。Workerman 在线客服系统要解决的就是把这套「请求-响应」模型换成常驻内存的长连接模型用 PHP 起一个常驻进程客户端和坐席都通过 WebSocket 挂上来消息由服务端主动推送。它适合谁适合已经用 PHP 做业务、又不想为了一个客服模块单独引入 Java 或 Go 技术栈的中小团队。你不需要额外学一门语言用熟悉的 PHP 就能把连接管理、消息路由、心跳保活全部握在手里。这一篇不讲空概念从进程模型讲到消息协议、从单机跑通讲到多进程排错最后落到几个能直接抄的参数和排查手法。2. Workerman 的进程模型与在线客服的选型理由2.1 为什么是常驻进程而不是 PHP-FPM传统 PHP-FPM 的生命周期是「请求进来 → 初始化 → 执行 → 销毁」每个请求都要重新加载框架、重建数据库连接。在线客服的核心诉求是「连接一直挂着、消息随时能推」这跟 FPM 的短生命周期天然冲突。Workerman 把 PHP 跑成一个常驻的 Master Worker 进程组Master 负责监听和拉起 WorkerWorker 常驻内存处理连接和业务。连接对象、在线坐席表、房间关系都放在内存里推送一条消息不需要查库、不需要走 HTTP直接遍历连接对象写回 socket。代价是你要自己管内存。常驻进程里一个没释放的数组、一个没断开的定时器跑几天就会把内存吃满。这是选型时必须接受的交换用「手动管理生命周期」换「实时推送能力」。2.2 四种进程角色怎么分工一个能上生产的客服系统进程不是随便起的常见做法是按职责拆成四类进程角色职责常见数量关键点Gateway维持客户端 WebSocket 连接按连接数扩只做收发不碰业务BusinessWorker处理消息逻辑、路由按 CPU 核数无状态可水平扩Register内部服务注册与发现1Gateway 和 Worker 靠它互相找到定时/推送进程心跳检测、离线消息补发12避免和业务 Worker 抢资源Gateway 和 BusinessWorker 分离是 Workerman 生态里很关键的一步。Gateway 只管连接BusinessWorker 只管逻辑两者通过内部协议通信。好处是坐席逻辑改崩了不会把连接层带崩扩容时也能分别扩。新手最容易犯的错是把所有逻辑塞进一个 Worker连接一多业务一卡整个服务全挂。2.3 最小可跑通的目录与启动脚本先不接数据库把「客户端连上、发消息、服务端回显」跑通这是后面所有功能的地基。# 目录结构纯手工建不依赖任何框架 workerman-kefu/ ├── start.php # 入口注册所有 Worker ├── app/ │ ├── Gateway.php # 连接层 │ └── Business.php # 业务层 └── composer.json# 安装 workerman用 composer版本以你本地拉到的为准 composer require workerman/workerman?php // start.php —— 入口文件只做进程注册不写业务 require_once __DIR__ . /vendor/autoload.php; use Workerman\Worker; // 1. 连接层对外暴露 WebSocket $gateway new Worker(websocket://0.0.0.0:8282); $gateway-name Gateway; $gateway-count 2; // 连接层进程数按并发调 $gateway-reusePort true; // 多进程共享端口减少惊群 // 2. 业务层处理消息逻辑 $business new Worker(); $business-name BusinessWorker; $business-count 4; // 一般等于 CPU 核数 $business-onWorkerStart function ($worker) { // 这里注册消息处理回调见下一章 }; // 3. 内部注册中心 $register new Worker(text://0.0.0.0:1236); $register-name Register; Worker::runAll();逻辑说明reusePort true让多个 Gateway 进程各自持有同一个端口的监听内核层面做负载比单进程 accept 再分发要平滑。count不是越大越好Gateway 进程数超过 CPU 核数太多上下文切换反而拖慢。参数上websocket://0.0.0.0:8282的 8282 是示例端口生产环境记得在防火墙只放行必要来源。启动用php start.php start调试用start后台跑用start -d改完代码要restart而不是reloadreload 不会重载入口文件里的进程定义。3. 消息协议设计与坐席路由的落地实现3.1 自定义 JSON 协议字段怎么定WebSocket 只负责传字节传什么格式是你自己定的。客服场景消息类型多文本、图片、转接、已读回执、正在输入。常见做法是统一一个 JSON 信封用type区分避免每种消息一套解析逻辑。{ type: chat.message, msg_id: c-20240101-0001, from: visitor_8821, to: agent_007, ts: 1704067200, payload: { content: 你好订单还没发货, content_type: text } }字段设计有几个血泪经验msg_id必须客户端生成并回传服务端用它做去重和回执关联否则弱网重发会出现重复消息ts用秒级时间戳别用毫秒字符串排序时容易踩坑type用「域.动作」两段式后面加类型不会和旧类型撞名。payload单独一层是为了让文本、图片、订单卡片共用外层路由字段解析时先看type再决定怎么读payload。3.2 坐席分配轮询、最少连接还是技能组访客进来要分给哪个坐席是客服系统最核心的一段逻辑。三种常见策略轮询实现最简单但坐席忙闲不均一个坐席手上压 20 个会话另一个闲着。最少连接按当前会话数排序取最小均衡性好实现也不复杂是多数团队的首选。技能组按业务线售前/售后/技术先分组组内再按最少连接分适合业务复杂的团队。下面是最少连接的落地写法坐席在线状态和会话数都放内存?php // app/Business.php 片段坐席分配 class AgentPool { // agent_id [conn 连接对象, sessions 当前会话数, group 技能组] public static $agents []; // 为一个访客挑选坐席 public static function pick($group default) { $best null; foreach (self::$agents as $id $info) { if ($info[group] ! $group) { continue; // 技能组不匹配直接跳过 } if ($best null || $info[sessions] $best[sessions]) { $best [id $id] $info; } } return $best; // 返回 null 表示无可用坐席 } // 会话结束时务必调用否则 sessions 只增不减 public static function release($agentId) { if (isset(self::$agents[$agentId])) { self::$agents[$agentId][sessions]--; } } }逻辑说明pick遍历所有在线坐席按sessions取最小。参数$group是技能组标识默认组兜底。这里有个必须强调的点sessions的增减必须成对分配时加一、会话关闭时减一。我见过线上坐席数明明够却一直提示「无可用坐席」排查半天发现是会话关闭的回调里漏了release计数只涨不跌坐席全被「假占满」。所以release一定要挂在连接断开和会话主动结束两个地方。3.3 心跳保活与断线重连长连接最怕「假死」网络断了但两端都没察觉消息发出去石沉大海。Workerman 自带onClose但移动网络下连接可能既不报错也不关闭。常见做法是应用层心跳客户端每 30 秒发一个ping服务端回pong服务端超过 90 秒没收到任何数据就主动断开。?php // 服务端心跳检测挂在 BusinessWorker 的 onWorkerStart 里 use Workerman\Timer; $business-onWorkerStart function ($worker) { Timer::add(30, function () { $now time(); foreach (AgentPool::$agents as $id $info) { // last_active 在每次收到该连接消息时更新 if ($now - $info[last_active] 90) { $info[conn]-close(); // 触发 onClose走清理逻辑 } } }); };参数说明检测周期 30 秒、超时阈值 90 秒是「3 次心跳丢失判定离线」的常见配比。周期太短浪费流量太长断线感知迟钝。客户端侧要配指数退避重连第一次 1 秒、第二次 2 秒、依次翻倍到 30 秒封顶避免服务端刚重启就被海量重连打垮。重连成功后第一件事是重新拉取未读消息而不是假设本地状态还对。4. 避坑与排查上线后最容易翻车的五个点4.1 消息重复现象是访客收到两条一样的回复现象弱网或客户端重连后同一条消息被处理两次访客看到重复回复。原因客户端超时重发服务端没有幂等判断msg_id形同虚设。解决服务端维护一个近期msg_id集合用 Redis 或内存 LRU处理前先查命中就直接丢弃并回一个已处理的回执。集合要设过期时间否则内存无限涨。4.2 内存只涨不降跑三天进程被 OOM 杀掉现象php start.php status看到某个 Worker 内存持续上涨几天后被系统杀掉。原因常驻进程里往静态数组塞数据却从不清理比如把每条历史消息都存进$allMessages。解决所有「按会话/按用户」累积的结构都要有清理时机会话结束就删排查时用status命令看各进程内存定位到具体 Worker 再回代码里找全局变量。4.3 坐席收不到转接消息跨进程连接找不到现象访客被转接给坐席 B但 B 的客户端没反应。原因Gateway 是多进程的访客连在进程 1、坐席 B 连在进程 2业务代码只在当前进程的连接表里找自然找不到。解决连接寻址必须走 Gateway 提供的跨进程发送接口按 client_id 发不要自己维护「进程内连接数组」然后直接遍历。这是 Gateway/Worker 分离架构里最经典的坑。4.4 定时器重复注册一条消息被推了 N 次现象某个提醒消息被推送了多次次数正好等于 Worker 进程数。原因Timer::add写在了onWorkerStart里而 Worker 有 4 个进程每个进程都注册了一遍定时器。解决定时任务要么只在一个进程里注册用进程 id 判断要么把定时逻辑独立成一个count 1的 Worker。凡是「全局只该跑一次」的逻辑都要显式限制进程数。4.5 平滑重启丢消息reload 期间连接被断现象发版reload时部分在线访客的连接被断开正在输入的内容丢失。原因reload 会平滑重启 Worker连接会短暂中断如果客户端没做重连和消息补发用户就感知到掉线。解决发版尽量选低峰期客户端必须实现重连 未读补拉服务端在断开前可以给客户端发一个「服务维护中」的提示帧让前端给出友好提示而不是白屏。5. 把客服系统做稳的三个进阶习惯第一个习惯是给消息加「可观测性」。别等用户投诉才发现问题在消息进出两个关键点打结构化日志msg_id、from、to、type、耗时。出问题时用msg_id一路 grep能快速判断是没收到、没路由还是没推送。日志别写进常驻进程的标准输出就完事要落到文件或日志服务否则进程一重启全没了。第二个习惯是把「在线状态」当成有生命周期的资源来管。坐席上线写进AgentPool下线、断线、超时三种情况都要触发清理且清理逻辑要幂等——重复清理不能把计数减成负数。我一般会在清理函数入口先判断这个坐席是否还在池子里不在就直接返回。这个判断看着多余但线上真能挡住不少重复回调引发的脏数据。第三个习惯是压测要压「连接数」而不是只压「消息量」。客服系统的瓶颈往往在同时挂着的连接数上而不是每秒消息条数。用脚本模拟几千个 WebSocket 连接挂着不发消息观察内存和文件描述符再模拟一部分连接高频发消息观察 BusinessWorker 的 CPU。两个维度分开压才能知道该扩 Gateway 还是扩 BusinessWorker。文件描述符上限ulimit -n是新手最容易忽略的连接一多就报「too many open files」改完系统限制记得重启进程才生效。最后说个我自己的教训早期我图省事把坐席分配、消息存储、推送全塞进一个 Worker本地测几十个连接一切正常上线到几百连接就开始随机卡顿排查了两天才意识到是单进程里一个慢查询把整个消息循环堵住了。后来拆成 Gateway BusinessWorker慢查询只影响业务层连接层照常收发问题立刻可控。做这类常驻服务职责分离不是架构洁癖是保命手段。希望帮到你。本文还有配套的精品资源点击获取
