PHPlivechat部署实战：无限坐席客服系统与移动端接入

简介：这套PHPlivechat在线客服系统为2021年12月修复版，实现无限坐席与电脑端、手机APP双端接入，面向需要自建在线客服的中小企业站长、PHP开发者和运维人员，可用于企业官网、电商平台及各类需要实时咨询的业务场景。压缩包共451个文件，以php后端逻辑、js前端交互、html页面模板、css样式文件为主，配合sql数据库备份、apk客服端安装包、png界面图、mp3提示音与mp4操作教程等，整体约133.83MB，目录结构清晰易查找。安装采用免配置机制，无需手动修改数据库信息，也无需预先导入数据库，上传源码后访问域名进入安装向导，填写数据库与后台账号即可完成部署；系统内置WEB管理后台，坐席可通过后台或安卓APP接客，APP扫描后台二维码即可绑定登录。资源附有详细搭建教程和APP使用教程，方便快速上手。目前已有1102人学习下载，适合需要快速部署商用级在线客服系统的读者。

1. 无限坐席 PHPlivechat 的手机端布局：网页客服之外还打包了什么

采购在线客服系统时最容易被忽略的限制是坐席数。很多源码部署版表面上不限用户，实际是在管理员表里写死了数量。这套 2021 年 12 月修复版的 PHPlivechat 把坐席判定改成动态读取用户表，后台新增管理员即新坐席，因此形成了无限坐席的部署形态。更值得注意的是它没有只做网页端：除桌面版客服后台外，附带一个安卓 APP 客服端，通过扫码绑定 WEB 后台生成的 QR 码完成服务器连接，不需要额外部署消息推送服务。安装方式也相当省事——不手工导入数据库、不改源码配置，访问域名后由安装器自动建表并写入 config.php。需要自有客服平台、对外交付客服系统的团队，以及想拿 PHP 源码做二次开发的人，都可以直接落地这套方案。

2. 宝塔 + Apache2.4 + PHP 5.6：PHPlivechat 的环境选型与免导库安装器逻辑

2.1 为什么指定 Apache 而不是 Nginx

常见部署组合是 Nginx + PHP-FPM，但 PHPlivechat 这套修复版给出的官方环境偏偏是 Apache 2.4.41 + PHP 5.6。这不是保守，而是这套源码的很多请求路径依赖 Apache 的 .htaccess 和 mod_rewrite 做路由。例如页面里不少链接是/chat、/history这类无扩展名路径，靠的是 .htaccess 里的 RewriteRule 映射到 index.php。Nginx 也能配等价 rewrite，但修复版没有附带 Nginx 规则文件，宝塔默认的 Nginx 伪静态模板是给 ThinkPHP、WordPress 用的，直接套上去大概率 404。Apache 站点配置里只要 httpd.conf 确认 AllowOverride All，PHP-FPM 处理动态请求时 .htaccess 能被正常读取，部署差异就只剩下代码本身。

# 检查 Apache 是否加载了 rewrite 模块 httpd -t -D DUMP_MODULES | grep rewrite # 查看当前 PHP 版本 php -v

httpd -t不只是语法检查，配合-D DUMP_MODULES会列出已编译的全部模块。如果 grep 没有输出 rewrite_module，需要在宝塔 Apache 配置里确认 LoadModule rewrite_module 没有被注释。php -v用来确认 CLI 版本和面板站点实际挂载的 PHP 版本一致——两者不一致时，安装到一半才暴露问题，报错信息往往还不直观。

2.2 安装器免导库的内部逻辑

这套源码部署时不需要手动创建数据库和导入 SQL，原因是安装器做了「连接 + 建库 + 建表 + 写配置」四步。与传统需要 phpMyAdmin 导入 .sql 的源码相比，它把数据库初始化完全收进了 PHP 进程里。安装器的典型流程是：访问根域名 → 检测 config.php 是否存在 → 不存在则进入安装页 → 提交表单 → 用 mysqli 连接 MySQL → 执行 schema.sql 建表 → 生成配置 → 跳转登录页。

