跳到主要内容

常见问题和故障排除

安装问题​

安装后页面空白​

空白页面几乎总是意味着 PHP 错误被静默抑制了。

  1. 在文件管理器（托管控制面板的文件管理器或 FTP）中打开 storage/logs/laravel.log。查看最后几行——会有一条错误消息解释出了什么问题。
  2. 常见原因：
    • 缺少 PHP 扩展（检查要求页面）
    • 文件权限错误（请参阅下面的权限部分）
    • 配置文件中的数据库凭据错误

500 Internal Server Error​

这意味着服务器遇到了无法恢复的错误。

  1. 检查 storage/logs/laravel.log 获取实际错误消息。
  2. 检查 Web 服务器的错误日志——在 cPanel 中位于日志 → 错误日志。
  3. 最常见的原因：
    • 数据库凭据错误
    • 配置文件中 APP_KEY 值缺失或太短
    • 未启用必需的 PHP 扩展

安装程序不断将我重定向回起始页​

这通常意味着安装程序无法写入磁盘。安装过程完成时会创建名为 storage/installed.lock 的文件。如果无法创建该文件，它会认为安装从未完成。

解决方法：确保 storage/ 文件夹及其内部所有内容可写。在托管文件管理器中，右键单击 storage 文件夹并将权限设置为 755 或 775。

数据库连接失败​

安装程序中的错误消息会显示"Connection refused"或"Access denied"。

  • 仔细检查数据库主机名、数据库名称、用户名和密码。这些都在 cPanel 中创建数据库时设置。
  • cPanel 托管的数据库主机名几乎总是 localhost。
  • 确保数据库用户对数据库具有完整权限。

权限错误（无法写入 storage 或 cache）​

LeadHub 需要写入某些文件夹。如果看到无法写入文件的错误：

在托管文件管理器中，确保这些文件夹设置为权限 755（某些主机需要 775）：

  • storage/
  • storage/logs/
  • storage/framework/
  • storage/app/
  • bootstrap/cache/

电子邮件问题​

电子邮件未发送​

  1. 前往设置 → 电子邮件，检查所有字段是否正确填写。
  2. 点击发送测试邮件并输入您自己的电子邮件地址。
  3. 如果测试邮件未到达，检查 storage/logs/laravel.log 文件中是否有 SMTP 错误。
  4. 确保 cron job 正在运行——电子邮件通过任务队列处理，需要 cron job 来处理。请参阅下面的 Cron Job 部分。

电子邮件进入垃圾邮件​

  • 最常见的原因是"发件人邮箱"地址与 SMTP 提供商授权的域不匹配。
  • 将 SPF 和 DKIM 记录添加到您域名的 DNS 设置中。您的电子邮件提供商（SendGrid、Mailgun 等）会告诉您具体要添加什么。
  • 避免使用个人 Gmail 或免费电子邮件地址作为事务性邮件的发件人地址。请使用专业发送服务。

测试邮件失败​

  • 检查您的 SMTP 凭据——哪怕一个字符错误也会导致失败。
  • 对于 Gmail，您必须使用应用专用密码，而不是常规密码。
  • 共享托管上端口 587 可能被封锁。请改用带 SSL 的端口 465。
  • 询问您的托管提供商是否允许您使用的端口上的出站 SMTP。

Cron Job 问题​

自动化不运行 / 报告未发送​

LeadHub 使用一个 cron job 来处理所有后台工作：自动化、电子邮件发送、报告发送和计划任务。

cron job 命令是：

php /path/to/your/leadhub/cron.php

将 /path/to/your/leadhub/ 替换为服务器上的实际路径。

在 cPanel 中设置：

  1. 登录 cPanel。
  2. 前往 Cron Jobs。
  3. 将频率设置为每分钟（五个字段全部填 *）。
  4. 命令：php /home/yourusername/public_html/cron.php
  5. 点击添加新 Cron Job。

如果不确定路径，请咨询托管提供商，或在 cPanel 文件管理器中导航到网站根目录时查看显示的完整路径。

没有其他需要运行的命令。不要尝试从 cron 运行 artisan 命令——只使用 cron.php。

如何检查 cron job 是否在运行​

