WeLive免费开源PHP在线客服系统部署实战：从环境配置到消息链路调优

简介：WeLive 5.9.0是一款企业级开源在线客服系统，采用PHP开发并基于WebSocket全双工通讯技术，适用于需要独立部署客服能力的网站运营者、中小企业及PHP开发者。程序小巧易用，支持Web与移动端访问，内置AI机器人自动回复、图片文件传输、多配色与中英文切换等功能，访客可直接在微信、QQ浏览器中进入对话，也可嵌入其他App，能有效降低客服运维成本。压缩包共287个文件，以PHP业务逻辑、JS前端交互与CSS样式文件为主体，辅以PNG界面图片和MP3访客提示音等素材，整体仅1.6MB，目录覆盖后台管理、访客会话及机器人模块，结构清晰易检索。资源已获332人学习下载，内部附完整源码、SQL数据库及环境配置，可迅速部署到自有服务器；该版本新增18种访客提示音、单双窗口切换及上传权限控制等优化，适合快速搭建、学习企业级客服产品设计或进行二次开发。

1. WeLive免费开源PHP在线客服系统：为什么值得自建一套

做了几年站点运维，我一直对在线客服系统有个执念：客户聊天数据必须在自己服务器里。用过几款SaaS客服，功能确实全，但按坐席数收费、聊天记录出不来、访客画像跟着别人走，这些问题一到续费节点就让人难受。WeLive这套免费开源的PHP在线客服系统，恰好解决了这个矛盾——它把访客端、坐席工作台、会话路由和消息存储全放在你自家环境里，数据想怎么导就怎么导，二次开发和私有化改造也没有商业授权限制。对个人站长、外包团队和有内部客服需求的中小公司来说，这是一个值得投入的方向：你能拿到一套可自控、可改、可审计的完整客服闭环。这篇笔记我会按部署环境、初始化配置、常见坑、链路验证一路写下来，新手能跟着跑通，熟手可以对照参数做调整。

2. 部署前必须搞懂的运行环境与安装流程：PHP版本、扩展与目录权限

2.1 环境选型：PHP 7.x/8.x与扩展清单怎么定

WeLive这类PHP客服系统的典型技术栈很直接：PHP处理业务逻辑，MySQL存会话和消息，Redis承担在线状态和消息队列，再加一个WebSocket服务做实时推送。别被“WebSocket”这个词吓到，很多版本在实际运行时会自动降级为轮询，但如果你想达到“访客刚发送消息，坐席端几乎同时弹出提醒”的效果，还是要把常驻进程跑起来。

环境版本上，我见过不少翻车现场是因为PHP版本太老或太新。常见可靠的选择是PHP 7.4或8.0/8.1，MySQL 5.7或8.0，Redis 5.0以上。你可以在部署前先检查一下扩展：

php -v php -m | grep -E "mysqli|pdo_mysql|redis|swoole|mbstring|curl|fileinfo|openssl|zip"

逻辑上，这条命令干了两件事：第一行确认PHP版本满足系统要求；第二行列出与通信、数据库、文件处理相关的扩展。mysqli或pdo_mysql是连MySQL的通道，缺了直接报“数据库连接失败”；redis扩展负责连Redis，如果没有，系统可能退回到文件缓存，在线状态刷新会明显变慢；swoole扩展是可选的，但它能显著提升WebSocket长连接的并发能力——如果你的在线访客量没有大到同时几千人，不用swoole也能跑，只是消息推送会走更笨重的轮询方式。

参数上唯一要注意的是PHP内存限制和上传大小。一般建议：

memory_limit = 256M upload_max_filesize = 20M post_max_size = 24M max_execution_time = 300

这几个值的逻辑是：客服工作台要加载访客列表、历史消息和统计面板，256M能避免大数据量页面卡死；附件上传大小限制在20M左右，既满足图片和工单附件的常见需求，又不至于让服务器磁盘被撑爆；max_execution_time给到300秒，是为了防止导入老数据或批量清理会话时脚本被中途掐断。

