Mautic使用手册翻译4: 故障处理

4. 故障排除

原文: Troubleshooting

按照以下步骤解决可能更快的解决您的问题。

我的Mautic表现怪异

即使通过开发人员和测试团队的努力，也可能会发生。首先，让我们尝试一些可以快速修复的技巧。

1.清除缓存

有几种方法可以做到这一点。最简单的是去 /var/cache 文件夹并删除其内容。如果要通过CLI命令执行此操作，请导航到Mautic根文件夹并运行 rm -rf var/cache/*。新的缓存文件将在浏览器中的下一次Mautic刷新后生成。

警告：滥用’rm -rf’命令可能会从您的项目中删除整个文件夹和文件。如果您不知道自己在做什么，请不要尝试。

文件可能不会自行生成。这可能是由于错误的文件夹权限引起的，并且Mautic没有写新缓存文件的权限。请与您的系统管理员联系，并请他们为您修复它。

提示：请勿自己以root用户身份执行Mautic命令，也不要在root crontab中运行Mautic命令。这样，该命令将创建的所有文件都将具有作者的根目录，而Mautic将无法重写这些文件。

2.尝试修复数据库架构

去 http://[your-mautic-url]/s/update/schema。如果有一些已知的更新要应用，它将更新您的数据库模式。

3. 查看日志

如果您的Mautic管理工作正常，请转到“管理”菜单（单击右上角的cog图标），然后依次单击“系统信息”和“日志”。您将看到Mautic今天记录的错误消息。

如果您的Mautic管理不起作用，请通过文件系统打开日志。去 [mautic_root]/var/logs 文件夹。您应该每天看到一个文件，称为 mautic_prod-YYYY-mm-dd.php 。打开最新的一个。

服务器日志

我没有所有操作系统和服务器的经验。我可以告诉你，Apache2将服务器日志保存在 Ubuntu中/var/log/apache2/error.log。如果您不知道服务器日志的存储位置，请联系您的系统管理员或尝试使用谷歌搜索。

MySQL日志

如果您的Mautic说由于某种原因它无法连接到MySql，则可以检查MySql日志中存储了哪些信息。同样，我只能建议日志在Ubuntu中的位置：/var/log/mysql/error.log。但老实说，在90％的情况下，数据库连接错误是由错误的凭据引起的。

日志文件太大

如果日志太大，以至于普通编辑器无法打开它，而您具有CLI访问权限，请尝试使用以下命令仅读取日志的最后几行

tail [mautic_root]/var/logs/mautic_prod-YYYY-mm-dd.php

您必须添加当前日期，而不是YYYY-mm-dd部分。如果要查看的行数多于默认行数-n 40，请在命令末尾使用该属性以查看最后40行。

但是我不明白错误信息
深吸一口气，然后尝试阅读错误消息。某些错误消息实际上已在其中写入了解决方案。看这一个：

Fatal: Automatically populating $HTTP_RAW_POST_DATA is deprecated and will be removed in a future version. To avoid this warning set 'always_populate_raw_post_data' to '-1' in php.ini and use the php://input stream instead. - in file Unknown - at line 0 [] []

您看到建议了吗？

为避免此警告，请在php.ini中将“ always_populate_raw_post_data”设置为“ -1”

但是您仍然不知道这意味着什么吗？在这种情况下，最简单的方法是与您的系统管理员联系，并告诉他们。

让我们看一些例子
错误：

PHP Fatal error:  Allowed memory size of 67108864 bytes exhausted (tried to allocate 10924085 bytes) in ...
Fatal: Maximum execution time of 120 seconds exceeded - in file ...

解决方案：这意味着Mautic需要的内存/时间超过服务器限制的时间。同样，请与系统管理员联系并咨询您的可能性。

错误：

Fatal: Class 'ZipArchive' not found

**解决方案：**可能缺少ZipArchive，MCrypt或任何其他PHP模块。同样，请咨询您知道谁安装它。

错误：

PHP Parse error:  syntax error, unexpected T_OBJECT_OPERATOR in

**解决方案：**这通常意味着您的PHP已过时。检查Mautic的要求。

错误：

exception 'RuntimeException' with message 'Unable to create the cache directory ...

**解决方案：**这意味着文件权限不正确，Mautic无法写入缓存文件。

错误：

mautic.WARNING: IP LOOKUP: The file "../var/cache/prod/../ip_data/GeoLite2-City.mmdb

**解决方案：**这意味着您只是没有下载IP查找库。转到Mautic的配置，滚动到底部，然后单击按钮进行下载。

错误：

Uncaught PHP Exception Doctrine\DBAL\DBALException: "An exception occurred while executing 'INSERT INTO

**解决方案：**这是一个SQL错误。这可能意味着您的数据库架构已过时，或者Mautic的某些部分存在错误。在第一种情况下，本文的步骤2应该对其进行修复。在第二种情况下，请查看下面的错误报告。

错误：

PHP Fatal error: Call to a member function isRendered() on a non-object in ...

解决方案: 通常意味着一个错误。

在哪里可以报告我的错误？

帮助您的开发人员，并在第一时间正确报告该错误。转到Github问题跟踪器，至少回答以下3个问题：

• Mautic版本：
• PHP版本：
• 重现该错误的步骤：

并在帖子模板的部分中粘贴错误消息。

4.1 命令行界面（CLI）命令

原文: Command Line Interface (CLI) commands

有时，您可能需要在Mautic中使用命令行（CLI）。以下是可以使用的CLI命令的列表。

您可以通过键入以下内容找到此列表（以及其他列表，例如与Doctrine和其他供应商有关的命令）

bin/console

在您的Mautic目录中的命令行中。

用法：命令[选项] [参数]

选项：

选项	描述
-h，–help	显示此帮助消息
-q, --quiet	不输出任何消息
-V, --version	显示此应用程序版本
–ansi	强制ANSI输出
–no-ansi	禁用ANSI输出
-n, --no-interaction	不要问任何互动问题
-s, --shell	启动外壳。
–process-isolation	从Shell启动命令是一个单独的过程。
-e, --env=ENV	环境名称[默认：“ prod”]
–no-debug	关闭调试模式。
-v -vv -vvv –verbose	增加消息的详细程度： 1表示正常输出， 2 表示更多详细输出， 3 表示调试

Mautic命令

这些是您可能需要相对于Mautic实例使用的命令。它们之前应带有bin / console。

选项	描述
mautic:assets:generate	将每个捆绑包中的资产文件合并并最小化为单个生产文件
mautic:broadcasts:send	处理正在等待接收频道广播的联系人。
mautic:campaigns:execute	执行特定的预定事件。
mautic:campaigns:messagequeue	处理消息队列的发送。
mautic:campaigns:messages	处理消息队列的发送。
mautic:campaigns:rebuild	根据联系人细分重建广告系列。
mautic:campaigns:trigger	触发已发布活动的定时事件。
mautic:campaigns:update	根据联系人细分重建广告系列。
mautic:campaigns:validate	验证联系人是否对某个决定无效，如果是，则执行事件。
mautic:citrix:sync	同步Citrix产品中的注册人信息
mautic:contacts:deduplicate	根据相同的唯一标识符合并联系人
mautic✉️fetch	提取并处理受监控的电子邮件。
mautic:emails:send	处理SwiftMail的邮件队列
mautic:import	将数据导入到Mautic
mautic:integration:fetchleads	从集成中获取线索。
mautic:integration:pipedrive:fetch	从Pipedrive中提取数据并将其发送到Mautic
mautic:integration:pipedrive:push	将数据从Mautic推送到Pipedrive
mautic:integration:pushactivity	推动潜在客户整合活动。
mautic:integration:pushleadactivity	推动潜在客户整合活动。
mautic:integration:synccontacts	从集成中获取线索。
mautic:iplookup:download	为利用本地查找的IP查找服务获取远程数据存储
mautic:maintenance:cleanup	更新Mautic应用程序
mautic:messages:send	处理消息队列的发送。
mautic:migrations:generate	生成一个空白的迁移类。
mautic:plugins:install	安装，更新，启用和/或禁用插件。
mautic:plugins:reload	安装，更新，启用和/或禁用插件。
mautic:plugins:update	安装，更新，启用和/或禁用插件。
mautic:queue:process	处理队列
mautic:reports:scheduler	处理报表导出的调度程序
mautic:segments:check-builders	比较给定细分的查询构建器的输出
mautic:segments:rebuild	根据新的联系人数据更新智能细分中的联系人。
mautic:segments:update	根据新的联系人数据更新智能细分中的联系人。
mautic:social:monitoring	查看监视器的记录并遍历它们。
mautic:theme:json-config	将主题配置从PHP转换为JSON
mautic:unusedip:delete	删除任何其他数据库表中未使用的IP地址
mautic:update:apply	更新Mautic应用程序
mautic:update:find	获取Mautic的更新
mautic:webhooks:process	处理排队的Webhook有效负载
social:monitor:twitter:hashtags	查看我们的监控记录并找到标签
social:monitor:twitter:mentions	搜索提到的推文

教义命令

选项	描述
doctrine:fixtures:load	安装Mautic样本数据，覆盖现有数据

4.2 更新失败

原文: Update Failed

有时，在更新Mautic时，该过程可能会停顿或部分失败。这可能会引起问题，因为它可能导致Mautic介于两个版本之间，并且经常使系统无法使用。

可以按照以下过程手动完成升级。

在开始这些步骤之前，请确保已对Mautic实例进行了测试备份

检查架构更新
Mautic有一个内置工具，可让您检查数据库并确定是否需要任何模式更新。访问your-mautic-url / s / update / schema以查看是否需要任何更新。

如果这是不可能的，或者您的Mautic实例完全关闭，请遵循以下提示。

如果您没有SSH访问权限，请跳至我没有SSH访问权限。

我有SSH存取权

拥有对服务器的SSH访问权限使事情变得更加容易。通过命令行登录，并使用以下命令将目录更改为Mautic的安装位置。

cd /your/mautic/directory

1.尝试清除缓存

如果在最后一步中升级尝试失败，则可能是导致问题的原因仅是过时的缓存。使用以下命令手动清除它：

php bin/console cache:clear

如果此命令引发PHP错误，则可以尝试使用以下命令删除缓存文件夹（请注意，这会删除指定路径中的所有文件和文件夹，因此请确保正确键入！）

rm -rf bin/cache

如果清除缓存仍无法解决您的问题，请继续下一步。

2.手动触发更新

第一步是使用以下命令找出是否有可用的更新：

php bin/console mautic:update:find

该命令的输出将告诉您是否有任何更新要应用。如果存在，请运行以下命令以应用它们：

php bin/console mautic:update:apply

如果找不到更新，请继续执行下一步。

3.检查未完成的数据库迁移

运行以下命令以检查是否有任何未完成的数据库迁移：

php bin/console doctrine:migration:status

如果有报告，请首先确保您已对数据库进行了测试，然后再继续操作，因为此命令将导致对数据库的更改，然后运行：

php bin/console doctrine:migration:migrate

4.尝试手动更新文件

此步骤需要一些手动干预-此部分没有命令。

要手动更新文件，您将必须：

1. 使用更快的FTP或scp命令将所有Mautic文件从服务器备份（下载）到本地计算机。
2. 删除所有Mautic文件和文件夹。使用FTP或rm命令（在使用后者时要格外小心）
3. 从https://www.mautic.org/download下载最新的Mautic软件包
4. 使用FTP或更快的scp命令将zip软件包上传到服务器，Mautic文件夹。
5. 用 unzip 2.16.zip 解压缩该软件包（更改文件名以匹配您上载的文件名）。然后，您可以使用命令 rm 2.16.zip 删除该zip文件。
6. 从本地计算机上的备份将 app / config / local.php 上传到服务器上的新Mautic文件夹（Mautic现在应该运行）
7. 上载您的自定义数据（如果有的话）。在以下文件夹中可以找到自定义字段：媒体/文件；插件; 主题；翻译

我没有SSH访问权限

有一个PHP脚本可以完成上述部分的几乎所有步骤。您可以在Gist中找到此脚本。

脚本本身下方提供了有关如何使用脚本的说明。您需要采取一些其他措施，因此请仔细阅读以下说明。例如，您将需要使用FTP上载和下载文件。您将需要在本地计算机上解压缩文件并上传这些文件，这将花费更长的时间。

执行命令时出现PHP错误

最好的办法是读取错误，然后在您首选的搜索引擎中搜索错误。您也可以搜索Mautic论坛，以查看其他人是否报告并解决了相同的问题。

允许的内存容量已用尽

该错误通常将报告为：

PHP Fatal error:  Allowed memory size of 67108864 bytes exhausted (tried to allocate 10924085 bytes) in ...

这意味着Apache可用的内存限制太低。编辑php.ini配置文件中的memory_limit。

缺少必需的PHP扩展名

Fatal: Class 'ZipArchive' not found

这意味着PHP无法与Zip软件包一起使用-需要对服务器配置进行更改以允许在命令行中解压缩文件。向您的托管服务提供商询问，或搜索教程以帮助解决此问题。

去哪寻找帮助

如果您陷入困境并需要帮助，可以在几个地方寻求帮助。请记住，大多数使用社区论坛，聊天和Github的人都是志愿者。

如果您认为您的配置引起了问题，请在Mautic社区论坛上提问。发布前先搜索，因为过去可能有人已经回答了您的问题。

您还可以在实时社区聊天中与某人聊天。

在所有情况下，描述问题以及详细解决问题所遵循的所有步骤非常重要。至少包括以下内容：

• 重现问题的步骤-有关问题如何产生或如何重现的分步教程
• 您的服务器的PHP版本
• 您看到的错误消息-如果您没有直接看到该错误消息，请在 app/logs 文件夹和服务器日志中进行搜索。根据您的设置，可以在不同位置找到服务器日志。Ubuntu服务器通常在 /var/log/apache2/error.log 中有日志。有时，您的托管服务提供商可能会提供GUI来查看“控制面板”中的日志。
  如果您没有至少提供上述信息，则可能会尝试帮助您的人将要求您提供此信息，因此请为他们省去麻烦，并提前提供信息。另外，重要的是，请保持礼貌。Mautic是一个开源项目，人们正在给予他们的空闲时间来帮助您。

如果您确定已发现错误，并且想将其报告给开发人员，则可以在Github上进行操作。

4.3 使用php.ini资源限制

在安装或使用Mautic时，服务器配置可能会遇到限制。这些通常表现为错误，例如：

The Uploaded file exceeds the upload_max_filesize directive
Maximum execution time of 30 seconds exceeded - in file <filepath> - at line <line number> 
PHP Error: Allowed memory size of <number> bytes exhausted (tried to allocate <number> bytes) - in file <filepath> - at line <number>

通常，这些不是Mautic的错误，它们与服务器的配置方式有关。要解决这些问题，您将需要对服务器配置进行一些更改。

要求

要解决这些问题，您将需要：

• 访问服务器以更改配置文件-通常通过SSH-或
• 访问托管服务提供商的控制面板，这可能使您可以通过用户界面更改这些设置
• 访问文本编辑器，例如nano或Vi

注意：本演练中使用了nano，如果您不使用Nano，则只需将“ nano”替换为您希望使用的编辑器的名称即可。使用Nano时，请参阅此资源以获取有用的键盘快捷键指南。

如果您没有这两种方法，或者您对进行这些更改没有信心，则可能需要向托管服务提供商索取支持票或聘请自由职业者为您进行这些更改。

查找php.ini文件

第一步是查找使用的php.ini文件。在php.ini文件是一个配置文件，控制PHP如何运作。

可以进入Mautic

如果您有权访问您的Mautic实例，请导航至“设置”>“系统信息”>“ PHP信息”，在这里您将能够查看一个文件，该文件告诉您Mautic正在使用的PHP的每个配置设置。特别是，以下屏幕截图中以红色概述的区域将为您提供相关文件的路径。

有关Local & master 的值

当您查看PHP信息文件时，您会注意到两个值，即Master和Local。

Master Value

这来自您的主要php.ini文件（上面已在“已加载的配置文件”部分加载的文件）。这是在整个服务器范围内应用的值。

Local Value

可以在多个位置本地覆盖全局设置，例如httpd.conf，.htaccess或其他Apache配置。

这通常用于绕过服务器级别的限制性设置，有时可能意味着在顶级全局级别进行更改不会滴入您的特定文件夹或位置。因此，如果两者之间有差异，请在Mautic目录中检查本地.htaccess或* .ini文件（或与托管服务提供商联系！）

无法使用Mautic

如果您无法访问Mautic的“系统信息”页面，则可以使用以下命令检查php.ini的文件路径：

php -i | grep .ini

您还可以使用相同的命令来查找正在使用的特定值：

php -i | grep upload_max_filesize

其中upload_max_filesize是您需要更改的值。

更新value

找到正在使用的php.ini文件后，应该可以使用以下命令对其进行编辑：

sudo nano path/to/file/php.ini

使用ctrl + w（“ where”的键盘快捷键）找到相关设置，然后键入您需要更改的设置-例如upload_max_filesize。

更改您在php.ini文件中看到的值，然后使用ctrl + x（“ exit”的键盘快捷键）进行保存，然后按“ y”保存更改。

重新启动Apache

保存更改后，您将需要重新启动Apache才能使更改生效。

最好先使用configtest命令进行空运行

sudo apachectl configtest

在重新启动服务之前，这会检查您的Apache配置是否正确。解决重新启动Apache之前发现的所有问题。

满意后，运行以下命令重新启动Apache：

Ubuntu和Debian

sudo systemctl restart apache2

CentOS和Red Hat

sudo systemctl restart httpd

覆盖value

如果您无法在php.ini级别更改该值，则有可能（取决于您的服务器配置）覆盖本地文件夹级别的值。

请查看本文，以获取有关如何使用本地.htaccess文件覆盖php.ini设置的更多详细信息。

作为两个设置的示例，您可能希望在本地htaccess文件中使用这些设置来覆盖全局php.ini文件中的值：

php_value upload_max_filesize 20M
php_value max_execution_time 600

这应该被视为万不得已，您的托管服务提供商可能不支持。

4.4 文件所有权和权限

如果遇到以下错误：

mautic.WARNING: PHP Warning - require(/mautic/var/cache/prod/doctrine/orm/Proxies/__CG__MauticCategoryBundleEntityCategory.php): failed to open stream: No such file or directory - in file /mautic/vendor/doctrine/common/lib/Doctrine/Common/Proxy/AbstractProxyFactory.php - at line 209

您极有可能在Mautic实例上对文件和文件夹的权限和/或所有权存在问题。

本文是从使用Apache的Linux服务器的角度编写的，Apache是​​Mautic最常见的托管环境。Nginx和IIS服务器将具有不同的配置，但是原理保持不变。

为什么权限很重要？

文件和文件夹权限指定可以读取，写入，修改和访问它们的人员和对象。所有权确定哪些用户“拥有”文件和文件夹-因此能够根据权限设置执行操作。

用户 user

用户是文件的所有者。默认情况下，创建文件的人成为其所有者。因此，用户有时也称为所有者。

组 group

一个组可以包含多个用户。属于一个组的所有用户将对该文件具有相同的访问权限。组用于简化权限-特定组中的所有用户将继承分配给该组的权限，而不必分别为每个用户分配权限。

其他 other

有权访问文件的任何其他用户都将进入“其他”，这意味着他们既未创建文件，也不属于拥有该文件的用户组。实际上，这意味着“世界其他地区”。因此，这也称为世界的权限。

Linux区分这三种用户类型，以防止用户访问，编辑或删除他们不应该更改的文件。阅读有关文件和文件夹所有权的更多信息。

权限和所有权设置对于确保服务器和Mautic实例的安全性至关重要，因此正确设置它们非常重要！如果您的文件没有适当的权限，则黑客可以更轻松地入侵您的文件并获得对Mautic实例的访问权限。正确设置文件许可权可能不会使您免受所有攻击，但是它将有助于使Mautic实例更安全。

为什么权限问题会导致Mautic错误？

Mautic需要访问Mautic目录中的读写文件，以使某些功能和脚本能够运行。如果权限设置不正确，或者尝试运行权限的用户没有正确的访问权限，则Mautic将无法运行，并且您将在应用程序和服务器日志中看到错误。

权限和所有权问题通常是由于以下原因而发生的：

• 您已经以与Mautic用来运行的用户不同的用户身份上传了Mautic或对文件和文件夹进行了更改-例如，您使用用户名“ user”的FTP帐户上传了文件，但您的Web服务器以用户“ www-data”。
• Mautic用于运行的用户对文件和文件夹没有适当的权限-例如，“用户”无法创建目录或读取文件
• 已以与Mautic用来运行的用户不同的用户身份运行更新-导致某些文件和文件夹的所有权发生了更改

如何解决Mautic中与权限相关的问题

重置文件和文件夹的权限需要在命令行中运行一些命令。您将需要具有对服务器的SSH访问权限，或要求其他人为您执行这些命令。如果这成为您的持续问题，某些托管服务提供商可能能够创建脚本以定期重置权限。

提供cPanel访问的托管提供商的解决方案

用于修复cPanel帐户的文件和目录上的权限和所有权的脚本。您可以要求托管服务提供商运行该脚本，以将权限重置为正确的值。这个方便的脚本可以在这里找到：GitHub -PeachFlame / cPanel-fixperms

找出问题

使用SSH登录到服务器，然后使用以下命令切换到Mautic目录

cd path/to/mautic

在此目录中，执行以下命令：

ls -l

该ls命令将列出文件和目录。它具有-l选项，该选项以长格式列出内容，包括其权限和所有权以及其他信息。

有关所有信息含义的更详细说明，请查看本文。

我们正在寻找的关键信息在第一，第三和第四栏中-权限以及拥有文件/文件夹的用户和组。

重置文件和文件夹权限

如果您的文件和文件夹权限不正确，则可以运行以下命令来重置它们：

find . -type f -not -perm 644 -exec chmod 644 {} +
find . -type d -not -perm 644 -exec chmod 755 {} +
chmod -R g+w var/cache/ var/logs/ app/config/
chmod -R g+w media/files/ media/images/ translations/
rm -rf var/cache/*

更改文件和文件夹的所有权
如果您的文件和文件夹由错误的用户拥有，即使拥有正确的文件和文件夹权限，您仍将继续遇到错误。这是因为用户可能没有所需的权限（因为他们不是文件/文件夹的所有者）。阅读有关文件和文件夹所有权的更多信息

# 要找出以哪个用户身份运行Apache，请执行以下命令并记下返回行中的第一个条目：
ps aux | grep apache2
# 使用此信息通过以下命令查找组
groups apache_user （其中apache_user是您从上述第一步确定的用户）
# 要重置文件和文件夹的所有权，请使用以下命令（确保将apache_user和apache_group替换为上述步骤中标识的值）：
sudo chown -R apache_user:apache_group

此命令chown，使用-R标志，这意味着递归-包括该位置内的所有文件/文件夹。阅读有关chown命令的更多信息