<?php // 安装器核心流程示意（按常见 livechat 安装器逻辑还原） if (isset($_POST['install'])) { // 收集表单中的数据库信息与管理账号 $db_host = trim($_POST['db_host']); // 通常为 localhost $db_user = trim($_POST['db_user']); // 宝塔建库时创建的用户 $db_pass = $_POST['db_pass']; // 避免含 @ # 等特殊字符 $db_name = trim($_POST['db_name']); // 先不指定库名连接，否则库不存在时直接失败 $conn = mysqli_connect($db_host, $db_user, $db_pass); if (!$conn) { exit('数据库连接失败，请确认账号密码'); } // 建库后切换当前库，再执行 schema.sql 里的 CREATE TABLE mysqli_query($conn, 'CREATE DATABASE IF NOT EXISTS `' . $db_name . '` DEFAULT CHARSET utf8'); mysqli_select_db($conn, $db_name); $schema = file_get_contents(__DIR__ . '/install/schema.sql'); mysqli_multi_query($conn, $schema); // 生成配置文件：PHP 5.6 时代没有 dotenv，配置直接写成变量 $config = "<?php\n" . "\$db_host = '{$db_host}';\n" . "\$db_user = '{$db_user}';\n" . "\$db_pass = '{$db_pass}';\n" . "\$db_name = '{$db_name}';\n"; file_put_contents(__DIR__ . '/config.php', $config); header('Location: index.php'); }

这段逻辑有几个关键点。第一，mysqli_connect不指定库名连接，是为了在数据库还不存在时也能拿到连接句柄；如果用户填入的数据库账号没有 CREATE DATABASE 权限，安装器会在建库那一步报错，解决方式是去宝塔数据库管理里手动执行建库语句，再回来填写已经建好的库名。第二，schema.sql 里的多条 CREATE TABLE 通过mysqli_multi_query顺序执行，任一条失败都会导致安装中断，常见原因是 PHP 5.6 的 mysqli 连不上 MySQL 8 的默认密码插件。第三，install 目录在安装成功后必须手动改名或删除，否则别人重新访问域名就能覆盖你的管理员密码。

2.3 PHP 版本与扩展检查

官方说 PHP 5.6 以上，实际在 5.6 和 7.0/7.2 上都验证过，但到 PHP 7.4 开始会陆续出现两类问题：一类是隐式可见性变化产生的 deprecation 警告，另一类是 mysql_* 系列函数的兼容层触发 fatal error。到 PHP 8 则基本跑不起来，需要先做代码审计而不是直接换版本。对这个部署场景来说，最稳妥的做法是把站点 PHP 版本固定在 5.6，宝塔软件商店里可以直接安装和切换。

php -m | grep -E 'mysqli|fileinfo|Zend OPcache'

如果 grep 输出里缺了 mysqli，说明当前 PHP 版本没有装 mysqli 扩展。宝塔里直接在软件商店的 PHP 设置页勾选并重载 PHP-FPM 即可，不需要编译源码。

3. 从源码上传到后台激活：PHPlivechat 站点配置与安装字段逐段拆解

3.1 上传目录与文件权限

在宝塔创建站点时，要把 PHP 版本下拉到 5.6，数据库生成方式选「连同站点一起创建」。这里有个常见误区：站点根目录不要选子目录，直接把解压后的源码放在站点根目录。PHPlivechat 的 CSS 和 JS 用的是相对路径，如果源码被放到/www/wwwroot/域名/sub/这样的二级目录，页面能打开但样式全丢，后台也进不去。域名方面，widget 移动端链接对域名依赖较重，建议使用可公网解析的域名而非 IP 加端口。

源码上传并解压后，需要处理权限。Apache 的 PHP-FPM 以 www 用户运行，config.php 和 runtime 缓存目录必须让 www 用户可写，但整个站点不能全放开到 777。

cd /www/wwwroot/你的站点目录 find . -type f -exec chmod 644 {} \; find . -type d -exec chmod 755 {} \; chown -R www:www .

先find统一设置文件 644、目录 755，再把属主改成 www。不能图省事全部 777：这类老系统的上传点不少，如果目录可写又暴露在公网，等于给已经存在的文件上传漏洞白送一个执行入口。后续安装时如果提示无法写入 config.php，优先查ls -la看属主和权限，而不是直接把目录改成 777。

