宝塔面板安装 LiveHelperChat 完整教程（原生PHP部署，稳定生产可用）

LiveHelperChat（简称 LHC）是开源免费在线客服系统，本教程采用宝塔 PHP 手动部署，适配 CentOS/Debian 宝塔，包含环境准备、源码安装、伪静态、SSL、权限、后台配置全流程。

一、环境要求（必须满足）

1. PHP 版本

推荐 PHP 8.1 / PHP 8.2（PHP7.x 易出现兼容报错）

2. 必装 PHP 扩展（宝塔软件商店→PHP 扩展安装）

json、cli、gd、xml、pdo、zip、mysqlnd、mbstring、bcmath、curl

 3. 推荐安装扩展（优化功能）

redis、igbinary、imap、opcache

4. 数据库

MySQL 5.7+/MariaDB 10.3+

5. 服务器

Nginx（宝塔默认），服务器放行 80/443 端口

二、宝塔前置配置

步骤 1：安装对应 PHP 并开启扩展

1. 宝塔左侧【软件商店】→【运行环境】，安装 PHP8.2
2. 点击 PHP8.2 右侧【设置】→【安装扩展】，勾选上面所有必装扩展，安装后重启 PHP-FPM

步骤 2：创建站点 + 数据库

1. 左侧【网站】→【添加站点】
   • 域名：填写客服二级域名，例 chat.xxx.com（提前域名解析到服务器 IP）
   • 数据库：勾选创建 MySQL 数据库，记录数据库名、账号、密码
   • PHP 版本：选择 PHP8.2
   • 点击【提交】自动生成网站目录 /www/wwwroot/chat.xxx.com

步骤 3：设置网站基础参数

站点→【设置】：

1. 运行目录：保持默认 /（LHC 无 public 目录，不要修改）
2. 关闭【防跨站攻击 (open_basedir)】（否则安装时权限报错）
3. 保存设置

三、下载并上传 LiveHelperChat 源码

1. 获取官方完整源码（带依赖包，无需 Composer）

官方下载地址：https://livehelperchat.com/download
选择：livehelperchat-x.x.x-with-dependencies.tgz（带依赖包，新手首选）

2. 上传解压源码

1. 宝塔【文件】进入站点根目录 /www/wwwroot/chat.xxx.com
2. 点击【上传】，上传 tgz 压缩包
3. 右键压缩包→解压到当前目录
4. 解压完成后，把解压出来文件夹内所有文件剪切到站点根目录（不要套多层文件夹）

3. 批量目录权限（关键，安装检测全绿）

文件→勾选站点全部目录，右键【权限】：

• 所有者：www
• 权限：目录 755，文件 644
• 勾选【递归应用到子目录】→确定

需要读写的核心目录（单独给 775 权限）：
cache、tmp、storage、userdata、lhc_web/cache

四、Nginx 伪静态配置（解决 404）

1. 站点【设置】→【伪静态】，选择 Nginx，粘贴以下规则：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9082; # 9082替换为你的PHP8.2端口，宝塔PHP设置可查看
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    fastcgi_param HTTP_PROXY "";
}
# 禁止访问敏感文件
location ~ /(config|install|backup)/ { deny all; }

2. 保存，重载 Nginx

五、在线安装 LHC 系统

1. 浏览器访问安装地址：
   https://chat.xxx.com/index.php/site_admin/install/install
2. 页面环境检测：全部项显示绿色 OK，如果红色：
   • 权限不足：重新设置目录 755/775
   • 扩展缺失：回到 PHP 扩展页面安装并重启 PHP
3. 点击下一步，填写数据库信息（刚才建站生成的数据库账号密码）
4. 设置超级管理员账号、密码、邮箱
5. 提交安装，等待数据库导入完成

六、SSL HTTPS 配置（强制 https，客服弹窗正常）

1. 站点【设置】→【SSL】，选择 Let’s Encrypt 免费证书
2. 勾选域名，点击申请，自动签发
3. 开启【强制 HTTPS】，保存

七、登录后台与基础使用

后台地址

https://chat.xxx.com/index.php/site_admin/user/login

访客聊天窗口地址

https://chat.xxx.com/index.php/chat/startchat

网站嵌入客服弹窗代码

后台 → 设置 → 嵌入代码，复制 JS 到你的业务网站底部即可：

<script type="text/javascript">
var LHC_API = LHC_API||{};
LHC_API.args = {
    mode:'widget',
    lhc_base_url:'https://chat.xxx.com/',
    widgetwidth:350,
    widgetheight:500
};
(function() {
    var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
    po.src = LHC_API.args.lhc_base_url + '/widgetrestapi/embedwidget';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
</script>

八、常见报错修复

1. 安装页面权限检测红色

• 关闭站点防跨站
• 递归目录所有者改为 www，cache/tmp 目录 775

2. 聊天加载空白 / 无法推送消息

1. 宝塔放行服务器防火墙：80/443
2. 云服务器安全组放行 80/443
3. 伪静态 PHP 端口与当前 PHP 版本一致
4. 后台设置开启 WebSocket 支持

3. PHP Composer 报错（下载不带依赖包源码时）

进入站点目录，宝塔终端执行：

cd /www/wwwroot/chat.xxx.com
php composer.phar install

4. 发送邮件失败

后台→系统设置→邮件配置，填写 SMTP 信息（QQ 邮箱 / 企业邮箱）

九、Docker 快速部署方案（备选，无需配置 PHP 环境）

适合不想手动配置 PHP 的用户：

1. 宝塔软件商店安装 Docker
2. 新建文件夹 /www/wwwroot/lhc-docker，新建 docker-compose.yml

version: '3'
services:
  lhc:
    image: livehelperchat/lhc
    ports:
      - "8080:80"
    volumes:
      - ./lhc_data:/var/www/html
    environment:
      - MYSQL_HOST=mysql
      - MYSQL_DATABASE=lhc
      - MYSQL_USER=lhcuser
      - MYSQL_PASSWORD=你的数据库密码
  mysql:
    image: mariadb:10.6
    volumes:
      - ./mysql_data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=数据库root密码
      - MYSQL_DATABASE=lhc
      - MYSQL_USER=lhcuser
      - MYSQL_PASSWORD=你的数据库密码

3. 宝塔终端进入目录执行启动：

cd /www/wwwroot/lhc-docker
docker compose up -d

4. 站点反向代理 127.0.0.1:8080，配置 SSL 即可访问

十、安全优化建议

1. 安装完成后删除 install 文件夹，禁止重复安装
2. 修改后台登录路径，开启两步验证
3. 宝塔 WAF 添加防护规则，拦截 SQL 注入
4. 定期备份站点文件 + 数据库（宝塔计划任务自动备份）
5. 后台限制登录 IP，仅办公网可访问客服后台