Laravel Horizon
简介
NOTE
在深入探讨 Laravel Horizon 之前，你应该先熟悉 Laravel 的基础队列服务。Horizon 为 Laravel 的队列增加了额外的功能，如果你还不熟悉 Laravel 提供的基本队列功能，可能会感到困惑。
Laravel Horizon 为你的基于 Redis 队列的 Laravel 应用提供了一个漂亮的仪表板和代码驱动的配置。Horizon 让你可以轻松监控队列系统的关键指标，如任务吞吐量、运行时间和任务失败情况。
使用 Horizon 时，你所有的队列工作器配置都存储在一个简单配置文件中。通过在版本控制文件中定义应用的工作器配置，你可以在部署应用时轻松扩展或修改应用的队列工作器。
安装
WARNING
Laravel Horizon 要求你使用 Redis 来驱动队列。因此，你应该确保在应用的 config/queue.php 配置文件中，队列连接设置为 redis。Horizon 目前不兼容 Redis 集群。
你可以使用 Composer 包管理器将 Horizon 安装到你的项目中：
composer require laravel/horizon安装 Horizon 后，使用 horizon:install Artisan 命令发布其资源：
php artisan horizon:install配置
发布 Horizon 的资源后，其主配置文件将位于 config/horizon.php。此配置文件允许你配置应用的队列工作器选项。每个配置选项都包含了其用途的说明，所以请务必仔细浏览此文件。
WARNING
Horizon 内部使用名为 horizon 的 Redis 连接。此 Redis 连接名称是保留的，不应在 database.php 配置文件中分配给另一个 Redis 连接，也不应作为 horizon.php 配置文件中 use 选项的值。
环境
安装后，你应该熟悉的主要 Horizon 配置选项是 environments 配置选项。此配置选项是一个数组，包含应用运行的环境，并为每个环境定义了工作器进程选项。默认情况下，此项包含 production 和 local 环境。但你可以根据需要添加更多环境：
'environments' => [
'production' => [
'supervisor-1' => [
'maxProcesses' => 10,
'balanceMaxShift' => 1,
'balanceCooldown' => 3,
],
],
'local' => [
'supervisor-1' => [
'maxProcesses' => 3,
],
],
],你也可以定义一个通配符环境 (*)，当找不到其他匹配的环境时将使用此环境：
'environments' => [
// ...
'*' => [
'supervisor-1' => [
'maxProcesses' => 3,
],
],
],当你启动 Horizon 时，它将使用应用运行所在环境的工作器进程配置选项。通常，环境由 APP_ENV 环境变量的值决定。例如，默认的 local Horizon 环境配置为启动三个工作器进程，并自动平衡分配给每个队列的工作器进程数量。默认的 production 环境配置为最多启动 10 个工作器进程，并自动平衡分配给每个队列的工作器进程数量。
WARNING
你应该确保 horizon 配置文件的 environments 部分包含了你计划运行 Horizon 的每个环境的条目。
主管
正如你在 Horizon 的默认配置文件中看到的，每个环境可以包含一个或多个“主管”。默认情况下，配置文件将这个主管定义为 supervisor-1；但是，你可以随意命名你的主管。每个主管基本上负责“监督”一组工作器进程，并负责平衡队列间的工作器进程。
如果你希望在一个环境中定义一组新的工作器进程，可以向该环境添加额外的主管。如果你想为应用使用的某个队列定义不同的平衡策略或工作器进程数量，你可以选择这样做。
维护模式
当你的应用处于维护模式时，队列任务将不会被 Horizon 处理，除非主管的 force 选项在 Horizon 配置文件中定义为 true：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'force' => true,
],
],
],默认值
在 Horizon 的默认配置文件中，你会注意到一个 defaults 配置选项。此配置选项为你的应用的主管指定了默认值。主管的默认配置值将与每个环境的主管配置合并，从而在定义主管时避免不必要的重复。
仪表板授权
Horizon 仪表板可以通过 /horizon 路由访问。默认情况下，你只能在 local 环境中访问此仪表板。但是，在你的 app/Providers/HorizonServiceProvider.php 文件中，有一个授权门卫的定义。此授权门卫控制在非本地环境中对 Horizon 的访问。你可以根据需要修改此门卫，以限制对 Horizon 安装的访问：
/**
* 注册 Horizon 门卫。
*
* 此门卫决定谁可以在非本地环境中访问 Horizon。
*/
protected function gate(): void
{
Gate::define('viewHorizon', function (User $user) {
return in_array($user->email, [
'taylor@laravel.com',
]);
});
}备用认证策略
请记住，Laravel 会自动将已认证用户注入到门卫闭包中。如果你的应用通过其他方法（如 IP 限制）提供 Horizon 安全性，那么你的 Horizon 用户可能不需要“登录”。因此，你需要将上面的 function (User $user) 闭包签名改为 function (User $user = null)，以强制 Laravel 不要求认证。
最大任务尝试次数
NOTE
在优化这些选项之前，请确保你熟悉 Laravel 默认的队列服务以及“尝试次数”的概念。
你可以在主管配置中定义任务可以消耗的最大尝试次数：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'tries' => 10,
],
],
],NOTE
此选项类似于使用 Artisan 命令处理队列时的 --tries 选项。
当使用诸如 WithoutOverlapping 或 RateLimited 之类的中间件时，调整 tries 选项至关重要，因为它们会消耗尝试次数。要处理此问题，可以在主管级别调整 tries 配置值，或者在任务类上定义 $tries 属性。
如果你没有设置 tries 选项，Horizon 默认为单次尝试，除非任务类定义了 $tries，此时任务类的设置优先于 Horizon 配置。
将 tries 或 $tries 设置为 0 允许无限次尝试，这在尝试次数不确定时是理想的。为了防止无休止的失败，你可以通过设置任务类的 $maxExceptions 属性来限制允许的异常数量。
任务超时
同样，你可以在主管级别设置一个 timeout 值，该值指定工作器进程在任务被强制终止之前可以运行多长时间。一旦终止，任务将根据你的队列配置被重试或标记为失败：
'environments' => [
'production' => [
'supervisor-1' => [
// ...¨
'timeout' => 60,
],
],
],WARNING
当使用 auto 平衡策略时，Horizon 会将进行中的工作器视为“挂起”，并在缩容期间根据 Horizon 超时将其强制终止。始终确保 Horizon 超时大于任何任务级别的超时，否则任务可能会在执行过程中被终止。此外，timeout 值应始终比 config/queue.php 配置文件中定义的 retry_after 值至少短几秒。否则，你的任务可能会被处理两次。
任务退避
你可以在主管级别定义 backoff 值，以指定 Horizon 在重试遇到未处理异常的任务之前应等待多长时间：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'backoff' => 10,
],
],
],你也可以通过为 backoff 值使用数组来配置“指数”退避。在此示例中，第一次重试的延迟为 1 秒，第二次重试为 5 秒，第三次重试为 10 秒，如果还有更多尝试，后续每次重试也为 10 秒：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'backoff' => [1, 5, 10],
],
],
],静默任务
有时，你可能对查看应用或第三方包分发的某些任务不感兴趣。为了让它们不占用你的“已完成任务”列表中的空间，你可以将它们静默。首先，将任务的类名添加到应用 horizon 配置文件中的 silenced 配置选项：
'silenced' => [
App\Jobs\ProcessPodcast::class,
],除了静默单个任务类之外，Horizon 还支持根据标签静默任务。如果你想隐藏共享公共标签的多个任务，这将非常有用：
'silenced_tags' => [
'notifications'
],或者，你想要静默的任务可以实现 Laravel\Horizon\Contracts\Silenced 接口。如果某个任务实现了此接口，它将自动被静默，即使它不在 silenced 配置数组中：
use Laravel\Horizon\Contracts\Silenced;
class ProcessPodcast implements ShouldQueue, Silenced
{
use Queueable;
// ...
}平衡策略
每个主管可以处理一个或多个队列，但与 Laravel 的默认队列系统不同，Horizon 允许你从三种工作器平衡策略中进行选择：auto、simple 和 false。
自动平衡
auto 策略（默认策略）根据队列的当前工作负载调整每个队列的工作器进程数量。例如，如果你的 notifications 队列有 1000 个待处理任务，而 default 队列为空，Horizon 将分配更多工作器给你的 notifications 队列，直到该队列为空。
使用 auto 策略时，你还可以配置 minProcesses 和 maxProcesses 配置选项：
minProcesses定义每个队列的最小工作器进程数。此值必须大于或等于 1。maxProcesses定义 Horizon 在所有队列中可扩展到的最大工作器进程总数。此值通常应大于队列数乘以minProcesses值。要防止主管生成任何进程，可以将此值设置为 0。
例如，你可以配置 Horizon 为每个队列至少维护一个进程，并扩展到总共 10 个工作器进程：
'environments' => [
'production' => [
'supervisor-1' => [
'connection' => 'redis',
'queue' => ['default', 'notifications'],
'balance' => 'auto',
'autoScalingStrategy' => 'time',
'minProcesses' => 1,
'maxProcesses' => 10,
'balanceMaxShift' => 1,
'balanceCooldown' => 3,
],
],
],autoScalingStrategy 配置选项决定 Horizon 如何为队列分配更多工作器进程。你可以在两种策略之间进行选择：
time策略将根据清空队列所需的总估计时间来分配工作器。size策略将根据队列上的任务总数来分配工作器。
balanceMaxShift 和 balanceCooldown 配置值决定 Horizon 扩展以满足工作器需求的速度。在上面的示例中，每三秒最多创建或销毁一个新进程。你可以根据应用的需要自由调整这些值。
队列优先级和自动平衡
使用 auto 平衡策略时，Horizon 不会强制队列之间的严格优先级。主管配置中的队列顺序不会影响工作器进程的分配方式。相反，Horizon 依赖于选定的 autoScalingStrategy 来根据队列负载动态分配工作器进程。
例如，在以下配置中，尽管 high 队列在列表中排在第一位，但它并不会优先于 default 队列：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'queue' => ['high', 'default'],
'minProcesses' => 1,
'maxProcesses' => 10,
],
],
],如果你需要在队列之间强制执行相对优先级，你可以定义多个主管并显式分配处理资源：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'queue' => ['default'],
'minProcesses' => 1,
'maxProcesses' => 10,
],
'supervisor-2' => [
// ...
'queue' => ['images'],
'minProcesses' => 1,
'maxProcesses' => 1,
],
],
],在此示例中，默认的 queue 可以扩展到最多 10 个进程，而 images 队列限制为一个进程。此配置确保你的队列可以独立扩展。
NOTE
在分发资源密集型任务时，有时最好将它们分配给具有有限 maxProcesses 值的专用队列。否则，这些任务可能会消耗过多的 CPU 资源并使你的系统过载。
简单平衡
simple 策略将工作器进程均匀地分布在指定的队列中。使用此策略，Horizon 不会自动缩放工作器进程的数量。相反，它使用固定数量的进程：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'queue' => ['default', 'notifications'],
'balance' => 'simple',
'processes' => 10,
],
],
],在上面的示例中，Horizon 将为每个队列分配 5 个进程，将总共 10 个进程平分。
如果你想单独控制分配给每个队列的工作器进程数量，你可以定义多个主管：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'queue' => ['default'],
'balance' => 'simple',
'processes' => 10,
],
'supervisor-notifications' => [
// ...
'queue' => ['notifications'],
'balance' => 'simple',
'processes' => 2,
],
],
],通过此配置，Horizon 将为 default 队列分配 10 个进程，为 notifications 队列分配 2 个进程。
无平衡
当 balance 选项设置为 false 时，Horizon 严格按照列出的顺序处理队列，类似于 Laravel 的默认队列系统。但是，如果任务开始累积，它仍然会缩放工作器进程的数量：
'environments' => [
'production' => [
'supervisor-1' => [
// ...
'queue' => ['default', 'notifications'],
'balance' => false,
'minProcesses' => 1,
'maxProcesses' => 10,
],
],
],在上面的示例中，default 队列中的任务始终优先于 notifications 队列中的任务。例如，如果 default 中有 1000 个任务，而 notifications 中只有 10 个，Horizon 将在处理 notifications 中的任何任务之前完全处理所有 default 任务。
你可以使用 minProcesses 和 maxProcesses 选项控制 Horizon 缩放工作器进程的能力：
minProcesses定义最小的工作器进程总数。此值必须大于或等于 1。maxProcesses定义 Horizon 可扩展到的最大工作器进程总数。
升级 Horizon
升级到 Horizon 的新主要版本时，请务必仔细查看升级指南。
运行 Horizon
一旦你在应用的 config/horizon.php 配置文件中配置了主管和工作器，你就可以使用 horizon Artisan 命令启动 Horizon。此单个命令将为当前环境启动所有配置的工作器进程：
php artisan horizon你可以使用 horizon:pause 和 horizon:continue Artisan 命令暂停 Horizon 进程并指示其继续处理任务：
php artisan horizon:pause
php artisan horizon:continue你也可以使用 horizon:pause-supervisor 和 horizon:continue-supervisor Artisan 命令暂停和继续特定的 Horizon 主管：
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1你可以使用 horizon:status Artisan 命令检查 Horizon 进程的当前状态：
php artisan horizon:status你可以使用 horizon:supervisor-status Artisan 命令检查特定 Horizon 主管的当前状态：
php artisan horizon:supervisor-status supervisor-1你可以使用 horizon:terminate Artisan 命令优雅地终止 Horizon 进程。任何当前正在处理的任务将被完成，然后 Horizon 将停止执行：
php artisan horizon:terminate自动重启 Horizon
在本地开发期间，你可以运行 horizon:listen 命令。使用 horizon:listen 命令时，当你想要重新加载更新后的代码时，无需手动重启 Horizon。在使用此功能之前，应确保你的本地开发环境中已安装 Node。此外，你应该在项目中安装 Chokidar 文件监视库：
npm install --save-dev chokidar安装 Chokidar 后，你可以使用 horizon:listen 命令启动 Horizon：
php artisan horizon:listen在 Docker 或 Vagrant 中运行时，应使用 --poll 选项：
php artisan horizon:listen --poll你可以使用应用 config/horizon.php 配置文件中的 watch 配置选项配置应监视的目录和文件：
'watch' => [
'app',
'bootstrap',
'config',
'database',
'public/**/*.php',
'resources/**/*.php',
'routes',
'composer.lock',
'.env',
],部署 Horizon
当你准备将 Horizon 部署到应用的实际服务器时，应配置一个进程监视器来监视 php artisan horizon 命令，并在它意外退出时重新启动它。别担心，下面我们将讨论如何安装进程监视器。
在应用的部署过程中，你应该指示 Horizon 进程终止，以便它可以被你的进程监视器重新启动并接收你的代码更改：
php artisan horizon:terminate安装 Supervisor
Supervisor 是 Linux 操作系统的进程监视器，如果 horizon 进程停止执行，它将自动重新启动它。要在 Ubuntu 上安装 Supervisor，可以使用以下命令。如果你不使用 Ubuntu，可能可以使用操作系统的包管理器安装 Supervisor：
sudo apt-get install supervisorNOTE
如果自己配置 Supervisor 听起来很麻烦，请考虑使用 Laravel Cloud，它可以为你的 Laravel 应用管理后台进程。
Supervisor 配置
Supervisor 配置文件通常存储在服务器的 /etc/supervisor/conf.d 目录中。在此目录中，你可以创建任意数量的配置文件，指示 supervisor 如何监视你的进程。例如，让我们创建一个 horizon.conf 文件来启动和监视 horizon 进程：
[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在定义 Supervisor 配置时，应确保 stopwaitsecs 的值大于你运行时间最长的任务所消耗的秒数。否则，Supervisor 可能会在任务完成处理之前将其终止。
WARNING
虽然上述示例适用于基于 Ubuntu 的服务器，但 Supervisor 配置文件的预期位置和文件扩展名可能因其他服务器操作系统而异。有关更多信息，请查阅服务器的文档。
启动 Supervisor
创建配置文件后，你可以使用以下命令更新 Supervisor 配置并启动受监视的进程：
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizonNOTE
有关运行 Supervisor 的更多信息，请查阅 Supervisor 文档。
标签
Horizon 允许你为任务分配“标签”，包括邮件、广播事件、通知和队列事件监听器。事实上，Horizon 会根据附加到任务的 Eloquent 模型智能地自动标记大多数任务。例如，看看下面的任务：
<?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 将使用模型的类名和主键智能地标记任务：
use App\Jobs\RenderVideo;
use App\Models\Video;
$video = Video::find(1);
RenderVideo::dispatch($video);手动标记任务
如果你想手动为你的可排队对象定义标签，可以在类上定义一个 tags 方法：
class RenderVideo implements ShouldQueue
{
/**
* 获取应分配给任务的标签。
*
* @return array<int, string>
*/
public function tags(): array
{
return ['render', 'video:'.$this->video->id];
}
}手动标记事件监听器
当检索排队事件监听器的标签时，Horizon 会自动将事件实例传递给 tags 方法，允许你将事件数据添加到标签中：
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 方法中调用这些方法：
/**
* 引导任何应用程序服务。
*/
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 秒的长时间等待阈值：
'waits' => [
'redis:critical' => 30,
'redis:default' => 60,
'redis:batch' => 120,
],将队列的阈值设置为 0 将禁用该队列的长时间等待通知。
指标
Horizon 包含一个指标仪表板，提供有关任务和队列等待时间及吞吐量的信息。为了填充此仪表板，你应该配置 Horizon 的 snapshot Artisan 命令，使其在应用的 routes/console.php 文件中每五分钟运行一次：
use Illuminate\Support\Facades\Schedule;
Schedule::command('horizon:snapshot')->everyFiveMinutes();如果你想删除所有指标数据，可以调用 horizon:clear-metrics Artisan 命令：
php artisan horizon:clear-metrics删除失败任务
如果你想删除一个失败的任务，可以使用 horizon:forget 命令。horizon:forget 命令接受失败任务的 ID 或 UUID 作为其唯一参数：
php artisan horizon:forget 5如果你想删除所有失败任务，可以为 horizon:forget 命令提供 --all 选项：
php artisan horizon:forget --all从队列中清除任务
如果你想从应用的默认队列中删除所有任务，可以使用 horizon:clear Artisan 命令：
php artisan horizon:clear你可以提供 queue 选项以从特定队列中删除任务：
php artisan horizon:clear --queue=emails