3.2 安装页面字段与后台账号对应关系

访问域名后触发安装页，安装表单的字段和后台配置文件之间的对应关系如下：

数据库密码建议先用简单密码把流程跑通，上线后再去 MySQL 里改。原因仍然是 PHP 5.6 时代的部分实现用字符串拼接连接信息，密码里出现#或@可能会被误解析成 host 分隔符或参数片段。安装完成后再把密码改复杂，同时更新 config.php 里的$db_pass，影响最小。

3.3 安装失败的表现与日志定位

安装失败最典型的现象有两种。第一种是提交后直接跳回安装页，这几乎都是 config.php 没有写成功造成的，原因是目录权限或磁盘空间；第二种是提交后白屏或 500，说明 SQL 执行到一半出错，重点看 MySQL 版本和建表语句的兼容性。排查时先确认配置文件的实际情况：

ls -la /www/wwwroot/你的站点目录/config.php tail -100 /www/wwwroot/你的站点目录/error.log

ls -la要确认 config.php 已经生成且大小不为 0。如果文件存在但安装页仍然反复跳转，检查站点是不是开启了 opcache，PHP 会把旧配置缓存住。error.log 的路径取决于宝塔站点配置，Apache 的错误日志默认在/www/wwwlogs/下，站点级错误会写在对应域名目录里，和 PHP-FPM 的日志路径不一定一致，两个都看一遍再下结论。

提示：安装器只在 config.php 不存在时运行，因此不要手动创建空配置文件占位，那样会让安装页永远不再出现，而又达不到可运行状态。

安装成功后，立刻把 install 目录改名或删除。这一步我一般会在上线清单里写死：删掉 install 目录后，重新访问域名应该直接跳到登录页，如果还能看到安装表单，说明删除不彻底或者站点配置指向了错误的根目录。

4. widget-mobile 聊天页与手机 APP 扫码绑定：移动端接入实现

4.1 widget-mobile 本质是 H5 聊天入口

客服专属聊天链接是你的域名/php/app.php?widget-mobile。这行 URL 表面上像是为 APP 准备的接口，实际是一个自适应 HTML 聊天页面。app.php 通过检查$_GET['widget-mobile']是否存在来决定加载移动端模板还是桌面端模板，模板内引用 widget-mobile.css 和配套 JS，渲染出的聊天窗口可以嵌入微信公众号菜单、企业微信应用，也可以直接发给用户用浏览器打开。它不是原生应用，不需要在服务器上单独开端口，也不需要配置 websocket 长连接，消息靠轮询或短轮询刷新。

<?php // php/app.php 的路由判断逻辑，按常见实现还原 $isMobileWidget = isset($_GET['widget-mobile']); if ($isMobileWidget) { // 加载移动端聊天模板：widget-mobile.css 负责移动端自适应 include __DIR__ . '/views/mobile_widget.php'; } else { // 桌面端客服工作台模板 include __DIR__ . '/views/desktop_app.php'; }

这个判断意味着移动端和桌面端共用同一套会话处理逻辑，只是模板不同。实际部署时注意：如果你的域名启用了 HTTPS，widget-mobile 页面里的 AJAX 请求也必须是 HTTPS，否则浏览器直接拦截混合内容，客服收不到访客消息。检查方式很简单，手机浏览器打开这个链接，F12 看 console 有没有 Mixed Content 报错。

4.2 后台生成 QR 码与 APP 扫码绑定机制

手机 APP 第一次使用时的流程是：打开 APP → 添加新的服务器 → 用 APP 自带扫码功能扫描后台的 QR 码 → 绑定成功后给服务器起名称 → 点保存 → 点击服务器填写登录表单。这个 QR 码不是普通的 URL 链接，它把服务器地址、握手令牌和接口路径编码成一段 JSON。后台生成时的逻辑一般是：

