Laravel Horizon - Knowledge of Laravel

什么是 Horizon

Laravel Horizon 是 Laravel 的 Redis 队列专用监控仪表板。它可以实时可视化任务吞吐量、执行时间和失败情况，并通过代码管理 Worker 配置。

Horizon 是扩展队列基础功能的包。请先理解队列与任务的基础知识后再继续阅读。此外，后端必须使用 Redis。

安装

Horizon 使用 Redis 作为队列后端。请确认 config/queue.php 的 QUEUE_CONNECTION 已设为 redis。目前不支持 Redis Cluster。

使用 Composer 安装。

composer require laravel/horizon

安装完成后，发布 Horizon 的资源与配置文件。

php artisan horizon:install

该命令会生成 config/horizon.php 与 app/Providers/HorizonServiceProvider.php。

配置

config/horizon.php 的结构

config/horizon.php 是管理所有 Worker 配置的文件。核心配置是 environments 选项。

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

    'local' => [
        'supervisor-1' => [
            // 其他值会从 defaults 部分继承
            'maxProcesses' => 3,
        ],
    ],
],

Horizon 内部使用一个名为 horizon 的 Redis 连接。请不要在 config/database.php 中把该名称用于其他连接。

CSP nonce（Content Security Policy）

若希望作为 Content Security Policy 的一环，为 Horizon 视图内使用的 script / style 标签设置 nonce 属性，可使用 Horizon::cspNonce 方法。由于每个请求都会分配新的 nonce，通常在中间件中调用。

use Closure;
use Illuminate\Http\Request;
use Laravel\Horizon\Horizon;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Horizon::cspNonce('csp-nonce');

    return $next($request);
}

将该中间件添加到 config/horizon.php 的 middleware 选项中。

'middleware' => [
    'web',
    App\Http\Middleware\AddHorizonCspNonce::class,
],

Supervisor（监督者）

每个环境可以拥有一个或多个”Supervisor”。Supervisor 是 Worker 组的管理单位，可以在同一环境下运行多个拥有不同队列、平衡策略和进程数的 Supervisor。

默认值

通过 defaults 选项可以为所有 Supervisor 设定默认值。

'defaults' => [
    'supervisor-1' => [
        'connection' => 'redis',
        'queue' => ['default'],
        'balance' => 'auto',
        'tries' => 1,
        'timeout' => 60,
        'maxProcesses' => 1,
    ],
],

维护模式

当应用处于维护模式时，Horizon 默认不会处理任务。若要强制处理，可使用 force 选项。

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

任务最大重试次数

'environments' => [
    'production' => [
        'supervisor-1' => [
            'tries' => 10,
        ],
    ],
],

将 tries 设为 0 表示允许无限次重试。

任务超时

'environments' => [
    'production' => [
        'supervisor-1' => [
            'timeout' => 60,
        ],
    ],
],

timeout 应设为比 config/queue.php 的 retry_after 短几秒的值。此外，在 auto 平衡策略下，超过该值的任务可能会被强制终止。

backoff（重试等待时间）

指定发生异常后到再次重试的等待秒数。

// 固定值
'backoff' => 10,

// 阶段性（指数退避）
'backoff' => [1, 5, 10],

其他 Worker 选项

除了 tries、timeout、backoff，每个 Supervisor 还支持控制 Worker 进程行为和自动重启时机的选项。定期重启长时间运行的进程是防止内存泄漏的良好实践。

'environments' => [
    'production' => [
        'supervisor-1' => [
            // ...
            'memory' => 128,
            'maxJobs' => 1000,
            'maxTime' => 3600,
            'sleep' => 3,
            'rest' => 0,
            'nice' => 0,
        ],
    ],
],

memory — Worker 进程在重启前可消耗的最大内存（MB）。默认为 128
maxJobs — 重启前处理的任务数。0 表示无限制。默认为 0
maxTime — Worker 在重启前可运行的秒数。0 表示不按时间重启。默认为 0
sleep — 无任务时距下一次轮询的等待秒数。默认为 3
rest — 每个任务处理之间暂停的秒数。默认为 0
nice — Worker 进程的优先级（“niceness”）。值越大优先级越低。默认为 0

平衡策略

Horizon 提供了 3 种 Worker 平衡策略。

auto（默认）

根据队列负载自动调整 Worker 数量。通过 minProcesses 和 maxProcesses 指定范围。

'supervisor-1' => [
    'balance' => 'auto',
    'autoScalingStrategy' => 'time', // 或 'size'
    'minProcesses' => 1,
    'maxProcesses' => 10,
    'balanceMaxShift' => 1,
    'balanceCooldown' => 3,
],

time — 按清空队列的预估时间进行伸缩
size — 按队列中的任务数进行伸缩

在 auto 策略下，队列的顺序并不代表优先级。若要强制优先级，请使用多个 Supervisor。

simple

固定 Worker 数量，并将其均匀分配到指定队列。

'supervisor-1' => [
    'balance' => 'simple',
    'processes' => 10,
    'queue' => ['default', 'notifications'],
],

上例会为 default 和 notifications 各分配 5 个进程。

false（无平衡）

严格按队列的列举顺序优先。行为与 Laravel 默认的队列系统类似，但会根据积压情况伸缩 Worker 数量。

'supervisor-1' => [
    'balance' => false,
    'queue' => ['default', 'notifications'],
    'minProcesses' => 1,
    'maxProcesses' => 10,
],

default 队列的任务将始终先于 notifications 队列被处理。

仪表板的授权

