PHP项目Horizon队列仪表盘

本文目录导读：

1. 什么是 Laravel Horizon？
2. 安装与配置
3. 启动 Horizon
4. 访问仪表盘
5. 仪表盘功能介绍
6. 常用命令
7. 队列配置示例
8. 性能优化建议
9. 监控告警配置
10. 常见问题解决

我来帮你了解和使用 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');

性能优化建议

1. 合理配置进程数

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

2. 使用队列优先级

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

3. 设置超时时间

   'timeout' => 60,  // 默认 60 秒

监控告警配置

配置通知

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

常见问题解决

仪表盘无法访问

• 检查 .env 中 APP_ENV 配置
• 确认 Horizon 服务正在运行

任务一直等待

• 检查 Redis 连接配置
• 确认队列名称匹配

内存溢出

• 增加 memory_limit
• 使用 php artisan horizon:terminate 定期重启

Laravel Horizon 为你的队列系统提供了强大的可视化和监控能力,让你能够轻松管理和优化队列任务的处理。