FEATURED · 精选文章

Coolify 的 Laravel Horizon Supervisor 配置详解:defaults/environments 合并机制、balance 策略与队列优先级

发布时间 / 2026/9/6 19:55:26
来源 / 创域科博编辑部
栏目 / 资讯中心
Coolify 的 Laravel Horizon Supervisor 配置详解:defaults/environments 合并机制、balance 策略与队列优先级 Coolify 的 Laravel Horizon Supervisor 配置详解defaults/environments 合并机制、balance 策略与队列优先级【免费下载链接】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 仓库中的 Horizon Supervisor 配置参考文档.agents/skills/configuring-horizon/references/supervisors.md展开聚焦一个具体问题在 config/horizon.php 中如何正确编写 supervisor 块才能让defaults与environments按预期合并、让balance策略auto / simple / false匹配负载形态、以及如何在多队列场景下真正实现优先级处理。读完本文你将能理解 Coolify 生产环境中s6supervisor 的完整参数来源并能复制出一套可运行的 supervisor 配置。Supervisor 配置在哪里定义在 Laravel Horizon 体系中所有队列 worker 的运行参数都集中在config/horizon.php的defaults与environments两个数组里。Horizon 在启动时会把每个 supervisor 块展开为实际的php artisan queue:work进程组minProcesses到maxProcesses之间的进程数就是该 supervisor 的伸缩区间。Coolify 中 Horizon 的完整生命周期技能文档见 .agents/skills/configuring-horizon/SKILL.md其中明确提醒在修改任何 supervisor 配置前应先查阅当前版本 Horizon 的文档因为选项名和默认值在不同 Horizon 版本之间会变化。参考文档给出的四个检索方向是horizon supervisor configuration完整的 supervisor 选项列表horizon balancing strategiesauto、simple、false三种 balance 模式horizon autoscaling workersautoScalingStrategy的细节horizon environment configurationdefaults与environments的合并规则。defaults 与 environments 是合并关系不是替换关系这是参考文档强调的第一个要点也是最常见的配置误区defaults数组定义了完整的基础 supervisor 配置连接、队列、balance 策略、重试与超时等environments数组按环境打补丁只覆盖其中显式列出的键因此不需要在每个环境块里重复所有键。参考文档给出的通用模式是在defaults中定义connection、queue、balance、autoScalingStrategy、tries、timeout然后在production环境中只覆盖maxProcesses、balanceMaxShift、balanceCooldowndefaults [ supervisor-1 [ connection redis, queue [default], balance auto, minProcesses 1, maxProcesses 10, tries 3, ], ], environments [ production [ supervisor-1 [maxProcesses 20, balanceCooldown 3], ], local [ supervisor-1 [maxProcesses 2], ], ],注意environments中的环境名对应 Laravel 的APP_ENVsupervisor 名必须与defaults中的键一致才会被合并。Coolify 的真实配置Coolify 仓库中的 config/horizon.php 正是这种defaults 全量 environments 打补丁写法的实例。其defaults中只定义了一个名为s6的 supervisor名字对应容器内 s6-overlay 进程管理器的服务命名习惯defaults [ 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两个环境只覆盖扩容相关参数environments [ production [ s6 [ autoScalingStrategy size, minProcesses env(HORIZON_MIN_PROCESSES, 1), maxProcesses env(HORIZON_MAX_PROCESSES, 4), balanceMaxShift env(HORIZON_BALANCE_MAX_SHIFT, 1), balanceCooldown env(HORIZON_BALANCE_COOLDOWN, 1), ], ], local [ s6 [ // 与 production 相同的覆盖方式 autoScalingStrategy size, minProcesses env(HORIZON_MIN_PROCESSES, 1), maxProcesses env(HORIZON_MAX_PROCESSES, 4), balanceMaxShift env(HORIZON_BALANCE_MAX_SHIFT, 1), balanceCooldown env(HORIZON_BALANCE_COOLDOWN, 1), ], ], ],对照上面讲到的合并语义可以读出几个关键信息connection、queue、tries、timeout等基础键只在defaults出现一次环境块无需重复所有与伸缩强度相关的参数maxProcesses、balanceMaxShift、balanceCooldown、minProcesses都通过环境变量暴露可在不改代码的情况下调整容量balance默认值是字符串false——即 Coolify 的 supervisor默认不做自动伸缩maxProcesses默认 4就是固定的 worker 上限这正好印证了参考文档中固定 worker 数场景的推荐做法。balance 策略选型auto、simple 与 false参考文档给出了三种典型场景及其对应的balance取值。场景一变负载下用 balance: auto 自动伸缩balance: auto让 supervisor 根据队列积压量在minProcesses与maxProcesses之间自动伸缩 worker 数量适合负载波动明显的场景。但 auto 模式在突发负载下可能在很短时间内连续上调再下调进程数造成 worker 频繁启停。参考文档的解法正是 Coolify 配置中已经采用的两个参数balanceCooldown两次伸缩决策之间的最小间隔秒参考文档建议通常设为 3~5用以平滑突发负载下的抖动balanceMaxShift单个伸缩周期内允许增减的最大进程数防止一次性拉起或杀掉大量 worker。Coolify 中两者默认值都是1HORIZON_BALANCE_COOLDOWN、HORIZON_BALANCE_MAX_SHIFT即最激进的伸缩节奏若将HORIZON_BALANCE打开为auto或simple建议同时把这两个值调大以贴合参考文档的建议。场景二专用队列用 balance: false 固定 worker 数参考文档指出的第二种场景如果某个队列必须始终保持恰好 N 个 worker——例如一个视频处理队列被硬件/许可限制在 2 个并发——就不该用自动伸缩因为 auto 模式会在流量高峰把进程数拉高超出限制。正确做法是supervisor-video [ connection redis, queue video, balance false, maxProcesses 2, ],balance: false时 supervisor 直接以maxProcesses为固定进程数运行。Coolify 的HORIZON_BALANCE默认false就是这种保守取向部署任务见 app/Jobs/ApplicationDeploymentJob.php本身执行时间长、资源消耗大固定进程数比随时扩缩更容易控制并发。场景三auto 与 simple 的差别体现在 autoScalingStrategy当需要自动伸缩但希望控制伸缩依据什么时autoScalingStrategy起作用。Coolify 在两个环境块中都将其固定为size。从源码结构看该值决定 supervisor 在多队列场景下按何种策略分配进程例如按队列积压量分配或在多个队列间均匀分配参考文档也建议用horizon autoscaling workers检索确认当前版本的autoScalingStrategy具体取值语义因为它属于版本间容易变化的选项。用多个命名 supervisor 强制队列优先级这是参考文档中非常关键、且容易被忽略的一条当单个 supervisor 使用balance: auto时Horizon 不会强制队列处理顺序queue数组的书写顺序对负载均衡是无效的。也就是说下面的写法不能保证notifications先于default被处理// 错误示例顺序在这里不起作用 supervisor-1 [ connection redis, queue [notifications, default], balance auto, ],参考文档给出的正确方案是拆成两个独立命名的 supervisor用不同的maxProcesses上限表达优先级// 高优先级队列给更高的并发上限 notifications [ connection redis, queue notifications, balance auto, minProcesses 1, maxProcesses 8, ], // 低优先级队列给更低的并发上限 default [ connection redis, queue default, balance auto, minProcesses 1, maxProcesses 2, ],这样在总容量受限时高优先级 supervisor 能占据更多 worker。Coolify 自身目前是单 supervisor 消费high,default两个队列HORIZON_QUEUES默认值high,default如果未来要为部署类任务与通知类任务建立优先级隔离参照文档的做法就是拆分为两个命名 supervisor而不是调整queue字符串顺序。supervisor 参数与超时链结合 Coolify 源码的纵深解读参考文档列出的 supervisor 选项connection、queue、balance、autoScalingStrategy、tries、timeout、maxProcesses、balanceMaxShift、balanceCooldown在 Coolify 的s6supervisor 中基本都有对应实现config/horizon.php 还额外配置了maxTime、maxJobs、memory、nice、sleep等 worker 生命周期参数。结合仓库中的实际取值可以梳理出一组相互关联的超时约束参数Coolify 取值来源balanceHORIZON_BALANCE默认falseconfig/horizon.phpqueueHORIZON_QUEUES默认high,defaultconfig/horizon.phpmaxJobs400单个 worker 处理 400 个任务后重启config/horizon.phpmemory128MBworker 内存上限config/horizon.phptries1任务不自动重试config/horizon.phpsleep3秒队列空闲时 worker 休眠时长config/horizon.phpsupervisortimeoutmin(max(HORIZON_TIMEOUT, 36600), 85800)config/horizon.phpredis 连接retry_after8640024 小时config/queue.php其中 supervisortimeout的表达式值得展开下限是ScheduledVolumeBackup::DEFAULT_TIMEOUT 600而 app/Models/ScheduledVolumeBackup.php 中DEFAULT_TIMEOUT为36000即至少36600秒保证一次带 10 分钟余量的卷备份任务不会被 supervisor 提前杀掉默认值HORIZON_TIMEOUT为3960011 小时上限被硬性钳制在85800秒约 23.8 小时。这条超时链与 redis 连接配置的retry_after86400 秒共同保证了同一 skill 目录下 SKILL.md 提到的顺序约束jobtimeout supervisortimeoutretry_after。以 app/Jobs/ApplicationDeploymentJob.php 为例部署任务自身声明$timeout 36001 小时小于 supervisor 的 39600 秒supervisor 上限 85800 秒又小于retry_after的 86400 秒。这个顺序一旦写反就会出现任务还没被 Horizon 判超时、Redis 侧却先释放了锁导致重复执行的问题。配置如何生效从 s6 服务到 horizon:manage了解配置写在哪里之后还需要知道配置如何被加载启动入口Coolify 生产容器通过 s6-overlay 托管 Horizondocker/production/etc/s6-overlay/s6-rc.d/horizon/run 的内容就是检查.env中是否有HORIZON_ENABLEDfalse否则exec php artisan horizon。php artisan horizon启动 master supervisor 时才会按当前APP_ENV把environments块合并进defaults并拉起对应数量的 worker。开发环境对应脚本为 docker/development/etc/s6-overlay/s6-rc.d/horizon/run。Dashboard 授权app/Providers/HorizonServiceProvider.php 中定义了viewHorizonGate只有 root 用户或配置在horizon.allowed_emails即 config/horizon.php 的HORIZON_ALLOWED_EMAILS中的邮箱能进入 Horizon 面板可以在这里直观查看每个 supervisor 的进程数随负载的变化验证balance与maxProcesses的实际效果。运行时排障仓库内置了交互式命令horizon:manageapp/Console/Commands/HorizonManage.php可查看 pending/running/failed 任务、当前 worker 列表、按队列 purge以及当前 worker 是否还有任务在跑用于安全重启判断。调整 supervisor 参数后重启 worker 前用它确认没有 in-progress 的部署任务是最稳妥的流程。部署任务与 Horizon 的联动app/Providers/HorizonServiceProvider.php 监听了JobReserved事件把ApplicationDeploymentJob的 Horizon job id 回写到ApplicationDeploymentQueue记录这也是 supervisor 配置尤其是tries: 1与超时链对部署可靠性产生直接影响的原因。小结一套可复用的 supervisor 检查清单综合参考文档与 Coolify 的实现修改 supervisor 配置前可以按以下清单自检新键是否应放在defaults、而环境差异是否只以最小补丁写入environments合并而非替换该队列的负载形态是波动的还是必须固定并发波动选auto固定并发如受限的视频处理队列选false 明确maxProcesses打开自动伸缩后是否已设置balanceCooldown建议 3~5 秒与balanceMaxShift抑制抖动存在优先级需求时是否拆成了多个命名 supervisor而不是依赖queue数组顺序超时链是否满足 jobtimeout supervisortimeoutretry_afterCoolify 中即 3600 39600 86400重启 worker 前是否用horizon:manage确认没有任务在跑以上全部路径与取值均可在 Coolify 仓库内直接对照验证核心文件为 config/horizon.php、config/queue.php、app/Providers/HorizonServiceProvider.php 与 app/Console/Commands/HorizonManage.php。【免费下载链接】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),仅供参考
RELATED — 相关阅读

相关资讯

LATEST — 最新资讯

最新发布

TODAY — 本日精选

新闻

WEEKLY — 本周精选

新闻

MONTHLY — 本月精选

新闻