安装与使用教程

一、环境要求

• PHP ≥ 8.2，扩展：openssl、pdo_mysql、mbstring、tokenizer、xml、ctype、json、bcmath
• MySQL 5.7+ / MariaDB
• Composer 2.x
• Nginx（推荐）+ PHP-FPM 8.3
• 可选：Supervisor 守护 Reverb 进程

二、安装步骤

1. 上传代码并安装依赖

cd /www/wwwroot/kefucms
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate

2. 配置数据库

编辑 .env 中的 DB_*，创建数据库后执行：

php artisan migrate --seed
php artisan storage:link

首次安装后请使用数据库种子创建的管理员账号登录（安装时自行设定，勿在公开页面展示）。

3. 目录权限

chown -R www:www storage bootstrap/cache
chmod -R 775 storage bootstrap/cache

4. 优化配置缓存

php artisan config:cache
php artisan route:cache
php artisan view:cache

三、环境变量（.env）

生产环境请全部使用 https://，不要使用 IP + HTTP。

四、Nginx 配置

1. 网站根目录

指向 public 目录，例如：/www/wwwroot/kefucms/public

2. Laravel 伪静态

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

3. WebSocket（Reverb）

location /app {
    proxy_pass http://127.0.0.1:8081;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 86400;
}

4. SSL 证书

在宝塔面板为 webcrisp.cc / www.webcrisp.cc 申请 Let's Encrypt，并开启强制 HTTPS。

若使用 Cloudflare，SSL 模式建议选「完全」或「完全（严格）」。

五、启动实时消息（Reverb）

客服工作台新消息依赖 WebSocket，需常驻运行：

php artisan reverb:start --host=127.0.0.1 --port=8081

生产环境建议用 Supervisor 守护，例如：

[program:kefucms-reverb]
command=php /www/wwwroot/kefucms/artisan reverb:start --host=127.0.0.1 --port=8081
directory=/www/wwwroot/kefucms
user=www
autostart=true
autorestart=true

六、嵌入您的业务网站

将以下代码放在您自己的业务网站每个页面 </body> 前（不要在 WebCrisp 官网首页加载 embed.js）。当前为单租户，全站一个站点 Key；多租户后续支持。

推荐在「聊天框设置」页复制自动生成的 HTTPS 代码。

<script>
  window.KEFU = { siteKey: 'duohaoba' };
</script>
<script async src="https://www.webcrisp.cc/embed.js?v=20260520"></script>

站点密钥（site_key）可在「聊天框设置」中查看；演示密钥：duohaoba

七、后台功能指引

推荐配置顺序

1. 聊天框设置 → 保存颜色、欢迎语、上传头像
2. 帮助文章 → 创建分类与 FAQ，并在聊天框设置中勾选展示
3. 快捷回复 → 添加常用话术
4. 复制嵌入代码到官网 → 客服登录收件箱测试
5. 点击侧栏「通知」→ 在浏览器弹窗中允许桌面通知

八、常见问题

桌面通知没有「允许」弹窗？

• 必须使用 HTTPS 访问 /agent，不能用 IP 或 HTTP
• 点击侧栏通知按钮（默认关闭），浏览器才会请求权限
• 若曾点过「阻止」，需在地址栏网站设置里手动改为「允许」后刷新

客服收不到实时消息？

• 确认 php artisan reverb:start 正在运行
• 确认 Nginx /app 已反代到 Reverb 端口
• .env 中 REVERB_SCHEME=https、BROADCAST_CONNECTION=reverb

嵌入后挂件不显示？

• 检查 siteKey 是否正确
• 检查 embed.js 地址是否为 HTTPS 且可访问
• 打开浏览器控制台查看是否有跨域或 mixed-content 错误

链接仍是 http://？

• 将 APP_URL 改为 https://... 后执行 php artisan config:cache
• 确保 Nginx 传递 X-Forwarded-Proto: https（反代/cloudflare）