LiveHelperChat（LHC）全场景常见问题汇总（含现象+原因+解决办法）

laoluo
laoluo
laoluo
管理员
160
文章
0
粉丝
教程评论15阅读模式

按部署安装、前端嵌入气泡、会话分配接待、Cron 定时任务、邮件通知、后台功能、数据库升级、性能权限、客户端 / 机器人、跨域防盗链十大类整理，覆盖 95% 运维故障。

一、部署安装类（新装 / 解压报错）

1. 访问页面空白、500 报错、提示 autoload.php 不存在

  • 现象：打开 LHC 域名直接白屏，日志报Failed opening vendor/autoload.php
  • 原因：Git 下载源码无 Composer 依赖，宝塔禁用 proc_open 函数、目录权限不足
  • 解决：
    1. 下载官方完整带依赖包，或进入目录执行composer install
    2. 宝塔软件商店 PHP 设置，删除禁用函数proc_open,proc_terminate
    3. 授权目录权限：chmod -R 755 var/ cache/ settings/; chown www:www -R 网站目录

2. 安装检测不通过，PHP 扩展缺失

  • 必装扩展：mbstring、curl、gd、pdo_mysql、json、fileinfo、openssl
  • 解决：宝塔 PHP 安装对应扩展，重启 PHP 服务

3. 访问后台 404 Not Found

  • 现象：域名/site_admin打不开，首页正常
  • 原因：Nginx/Apache 伪静态未配置、URL 省略 index.php
  • 解决：
    1. 标准访问地址：https://lhc域名/index.php/site_admin/user/login
    2. Nginx 添加 LHC 官方伪静态规则，开启 PATH_INFO

4. 数据库连接失败、安装时报 SQL 错误

  • 原因：数据库账号权限不足、编码非 utf8mb4、InnoDB 引擎、数据库不存在
  • 解决：
    1. 数据库授予账号全部权限（CREATE/ALTER/DROP）
    2. 数据库排序规则改为utf8mb4_general_ci，引擎统一 InnoDB

二、网站嵌入 / 气泡前端异常（最多人遇到）

1. 右下角悬浮气泡完全不显示、加载转圈

  1. X-Frame-Options 拦截
    现象：浏览器控制台报错Refused to display in a frame because X-Frame-Options
    原因：Nginx/Apache 安全头禁止 iframe 嵌套客服窗口
    解决：Nginx 删除X-Frame-Options DENY，或改为ALLOWALL
  2. HTTP/HTTPS 协议不匹配
    现象：网站 HTTPS，LHC 地址写 http，浏览器混合内容拦截
    解决：嵌入代码里lhc_base_url必须写完整 https 域名
  3. 跨域 CORS 报错
    控制台出现 Access-Control-Allow-Origin，气泡加载失败
    解决：Nginx 配置 LHC 站点添加跨域头，后台嵌入代码填写允许域名白名单
  4. JS 代码粘贴位置错误
    必须放在网站</body>结束标签前，放 head 会加载异常
  5. 缓存未清：后台 System → Clean cache，浏览器 Ctrl+F5 强制刷新

2. 气泡窗口极小、手机端显示错乱

  • 原因：网站缺少 viewport 移动端适配标签
  • 解决：网页头部添加
<meta name="viewport" content="width=device-width, initial-scale=1">

 

3. 无客服在线，不弹出留言表单

  • 原因：嵌入代码未勾选「无坐席在线显示留言」、部门离线配置关闭留言
  • 解决：
    1. Embed code 页面勾选 Show leave message form
    2. System → Live help config 设置离线展示留言表单

4. 访客刷新页面，每次重新发起对话，不恢复历史会话

  • 路径：System → Live help configuration → Misc
  • 开启：Reopen chat functionality enabled

5. 其他网站盗用我的客服气泡

  • 解决：嵌入代码配置 Allowed domains 白名单，仅填写自己网站域名

三、会话分配与客服接待故障（核心业务问题）

1. 访客发起咨询，坐席收不到会话、不会自动分配

  1. Cron 定时任务未配置（头号元凶）
    LHC 自动分配、排队、转人工完全依赖 cron/workflow，没配置完全不分配会话
    标准定时（每分钟执行）：

    */1 * * * * php /lhc_web/cron.php -s site_admin -c cron/workflow
  2. 坐席状态不是 Online（离线 / 离开不接单）
  3. 访客选择的部门，坐席未加入该部门
  4. 部门设置了工作时间，当前不在接待时段
  5. 部门自动分配模式关闭，单坐席接待上限已满

2. 坐席看不到排队访客、无法接手待处理会话

  • 原因：角色权限缺少chat,take_unassigned、chat,open_all权限
  • 解决：后台 Users → Roles，给客服角色开启「查看所有待处理会话」权限

3. 会话自动关闭太快，访客消息没来得及回复就结束

  • 路径：System → Live help configuration → Auto close
  • 调大：未接待自动关闭、闲置会话自动关闭分钟数

4. 访客发送消息，坐席无声音 / 浏览器通知提醒

  • 解决：
    1. 后台开启 Sound notifications 提示音
    2. 浏览器允许该站点通知权限
    3. 关闭浏览器静音、电脑系统音量

5. 转接会话、内部客服私聊功能失效

  • 排查：Cron transfer_workflow 任务未执行；清理系统缓存；坐席权限不足

