Coolify 的 Horizon 指标与快照让 Metrics 面板不空白的 horizon:snapshot 与 trim_snapshots 配置【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify本文以 Coolify 仓库中关于 Laravel Horizon 指标Metrics Snapshots的参考文档为主体讲清楚三件事为什么 Horizon 的指标图表默认是空白的、horizon:snapshot必须通过 Laravel Scheduler 注册而非手动执行、以及config/horizon.php中metrics.trim_snapshots的真实语义快照个数而非时间长度。读完本文你可以直接在 Coolify 或任何 Horizon 项目中定位指标面板空白的根因、复用 Coolify 的调度注册写法并按需调整指标历史保留时长与 Redis 内存开销之间的平衡。一、指标图表为空是设计使然Horizon 不会自动产出指标参考文档给出的第一个关键事实是运行horizonartisan 命令本身并不会自动填充指标数据。Horizon 的 metrics 图表并不是由 worker 在消费任务时实时写入的而是完全由快照snapshot构建的——只有horizon:snapshot命令执行后才会生成一条用于绘图的数据点。这意味着一个常见误区只要php artisan horizon起来了dashboard 上就应该有曲线。实际上如果调度器从未触发horizon:snapshotMetrics 面板会一直保持空白且不会报任何错误。Coolify 项目完整集成了 Horizoncomposer.json中依赖laravel/horizon: ^5.48.2其生产镜像通过 s6-overlay 服务启动 Horizondocker/production/etc/s6-overlay/s6-rc.d/horizon/run 中最终执行exec php artisan horizon。可以注意到这个脚本只负责启动 Horizon 主进程整个仓库里没有任何地方在进程启动时顺手做快照——这正是文档强调metrics 与 horizon 进程解耦的实际体现指标数据是调度侧的职责不是 worker 侧的副作用。二、正确做法把 horizon:snapshot 注册进 Scheduler而不是手动跑文档第二个要点手动执行一次horizon:snapshot只会让 dashboard 短暂出现一个数据点随后立刻过期因为它不会持续更新。正确做法是把快照命令注册进 Laravel 调度器每 5 分钟执行一次与trim_snapshots的计数配合形成连续的时间序列。Coolify 仓库中恰好给出了该命令的真实注册位置——应用 Console Kernel 的schedule(Schedule $schedule)方法并且按环境区分了两种频率if (isDev()) { // 开发环境每分钟一次便于调试时快速看到曲线变化 $this-scheduleInstance-command(horizon:snapshot)-everyMinute(); // ... } else { // 生产环境标准做法每 5 分钟一次 $this-scheduleInstance-command(horizon:snapshot)-everyFiveMinutes(); // ... }两个细节值得注意调度器必须真正在运行。在 Coolify 的容器化部署里schedule:work由独立的 s6 服务进程承担见 scheduler-worker 服务脚本开发环境见 docker/development 下的同名脚本其最终执行php artisan schedule:work。如果只启动了horizon服务而漏掉scheduler-workerhorizon:snapshot永远不会触发症状就是进程都活着但指标图是空的——排查时应优先确认调度器进程存在而不是怀疑 Horizon 本身。参考文档还提醒调度注册的写法在 Laravel 10 与 11 之间存在差异。上例中 Coolify 采用的是新版写法schedule(Schedule $schedule)直接接收 Schedule 实例。如果你要在旧版 Laravel 10 的项目里复制这段逻辑请对照对应版本的调度器文档确认注册语法不要跨版本盲抄。补充一个 Coolify 特有的开关config/constants.php中定义了is_horizon_enabled env(HORIZON_ENABLED, true)config/constants.php而生产 s6 脚本会在启动前检查.env是否包含HORIZON_ENABLEDfalse若是则让服务睡眠不启动 Horizon。也就是说在 Coolify 中指标图空白还有一种前置原因Horizon 整体被环境变量关掉了。三、trim_snapshots 是快照个数不是时长——保留历史的标准算法文档第三个要点也是最容易误读的参数config/horizon.php中metrics.trim_snapshots下的job与queue值是要保留的快照数量而不是分钟数或小时数。Coolify 仓库的实际配置位于 config/horizon.php 的 Metrics 段落metrics [ trim_snapshots [ job 24, // 保留 24 个 job 维度快照 queue 24, // 保留 24 个 queue 维度快照 ], ],其注释原文也点明了语义这个配置将和horizon:snapshot的调度一起使用决定指标保留多久。由此可以推出保留历史的标准计算公式历史时长 快照个数 × 快照间隔 24 个 × 5 分钟 2 小时即 Coolify 默认配置下Metrics 面板上的 job/queue 曲线最多展示最近 2 小时的数据。要延长曲线跨度唯一正确的方式是调大trim_snapshots的数值例如 48 个 → 4 小时而不是去改horizon:snapshot之外的任何时间参数。代价是 Redis 内存每个快照都会写入 Horizon 使用的 Redis 连接Coolify 中为use default数据键统一带前缀见 config/horizon.php 的prefix配置默认形如{APP_NAME}_horizon:。保留的快照越多累积的 key 越多因此调大该值前应在 Redis 容量上留有余量。文档的结论可以概括为一条权衡规则在 Redis 内存可接受的前提下增大trim_snapshots换取更长的指标历史反之维持 24 的默认值以节省内存。顺带一提同一份配置中的waits段redis:default 60config/horizon.php定义的是队列等待阈值秒与快照保留无关注意不要混淆这两个时间型参数。四、Coolify 的配套s6 监督器配置如何影响指标曲线的内容理解trim_snapshots的作用对象job 与 queue 两个维度后再结合 Coolify 的监督器supervisor配置就能读懂指标图里曲线的来源。Coolify 在 config/horizon.php 的 defaults 段 只定义了一个名为s6的监督器s6 [ connection redis, balance env(HORIZON_BALANCE, false), queue env(HORIZON_QUEUES, high,default), maxTime env(HORIZON_MAX_TIME, 0), maxJobs 400, memory 128, tries 1, nice 0, sleep 3, timeout min( max((int) env(HORIZON_TIMEOUT, 39600), ScheduledVolumeBackup::DEFAULT_TIMEOUT 600), 85800, ), ],其中environments段为 production/local 两个环境补充了自动扩缩参数autoScalingStrategy size、minProcesses/maxProcesses默认 1~4、balanceMaxShift与balanceCooldown默认均为 1。从源码结构看队列维度默认覆盖high和default两条队列可用环境变量HORIZON_QUEUES调整——当你新增自定义队列后需要确认它被纳入了某个监督器否则该队列的任务不会出现在 queue 维度的指标快照中快照只统计被 Horizon 监督的工作负载。五、排查清单Metrics 面板空白时的检查顺序综合参考文档与 Coolify 仓库的实际实现按以下顺序排查可以覆盖绝大多数指标不显示场景horizon:snapshot是否已注册进调度器在schedule()方法中搜索horizon:snapshotCoolify 位于 app/Console/Kernel.php 与 #L72且间隔应 ≤ 5 分钟调度器进程是否存活Coolify 容器化部署中即scheduler-worker服务php artisan schedule:work手动执行快照无法替代它间隔与保留数是否匹配快照间隔 ×trim_snapshots个数 可见历史长度默认 24 × 5 分钟 2 小时Horizon 是否被整体关闭检查.env中HORIZON_ENABLEDfalse及 config/constants.php 的默认值Redis 容量调大trim_snapshots前先评估prefix命名空间下的键增长。最后需要强调文档反复提示的一条限制metrics.trim_snapshots的语义是计数不是时长任何把它当保留分钟数来调的写法都是错误的这也是本文与参考文档最想让读者记住的一点。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考