开源PHP客服系统WeLive实战：部署、轮询机制与二次开发-北京尧图网络

简介这是一款用PHP开发的开源企业级在线客服系统基于全双工通信技术适合需要将客服功能独立部署在自有服务器上的网站开发者与外贸业务运营者。系统提供中英文双语自动切换、五种配色方案、人工智能机器人自动回复、访客文件上传授权以及多窗口模式切换等实用功能。压缩包内共包含二百八十七个文件以PHP程序文件为主体辅以前端样式脚本、图片图标和提示音素材整体大小仅有一点六兆便于快速获取与部署。已有三百三十二人学习下载。对想要快速搭建或了解客服系统实现的开发者这份资源提供了可直接运行的完整代码、数据库建表语句及常见配置说明既可投入实际使用也能帮助深入理解实时通信与客服系统的整体架构。1. 从一个小需求聊起为什么要在网站里自建客服通道客服系统是个低频但刚需的模块。之前帮客户维护一个小商城老板一直想装个“点开就能聊”的在线客服第三方平台按坐席收费还强制弹广告数据也拿不回来。后来翻到WeLive这套免费开源的PHP客服系统前端是仿QQ的聊天窗后台管坐席分组、访客会话、历史消息部署在自己服务器上数据完全可控。对个人站长、外包项目和中小团队来说这是性价比很高的一条路。下文按部署、原理、二次开发、避坑、进阶的顺序拆一遍想在自己网站上装一套能用客服系统的可以照抄。2. 部署环境LNMP下安装WeLive的版本选择与参数配置部署环境决定后续踩多少坑。WeLive是纯PHP项目理论上放PHPMySQL环境就能跑但版本选不对安装页面直接白屏或者装完聊天窗一直转圈。先把不翻车的选型说清楚再给完整参数。2.1 PHP版本与扩展别直接上最新版WeLive这套源码的核心逻辑还保留着PHP 5时代的写法虽然能在PHP 7下运行但PHP 8以后废弃了不少旧函数比如mysql_*系列、each()装到新版本上大概率白屏或报“Function not found”。我一般建议用PHP 7.2或7.4Nginx搭PHP-FPM稳定性和兼容性都平衡。如果你服务器上已经装了PHP 8.x别急着跑安装向导先准备一个PHP 7.4的版本再继续。先确认扩展有没有装全。用下面这个脚本检测?php // check.php部署前环境自检放在网站根目录临时运行 $required [pdo_mysql, mysqli, curl, gd, mbstring]; foreach ($required as $ext) { echo $ext, : , extension_loaded($ext) ? OK : MISSING, PHP_EOL; }这段脚本用extension_loaded()逐一检查WeLive运行需要的基础扩展。pdo_mysql和mysqli是数据库连接用的缺了会连不上MySQLcurl用于访客端发消息时可能触发的HTTP回调gd用于生成验证码后台登录没有验证码图就是它的锅mbstring影响中文字符串截取和字符集转换缺了聊天内容可能出现乱码。还有两个php.ini参数需要注意。一个是memory_limit建议至少128M另一个是upload_max_filesize如果访客要在聊天里传图片这个值默认2M太小我一般改成8M左右memory_limit 128M upload_max_filesize 8M post_max_size 8M max_execution_time 120post_max_size如果小于upload_max_filesize上传还是失败所以两者保持一样。max_execution_time主要影响后台导出历史消息这类耗时的操作默认30秒可能中途断掉。2.2 Web服务器与数据库Nginx伪静态、MySQL建库Web服务器用Nginx的话需要在server块里配置PHP解析路径。WeLive的入口是index.php访客端和坐席端共用一套入口目录结构里会区分admin和client。下面这份Nginx配置可以直接参考server { listen 80; server_name kefu.example.com; root /var/www/weLive; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include fastcgi_params; fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }这里关键的是try_files $uri $uri/ /index.php?$query_string把不存在的路径转发给index.php这样访客端访问、路由分发都走同一个入口。fastcgi_pass指向PHP-FPM监听的端口如果PHP-FPM用的是socket方式要改成unix:/run/php/php7.4-fpm.sock具体取决于环境。另外一点如果服务器上同时跑着多个PHP项目每个项目的fastcgi_param最好单独核对否则容易出现“这个项目能跑那个项目404”。还有个小习惯Nginx配置改完先nginx -t再reload别直接 restart否则配置写错会让整个站瞬间挂掉。数据库直接用MySQL 5.7或者MariaDB 10.3都行建库时注意字符集统一用utf8CREATE DATABASE welive DEFAULT CHARACTER SET utf8; CREATE USER welivelocalhost IDENTIFIED BY 你的密码; GRANT ALL PRIVILEGES ON welive.* TO welivelocalhost; FLUSH PRIVILEGES;用命令行建库的好处是不容易踩编码的坑。如果安装时手动建的库选成了utf8mb4_unicode_ci大部分情况下问题不大但个别老版本表用的TEXT字段存中文时字符集不统一会导致串字符。真正需要留意的是安装向导里填的库名和这里的库名保持一致包括大小写。2.3 安装向导与目录权限十分钟跑起来的步骤下载包解压后根目录一般会有一个 install/ 目录或者安装引导入口具体看包内结构常见的是一个install.php文件加一个 install 目录安装页会让你填数据库地址、库名、用户名、密码以及管理员账号。步骤如下把源码传到Web根目录比如/var/www/weLive用浏览器访问http://你的域名/install/开始安装填数据库连接参数创建管理员密码完成后按页面提示删除或重命名 install 目录防止重装或被人利用登录后台看左侧菜单是否能正常加载。注意安装完成后服务端代码里可能有一个用于存放缓存和会话文件的目录通常是runtime/或tmp/必须让PHP进程有写权限。权限给太大不安全最小化配置一般是以下两条chmod -R 755 /var/www/weLive chmod -R 775 /var/www/weLive/runtime chown -R www-data:www-data /var/www/weLive这里面的道理是代码文件只需要读权限所以755足够runtime目录要写所以给775属主改成www-data确保PHP-FPM进程以www-data身份运行能直接写入。如果主机环境用的不是www-data用户先ps aux | grep php-fpm看进程用户按实际用户来改。权限这块经常被忽略访客端可以打开、但坐席端登录不了十有八九就是runtime目录没有写入权限。安装完成后别急着删install目录先登录后台把基本参数填一遍确认坐席端能登录、访客端能弹出聊天窗再回头清理install。这个顺序能避免“装完发现配置不对想重装又装不了”的尴尬。3. 核心逻辑拆解访客会话、坐席分配与消息推送的工作方式装完只是第一步。要是不知道系统是怎么跑起来的后面调参和排错会很痛苦。这章把三条核心链路讲清楚访客怎么和坐席建立会话、消息怎么到达对方、坐席多了以后谁接这条消息。3.1 会话生命周期cookie标识与坐席分组分配规则访客访问部署了客服脚本的页面时会加载一段JSJS会拼出一个链接去请求服务端的client/index.php之类入口这时系统会做几件事生成一个访客标识写入cookie、把访客信息来源页、IP、浏览器UA落表、然后进入“排队等待坐席”状态。这个标识是整个会话的主键后续所有消息都挂在它下面。用cookie而不是session是因为访客cookie天然能跨刷新、跨页面保持session在php.ini配置不好时容易丢。访客端脚本一般有两种接入方式一种是全站异步加载每个页面右下角都出现浮动按钮另一种是手动指定按钮位置只在你需要的位置触发。不管哪种cookie的生成逻辑是一致的。会话分配规则一般按两个层级来先看访客进入时带的“分组参数”比如移动端访客进移动客服组再看坐席的在线状态和当前接待人数。如果所有坐席都不在线访客会看到“留言”按钮消息转成离线留言。这个决策过程用伪代码可以描述成?php // visitor_route.php访客进来时的坐席分配决策 function routeToAgent($visitorGroup, $agents) { // 1. 先按分组筛选出可接单的坐席 $candidates array_filter($agents, function($agent) use ($visitorGroup) { return $agent[online] $agent[group] $visitorGroup; }); // 2. 按当前接待数升序排列 usort($candidates, function($a, $b) { return $a[current_load] $b[current_load]; }); // 3. 取最空闲的那个否则返回false进入留言 return $candidates ? $candidates[0] : false; }routeToAgent做的是“找得到人才分配”的兜底逻辑。online字段由坐席端的定时心跳维持长时间没有心跳系统会自动置为离线。current_load是坐席正在接待的会话数有的系统里也叫“接待上限”可以避免消息全部堆到某一个坐席身上。这套逻辑的核心取舍是优先保证“有人接”其次才追求“分配给最合适的人”。实际排错时如果“访客在排队一直没人接”按这个函数的逻辑去查非常快先查坐席是否在线、再查分组是否匹配、最后查接待数是否到达上限。3.2 消息推送短轮询机制的间隔参数与负载取舍WeLive这类老牌PHP系统访客端和坐席端一般不做WebSocket而是用轮询前端每N秒发一次请求问“有没有新消息”。坐席端后台界面通常会有一个可见的时间参数配置比如“会话刷新间隔”常见默认是3秒或5秒。轮询间隔是非常核心的参数。调得越小消息越接近实时但服务器压力线性上升500个并发访客、每3秒一次轮询后台相当于同时扛着每秒160的轻量查询。调得太大比如10秒聊天体验明显“卡顿”客户容易觉得没人理。三种方案放一起对比就能理解为什么老系统选短轮询方案实时性服务器压力实现复杂度短轮询取决于间隔通常1-5秒高和并发数线性相关低PHP天然支持长轮询较好1秒内中但连接占用久中需要处理挂起请求WebSocket毫秒级低一次连接反复用高需要常驻服务WeLive默认选短轮询不是技术上做不了WebSocket而是为了降低部署门槛纯PHP环境就能跑不需要额外装swoole或Node服务。知道这一点你就能接受它的短板。一个折中方案是访客端用较短的间隔比如2秒坐席端用稍长的间隔比如3秒两端分开配置。原因是访客端是客户体验优先级高坐席端同时在线人数远少于访客数压力可以接受。改参数的位置一般在后台“系统设置→会话参数”里如果找不到直接查数据库里的设置表-- 查询当前刷新间隔配置 SELECT param_key, param_value FROM setting WHERE param_key IN (poll_interval_client, poll_interval_agent);poll_interval_client对应访客端轮询间隔poll_interval_agent对应坐席端。改成多少合适没有绝对答案和服务器配置强相关。单机2核4G、总共几百个在线访客的场景我会把访客端设成2秒、坐席端设成3秒如果机器只有1核改成3秒/4秒更稳。监控手段也很简单看PHP-FPM的CPU占用和MySQL的QPS哪边吃紧就回调间隔。3.3 坐席分流技能组与并发接待数限制多坐席团队在后台会建多个分组比如“售前组”“售后组”。每个坐席可以归属一个或多个分组系统再给坐席设置最大接待数。分流时有两处容易理解错的地方一是访客点“转人工”后不一定会再分配一次很多实现里只是改了会话状态二是接待数限制的作用点是“正在进行的会话数”不是“今天的会话总数”。如果坐席的接待数已经到达上限即使在线在候选列表里也会被过滤掉。理解这一点调试“明明两个坐席都开着客户却被分给同一个人”这类问题就很快。排查坐席分配问题时我常用的SQL是先看坐席状态-- 查看所有坐席的在线状态、分组和当前接待数 SELECT id, realname, online, group_id, current_load, max_load FROM agent WHERE online 1 ORDER BY current_load ASC;执行完基本一眼就能看出问题。如果current_load都等于max_load说明接待数全部打满新访客只能排队或留言。如果online0但坐席明明在浏览器里开着后台那是心跳机制的问题按第5章的方法去处理。这部分没有标准答案每个发行版的实现细节略有差异但排查思路是一致的先看坐席是否真的在线再看分组是否匹配最后看接待数是不是满了。4. 二次开发对接自有用户体系与界面定制开源系统的价值一半在于能改。这一章讲两个最常见的改动把WeLive和现有网站的用户系统打通以及把前端界面改成自己公司的风格。4.1 免登录接入把现有用户ID与客服系统绑定如果网站本身已有用户系统不想让用户再注册一个客服账号可以做一个“免登录接入”网站端生成一个token带着用户信息和签名跳转到客服系统客服系统验签通过后直接建立会话。一个最简的实现思路是网站这边写一个接口生成带用户ID的加密串在页面挂客服JS时把这个参数传过去?php // token_generate.php生成带签名的访问令牌 $secret 替换成你自己的盐值; $payload json_encode([ uid 10001, // 你自己系统的用户ID nickname 王小明, expire time() 600, // 令牌10分钟有效 ]); $token hash_hmac(sha256, $payload, $secret); $visitUrl https://kefu.example.com/client/index.php?token . urlencode(base64_encode($payload)) . sign . $token;这段逻辑的核心是用hash_hmac对用户信息做签名对方拿到参数后用同一个密钥计算签名一致才放行。expire字段不是必须的但建议加上防止token被拿去反复请求。密钥只保存在网站和客服系统服务端千万不要下发到页面JS里。验签后只要查一下这个访客ID有没有历史会话有就恢复没有就新建会话。这样用户不用输入任何客服系统账号体验就顺了。这里有个很容易被忽略的点接完免登录后客服系统里看到的访客昵称是你传的nickname而不是系统随机生成的“访客1234”这对坐席识别老客户非常关键。数据表里的对话记录也会带上uid方便后续做“这个用户之前买过什么”的画像分析。4.2 界面与文案修改改访客端浮动框和聊天窗访客端的表现形态一般是右下角的浮动按钮点开是聊天窗。样式文件多数在/client/views/default/这种结构下具体名称以实际包为准。改起来无非两类改CSS换配色改模板换文案和结构。CSS部分全局查找主色变量比如按钮背景色会有一两处定义替换成自己的品牌色即可。聊天窗的标题文字一般直接改模板文件里的HTML文本就行。有两点容易忽略一是改完记得清浏览器缓存或给CSS文件加版本号否则用户看到的还是旧的二是浮动按钮在手机端的位置默认在右下角如果和网站自己的悬浮二维码插件抢位置需要单独加媒体查询调间距media (max-width: 768px) { .welive_float_btn { right: 12px !important; bottom: 70px !important; } }!important在这里是为了覆盖JS里可能内联的样式没有它某些移动端浏览器还会取内联样式的值改了半天看不出效果。如果只是想改图标和欢迎语路径更好找图标相关文件一般放在/client/images/目录欢迎语则在语言包或模板文件里全局搜“欢迎”两个字就出来了。4.3 常用数据表会话表、消息表、坐席表的结构与用途数据库里最常用的三张表会话表记录访客和坐席的一次对话、消息表记录每条聊天内容、坐席表记录坐席账号和分组。这三张表的结构大致如下表名关键字段用途sessionvisitor_id, agent_id, group_id, status, create_time, update_time记录每次会话的开始、分配、结束状态messagesession_id, from_type, content, type, create_time记录每条消息的发送方、内容和时间agentrealname, online, group_id, current_load, max_load管理坐席账号、在线状态和接待数要导出聊天记录直接join这两张表即可SELECT m.create_time, m.from_type, m.content FROM message m JOIN session s ON m.session_id s.id WHERE s.visitor_id 访客ID ORDER BY m.create_time ASC;平时排查问题时SQL也有用。比如“历史消息丢失”多半不是Bug而是聊天记录被自动清理了。找到系统里的清理任务或定时逻辑看它的保留天数设置默认可能是30天这比一条一条恢复数据要省事得多。另外数据量一旦上来message表务必加索引最常见的就是集中在session_id和create_time上ALTER TABLE message ADD INDEX idx_session_time (session_id, create_time);这个复合索引能同时加速“按会话查消息”和“按时间范围清理数据”两类操作加完以后查询耗时能降一个量级。如果你的表数据已经超过几十万行加索引的那几分钟恰好是上线后最值得花的时间。5. 避坑手册部署WeLive时最常见的五个翻车现场这章把线上最容易遇到的问题集中说一下每条按“现象→原因→解决”的方式写方便你直接对号入座。5.1 部署阶段安装向导进不去、前台转圈、后台无限跳转现象一访问安装向导显示404。原因是Nginx的server_name或root路径不对或者文件没传到指定目录。解决先ls确认文件确实在再比对Nginx的root路径最后才去怀疑伪静态规则。好多人一上来就改伪静态折腾半天发现文件压根没传到位置。现象二安装完访客端聊天窗打开后一直“连接中/转圈”。这个翻车现场太常见了主要原因有几个PHP-FPM进程数太少或请求超时导致轮询请求被丢也可能是fastcgi超时时间设置太短。解决先看浏览器的开发者工具Network面板轮询接口是不是返回5xx或超时如果是就把fastcgi_read_timeout提高并检查PHP-FPM的pm.max_childrenlocation ~ \.php$ { fastcgi_read_timeout 300; }fastcgi_read_timeout默认60秒对普通页面够用但客服系统的轮询请求一个接一个超时一断前端就要等到下个周期才能续上体感就是“转圈”。这个值设在300秒后基本不会再因为这个原因断轮询。现象三后台登录成功后又跳回登录页像是个死循环。这通常和session保存路径有关。如果自定义过session.save_path但那个目录没有被PHP进程写权限session就存不进去登录态也就保持不住。解决创建一个目录并且设置权限在php.ini里指明session.save_path /var/lib/php/sessions然后把目录属主改成PHP进程用户chown -R www-data:www-data /var/lib/php/sessions。一个很隐蔽的相似问题redis或memcache配置了session存储但服务没启动现象一模一样排查方向就是先看Session有没有写入。5.2 运行阶段消息延迟、会话丢失与坐席离线现象一两个坐席明明在线客户发消息却特别延迟要转好几秒。先看是不是轮询间隔设太大再看PHP-FPM是不是被别的项目吃满了。遇到过一次这种情况原因是同一台服务器上另一个项目出现了死循环PHP-FPM的进程全被占住了。解决把客服系统单独放一台机器或者在Nginx层给客服路径单独配置PHP进程保证客服系统的PHP-FPM worker不会被其他项目拖垮。现象二访客关掉浏览器再打开历史会话没了。原因很可能是cookie域名不对。访客系统部署在kefu.example.com但网站主域名是example.comJS里请求的接口跨域cookie在子域名下没有带过去。解决后台设置的“客服系统域名”填通配的.example.com或者把客服系统部署在主域名的二级路径下让cookie作用域一致。实际操作时还要注意https和http的区别如果主站是https客服系统的JS地址也必须是https否则浏览器会拦截混合内容访客端连浮动按钮都加载不出来。现象三坐席端后台明明在打开状态过一会儿显示离线。很多老系统的坐席在线状态是靠“心跳”维持的心跳间隔比后端清理过期状态的间隔长就会被误判离线。解决把前端心跳间隔调短同时把后端清理任务的过期时间适当放宽。一般心跳30秒一次清理任务把10分钟无心跳的坐席置为离线就比较合理。这个比值不要拉得太极端比如心跳5秒一次但清理任务5分钟才扫一遍坐席状态更新会有延迟导致访客被分到一个其实已经走开的坐席客户体验更糟。还有一条值得单独放在这不要把install目录留在线上。装完把install目录重命名或删除否则别人访问安装脚本可以重置数据库这个错误比版本选错、参数填错都要严重是看过的所有翻车现场里危险指数最高的一种。6. 收尾技巧把定时清理与自动备份做成一个不用操心的脚本上线一段时间后数据库里会积累大量历史消息和日志尤其是消息表膨胀得很快。放任不管MySQL查询变慢后台导出也卡管得太狠万一误删又没备份聊天记录想找回来就是玄学。我的习惯是装一个crontab每天凌晨做两件事先备份当天数据再清理超过保留期比如90天的历史消息。#!/bin/bash # welive_backup.sh每天的备份与清理任务 BACKUP_DIR/data/backup/welive DATE$(date \%Y\%m\%d) mkdir -p $BACKUP_DIR mysqldump -uwelive -p密码 welive message session \ --wherecreate_time DATE_SUB(NOW(), INTERVAL 30 DAY) \ $BACKUP_DIR/hot_$DATE.sql mysql -uwelive -p密码 welive -e DELETE FROM message WHERE create_time DATE_SUB(NOW(), INTERVAL 90 DAY); DELETE FROM session WHERE update_time DATE_SUB(NOW(), INTERVAL 90 DAY); mysqldump的--where参数只导出最近30天的热数据适合做日常快速恢复DELETE删除90天前的记录时两条删除顺序不能反先删message再删session否则session先被删的话message就成了孤儿数据。真正要长期留存的按季度做一次全量备份这样恢复成本可控。脚本里建议用--single-transaction避免备份时锁表导致客服系统短暂卡顿。把脚本放进cron每天凌晨执行0 3 * * * /bin/bash /data/scripts/welive_backup.sh /data/scripts/welive_backup.log 21选凌晨3点是因为这个时段访问量最低配合--single-transaction对线上基本无感。日志重定向一定要写否则脚本报错你完全不知道等发现时备份已经断了好几天。我习惯每次部署完亲手跑一遍脚本确认备份文件生成成功再挂到cron里。从那以后我每次部署完客服系统都强制自己走一遍完整检查清单PHP版本对不对、目录权限是不是够、轮询间隔能不能接受、install目录有没有删、定时任务有没有挂上、坐席心跳和清理时间是匹配的。这套清单跑下来客服系统基本不会在半夜突然闹脾气。希望帮到你。本文还有配套的精品资源点击获取

开源PHP客服系统WeLive实战：部署、轮询机制与二次开发

相关推荐

算法竞赛树结构进阶：从LCA到树链剖分与虚树实战

蓝桥杯Python组备赛全攻略：题型拆解、高频考点与避坑指南

STM32F105的USB BULK批量传输实战：从虚拟串口到高速可靠通信

更多资讯

Dinic最大流算法详解：分层图、多路增广与当前弧优化

ReactDOMRoot源码解析：从createRoot到render的完整链路

MySQL学生选课系统源码实战：表结构设计与事务并发控制

MySQL学生智能选课系统：数据库设计、事务锁与高并发避坑指南

CPU指令执行五阶段硬件原理与流水线设计

PCA-LSTM多变量时间序列预测：从高维特征压缩到时序建模实战

今日更新

声子晶体仿真：三角晶格与六角晶格的能带计算实战

度假村安保定岗定编：岗位梳理、编制测算与排班设计

COMSOL等离子体模块实战：氩气双层DBD仿真建模全解析

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？