PHP项目Horizon队列仪表盘

wen PHP项目 2026-07-24 1

本文目录导读：

PHP项目Horizon队列仪表盘

什么是 Laravel Horizon？
安装与配置
启动 Horizon
访问仪表盘
仪表盘功能介绍
常用命令
队列配置示例
性能优化建议
监控告警配置
常见问题解决

我来帮你了解和使用 Laravel Horizon——一个为 Redis 驱动的 Laravel 队列系统提供的仪表盘和监控工具。

什么是 Laravel Horizon？

Laravel Horizon 是 Laravel 官方提供的队列监控系统，专门为使用 Redis 驱动的队列提供：

实时仪表盘 - 可视化查看队列状态
进程管理 - 自动管理队列工作进程
性能监控 - 提供队列执行统计
故障处理 - 自动重启失败的队列

安装与配置

安装 Horizon

composer require laravel/horizon

发布资源

php artisan vendor:publish --provider="Laravel\Horizon\HorizonServiceProvider"

配置 Horizon

配置文件位于 config/horizon.php：

'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default', 'emails', 'notifications'],
            'balance' => 'auto',
            'processes' => 3,
            'tries' => 3,
        ],
    ],
    'local' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'auto',
            'processes' => 3,
            'tries' => 3,
        ],
    ],
],

启动 Horizon

开发环境

php artisan horizon

生产环境（使用 Supervisor 守护进程）

创建 Supervisor 配置：

[program:horizon]
process_name=%(program_name)s
command=php /path/to/project/artisan horizon
autostart=true
autorestart=true
user=forge
redirect_stderr=true
stdout_logfile=/path/to/project/storage/logs/horizon.log

访问仪表盘

默认路由

访问：http://your-app.com/horizon

保护仪表盘

在 app/Providers/HorizonServiceProvider.php 中配置授权：

protected function gate()
{
    Gate::define('viewHorizon', function ($user) {
        return in_array($user->email, [
            'admin@example.com',
        ]);
    });
}

仪表盘功能介绍

概览页面

队列等待任务数
处理中的任务
失败的任务
任务处理速率

队列监控

每个队列的实时状态
任务等待时间
处理时间统计

工作进程管理

活跃的 Supervisor
运行的进程数
进程状态监控

任务统计

每小时任务处理量
任务处理时长分布
失败率统计

常用命令

# 重启 Horizon
php artisan horizon:terminate
# 暂停 Horizon
php artisan horizon:pause
# 继续 Horizon
php artisan horizon:continue
# 查看 Horizon 状态
php artisan horizon:status
# 查看任务统计
php artisan horizon:snapshot
# 清理失败的任务
php artisan horizon:clear --queue=default

队列配置示例

定义队列任务

class ProcessPodcast implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    public function handle()
    {
        // 处理任务
    }
    // 指定队列
    public $queue = 'processing';
}

分配队列

ProcessPodcast::dispatch()->onQueue('processing');

性能优化建议

合理配置进程数

'processes' => 8, // 根据服务器 CPU 核心数调整

使用队列优先级

'queue' => [
    'high',       // 高优先级
    'default',    // 普通优先级
    'low'         // 低优先级
],

设置超时时间
```
'timeout' => 60,  // 默认 60 秒
```

监控告警配置

配置通知

// config/horizon.php
'waits' => [
    'redis:default' => 60, // 等待超过 60 秒触发告警
],
'slack' => [
    'webhook_url' => env('HORIZON_SLACK_WEBHOOK_URL'),
],