README

Queue-Fair for Magento 适配器 README & 安装指南

Queue-Fair 可以在几分钟内轻松添加到任何 Magento 安装中。您需要一个 Queue-Fair 账号 - 如果您还没有，请访问 https://queue-fair.com/free-trial。您还应收到我们的技术指南。您可以在 https://queue-fair.com 上了解有关 Queue-Fair 的所有信息。

客户端 JavaScript 适配器

我们的大部分客户更喜欢使用客户端 JavaScript 适配器，这对于所有只想防止过载的网站都适用。

要将 Queue-Fair 客户端 JavaScript 适配器添加到您的 Magento 安装中，您不需要此扩展中包含的 PHP 文件。

相反，执行以下步骤

以管理员身份登录到您的 Magento 安装
从左侧导航选择内容 -> 配置
要添加适配器到您的 Magento 网站上的所有页面，请点击全局记录的编辑
在其他设置中，展开 HTML Head
在脚本和样式表中，复制并粘贴以下代码行

<script data-queue-fair-client="CLIENT_NAME" src="https://files.queue-fair.net/queue-fair-adapter.js"></script>`

将 CLIENT_NAME 替换为 Queue-Fair 门户中“账户 -> 您的账户”页面可见的账户系统名称
保存配置
提示时清除缓存

刷新页面后，您现在应该能够在查看源代码后看到适配器标签。

您可以在 https://magefan.com/blog/how-to-add-custom-code-in-html-head 上看到这些步骤的操作视频。

完成！您现在可以在 Queue-Fair 门户中配置队列和激活规则。

服务器端适配器

服务器端适配器意味着您的 Magento 服务器直接与 Queue-Fair 服务器通信，而不是与您的访客的浏览器通信。

这可能在我们的系统之间引入依赖关系，这就是为什么大多数客户更喜欢客户端适配器。

在以下用例中首选服务器端适配器

当您有技术熟练的访客或价值高且数量有限的商品，并且人们可能会尝试跳过队列时，或者
当预计您的 web 服务器无法处理您的主页或着陆页的流量，并且您无法或不能使用直接链接集成方法（请参阅技术指南）时。

服务器端适配器是一个小的 PHP 库，当访客访问您的网站时将运行。它定期检查您是否在门户中更改了 Queue-Fair 设置，但除此之外，如果访客请求的页面不符合任何队列的激活规则，它将不执行任何操作。

如果访客请求的页面确实符合任何队列的激活规则，适配器将确定该特定访客是否应该排队。如果是这样，访客将被发送到我们的队列服务器，并且将停止对那个访客的 HTTP 请求执行和生成页面。如果适配器确定该访客不应该排队，它将设置一个 cookie 来指示该访客已被处理，并且您的页面将正常执行和显示。

因此，服务器端适配器通过禁用客户端JavaScript适配器来阻止访客跳过队列，并在繁忙时减少您的Magento服务器的负载。

运行服务器端适配器需要PHP版本5.4或更高。

以下是安装的每个按键。

1. 创建一个可读、可写和可执行的文件夹，以便可以本地保存队列公平设置（这对于您的网站在负载下的性能是必要的）

    sudo mkdir /opt/qfsettings    
    sudo chmod 777 /opt/qfsettings

注意：设置文件夹可以放在任何地方，但为了最大安全性，这个文件夹不应放在您的网站根目录中。文件夹需要可执行权限，以便适配器可以检查其内容。您可以在门户文件管理器中查看队列公平设置 - 当您点击“使实时”时，它们会更新。

2. 重要：确保您的网站服务器的系统时钟准确设置为网络时间！在Unix系统上，这通常是通过使用ntp软件包完成的。您使用的时区无关紧要。对于Debian/Ubuntu

    sudo apt-get install ntp

3. 前往您的Magento安装

    cd /path/to/magento

4. 将服务器端扩展添加到您的composer需求中

    composer require queue-fair/magadapter --no-update

5. 更新composer

    composer update

这将创建一个新的文件夹 /path/to/magento/vendor/queue-fair/magadapter

6. 接下来，编辑 vendor/queue-fair/magadapter/QueueFairConfig.php

    nano vendor/queue-fair/magadapter/QueueFairConfig.php

7. 在 QueueFairConfig.php 的顶部设置您的账户名称和账户密钥，以匹配队列公平门户“您的账户”页面上的账户系统名称和账户密钥。

8. 将 settingsFileCacheLocation 更改为匹配您创建的设置文件夹的文件夹路径。

9. 注意 settingsFileCacheLifetimeMinutes 设置 - 这是您的网站服务器多久会检查一次来自队列公平队列服务器的更新设置（当您点击“使实时”时，这些设置会更改）。默认值是5分钟。您可以将其设置为-1来禁用本地缓存，但在您的生产机器/实时队列中，请勿这样做，否则您的服务器可能会因负载而崩溃。

10. 注意 adapterMode 设置。建议使用“safe”，我们还支持“simple” - 请参阅技术指南以获取更多信息。

11. 重要注意 debug 设置 - 默认情况下，此设置为true，但您必须在生产机器/实时队列上将其设置为false，否则您的网站日志将迅速填满。您可以将它设置为单个IP地址，以便在生产机器上仅输出单个访客的调试信息。

调试日志语句将出现在php设置的输出错误信息信息的文件中。如果您使用Apache，它将出现在apache错误日志中，您可以使用以下方式查看消息

    sudo tail -f /var/log/apache2/error.log | sed 's/\\n/\n/g'

12. 当您完成对 QueueFairConfig.php 的更改后，按 CTRL-O 保存，按 CTRL-X 退出nano。

要使适配器实际运行，您需要编辑主Magento index.php文件。在编辑之前，请确保创建index.php文件的备份副本。

    nano /path/to/magento/pub/index.php

并在 <?php 标签之后，第二行添加

if(strpos($_SERVER["REQUEST_URI"],"/rest/") === false && strpos($_SERVER["REQUEST_URI"],"/ajax/") === false) { 
    require_once "../vendor/queue-fair/magadapter/QueueFairConfig.php";
    require_once "../vendor/queue-fair/magadapter/QueueFairAdapter.php";
    
    $queueFair = new QueueFair\Adapter\QueueFairAdapter(new QueueFair\Adapter\QueueFairConfig());
    
    $queueFair->requestedURL = (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? "https://" : "http://")
        .$_SERVER["HTTP_HOST"].$_SERVER["REQUEST_URI"];
    $queueFair->query = $_SERVER["QUERY_STRING"];
    $queueFair->remoteAddr = $_SERVER["REMOTE_ADDR"];
    $queueFair->userAgent = $_SERVER["HTTP_USER_AGENT"];
    $queueFair->cookies = $_COOKIE;
    
    if(!$queueFair->go()) {
        exit();
    }
    unset($queueFair);
}

这将确保当访客访问任何页面时，适配器是首先运行的，这既是保护服务器免受大量访客的负载，也是为了让适配器设置必要的cookie。然后，您可以使用门户中的激活规则来设置哪些页面可能触发队列。

if语句阻止适配器在后台Magento AJAX和RestAPI调用上运行 - 您真的只想在页面请求上运行适配器。

在适配器将请求发送到其他地方（例如显示用户队列页面）的情况下，go() 方法将返回 false，页面的其余部分将不会生成，这意味着它不会发送到访客的浏览器，这使得它更加安全，同时防止您的服务器执行生成页面其余部分的工作。重要的是，此代码必须在 Magento 框架初始化之前运行，以便您的服务器可以在负载下执行此操作，当完整 Magento 框架加载过于繁重时。

注意：如果您的 Magento 服务器位于代理、CDN 或负载均衡器后面，您可能需要编辑上述段落的属性集，以使用转发头中的值。如果您需要帮助，请联系 Queue-Fair 支持。

重要与仅在运行 JavaScript 的浏览器中运行，并且仅在请求包含适配器标签的页面 URL 的浏览器中运行的 JavaScript 客户端适配器不同，服务器端适配器可能在每个请求上运行。这意味着如果您有自动化的系统调用您的网站上的 API 或回调 URL（如支付网关），并且您的激活规则匹配这些 URL，那么在忙碌时它们也会被排队，这可能会产生不利影响。我们建议您在代码的逻辑中排除 API 或回调 URL - 您也可以使用激活规则来实现这一点。

按 CTRL-O 保存，按 CTRL-X 退出 nano。您还应在修改 index.php 文件后进行备份，以防它被未来的任何更新覆盖。

这就完成了！

要测试服务器端适配器

使用不在其他页面上使用的队列，或者为测试创建一个新队列。

测试 SafeGuard

设置一个激活规则以匹配您想要测试的页面。点击“使实时”。转到队列的设置页面。将其置于 SafeGuard 模式。再次点击“使实时”。

在一个新的私密浏览窗口中，访问您网站上的页面。

验证您是否可以在错误日志中看到适配器的调试输出。
验证是否已创建名为 Queue-Fair-Pass-queuename 的 cookie，其中 queuename 是您队列的系统名称
如果适配器处于安全模式，还验证是否已创建名为 QueueFair-Store-accountname 的 cookie，其中 accountname 是您账户的系统名称（在门户的“您的账户”页面上）。
如果适配器处于简单模式，则不会创建 Queue-Fair-Store cookie。
点击刷新。验证 cookie 的值没有更改。

测试队列

返回到门户，并在队列设置页面将队列置于演示模式。点击“使实时”。从您的浏览器中删除任何 Queue-Fair-Pass cookie。在新标签页中，访问 https://accountname.queue-fair.net ，并删除任何出现的 Queue-Fair-Pass 或 Queue-Fair-Data cookie。刷新您访问的网站页面。

验证您现在被发送到队列。
当您从队列返回到页面时，验证是否已创建新的 QueueFair-Pass-queuename cookie。
如果适配器处于安全模式，还验证 QueueFair-Store cookie 的值没有更改。
点击刷新。验证您没有再次排队。验证 cookie 的值没有更改。

重要：一旦您确认服务器端适配器按预期工作，请从您的页面上删除客户端 JavaScript 适配器标签，并不要忘记在 QueueFairConfig.php 中禁用调试级别的日志记录，并将 settingsFileCacheLifetimeMinutes 设置为至少 5。

为了最大的安全性

服务器端适配器包含多项检查，以防止访客绕过队列，无论是通过篡改设置的cookie值或查询字符串，还是通过相互分享这些信息。当检测到篡改时，访客将被视为新访客，如果有人排队，将被发送到队列的末尾。

服务器端适配器会检查浏览器提供的已通过cookie和已通过字符串是否由我们的队列服务器签名。它使用每个队列设置页面上的可见密钥来完成此操作。
如果您更改队列密钥，这将使所有人的cookie无效，并导致排队的任何人失去位置，所以请谨慎修改！
服务器端适配器还会检查从我们的队列服务器到您的Web服务器发送的已通过字符串是否在最后300秒内产生，这也是为什么您的时钟必须设置准确的原因。
服务器端适配器还会检查已通过的cookie是否在队列设置页面上的已通过有效期限制内产生，以防止访客通过篡改cookie过期时间或共享cookie值来作弊。因此，已通过有效期应该设置得足够长，以便访客完成他们的交易，同时为那些速度较慢的访客留出余地，但不要过长。
签名还包括访客的USER_AGENT，以进一步防止访客共享cookie值。

最后

所有客户端可修改的设置都在QueueFairConfig.php中。您永远不应该需要修改QueueFairAdapter.php - 但如果出现问题，请立即联系support@queue-fair.com，以便我们讨论您的需求。

请记住，我们在这里帮助您！集成过程不应超过一小时 - 所以如果您感到困惑，请向我们询问。许多答案也包含在技术指南中。我们总是乐意帮助！

queue-fair / magentoadapter

维护者

详情