Laravel Horizon

介绍
安装
升级 Horizon
运行 Horizon
- 部署 Horizon
标签
通知
指标
删除失败的作业
从队列中清除作业

介绍

NOTE

在深入了解 Laravel Horizon 之前，您应该熟悉 Laravel 的基本队列服务。Horizon 增强了 Laravel 的队列，提供了额外的功能，如果您尚未熟悉 Laravel 提供的基本队列功能，可能会感到困惑。

Laravel Horizon 提供了一个美观的仪表板和基于代码的配置，用于您的 Laravel 驱动的 Redis 队列。Horizon 使您能够轻松监控队列系统的关键指标，例如作业吞吐量、运行时间和作业失败。

使用 Horizon 时，所有队列工作者的配置都存储在一个简单的配置文件中。通过在版本控制文件中定义应用程序的工作者配置，您可以在部署应用程序时轻松扩展或修改应用程序的队列工作者。

安装

WARNING

Laravel Horizon 要求您使用 Redis 来驱动您的队列。因此，您应该确保在应用程序的 config/queue.php 配置文件中将队列连接设置为 redis。

您可以使用 Composer 包管理器将 Horizon 安装到您的项目中：

shell

composer require laravel/horizon

安装 Horizon 后，使用 horizon:install Artisan 命令发布其资产：

shell

php artisan horizon:install

配置

发布 Horizon 的资产后，其主要配置文件将位于 config/horizon.php。此配置文件允许您配置应用程序的队列工作者选项。每个配置选项都包含其目的的描述，因此请务必仔细查看此文件。

WARNING

Horizon 在内部使用名为 horizon 的 Redis 连接。此 Redis 连接名称是保留的，不应在 database.php 配置文件中分配给另一个 Redis 连接，或作为 horizon.php 配置文件中 use 选项的值。

环境

安装后，您应该熟悉的主要 Horizon 配置选项是 environments 配置选项。此配置选项是一个数组，定义了您的应用程序运行的环境，并为每个环境定义工作进程选项。默认情况下，此条目包含 production 和 local 环境。但是，您可以根据需要添加更多环境：

php

'environments' => [
    'production' => [
        'supervisor-1' => [
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

您还可以定义一个通配符环境 (*)，当没有找到其他匹配环境时将使用该环境：

php

'environments' => [
    // ...

    '*' => [
        'supervisor-1' => [
            'maxProcesses' => 3,
        ],
    ],
],

当您启动 Horizon 时，它将使用您的应用程序正在运行的环境的工作进程配置选项。通常，环境是由 APP_ENV 环境变量的值确定的。例如，默认的 local Horizon 环境配置为启动三个工作进程，并自动平衡分配给每个队列的工作进程数量。默认的 production 环境配置为启动最多 10 个工作进程，并自动平衡分配给每个队列的工作进程数量。

WARNING

您应该确保 horizon 配置文件的 environments 部分包含您计划运行 Horizon 的每个环境的条目。

监视器

正如您在 Horizon 的默认配置文件中看到的，每个环境可以包含一个或多个“监视器”。默认情况下，配置文件将此监视器定义为 supervisor-1；但是，您可以自由地将监视器命名为您想要的任何名称。每个监视器负责“监视”一组工作进程，并负责在队列之间平衡工作进程。

如果您希望为特定队列定义不同的平衡策略或工作进程数量，您可以在给定环境中添加额外的监视器，以定义一组新的工作进程。

维护模式

当您的应用程序处于维护模式时，Horizon 将不会处理排队的作业，除非监视器的 force 选项在 Horizon 配置文件中定义为 true：

php

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'force' => true,
        ],
    ],
],

默认值

在 Horizon 的默认配置文件中，您会注意到一个 defaults 配置选项。此配置选项指定了您应用程序的监视器的默认值。监视器的默认配置值将合并到每个环境的监视器配置中，从而避免在定义监视器时不必要的重复。

平衡策略

与 Laravel 的默认队列系统不同，Horizon 允许您选择三种工作平衡策略：simple、auto 和 false。simple 策略将传入的作业均匀分配给工作进程：

php

'balance' => 'simple',

auto 策略是配置文件的默认值，根据队列的当前工作负载调整每个队列的工作进程数量。例如，如果您的 notifications 队列有 1,000 个待处理作业，而您的 render 队列为空，Horizon 将为您的 notifications 队列分配更多的工作进程，直到队列为空。

使用 auto 策略时，您可以定义 minProcesses 和 maxProcesses 配置选项，以控制每个队列的最小进程数和 Horizon 应该扩展和收缩的最大工作进程总数：

php

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'auto',
            'autoScalingStrategy' => 'time',
            'minProcesses' => 1,
            'maxProcesses' => 10,
            'balanceMaxShift' => 1,
            'balanceCooldown' => 3,
            'tries' => 3,
        ],
    ],
],