6. 访客上传图片 / 文件失败

  • 原因：var/storage 目录无写入权限、PHP 上传大小限制过小、禁止后缀拦截
  • 解决：授权目录 755；php.ini 调大 upload_max_filesize；后台开启文件上传开关

四、Cron 定时任务全套问题（功能失效根源）

1. 机器人自动回复不生效、离线留言不触发

  • 根源：cron/workflow 未每分钟执行

2. 会话自动清理、过期记录删除失效

  • 缺少每日凌晨清理定时：0 3 * * * php cron.php -s site_admin -c cron/maintenance

3. Cron 执行报错、权限拒绝

  • 原因：定时运行用户为 root，网站目录属 www，读写权限冲突
  • 解决：crontab -u www -e 用网站运行用户配置定时任务

4. 定时任务卡住 running 状态不结束

  • 磁盘满、PHP 执行超时，手动删除缓存临时文件，重启 cron

五、邮件通知故障（离线留言、会话回执收不到邮件）

1. 配置 SMTP 后测试发送失败

  • 常见报错：550 权限拒绝、连接超时、端口不通
  • 排查步骤：
    1. SMTP 地址、端口、SSL/TLS 匹配（465=SSL，587=TLS）
    2. 服务器防火墙放行对应出站端口
    3. 企业邮箱开启 SMTP 授权码，不要直接用登录密码
    4. 后台 Mail settings 测试发送，查看日志报错

2. 邮件发送成功，但访客收不到（垃圾箱也无）

  • 原因：发件 IP 被邮箱服务商拉黑、缺少 SPF 解析记录、邮件模板为空
  • 解决：域名添加 SPF 记录；更换企业邮箱发件；检查邮件模板内容

3. 会话结束、离线留言无邮件推送管理员

  • 检查：部门离线通知开关、邮件模板启用、cron 任务正常运行

六、机器人（Bot）功能异常

1. 访客提问机器人无自动回复

  1. Cron workflow 未配置
  2. Bot 模块未启用、工作流未发布启用
  3. 关键词匹配规则错误、未设置转人工触发词
  4. 工作时段判断逻辑冲突，直接跳过机器人

2. 机器人收集手机号 / 订单号，自定义字段不保存

  • 工作流字段绑定错误；清理缓存；数据库字段权限不足

七、升级 / 数据库报错（更新版本必出问题）

1. 升级后页面报错：表不存在 Table lhc_xxx doesn't exist

  • 原因：升级后未同步数据库结构
  • 修复命令：
php cron.php -s site_admin -c cron/util/update_database

2. 升级后后台空白、功能错乱

  1. 执行 composer install 更新依赖
  2. 后台 Clean cache 清理全部缓存
  3. 手动执行数据库更新脚本

3. 数据库字符集错误，中文乱码

  • 数据库、数据表统一改为 utf8mb4，连接配置指定 utf8mb4 编码

八、后台权限、统计、基础配置问题

1. 普通客服看不到数据统计、聊天记录导出

  • Roles 角色权限未开启报表、聊天记录导出权限

2. 修改文案、气泡颜色、嵌入代码，前端不更新

  • LHC 重度缓存机制，修改任何前端配置必须后台 Clean cache + 浏览器强制刷新

3. 在线访客列表空白，看不到当前访问用户

  • 权限缺少在线访客查看权限；Cron 状态同步失败；JS 跨域报错

4. 主动邀请弹窗（Proactive）不自动弹出

  • 嵌入代码未开启主动邀请；停留秒数设置错误；缓存未清理

九、客户端（Electron 桌面端）异常

1. 桌面客户端收不到新会话提醒，网页端正常

  • 客户端版本老旧，API 不兼容，升级官方 Electron 客户端，弃用 QT 旧客户端

2. 快捷回复（Canned Messages）下拉为空

  • 后台重新保存快捷回复、清理缓存；数据库不支持 JSON 函数，升级 MySQL/MariaDB

十、性能、服务器、安全类问题

1. 大量访客同时咨询，系统卡顿缓慢

  • 优化：开启 Redis 缓存；定时归档历史会话；限制单坐席接待上限；升级 PHP 版本至 8.1+

2. 磁盘占满，客服系统完全无法使用

  • 清理 var/log 日志、过期聊天记录、上传附件；配置定时自动清理会话

3. 访问后台提示维护模式、无法登录

  • 升级中断导致维护标记未关闭；执行数据库更新命令，清理缓存

4. 接入 CDN/Cloudflare 后访客 IP 识别错误

  • 后台 settings.ini 开启代理 IP 解析，读取 CDN 真实访客 IP 头，否则会话分配异常

LiveHelperChat 完整实操手册（后台配置+嵌入+接待+高级功能+排错）
LiveHelperChat（LHC）完整中文设置教程
宝塔面板安装 LiveHelperChat 完整教程（原生PHP部署，稳定生产可用）
LiveHelperChat 完整实操手册（后台配置+嵌入+接待+高级功能+排错）
 
laoluo
  • 本文由 laoluo 发表于2026年7月5日 18:19:42
  • 转载请务必保留本文链接：https://www.mydata-api.com/tutorials/373.html

加载中...

匿名

发表评论

匿名网友
确定

拖动滑块以完成验证