Horizon 仪表板可通过 /horizon 路由访问。本地环境默认对任何人开放，但生产环境需要通过 Gate 定义限制访问。编辑 app/Providers/HorizonServiceProvider.php 的 gate() 方法。

use App\Models\User;
use Illuminate\Support\Facades\Gate;

protected function gate(): void
{
    Gate::define('viewHorizon', function (User $user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

若不需要认证（例如已通过 IP 限制保护），可以将参数设为可选。

Gate::define('viewHorizon', function (User $user = null) {
    // 通过 IP 地址等进行限制的情况
    return true;
});

启动 Horizon

基本命令

# 启动
php artisan horizon

# 暂停 / 恢复
php artisan horizon:pause
php artisan horizon:continue

# 暂停 / 恢复指定 Supervisor
php artisan horizon:pause-supervisor supervisor-1
php artisan horizon:continue-supervisor supervisor-1

# 查看状态
php artisan horizon:status
php artisan horizon:supervisor-status supervisor-1

# 优雅关闭
php artisan horizon:terminate

本地开发：自动重启

要检测文件变更并自动重启 Horizon，可使用 horizon:listen 命令。

npm install --save-dev chokidar
php artisan horizon:listen

# 在 Docker / Vagrant 环境下
php artisan horizon:listen --poll

通过 Supervisor 持续运行

在生产环境中，使用 Supervisor 让 Horizon 保持常驻运行。

安装 Supervisor

sudo apt-get install supervisor

创建配置文件

创建 /etc/supervisor/conf.d/horizon.conf。

[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 设置为大于最长任务执行时间的值。若过小，Supervisor 会在任务中途强制终止它。

启动 Supervisor

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start horizon

部署时

每次部署代码后重启 Horizon 以应用变更。

php artisan horizon:terminate

只要 Supervisor 设置了 autostart=true / autorestart=true，终止后会自动重启。

任务管理

静默

不希望显示在仪表板”已完成任务”列表中的任务，可以在 config/horizon.php 中进行静默。

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

// 按标签静默
'silenced_tags' => [
    'notifications',
],

也可以通过实现 Silenced 接口的方式。

use Laravel\Horizon\Contracts\Silenced;

class ProcessPodcast implements ShouldQueue, Silenced
{
    use Queueable;
    // ...
}

指标与监控

Horizon 的指标仪表板会显示任务与队列的吞吐量和执行时间。为定期获取快照，需要设置调度。

// routes/console.php
use Illuminate\Support\Facades\Schedule;

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

通过 config/horizon.php 的 metrics.trim_snapshots 选项，可以设置指标图表保留的快照数量。该配置不是限制快照的经过时间而是件数，因此实际保留时间取决于 horizon:snapshot 命令的执行频率。

'metrics' => [
    'trim_snapshots' => [
        'job' => 24,
        'queue' => 24,
    ],
],

要删除所有指标数据，可执行如下命令。

php artisan horizon:clear-metrics

任务失败的通知

当队列等待时间过长时，可以接收通知。可在 app/Providers/HorizonServiceProvider.php 的 boot() 方法中配置。

use Laravel\Horizon\Horizon;

public function boot(): void
{
    parent::boot();

    Horizon::routeMailNotificationsTo('[email protected]');
    Horizon::routeSlackNotificationsTo('slack-webhook-url', '#ops');
    Horizon::routeSmsNotificationsTo('15556667777');
}

等待时间阈值

通过 config/horizon.php 的 waits 选项设置触发通知的等待秒数。

'waits' => [
    'redis:critical' => 30,  // 等待 30 秒以上就通知
    'redis:default' => 60,
    'redis:batch' => 120,
],

设为 0 会禁用该队列的通知。

失败任务的管理

失败的任务可以通过 ID 或 UUID 删除。

# 删除指定失败任务
php artisan horizon:forget 5

# 删除所有失败任务
php artisan horizon:forget --all

若要清空队列中的所有任务，使用如下命令。

# 清空默认队列
php artisan horizon:clear

# 清空指定队列
php artisan horizon:clear --queue=emails

升级

Horizon 大版本升级时，请务必查看升级指南。

队列与任务

Laravel 队列的基础。介绍任务的创建、派发、批处理与失败处理。

Redis

作为 Horizon 后端所需的 Redis 的配置与用法。

​什么是 Horizon

​安装

​配置

​config/horizon.php 的结构

​CSP nonce（Content Security Policy）

​Supervisor（监督者）

​默认值

​维护模式

​任务最大重试次数

​任务超时

​backoff（重试等待时间）

​其他 Worker 选项

​平衡策略

​仪表板的授权

​启动 Horizon

​基本命令

​本地开发：自动重启

​通过 Supervisor 持续运行

​安装 Supervisor

​创建配置文件

​启动 Supervisor

​部署时

​任务管理

​标签

​静默

​指标与监控

​任务失败的通知

​等待时间阈值

​失败任务的管理

​升级

​相关页面

队列与任务

Redis

什么是 Horizon

安装

配置

config/horizon.php 的结构

CSP nonce（Content Security Policy）

Supervisor（监督者）

默认值

维护模式

任务最大重试次数

任务超时

backoff（重试等待时间）

其他 Worker 选项

平衡策略

仪表板的授权

启动 Horizon

基本命令

本地开发：自动重启

通过 Supervisor 持续运行

安装 Supervisor

创建配置文件

启动 Supervisor

部署时

任务管理

标签

静默

指标与监控

任务失败的通知

等待时间阈值

失败任务的管理

升级

相关页面