autoScalingStrategy 配置值决定了 Horizon 是否根据清空队列所需的总时间（time 策略）或队列中的作业总数（size 策略）为队列分配更多的工作进程。

balanceMaxShift 和 balanceCooldown 配置值决定了 Horizon 满足工作需求的速度。在上面的示例中，每三秒最多创建或销毁一个新进程。您可以根据应用程序的需要自由调整这些值。

当 balance 选项设置为 false 时，将使用默认的 Laravel 行为，其中队列按配置中列出的顺序处理。

仪表板授权

Horizon 仪表板可以通过 /horizon 路由访问。默认情况下，您只能在 local 环境中访问此仪表板。然而，在您的 app/Providers/HorizonServiceProvider.php 文件中，有一个授权网关定义。此授权网关控制在 非本地 环境中对 Horizon 的访问。您可以根据需要修改此网关，以限制对您的 Horizon 安装的访问：

php

/**
 * 注册 Horizon 网关。
 *
 * 此网关确定谁可以在非本地环境中访问 Horizon。
 */
protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

替代认证策略

请记住，Laravel 会自动将经过身份验证的用户注入到网关闭包中。如果您的应用程序通过其他方法提供 Horizon 安全性，例如 IP 限制，则您的 Horizon 用户可能不需要“登录”。因此，您需要将上面的 function (User $user) 闭包签名更改为 function (User $user = null)，以强制 Laravel 不要求身份验证。

静默作业

有时，您可能对应用程序或第三方包调度的某些作业不感兴趣。为了避免这些作业占用“已完成作业”列表中的空间，您可以将它们静默。要开始，请将作业的类名添加到您应用程序的 horizon 配置文件中的 silenced 配置选项中：

php

'silenced' => [
    App\Jobs\ProcessPodcast::class,
],

或者，您希望静默的作业可以实现 Laravel\Horizon\Contracts\Silenced 接口。如果作业实现了此接口，即使它不在 silenced 配置数组中，也会自动被静默：

php

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;

    // ...
}

升级 Horizon

在升级到 Horizon 的新主要版本时，重要的是您要仔细查看升级指南。

运行 Horizon

一旦您在应用程序的 config/horizon.php 配置文件中配置了监视器和工作者，您可以使用 horizon Artisan 命令启动 Horizon。此单个命令将启动当前环境中所有配置的工作进程：

shell

php artisan horizon

您可以使用 horizon:pause 和 horizon:continue Artisan 命令暂停 Horizon 进程并指示其继续处理作业：

shell

php artisan horizon:pause

php artisan horizon:continue

您还可以使用 horizon:pause-supervisor 和 horizon:continue-supervisor Artisan 命令暂停和继续特定的 Horizon 监视器：

shell

php artisan horizon:pause-supervisor supervisor-1

php artisan horizon:continue-supervisor supervisor-1

您可以使用 horizon:status Artisan 命令检查 Horizon 进程的当前状态：

shell

php artisan horizon:status

您可以使用 horizon:supervisor-status Artisan 命令检查特定 Horizon 监视器的当前状态：

shell

php artisan horizon:supervisor-status supervisor-1

您可以使用 horizon:terminate Artisan 命令优雅地终止 Horizon 进程。任何当前正在处理的作业将完成，然后 Horizon 将停止执行：

shell

php artisan horizon:terminate

部署 Horizon

当您准备将 Horizon 部署到应用程序的实际服务器时，您应该配置一个进程监视器来监视 php artisan horizon 命令，并在其意外退出时重新启动它。别担心，我们将在下面讨论如何安装进程监视器。

在应用程序的部署过程中，您应该指示 Horizon 进程终止，以便它将由您的进程监视器重新启动并接收您的代码更改：

shell

php artisan horizon:terminate

安装监视器

Supervisor 是 Linux 操作系统的进程监视器，如果 horizon 进程停止执行，它将自动重新启动。要在 Ubuntu 上安装 Supervisor，您可以使用以下命令。如果您不是使用 Ubuntu，您可以使用操作系统的包管理器安装 Supervisor：

shell

sudo apt-get install supervisor

NOTE

如果自己配置 Supervisor 听起来令人不知所措，请考虑使用 Laravel Forge，它将自动为您的 Laravel 项目安装和配置 Supervisor。

监视器配置

监视器配置文件通常存储在服务器的 /etc/supervisor/conf.d 目录中。在此目录中，您可以创建任意数量的配置文件，指示监视器如何监视您的进程。例如，让我们创建一个 horizon.conf 文件来启动和监视一个 horizon 进程：

ini

[program:horizon]
process_name=%(program_name)s
command=php /home/forge/example.com/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/home/forge/example.com/horizon.log
stopwaitsecs=3600

在定义您的监视器配置时，您应该确保 stopwaitsecs 的值大于您最长运行的作业所消耗的秒数。否则，监视器可能会在作业完成处理之前终止作业。

WARNING