<?php // 后台生成 APP 绑定二维码的核心逻辑（示意） $site_secret = '后台安装时生成的站点密钥'; $admin_id = $_SESSION['admin_id']; // 当前登录的管理员 ID // 绑定信息：server 是公网可访问的域名或 IP $bindPayload = json_encode([ 'server' => 'https://你的域名', // 必须与站点实际域名一致 'token' => md5($site_secret . $admin_id), // 站点密钥 + 管理员 ID 的哈希 'path' => '/php/api.php', // APP 调用的 API 路径前缀 ]); // 调用二维码库输出图片 echo qrcode($bindPayload);

这段代码里最关键的是server字段。如果后台生成二维码时用的是内网 IP 或 localhost，APP 在 4G/5G 网络下自然连不上服务器。token是管理员身份的后端凭据，它在 APP 扫码时被保存到手机本地，后续请求 API 时放在 header 或参数里，服务器通过它识别是哪个管理员在操作。地址栏手动访问这个接口，能看到一段 JSON 返回，才说明扫码绑定的链路是通的。

4.3 APP 登录表单与后台会话的同步

扫码绑定完成后，APP 端保存的是「服务器别名 + server 地址 + token」的映射表。点击服务器后填写的登录表单，实际上是拿着 token 加管理员用户名密码去做一次绑定登录，成功后 APP 就会轮询path指定的 API，拉取会话列表和消息记录。这套设计避开了在内网开额外端口做长连接推送的麻烦，也意味着 APP 对公网域名的可用性极其敏感。

Android 9 及以上默认禁止明文 HTTP 流量，如果你的站点没有配 HTTPS，APP 在部分系统版本上会直接拒绝连接。处理方式要么给域名配 SSL 证书，要么在 APP 的网络安全配置里允许特定域名明文传输——后者只适合内网测试，对外部署我一般建议直接上 HTTPS。这也是为什么后台生成 QR 码时，server字段要写成完整的https://地址，而不是裸域名。

5. PHP 版本冲突与 APP 失联：PHPlivechat 部署后的典型故障修复路径

5.1 PHP 8 环境下的兼容性判断

如果坚持用 PHP 7.4 或 8.0 跑这套源码，先用下面这条命令做快速体检：

php -r "var_dump(function_exists('each'), extension_loaded('mysqli'));"

输出bool(false)加bool(true)说明 each() 已被移除而 mysqli 正常，需要代码层面的兼容层才可能运行；如果两项都是 false，那基本可以放弃 PHP 8 方案。修复版在源码里已经做过一部分 mysql_* 到 mysqli 的兼容处理，但 PHP 8 移除的libxml_disable_entity_loader、fgetcsv行为变化等无法靠简单替换解决。与其补兼容层，不如在宝塔里把站点 PHP 版本切回 5.6，一行配置改动，省掉后续无休止的报错定位。

5.2 安装器反复跳回安装页

config.php 存在但页面仍然进入安装流程，最常见原因是 opcache 还缓存着「配置文件不存在」的状态。宝塔 PHP 设置页里临时关闭 opcache.enable，重载 PHP-FPM，再刷新页面。同时确认 config.php 内容没有被截断，用 CLI 直接解析：

php -r "include '/www/wwwroot/你的站点目录/config.php'; var_dump(\$db_name);"

如果 CLI 下解析正常但网页依然 500，说明问题在 Apache/PHP-FPM 进程侧，这时去站点 error_log 里看最后的 fatal error 信息，而不是重复提交安装表单。

5.3 APP 扫码后提示服务器不可达

按顺序排查三个位置。第一，手机浏览器直接打开你的域名/php/app.php?widget-mobile，看页面能不能正常加载；第二，把后台 QR 码里的 server 字段复制出来，确认不是内网地址，如果生成二维码时后台是用 localhost 登录的，这段地址几乎必然是错的；第三，管理员密码或 token 失效后，去后台重新生成一次二维码再扫码。我把这步固化成上线标准动作：安装成功后，先确认 config.php 权限为 644，删掉 install 目录，然后重新登录后台生成一次绑定二维码，用手机 APP 完成扫码并保持前台轮询，观察后台会话列表是否出现来自 APP 的标识——能看到标识，说明网页端和移动端已经完整打通。

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