简介WeLive5.9.0 是一套基于 PHP 与 WebSocket 的企业级在线客服系统源码面向需要自主部署、不受第三方限制的开发者与企业。程序小巧支持网页和移动端中英文双语自动切换内置人工智能机器人自动回复、多配色方案以及访客图片文件上传授权免年费且坐席无限制适合外贸站、独立站及电商平台接入使用。压缩包共 287 个文件约 1.6MB以 56 个 PHP 核心代码为主辅以 js、css、png、gif 等前端资源含完整的数据表 sql 文件与 mp3 提示音结构清晰便于二次开发。WeLive5.9.0 在原有功能基础上新增 18 种访客提示音、多/单窗口切换、离线访客关闭、截图发送等优化压缩包包含完整源码与数据库脚本下载后可直接部署调试也可作为学习 PHP 实时通信与客服系统架构的参考。目前已有 331 人学习使用。1. WeLive 免费开源 PHP 在线客服系统把访客咨询拉回自己服务器很多网站是在流量突然起来之后才发现连个咨询入口都没有。WeLive 是一款用 PHP 写的免费开源在线客服系统也被不少开发者按版本叫成 WeLive5一套 PHP MySQL 就能跑完整套服务前端用一段 JavaScript 挂载到任意页面坐席端是独立的网页工作台支持多坐席、分组、历史消息和基础统计。它解决的不只是「有人接待」关键是把访客数据、聊天记录、坐席工作量全部留在自己数据库里后续接 CRM 或做报表都不受第三方接口限制。适合从零起步的站长也适合外包项目里需要给客户交付一套可定制客服系统的开发者。我按部署、消息链路、定制和排障顺序拆尽量每个步骤都能直接照着做。2. 深入 WeLive 的消息链路PHP 后端、数据库与访客端的协作方式2.1 一条咨询消息从生成到落库的路径先把消息链路理清楚后面部署和调参才不会瞎试。访客在前台网页打开客服浮窗点击后触发一段 JavaScript 接口向服务端发起会话创建请求。服务端的 PHP 控制器先校验访客标识这个标识会存到 cookie 或 localStorage 里然后为这个会话分配坐席如果所有坐席都不在线会话进入留言队列。消息写入消息表时状态字段标记为未读坐席端通过轮询或长连接定时拉取未读消息。常见做法是每 3 秒轮询一次未读数。这个间隔不是拍脑袋定的太短会打爆 PHP-FPM 进程太长又让访客觉得消息不实时。WeLive 这类开源系统默认轮询间隔一般在 2 到 5 秒之间。我部署时先保持默认等白天高峰期看服务器负载再调别一上来就改成 1 秒那基本等于自杀式轮询。整条链路里最容易出问题的不是消息本身而是「会话上下文」。访客发一条消息服务端要先判断这个访客属于哪个会话、对应哪个坐席、会话当前状态是否还允许发消息。很多二次开发的人直接往消息表里 insert 数据结果坐席端看不到就是因为跳过了会话状态校验只写了消息没更新会话的最后活动时间。2.2 核心数据表与会话状态流转源码包里通常会带一个 sql 目录导入后生成一组数据表。以常见表结构为例大致有这几类坐席表账号、密码、昵称、分组 ID、在线状态、访客表访客 ID、来源页面、IP、首次访问时间、会话表会话编号、访客 ID、坐席 ID、开始时间、结束时间、状态、消息表会话编号、发送者类型、内容、发送时间、是否已读。会话表的 status 字段是关键。一个会话从访客发起开始先处于「排队」状态坐席点击接待后变成「进行中」主动结束或超时后置为「已结束」。很多站点运营者反馈「客服明明关了浏览器会话还一直挂着」本质就是会话结束时机没写对——坐席端关闭页面时只断开了连接没有调用结束会话的接口。排查这类问题时第一步就去会话表里看 status凡是长时间停留在「进行中」又没有新消息的基本都是异常会话。访客身份识别也要说一句。访客 ID 通常会种在 cookie 里但如果用户清理了 cookie 或者换设备系统就认不出老访客会生成一个新的访客 ID。这对客服系统来说其实可接受你需要关注的是来源页面字段它记录了访客第一次进来时是从哪个 URL 触发的会话这个字段对分析投放渠道非常有用。2.3 消息实时性方案轮询还是长连接WeLive 开源版本常见的消息获取方式是 Ajax 轮询。这种方案的好处是部署简单不需要额外安装 WebSocket 服务PHP-FPM 加 MySQL 就能撑起一个小型客服场景。缺点是实时性受轮询间隔限制访客数和坐席数大了之后数据库查询压力会成倍增长。我自己的判断标准是这样的同一时间在线访客峰值不超过一两百人轮询完全够用。我之前给一个日访客两三千的小型电商站部署轮询间隔保持 4 秒服务器负载一直很稳。但如果你的场景是直播带货、活动页引流这种短时高并发咨询就得考虑接入独立的 WebSocket 服务把新消息推送从「访客轮询」改成「服务端推送」。接入 WebSocket 通常要改两处源码一处是访客端 JS 里的消息接收逻辑把它从 setTimeout 轮询改成 WebSocket onmessage另一处是 PHP 端的消息发送接口发送成功后把消息推送到消息队列或直接广播给对应坐席会话。这个改动不算大但涉及前端 JS 和后端 PHP 同时调整测试时要特别注意多坐席同时在线的情况避免消息重复或丢失。提示改轮询方案前先打开浏览器开发者工具的 Network 面板看当前轮询接口的返回频率和耗时。如果接口平均响应时间超过 300ms不要光调间隔先查数据库慢查询或者索引缺失否则把轮询从 3 秒改到 5 秒只是把问题往后推。3. 部署 WeLive 客服系统环境配齐、跑通安装、前端嵌入三件事3.1 准备 PHP 环境与下载源码WeLive 后端基于 PHP部署环境我推荐 PHP 7.2 到 7.4 加 MySQL 5.7这套组合兼容性最好踩坑最少。PHP 8 的语法变化对老代码不友好除非源码包明确支持否则先别上。你还需要确认几个 PHP 扩展已经装好PDO、pdo_mysql、fileinfo、curl。这些是客服系统处理数据库连接和图片上传的基础依赖。先检查环境用一行命令把已加载的扩展列出来php -m | grep -E PDO|pdo_mysql|fileinfo|curl如果输出里缺少 pdo_mysql 或 fileinfo在 Debian/Ubuntu 上安装语言包并重启 PHP-FPMsudo apt install php7.4-mysql php7.4-curl php7.4-fileinfo sudo systemctl restart php7.4-fpm这一步做完后把源码包下载下来解压到网站根目录。我一般习惯把入口文件放在子目录部署比如/var/www/welive然后在 Nginx 站点配置里把 root 指到该目录下的 public 或 web 目录具体看源码包里入口文件的位置。3.2 导入数据库并改写连接配置先把数据库建好。用 MySQL 命令行登录创建库并导入初始化脚本。源码包的 sql 文件常见命名是welive.sql或install.sql你在根目录或者 docs 目录里找一下mysql -u root -p -e CREATE DATABASE welive DEFAULT CHARACTER SET utf8mb4; mysql -u root -p welive /var/www/welive/sql/welive.sql导入完成后改数据库连接配置。以常见源码包布局为例配置文件一般在application/database.php或者根目录的config目录里把主机、库名、账号、密码改成你自己的return [ type mysql, hostname 127.0.0.1, database welive, username welive_user, password YourStrongPassword, hostport 3306, charset utf8mb4, prefix wl_, ];注意charset要跟建库时的字符集一致。如果建库用了 utf8配置文件写 utf8mb4连接会报字符集错误或者中文乱码。另外prefix表前缀不能乱改改完后面所有查询都会找不到表除非你连表名一起改了。3.3 把营业台挂到网站页面上前端接入不复杂在页面/body标签之前引入一段 JS。这段 JS 的作用是加载客服浮窗、建立会话并发送消息。常见做法是给 script 标签传入一个服务端地址参数指向你的 WeLive 入口script srchttps://chat.yourdomain.com/welive/js/embed.js idwelive-script >// 伪代码按来源页面匹配欢迎语 $pageUrl parse_url($_SERVER[HTTP_REFERER], PHP_URL_PATH); if (strpos($pageUrl, /product/) ! false) { $welcomeMsg 您好想了解这款产品的具体参数吗; } else if (strpos($pageUrl, /price/) ! false) { $welcomeMsg 您好留下您的联系方式我给您发一份报价单。; } else { $welcomeMsg 您好请问有什么可以帮您; }这里要注意HTTP_REFERER是浏览器传来的访客可以伪造不要用它做权限判断只用来做展示层逻辑就够了。缓存也要处理很多客服系统会把欢迎语缓存到内存里改完数据库不生效先去后台清缓存再刷新页面。4.2 坐席分组与路由配置坐席分组的价值在于把不同业务线的咨询分流到对应客服。比如售前组管产品咨询售后组管退换货。坐席表里有个 group_id 字段访客端发起会话时通过>// 伪代码优先分配历史接待坐席 $historyKefu $this-visitorModel-getLastKefuId($visitorId); if ($historyKefu $this-kefuModel-isOnline($historyKefu)) { $assignKefuId $historyKefu; } else { $assignKefuId $this-kefuModel-getLeastBusyKefu($groupId); }这个改动适合老客户复购率高的业务但要注意隐私边界访客数据保留周期别无限拉长。4.3 轮询间隔与消息提醒调整轮询间隔一般在配置文件或 JS 变量里定义。有些版本把它写在访客端 JS 的const里有些把它放在 PHP 配置里动态输出到页面。推荐用后一种方式这样不用发布前端文件就能调参数。// 在控制器中输出轮询配置 $view-assign(pollInterval, 3000);同时还要关注坐席端的提示音和新消息提醒。坐席端浏览器的自动播放策略会拦截提示音用户必须跟页面产生一次交互之后才能发声。很多客服反馈「没有声音提示」其实不是代码问题是浏览器策略。解决方式是在坐席端页面加一个手动开启提示音的按钮用户点击后再初始化 Audio 对象。4.4 权限与敏感操作后台坐席账号建议分权限等级。普通坐席只允许接待和查看自己的历史会话管理员才能看到全部消息记录和导出数据。权限控制通常用 session 里的角色字段做判断在控制器构造函数里统一拦截// 伪代码控制器基类中的权限校验 public function __construct() { $role session(kefu_role); if ($role ! admin) { return json([code 403, msg 无权限访问]); } }注意别只在前端隐藏入口后端接口必须校验角色否则有人直接拼 URL 就能绕过界面拿到全部数据。这个是我见过最多人踩的坑前端按钮藏了后端接口没拦等于白藏。5. 常见问题排查掉线、消息延迟、乱码与静态资源 4045.1 访客刷新页面就掉线现象访客在页面间跳转聊天窗口每次都要重新发起会话坐席端看到访客不断下线再上线。原因访客标识没有正确持久化。常见有两种情况一是 cookie 作用域设置太窄只对当前页面生效跳转后丢失二是本地存储方案失效访客端 JS 在初始化时没从 localStorage 读到旧访客 ID服务端认为这是新访客。解决打开浏览器开发者工具在 Application 面板里看 cookie 和 localStorage。如果 cookie 的 path 设置为/detail这类具体路径改成/让它整站生效。如果是 localStorage 没存上检查访客端 JS 里是否有localStorage.setItem调用并确认页面加载顺序没有把这段 JS 放在会报错的位置。5.2 消息发出去要等好几秒才到现象坐席端发一条回复访客端要等 3 到 5 秒才收到且坐席端和访客端都卡。原因轮询接口响应慢。先看数据库慢查询日志常见语句是对消息表做全表扫描。如果消息表没有按会话 ID 和已读状态建索引数据量到几万条时查询就会明显变慢。解决给消息表加组合索引会话 ID 加已读状态一起索引查询速度通常能提升几十倍ALTER TABLE wl_message ADD INDEX idx_session_read (session_id, is_read);另外排查 PHP-FPM 进程数配置pm.max_children设太小会导致并发请求排队接口响应时间被无限拉长这种情况调索引没用先扩容进程。5.3 中文乱码现象数据库里中文正常显示但网页上显示为问号或乱码。原因字符集不一致。最常见的组合是数据库表用了 utf8mb4但 PHP 连接配置里写的是 utf8导致写入时数据被转码损坏。另一种情况是 HTML 页面没有声明 UTF-8。解决先改 PHP 配置文件把 charset 统一成 utf8mb4然后清空对应表重新导入。已损坏的数据需要从备份恢复无法直接修复因为字符在写入时已经丢失了原始字节。页面端检查meta charsetutf-8是否在 JS 引入之前渲染。5.4 页面能开但 JS 报 404现象首页和后台都能打开但客服浮窗加载不出来Network 面板里 embed.js 请求返回 404。原因伪静态规则缺失或者入口目录设置错误。WeLive 这类 PHP 项目通常需要把请求重写到入口文件Nginx 下如果没配try_files规则JS 文件会被当路由拦截。解决Nginx 的站点配置里加上伪静态规则location / { try_files $uri $uri/ /index.php?s$uri$args; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php7.4-fpm.sock; }配置完执行nginx -t校验然后systemctl reload nginx。改了还不行就到源码目录下确认 embed.js 的实际文件路径有时候是引用路径写成了相对路径层级不对导致 404。提示以上四条是按出现频率排序的。我统计过自己经手的部署掉线和乱码占了一半以上剩下的是轮询慢和路径问题。排查时从 Network 面板和数据库两个入口入手大部分问题在五分钟内能定位到原因。6. 进阶让 WeLive 在长期运行中不翻车备份、HTTPS 与日志检查WeLive 部署并跑通之后真正考验人的是持续运行阶段的稳定性。我最开始给客户部署完就以为结束了结果一个月后客户反馈「消息记录丢了」排查发现是 MySQL 没有定时备份一次误操作把表删了又没留快照。从那以后我每次部署 WeLive都会顺手做完下面三件事。第一配置 MySQL 定时备份。写一个简单脚本每天凌晨把welive库导出到指定目录保留最近 7 天#!/bin/bash DATE$(date %F) mysqldump -u root -p$DB_PASS welive | gzip /backup/welive-$DATE.sql.gz find /backup -name welive-*.sql.gz -mtime 7 -delete添加 crontab 任务并实际跑一次确认备份文件真实存在。现在 MySQL 8 对 mysqldump 权限有要求备份账号需要SELECT, LOCK TABLES权限。第二把 HTTPS 配置干净。WeLive 的访客端 JS 和坐席端工作台都必须走 HTTPS否则浏览器会拦截混合内容。我给客户配置了免费证书然后在 Nginx 里加跳转规则server { listen 80; server_name chat.example.com; return 301 https://$host$request_uri; }证书续期也要自动化用 certbot 的 hook 在续期后重新加载 Nginx。第三记录轮询接口的响应耗时。这一步很多人忽略却是早期发现性能问题的关键。我在坐席端轮询接口的控制器入口加了一行日志输出把每次请求的耗时写入日志文件配合 crontab 检查接口 500 状态。awk {print $1, $2, $NF} /var/log/nginx/api.log | sort | uniq -c | sort -nr | head -20这套组合拳做完WeLive 才算真正具备长期运行的前提条件。从那以后我每次部署完都会强制走一遍备份脚本、HTTPS 跳转和接口日志三件套虽然每次多花十分钟但至少不会再半夜被客户的「数据丢了」电话吵醒。希望帮到你。本文还有配套的精品资源点击获取