LaravelHorizon监控Redis队列教程

Laravel Horizon 是一个功能强大的 Redis 队列监控工具，但其真正落地使用远不止执行一条 artisan 命令——从监控页面无法访问、任务卡在 waiting 状态、Redis 内存持续暴涨，到任务实际失败却显示 success，种种“看似异常”的现象背后，往往源于路由未注册、队列名不匹配、Supervisor 配置缺失、trim 参数未合理设置，或对 Horizon 状态判定逻辑的误解；掌握这些关键细节，才能让 Horizon 不仅“跑起来”，更能稳定、安全、真实地反映队列运行状况。

Horizon 启动后看不到队列监控页面

默认装完 laravel/horizon 并运行 php artisan horizon，不代表 Web 界统就自动可用。它只是启动了工作进程，Web 控制台需要额外配置路由和权限。

• 必须在 routes/web.php 中手动注册 Horizon 路由：Horizon::routes();
• 确保该路由只在非生产环境启用，否则会暴露敏感信息；常见写法是包在 if (app()->environment('local', 'staging')) { ... } 里
• 如果用了自定义中间件（比如强制登录），得显式允许 horizon 路由跳过或使用 auth 中间件——默认它不带任何认证逻辑
• 访问路径是 /horizon，不是 /admin/horizon 或其他变体；Nginx/Apache 若有重写规则，要确认没拦截掉这个路径

任务卡在 “waiting” 状态不执行

这通常不是 Horizon 本身的问题，而是 Redis 连接、队列配置或 Supervisor 设置没对齐。

• 检查 .env 中 QUEUE_CONNECTION=redis 是否生效，且 REDIS_HOST、REDIS_PORT 可连通（用 redis-cli -h xxx ping 验证）
• Horizon 默认监听 default 队列，但你的任务可能发到了 emails 或 notifications —— 要么改任务的 onQueue('default')，要么在 config/horizon.php 的 environments 里把对应队列加进 supervisor-1 的 queues 数组
• Supervisor 没跑？运行 ps aux | grep horizon，若只有 1 个主进程没子进程，说明 supervisor 配置漏了 numprocs=4 或没 reload：执行 sudo supervisorctl reread && sudo supervisorctl update && sudo supervisorctl start horizon:

Redis 内存暴涨，horizon:terminate 不起作用

Horizon 会持续往 Redis 写入任务元数据（如 job ID、状态、执行时间），尤其在高频短任务场景下容易堆积。直接删 key 很危险，得靠配置+清理双管齐下。

• trim 配置控制保留多少条历史记录，默认是 'recent' => 1000，但这个只影响 UI 展示，不删底层数据；真正释放内存靠 'failed' => 1000 和 'completed' => 1000，它们决定 Redis 中 horizon:failed_jobs 和 horizon:recent_jobs 的最大长度
• 别依赖 php artisan horizon:terminate 来清内存——它只是通知 worker 优雅退出，不清理 Redis 数据；定期执行 php artisan horizon:clear 才会删掉过期的 completed/failed 记录
• 如果用的是 Redis Cluster 或哨兵模式，Horizon 不支持，会报 ERR unknown command `evalsha` 类错误；必须切回单机 Redis 或用 Proxy

任务抛出异常但 Horizon 显示 “success”

这是 Laravel 队列和 Horizon 状态同步的盲区：只要任务被消费并退出（哪怕 exit(1)），Horizon 就认为“执行完成”，不区分成功/失败语义。

• 关键看 failed_jobs 表或 Redis 的 horizon:failed_jobs —— 只有触发 failed() 方法（即任务类里定义了该方法且被调用）才算失败记录
• 如果你用 try/catch 吞掉异常但没 re-throw，或者没调用 $this->fail()，Horizon 就不会标记为 failed，只会记一条 “completed” 日志
• 调试时打开 LOG_LEVEL=debug，查 storage/logs/laravel.log 里是否有 App\Jobs\YourJob has been processed 后跟异常堆栈，那是实际失败点

终于介绍完啦！小伙伴们，这篇关于《LaravelHorizon监控Redis队列教程》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！