Laravel Horizon队列监控面板部署指南-php教程-PHP中文网

horizon 面板正常运行需 redis 连通、定时快照（horizon:snapshot）、权限放行和独立进程四者同时就位；缺一则导致白屏、指标停滞或失败任务不显示。

laravel horizon队列监控面板部署指南

Horizon 面板不是装完就能用的，它依赖 Redis 连通性、定时快照、权限放行和独立进程三者同时就位；缺一不可，否则页面空白、吞吐量冻结或失败任务不显示都是常态。

最常见原因是路由未注册或权限拦截过严。Horizon 默认只在 APP_ENV=local 下自动注册路由，生产环境必须手动放开。

检查 config/horizon.php 中 enabled 是否为 true（设成 false 会静默禁用全部功能）
确认 App\Providers\HorizonServiceProvider::class 在 config/app.php 的 providers 数组中且未被注释
在 AppServiceProvider::boot() 中添加授权回调：Horizon::auth(fn ($request) => true);（临时测试可用，上线前替换为真实鉴权逻辑）
新版 Horizon（v5.10+）推荐用 php artisan horizon:install 初始化，它会自动创建配置、迁移和软链接资源，比 vendor:publish 更可靠

吞吐量、延迟、活跃任务数等指标全靠 horizon:snapshot 命令定时采集并写入 Redis 和数据库，这个命令默认由 Laravel Scheduler 每分钟执行一次。没配调度，数据就永远停在初始状态。

laravel-specialist

精通 Laravel 10+，遵循现代 PHP 实践的 Laravel 专家。擅长优雅语法、Eloquent ORM、队列系统及企业级特性...

下载

在 app/Console/Kernel.php 的 schedule() 方法中加入：$schedule->command('horizon:snapshot')->everyMinute();
确认服务器 cron 正确指向：* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1
手动运行 php artisan horizon:snapshot 观察输出——如果报 Redis 连接超时或权限拒绝，说明底层连接异常，horizon:snapshot 失败时通常静默，不会抛错
注意：在 APP_ENV=testing 下，Horizon 会跳过所有快照收集，测试时切到 local 或 production

Horizon 展示失败任务的前提是：任务确实被 Laravel 队列系统捕获并存入 horizon:failed（Redis）或 failed_jobs（database），而不是直接崩溃退出。

确保 config/queue.php 中 failed 配置启用；Redis 驱动下，失败任务默认存进 Redis 的 horizon:failed 列表，**不是** failed_jobs 表——所以 php artisan queue:failed 不会列出 Horizon 管理的失败任务
检查 config/horizon.php 中 trim 配置项，若 failed 设置过小（如 'failed' => 10），旧失败任务会被自动清理，导致面板里“刚失败就消失”
重试操作本质是把任务从 horizon:failed 移回对应队列（如 redis:queues:default），若重试后仍不执行，先确认该队列是否在 config/horizon.php 的 queues 列表中被监听
堆栈为空？检查任务类中是否用了 try/catch 吞掉了异常，或在 failed() 方法里没调用 parent::failed($exception)，导致 Horizon 无法提取原始错误上下文

Horizon 是独立守护进程，它不依赖 queue:work，也不能和 queue:work 共存于同一队列——否则会抢任务、漏执行、指标错乱。

确认 .env 中 QUEUE_CONNECTION=redis，且 config/queue.php 的 redis 连接块中 connection 值与 config/database.php 的 Redis 配置键名完全一致（比如写成 'connection' => 'cache'，但 database.php 里根本没有叫 cache 的 Redis 配置）
执行 php artisan tinker 后输入 Redis::ping()，返回 "PONG" 才算 Redis 真通；改了配置后必须 php artisan config:clear，否则 Horizon 静默加载旧缓存
运行 php artisan migrate —— horizon:install 只生成迁移文件，不执行；它会建 horizon_monitoring 表（存指标）和 failed_jobs 表（若不存在）
启动命令只能是 php artisan horizon（开发）或 php artisan horizon --daemon（生产），Supervisor 配置里也必须指向这个命令，绝不能混用 queue:work