2.2 解压上传与目录授权：三个容易出错的路径

拿到安装包之后，最常见的做法是解压后把整个目录传到Web根目录。目录名可以随意，但注意不要带中文和空格，否则部分Linux环境的URL重写规则会出怪问题。传到服务器后，第一件事不是急着打开安装向导，而是处理目录权限。

unzip welive.zip -d /www/wwwroot/welive cd /www/wwwroot/welive chown -R www:www . chmod -R 755 . chmod -R 775 upload uploads storage runtime

这里的关键逻辑是：PHP-FPM进程默认以www用户运行，如果目录owner是root，PHP就没有写权限。upload和storage是访客头像、聊天附件、临时文件的落盘目录；runtime是日志和缓存目录。这三个目录如果不可写，表现很诡异——安装向导能过，但一传头像就报错，或者聊天记录刷不出来。很多第一次部署的人会在这上面耗掉半天，其实只是忘了给写权限。

另外，Linux下不要用root直接运行chmod -R 777图省事。777意味着任何系统用户都能写这些目录，一旦某个目录被上传了恶意脚本，影响面会非常大。775是更稳妥的折中：owner和group可读写执行，其他用户只读。

2.3 配置Nginx伪静态与访问入口：前后端分离的URL约定

如果服务端是Apache，一般在.htaccess里已经写好了重写规则，不需要额外配置。但国内很多服务器用Nginx，安装包里不会自动生成Nginx的伪静态配置，必须手动补一段。