虽然上面的示例对于基于 Ubuntu 的服务器是有效的，但监视器配置文件的预期位置和文件扩展名可能因其他服务器操作系统而异。请查阅您服务器的文档以获取更多信息。

启动监视器

创建配置文件后，您可以使用以下命令更新监视器配置并启动监视的进程：

shell

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start horizon

NOTE

有关运行监视器的更多信息，请查阅监视器文档。

<?php

namespace App\Jobs;

use App\Models\Video;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class RenderVideo implements ShouldQueue
{
    use Queueable;

    /**
     * 创建一个新的作业实例。
     */
    public function __construct(
        public Video $video,
    ) {}

    /**
     * 执行作业。
     */
    public function handle(): void
    {
        // ...
    }
}

如果此作业与具有 id 属性为 1 的 App\Models\Video 实例一起排队，它将自动接收标签 App\Models\Video:1。这是因为 Horizon 将搜索作业的属性以查找任何 Eloquent 模型。如果找到 Eloquent 模型，Horizon 将使用模型的类名和主键智能地标记作业：

php

use App\Jobs\RenderVideo;
use App\Models\Video;

$video = Video::find(1);

RenderVideo::dispatch($video);

手动标记作业

如果您希望手动定义队列对象的标签，您可以在类上定义一个 tags 方法：

php

class RenderVideo implements ShouldQueue
{
    /**
     * 获取应分配给作业的标签。
     *
     * @return array<int, string>
     */
    public function tags(): array
    {
        return ['render', 'video:'.$this->video->id];
    }
}

手动标记事件监听器

在检索排队事件监听器的标签时，Horizon 将自动将事件实例传递给 tags 方法，允许您将事件数据添加到标签中：

php

class SendRenderNotifications implements ShouldQueue
{
    /**
     * 获取应分配给监听器的标签。
     *
     * @return array<int, string>
     */
    public function tags(VideoRendered $event): array
    {
        return ['video:'.$event->video->id];
    }
}

通知

WARNING

在配置 Horizon 以发送 Slack 或 SMS 通知时，您应该查看相关通知通道的先决条件。

如果您希望在队列等待时间过长时收到通知，您可以使用 Horizon::routeMailNotificationsTo、Horizon::routeSlackNotificationsTo 和 Horizon::routeSmsNotificationsTo 方法。您可以在应用程序的 App\Providers\HorizonServiceProvider 的 boot 方法中调用这些方法：

php

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    parent::boot();

    Horizon::routeSmsNotificationsTo('15556667777');
    Horizon::routeMailNotificationsTo('example@example.com');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#channel');
}

配置通知等待时间阈值

您可以在应用程序的 config/horizon.php 配置文件中配置多少秒被视为“长等待”。此文件中的 waits 配置选项允许您控制每个连接/队列组合的长等待阈值。任何未定义的连接/队列组合将默认为 60 秒的长等待阈值：

php

'waits' => [
    'redis:critical' => 30,
    'redis:default' => 60,
    'redis:batch' => 120,
],

指标

Horizon 包含一个指标仪表板，提供有关您的作业和队列等待时间及吞吐量的信息。为了填充此仪表板，您应该在应用程序的 routes/console.php 文件中配置 Horizon 的 snapshot Artisan 命令每五分钟运行一次：

php

use Illuminate\Support\Facades\Schedule;

Schedule::command('horizon:snapshot')->everyFiveMinutes();

删除失败的作业

如果您希望删除失败的作业，可以使用 horizon:forget 命令。horizon:forget 命令接受失败作业的 ID 或 UUID 作为其唯一参数：

shell

php artisan horizon:forget 5

如果您希望删除所有失败的作业，可以向 horizon:forget 命令提供 --all 选项：

shell

php artisan horizon:forget --all

从队列中清除作业

如果您希望删除应用程序默认队列中的所有作业，可以使用 horizon:clear Artisan 命令：

shell

php artisan horizon:clear

您可以提供 queue 选项以删除特定队列中的作业：

shell

php artisan horizon:clear --queue=emails

Laravel Horizon ​

介绍 ​

安装 ​

配置 ​

环境 ​

监视器 ​

维护模式 ​

默认值 ​

平衡策略 ​

仪表板授权 ​

替代认证策略 ​

静默作业 ​

升级 Horizon ​

运行 Horizon ​

部署 Horizon ​

安装监视器 ​

监视器配置 ​

启动监视器 ​

标签 ​

手动标记作业 ​

手动标记事件监听器 ​

通知 ​

配置通知等待时间阈值 ​

指标 ​

删除失败的作业 ​

从队列中清除作业 ​

Laravel Horizon

介绍

安装

配置

环境

监视器

维护模式

默认值

平衡策略

仪表板授权

替代认证策略

静默作业

升级 Horizon

运行 Horizon

部署 Horizon

安装监视器

监视器配置

启动监视器

标签

手动标记作业

手动标记事件监听器

通知

配置通知等待时间阈值

指标

删除失败的作业

从队列中清除作业