在 cPanel 中，前往 Cron Jobs 查看您创建的 cron job。如果列在那里，说明它已被调度。要验证它是否真正在执行，可以暂时在命令末尾添加 >> /tmp/crontest.log 2>&1，等待一分钟，然后检查文件中的输出。

线索来源问题​

Webhook 未收到线索​

  1. 检查您在外部服务（Facebook、Typeform 等）中配置的 webhook URL 是否完全正确，包括末尾的令牌。
  2. 在 LeadHub 中，前往集成或线索来源设置并查找"Test"或"Ping"按钮——使用它来验证连接。
  3. 检查 storage/logs/laravel.log 中是否有传入 webhook 错误。
  4. 确保您的服务器可以从互联网访问（不在阻止传入连接的防火墙后面）。

IMAP 收件箱未被轮询​

IMAP 轮询（检查电子邮件收件箱中的线索）需要 cron job 运行。请参阅上面的 Cron Job 部分。如果 cron job 正在运行但 IMAP 仍未轮询：

  1. 检查集成配置中的 IMAP 连接设置。
  2. 确保服务器上安装了 php-imap PHP 扩展。
  3. 检查 storage/logs/laravel.log 中是否有 IMAP 连接错误。

共享托管上的性能问题​

应用程序缓慢或超时​

共享托管资源有限。您可以做以下几件事：

增加 PHP 内存限制： 将此行添加到网站根目录中的 .htaccess 文件：

php_value memory_limit 256M

或者请求托管提供商在您的 PHP 设置中增加它。

启用缓存： 确保配置文件中有 CACHE_DRIVER=file 或 CACHE_DRIVER=database。这些在共享托管上无需额外设置即可使用。

减少队列批量大小： 如果服务器在处理大型导入或批量操作时遇到困难，请处理较小的批次。

如何查看日志​

主日志文件位于：

storage/logs/laravel.log

您可以在托管文件管理器中导航到该文件并点击打开来查看。查看文件底部——那里显示最新的错误。

日志文件随时间会变大。您可以安全地删除它（应用程序会自动创建新文件）。

如何清除缓存​

如果看到过时数据或页面未反映最近更改，清除缓存可能会有帮助。

通过托管文件管理器执行此操作：

  1. 导航到 bootstrap/cache/
  2. 删除此文件夹中的所有文件（但不要删除文件夹本身）
  3. 导航到 storage/framework/cache/data/
  4. 删除此文件夹中的所有文件和子文件夹

缓存会在下次页面加载时自动重建。

不要删除文件夹本身——只删除内容。

如何重新运行安装程序​

如果需要再次通过安装向导（例如，迁移到新数据库后）：

  1. 在托管文件管理器中，导航到 storage/ 文件夹。
  2. 删除名为 installed.lock 的文件。
  3. 在浏览器中访问您的网站——安装程序将自动启动。

这不会删除您的数据。它只是让安装程序再次运行。您的数据库和文件保持完整。

配置文件中的常见错误​

网站根目录中的配置文件（.env）控制许多设置。常见错误：

  • 缺少 APP_KEY — 这必须是 32 个字符的随机字符串。如果缺失或错误，应用程序将无法启动。
  • DB_HOST 错误 — 对于共享托管，这几乎总是 localhost。不要使用您的域名。
  • = 周围有空格 — 格式为 KEY=value，不带空格。KEY = value 不起作用。
  • 包含特殊字符的值未加引号 — 如果您的数据库密码包含 # 或 &，请将整个值用双引号括起来：DB_PASSWORD="my#p@ss&word"

获取帮助​

如果无法使用本文档解决问题：

  1. 首先检查日志文件 storage/logs/laravel.log。其中的错误消息通常会告诉您确切的问题所在。
  2. 搜索 CodeCanyon 评论 LeadHub 产品页面上——许多常见问题已在那里得到解答。
  3. 在 CodeCanyon 上提交支持工单，前往 LeadHub 产品页面并点击支持。提交时附上日志文件的相关部分。

联系支持时，请始终包含：

  • 您的托管环境（共享托管 / VPS，哪个提供商）
  • 服务器运行的 PHP 版本
  • storage/logs/laravel.log 的最后几行