server { listen 80; server_name your-domain.com; root /www/wwwroot/welive/public; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ { expires 7d; access_log off; } # 禁止访问隐藏文件和备份文件 location ~ /\.(?!well-known) { deny all; } location ~* \.(sql|bak|sh|log)$ { deny all; } }

这段配置的核心逻辑是：站点根目录指向public，而不是整个项目根目录。这样做的好处是PHP脚本不会直接暴露在Web根下，用户通过URL只能访问public里的入口文件，安装包里的配置文件、数据库备份文件天然被隔在Web可访问范围之外。try_files那行是把所有不存在的URL交给index.php处理，这样客服工作台里的各种路由地址才能正常解析。

参数上值得调整的是fastcgi_pass的地址和版本。PHP-FPM如果用的是Unix Socket方式，这里要改成unix:/tmp/php-cgi-72.sock之类的具体路径；PHP 8.0以上版本对应9000端口的写法也能用，但性能不如Socket方式。静态资源缓存7天能明显减少工作台重复请求图片和JS文件的延迟，聊天气泡里的头像加载会快很多。

3. 初始化配置与关键参数：从安装向导到消息推送

3.1 安装向导的字段含义与数据库初始化

访问http://your-domain.com/，一般会自动跳到安装向导。这里填的不是系统账号，而是数据库连接参数和数据表前缀。先创建数据库再填表：

CREATE DATABASE welive DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'welive_user'@'localhost' IDENTIFIED BY '你的强密码'; GRANT ALL PRIVILEGES ON welive.* TO 'welive_user'@'localhost'; FLUSH PRIVILEGES;

为什么一定要在建库时指定utf8mb4？因为客服聊天内容不可避免会有表情符号，这些符号在utf8字符集下存不进去，会变成问号，而utf8mb4完整支持4字节的emoji字符。排序规则选unicode_ci是为了让中英文排序更接近自然阅读顺序，不影响功能，但建议养成习惯。

数据库账号不要用root。客服系统会记录所有访客对话，一旦Web层面出现SQL注入漏洞，攻击者能操作的数据范围仅限于welive这一个库，不会牵连同服务器上的其他业务库。这是“最小权限”原则最简单的实践。

安装向导里还有一项“数据表前缀”，默认是welive_。对单站点部署来说，前缀改成别的值实际意义不大；但如果同一台服务器的同一个MySQL实例里跑了多套系统，前缀就是隔离命名空间的唯一手段。我一般习惯改成wl_这种短前缀，写SQL排查时能少打几个字。

3.2 消息实时性配置：轮询还是WebSocket

安装完成后，进管理后台第一件事是打开“消息发送方式”之类的配置项。WeLive这类系统基本都提供两种模式：HTTP轮询和WebSocket长连接。轮询实现简单，但有个明显问题：每个访客最短间隔3秒请求一次服务器，如果同时在线200个访客，每秒就有六七十个HTTP请求打在PHP和MySQL上；WebSocket则是一次握手之后保持长连接，服务端有消息才推给客户端，负载低得多。

// 伪代码示例，仅说明轮询与长连接的选择逻辑 $config['message_engine'] = 'websocket'; // 可选值: polling / websocket $config['ws_host'] = '127.0.0.1'; $config['ws_port'] = 9501; $config['ws_heartbeat'] = 30; // 心跳间隔，单位秒 $config['ws_max_conn'] = 1000; // 单进程最大连接数

这里的逻辑很直白：选websocket模式后，系统会启动一个常驻进程监听9501端口，PHP收到新消息后往Redis的频道里发一条通知，这个常驻进程订阅到通知就主动推给对应连接。心跳30秒的意思是客户端30秒没数据往来就发一个空包确认连接还活着；这个值如果小于15秒，移动端弱网环境会频繁重连，如果大于60秒，Nginx的proxy_read_timeout默认60秒可能会先把空闲连接断开，导致消息突然收不到。max_conn根据服务器内存调整，一般每个连接消耗20KB左右内存，1000连接约20MB，对小型服务器完全没压力。

我一般会建议先把配置切到websocket模式，然后用两个浏览器窗口分别开访客端和坐席端实测。如果30秒内消息能完整互达，再考虑调优并发。很多部署失败的案例恰恰是卡在这一步：页面能打开，但消息就是延迟很久才出现，那是因为轮询间隔太长或WebSocket服务根本没跑起来。

3.3 会话路由与坐席分配的常见规则

客服系统的核心体验不只是“能聊”，而是“找对人”。WeLive通常支持按部门分组、按客服负载轮询、按固定客服分配三类规则。后台配置项一般长这样：

$config = [ 'assign_rule' => 'round_robin', // round_robin: 轮流 / least_load: 最少接待 / fixed: 固定客服 'max_waiting_chats' => 10, // 单个客服最多同时接待会话数 'auto_accept' => true, // 新会话是否自动接入 'offline_message_enabled' => true, // 非工作时间是否收取留言 'business_hours' => [ 'start' => '09:00', 'end' => '18:00', ], ];

round_robin适合客服水平接近的团队，每个人都能均匀分到会话，不会出现有人闲着有人爆满。least_load适合客服能力有差异的场景，判断依据是“当前正在接待的会话数”而不是历史总量，能力强的客服因为处理快、被占用的会话少，自然会分到更多新会话。fixed规则适合企业专属客服场景——大客户A只认资深客服张三，那就把对应来源的会话固定到张三名下。

max_waiting_chats是个容易被忽视的参数。如果设得太小，比如2，客服正在处理两个会话时新访客就会被排进等待队列，等待超过一定时间访客可能直接关闭窗口；设得太大，比如30，客服根本忙不过来，访客等半天没人回复，体验反而更差。10左右是一个相对平衡的起步值。

auto_accept这个开关我建议测试阶段先关掉。开着的话，新会话自动接入客服，坐席端会连续弹窗，测试时容易打断配置思路。正式上线前再打开也不迟。

4. WeLive部署常见问题与排查：从消息发不出到访客列表消失

4.1 消息发不出去但页面能打开

现象：访客端和坐席端都能正常打开，页面样式、头像、历史记录都显示正常，但只要一发送消息就转圈，几秒后提示发送失败。查看网络请求发现POST接口返回500或超时。

原因排查顺序要按“配置-服务-权限”来，不要一上来就怀疑代码。首先确认消息发送走的是轮询还是WebSocket渠道：如果是WebSocket，先看常驻进程有没有起来，进程挂了页面本身不会报警；其次看Redis是否还在运行，PHP与Redis断连时，很多系统会自动降级为写数据库，但WebSocket服务拿不到推送事件，就会表现为“发送成功但没有实时通知”。

解决：先重启相关服务，再逐层验证。

# 检查监听端口 netstat -tunlp | grep -E "9501|6379|9000" # 检查PHP进程状态 ps aux | grep -E "php|swoole|websocket" # 检查Redis连通性 redis-cli ping

这三个命令分别对应三种不同原因：9501端口没监听说明WebSocket服务没起来；PHP进程异常说明可能是opcache缓存了旧代码或内存溢出导致进程退出；redis-cli ping返回PONG才是正常，如果报错说明Redis服务或密码配置有问题。我遇到过最典型的翻车是服务器重启后，WebSocket常驻进程没有配置开机自启动，人在公司电脑上改了代码推到服务器，等客户反映“发送消息没反应”才发现服务根本没起来。

4.2 访客列表为空或会话自动关闭

现象：首页能看到统计数字，但访客列表一直转圈或显示“暂无访客”；客服明明还在和某访客聊天，过几分钟会话就被标记为已结束。

原因拆成两部分看。访客列表为空，最常见的是前端JS没有正确加载埋点，访客端页面里那行初始化脚本被广告插件或浏览器拦截了；也可能是访客信息写入了Redis但没同步到MySQL，刷新后Redis里过期了，数据就消失了。会话自动关闭，基本栽在心跳超时上——服务端默认判断访客离线的时间太短，比如60秒没收到访客端心跳就关闭会话，移动端切后台或者网络波动稍微久一点，会话就断了。

解决思路是延长离线判断窗口，并确认访客端心跳JS确实在执行。

// 会话超时配置，单位：秒 $config['visitor_timeout'] = 300; // 访客无操作多久后判定离线 $config['session_ttl'] = 1800; // 会话数据在Redis里的有效期

visitor_timeout设成300秒的考虑是：用户切出去看个资料、接个电话，回来还能继续聊，不会被强制结束。设成60秒会非常激进，移动端几乎必被误杀。session_ttl是Redis里会话数据的有效时间，至少要比visitor_timeout大几倍，否则会出现“访客还在聊天，但会话上下文被Redis清掉”的诡异现象。改完参数后记得清一下缓存，否则旧配置还驻留在内存里。

4.3 坐席端上传头像失败与附件丢失

现象：客服设置自己的头像时，上传进度条走到一半就报“文件上传失败”；访客发了张截图，坐席端能看到缩略图，但点击下载时提示文件不存在。

原因基本都是目录权限和路径配置不匹配。上传文件先落在临时目录，再移动到upload目录；如果upload目录可写但路径配置里写的是绝对路径，比如/var/www/welive/public/upload，而实际目录结构是/www/wwwroot/welive/public/upload，PHP的move_uploaded_file函数就会静默失败，前端表现就是上传失败或附件丢失。另一种情况是Nginx的client_max_body_size没调大，默认1M，传大图直接被Nginx拦截。

解决：检查物理路径与配置路径是否一致，并清点三个上传相关目录。

ls -l /www/wwwroot/welive/public/upload ls -l /www/wwwroot/welive/runtime/temp php -r "echo ini_get('upload_tmp_dir');"

最后一行输出了PHP临时文件目录，如果这个目录不存在或不可写，PHP会退回系统临时目录，而系统临时目录在部分服务器上挂载在内存盘，重启后清空，就会造成“上传时成功、重启后消失”。我建议直接把upload_tmp_dir显式指定到项目runtime/temp下，这样临时文件与正式附件落在同一块磁盘，排查路径问题只需盯着项目目录。

4.4 定时任务没有正确执行导致的统计异常

现象：今日会话数、消息总数等统计数字一直不动，或者每天凌晨的数据汇总丢了；某些自动回复、离线留言提醒也不触发。

原因几乎可以断定是计划任务缺失或命令路径不对。很多PHP系统的定时任务不是靠服务器cron，而是依赖Web访问触发，但WeLive这类系统出于性能考虑，会要求在crontab里注册一个PHP脚本入口。如果部署时漏了这一步，统计功能就变成“只有在有人访问后台时顺便更新一下”，自然时灵时不灵。

解决：确认crontab已正确写入，并验证脚本能独立运行。

crontab -e # 每5分钟执行一次任务调度，具体路径以安装包文档为准 */5 * * * * php /www/wwwroot/welive/think cron:run >> /www/wwwroot/welive/runtime/cron.log 2>&1

这个命令把计划任务输出单独写到runtime/cron.log，这是刻意的。我在生产环境里遇到过多次“cron在跑但没结果”的情况，检查/var/mail/root里的系统邮件太绕，直接看这个日志文件更直观。如果log里出现错误，比如Class not found或Call to undefined function，说明PHP环境缺扩展，回到第2章的扩展检查清单里逐个核对。

5. 从能用跑到稳定：验证消息链路与超时参数调优

5.1 用日志定位消息链路的三个关键点

部署完成不是终点，真正要看的是消息从访客浏览器发出、经过服务端中转、再到达坐席浏览器的完整链路。常见做法是在三个位置打点：访客端发送事件、服务端接收写入、WebSocket推送事件。

# 实时跟踪WebSocket服务的收发日志 tail -f runtime/log/websocket.log | grep -E "send|recv|error" # 查看PHP业务日志，确认消息是否成功写入数据库和Redis tail -f runtime/log/sql.log | grep "INSERT INTO chat_message"

第一条命令能立刻看出长连接是否建立、客户端与服务器之间有没有心跳报警。如果日志里只有recv没有send，说明消息收到了但没推出去，问题在推送环节；如果连recv都没有，说明连接本身没建立成功，回到防火墙和端口监听排查。第二条命令验证消息有没有真正入库。有时WebSocket推送正常，界面也显示已发送，但刷新后历史记录丢失，那就是这条INSERT没执行成功——可能是字段超长、也可能是数据库表损坏。

这三个关键点按顺序排查，基本能定位90%的消息异常。不要上来就改代码，日志是最诚实的黑匣子，先看它怎么说。

5.2 会话超时与心跳参数的推荐值

最后把几个超时参数一起调好，能避免很多“聊着聊着断线”的投诉。我用过几轮不同参数，总结下来这套组合在中小并发下比较稳：

这几个参数是联动关系。Nginx的proxy_read_timeout是很多人容易漏掉的一环：默认60秒，如果WebSocket经过Nginx反代，光调系统里的心跳配置没用，Nginx会把空闲的连接掐掉，客户端还没等到报错就发现连接静默关闭，表现是消息延迟甚至丢失。改成3600秒并重启Nginx后，这个问题直接消失。

我在正式环境里最终验证的步骤是：用一个手机浏览器开访客端，电脑浏览器开坐席端，中间把手机切到飞行模式30秒再切回来，看能不能断线重连且不丢消息。这个模拟弱网的操作能暴露绝大多数超时配置问题。如果切回飞行模式后消息补发不完整，就把session_ttl再调大一些，同时检查Redis内存是否够用。

回看这些年折腾客服系统的经历，最后留下来的经验只有一条：在线客服这种强交互系统，八成问题出在长连接保活和会话数据生命周期上，不是功能逻辑。用日志验证链路、按业务场景调超时参数、把定时任务和目录权限一次性弄干净，这套组合比任何花哨功能都更能决定项目成败。希望帮到你。

本文还有配套的精品资源，点击获取