Laravel Horizon面板如何监控Redis队列状态？ (安装与指标解读)

Horizon仅监控laravel队列作业生命周期，不监控redis服务状态；需通过redis-cli或第三方工具检查Redis内存、连接等；安装时须确认database.php、queue.php配置及HORIZON_PREFIX环境变量。

Horizon 面板本身不直接监控 Redis 服务状态（比如内存、连接数、持久化），它只监控 Laravel 应用通过 RedisQueue 推送和消费的队列作业生命周期。想看队列“有没有卡住”“积压多少”“谁在慢”，Horizon 是对的工具；但 Redis 连不上或 OOM 了，得靠 redis-cli info 或第三方监控。

Horizon 安装时必须确认的三个 Redis 配置点

很多面板打不开或数据空白，根源不在 Horizon 本身，而在底层 Redis 连接没对齐：

• config/database.php 中 redis 默认配置必须指向实际运行的 Redis 实例（尤其注意 host 和 port，docker 环境常错配为 127.0.0.1）
• config/queue.php 的 redis 连接必须启用 retry_after（建议 ≥ 90），否则超时作业不会重入 failed_jobs 表，Horizon 就看不到失败记录
• HORIZON_PREFIX 环境变量不能与其它 Laravel 应用冲突（默认是 laravel:horizon:），否则多个项目会互相覆盖队列统计键

Dashboard 里「Jobs」标签页关键指标含义

这是最常被误读的部分：所有数字都基于 Horizon 自身采集的 Redis Sorted Set（laravel:horizon:jobs 等），不是实时 llen 结果：

• Waiting：当前在 queues:default（或你定义的队列名）List 里的作业数 —— 这个值 ≈ LLEN queues:default，代表真正待处理量
• Pending：已推入但尚未被 Worker 拉取的作业（存在 laravel:horizon:jobs ZSET 中，score 为未来时间戳），通常为 0；若持续 > 0，说明 Worker 崩溃或未启动
• Recent：过去 1 小时内完成/失败的作业总数，用于判断吞吐是否异常下滑
• Failed：失败作业数，对应 failed_jobs 表记录，不是 Redis 里的临时失败标记

如何快速定位「队列不动了」的真实原因

别只盯着 Horizon 页面刷新，按顺序查这三处：

• 执行

  php artisan horizon:supervisors

  ，确认 Supervisor 进程是否存活（输出应含 status: running）

• 检查 Redis 中实际队列长度：

  redis-cli -h 127.0.0.1 -p 6379 LLEN queues:default

  ，如果该值远大于 Horizon 显示的 Waiting，说明 Horizon 采集延迟或崩溃

• 查日志：

  tail -f storage/logs/horizon-*.log

  ，重点找 Connection refused、read Error on connection —— 这类错误 Horizon 不报红，但会导致指标停更

Horizon 的统计依赖定时采样（默认每 5 秒扫一次 Redis），所以「Waiting」数字有轻微滞后；真正要保可靠性，得配合 redis-cli ping 健康检查和 MONITOR 抓包看实际 LPUSH/BRPOP 流量。