Coolify 中的 Laravel Horizon 任务标签与静默机制Tags Silencing实战指南【免费下载链接】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在基于 Laravel 的项目中Laravel Horizon 仪表盘是观察后台队列运行状态的窗口而队列任务Job的**标签Tags与静默Silencing**正是这套窗口的筛选与降噪机制。Coolify 作为一个大量依赖异步队列任务的 PaaS 系统在其 config/horizon.php 与 app/Jobs 中完整落地了这一机制。本文以.cursor/skills/configuring-horizon/references/tags.md为核心骨架结合 Coolify 仓库源码项目依赖 composer.json 中laravel/horizon: ^5.48.2、laravel/framework: ^12.65.0系统讲解 Horizon 自动标签规则、自定义tags()方法、以及silenced与silenced_tags两类静默配置帮助你掌握如何给任务打标和如何让吵闹的任务从仪表盘消失这两项核心能力。一、机制总览先在哪个层面理解标签与静默Horizon 的标签tag是记录在每个队列消息 payload 上的字符串数组用于在仪表盘中按类目过滤任务静默silencing则是针对已完成任务列表completed jobs view的展示层过滤。两者有本质区别标签改变的是任务的可检索维度不改变任务的执行行为silenced按任务类隐藏把某个 Job 类加入数组后该类任务不再出现在已完成列表但任务照常运行silenced_tags按标签隐藏任何携带匹配标签字符串的任务都会从已完成列表消失适合对notifications这类一整类任务做集体降噪而不是逐个类去配置。在 Coolify 中这份机制被进一步用于部署链路追踪见下文第三节中tags()方法与 HorizonServiceProvider.php 的联动。关键词检索定位在官方文档中搜索horizon tags可获得标签 API 与自动打标行为搜索horizon silenced jobs可获得silenced与silenced_tags配置选项说明。二、自动标签Eloquent 模型任务的零代码打标核心规则如果某个 Job 的构造函数接收 Eloquent 模型实例Horizon 会自动为该任务打上ModelClass:id格式的标签例如App\Models\User:42。该规则意味着无需在 Job 类里写任何额外代码任务就会携带模型标签这些自动标签可以直接在仪表盘中按标签过滤只有当你需要超越自动标签之外的自定义标签时才需要手写tags()方法。在 Coolify 中的印证Coolify 的部署任务 ApplicationDeploymentJob.php 恰恰展示了一个何时必须自定义标签的典型反例——它的构造函数接收的是int主键而不是模型实例因此不会触发自动打标必须手动补上public function tags() { // Do not remove this one, it needs to properly identify which worker is running the job return [App\Models\ApplicationDeploymentQueue:.$this-application_deployment_queue_id]; } public function __construct(public int $application_deployment_queue_id) { $this-onQueue(deployment_queue()); }这段源码有两点值得注意标签格式保持与 Eloquent 自动打标一致ModelClass:id即使任务只接收主键也能模拟出模型级标签保证仪表盘过滤行为统一注释中的 Do not remove this one 表明该标签已不是纯粹的 UI 装饰而是被上游逻辑强依赖的标识见下一节。三、标签的消费端把标签变成可追踪的业务 ID标签并不只是仪表盘上的分类文字。Coolify 在 HorizonServiceProvider.php 中通过监听JobReserved事件把标签解析成业务主键实现Horizon 任务 ID ↔ 部署队列记录的双向关联Event::listen(function (JobReserved $event) { $payload $event-payload-decoded; $jobName $payload[displayName]; if ($jobName App\Jobs\ApplicationDeploymentJob) { $tags $payload[tags]; $id $payload[id]; $deploymentQueueId collect($tags)-first(function ($tag) { return str_contains($tag, App\Models\ApplicationDeploymentQueue); }); if (blank($deploymentQueueId)) { return; } $deploymentQueueId explode(:, $deploymentQueueId)[1]; $deploymentQueue ApplicationDeploymentQueue::find($deploymentQueueId); $deploymentQueue-update([ horizon_job_id $id, ]); } });从这段实现可以看出标签机制的实战威力任务入队时通过tags()写入的App\Models\ApplicationDeploymentQueue:id标签在任务被 worker 预留reserved时被反向解析回deployment_queue_id再写回ApplicationDeploymentQueue表的horizon_job_id字段从而打通用户侧部署状态与Horizon 侧执行详情两张视图。只要标签规则被改动或移除这段追踪逻辑就会静默失效——这正是源码注释强调标签不可删的原因。四、silenced按任务类隐藏已完成记录silenced是一组任务类名数组配置位置在 config/horizon.php/* |-------------------------------------------------------------------------- | Silenced Jobs |-------------------------------------------------------------------------- | | Silencing a job will instruct Horizon to not place the job in the list | of completed jobs within the Horizon dashboard. This setting may be | used to fully remove any noisy jobs from the completed jobs list. | */ silenced [ // App\Jobs\ExampleJob::class, ],使用要点写法以\App\Jobs\ExampleJob::class形式完整类名加入数组作用范围只影响 Horizon 仪表盘的已完成任务列表任务本身照常排队、执行、重试定位它是仪表盘降噪工具不是禁用任务的手段——若想不让某任务执行应移除其分发调用或调整队列分发逻辑而非依赖silenced适用场景周期性、高频率且无人需要逐条回看结果的任务如各类心跳检查、探活任务、频发的内部清理任务。以 Coolify 为例app/Jobs 目录下大量存在ServerCheckJob、ScheduledTaskJob、SendWebhookJob等高频任务若某一类任务在已完成列表里刷屏且无追溯价值即可放入该数组。当前 config/horizon.php 中该数组为空仅保留示例注释说明 Coolify 默认不静默任何任务全部执行记录都保留在仪表盘中。五、silenced_tags按标签批量隐藏一类任务silenced_tags与silenced的区别在于匹配维度从类名变为标签字符串任何携带匹配标签的任务都会从已完成列表隐藏。因此在配置时需要与第二节的自动打标规则、第三节的自定义tags()返回的标签字符串保持一致。典型用法silenced [ // 按任务类静默 // App\Jobs\NotificationJob::class, ], silenced_tags [ // 按标签静默所有携带 notifications 标签的任务都不出现在已完成列表 notifications, ],决策参考何时用哪一个噪声来自单一任务类→ 用silenced精确、直观、易维护噪声横跨多个任务类、但共享同一业务语义标签例如所有发送类任务统一打notifications标签→ 用silenced_tags一条规则覆盖整类无需随任务类新增而反复改配置两者可同时使用互为补充不会互相排斥。需要留意的是与silenced相同silenced_tags不会阻止任务执行它纯粹是 Horizon 前端展示层的过滤器。此外当前仓库的 config/horizon.php 中尚未声明silenced_tags键仍保持 Laravel Horizon 5.x 的默认行为说明这是留给使用方按需开启的能力动手前建议先检索官方文档中horizon silenced jobs以核对当前版本的选项名与默认值。六、与静默相关的仪表盘权限与运维提醒在实施标签与静默策略时还应一并确认谁有权限查看这些过滤后的仪表盘数据。Coolify 在 HorizonServiceProvider.php 中通过自定义viewHorizonGate 做了精细化授权protected function gate(): void { Gate::define(viewHorizon, function (User $user) { if ($user-id 0) { return true; } return str(config()-string(horizon.allowed_emails)) -lower() -explode(,) -map(fn (string $email) trim($email)) -contains($user-email); }); }其规则为id 0的超级管理员Coolify 的 root 用户始终放行其余用户只有在其邮箱命中 config/horizon.php 中HORIZON_ALLOWED_EMAILS环境变量配置的白名单逗号分隔、大小写不敏感时才能访问。配置静默策略前确认该 Gate可避免已经隐藏了任务却仍被无关人员观察队列的权限隐患。七、小结与落地清单回到.cursor/skills/configuring-horizon/references/tags.md的三个核心论断均可在 Coolify 仓库中得到实现级印证论断实现依据结论Eloquent 模型任务自动打ModelClass:id标签无需额外代码接收模型实例的 Job 自动获得标签Coolify 部署 Job 因只收主键故在 ApplicationDeploymentJob.php 手动补全同名格式标签只有需要自定义标签时才写tags()silenced仅从已完成列表隐藏任务不阻止执行config/horizon.php 注释明确 not place the job in the list of completed jobs它是降噪工具不是禁用开关silenced_tags按匹配标签隐藏所有携带任务与tags()返回的标签字符串联动生效适合按notifications等语义标签批量静默落地时的四步检查清单先盘点噪声来源打开 Horizon 仪表盘的已完成列表区分是单一类高频还是多类共享语义决定静默维度单一类用silenced共享标签用silenced_tags并在 config/horizon.php 的silenced [...]中维护校验标签一致性若使用silenced_tags确认目标 Job 的tags()返回字符串或 Eloquent 自动标签格式与数组条目完全一致确认权限模型通过 HorizonServiceProvider.php 的viewHorizonGate 与HORIZON_ALLOWED_EMAILS限制访问面并运行php artisan horizon后在仪表盘中验证过滤效果。【免费下载链接】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），仅供参考 Coolify 中的 Laravel Horizon 任务标签与静默机制（Tags Silencing）实战指南
Coolify 中的 Laravel Horizon 任务标签与静默机制Tags Silencing实战指南【免费下载链接】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在基于 Laravel 的项目中Laravel Horizon 仪表盘是观察后台队列运行状态的窗口而队列任务Job的**标签Tags与静默Silencing**正是这套窗口的筛选与降噪机制。Coolify 作为一个大量依赖异步队列任务的 PaaS 系统在其 config/horizon.php 与 app/Jobs 中完整落地了这一机制。本文以.cursor/skills/configuring-horizon/references/tags.md为核心骨架结合 Coolify 仓库源码项目依赖 composer.json 中laravel/horizon: ^5.48.2、laravel/framework: ^12.65.0系统讲解 Horizon 自动标签规则、自定义tags()方法、以及silenced与silenced_tags两类静默配置帮助你掌握如何给任务打标和如何让吵闹的任务从仪表盘消失这两项核心能力。一、机制总览先在哪个层面理解标签与静默Horizon 的标签tag是记录在每个队列消息 payload 上的字符串数组用于在仪表盘中按类目过滤任务静默silencing则是针对已完成任务列表completed jobs view的展示层过滤。两者有本质区别标签改变的是任务的可检索维度不改变任务的执行行为silenced按任务类隐藏把某个 Job 类加入数组后该类任务不再出现在已完成列表但任务照常运行silenced_tags按标签隐藏任何携带匹配标签字符串的任务都会从已完成列表消失适合对notifications这类一整类任务做集体降噪而不是逐个类去配置。在 Coolify 中这份机制被进一步用于部署链路追踪见下文第三节中tags()方法与 HorizonServiceProvider.php 的联动。关键词检索定位在官方文档中搜索horizon tags可获得标签 API 与自动打标行为搜索horizon silenced jobs可获得silenced与silenced_tags配置选项说明。二、自动标签Eloquent 模型任务的零代码打标核心规则如果某个 Job 的构造函数接收 Eloquent 模型实例Horizon 会自动为该任务打上ModelClass:id格式的标签例如App\Models\User:42。该规则意味着无需在 Job 类里写任何额外代码任务就会携带模型标签这些自动标签可以直接在仪表盘中按标签过滤只有当你需要超越自动标签之外的自定义标签时才需要手写tags()方法。在 Coolify 中的印证Coolify 的部署任务 ApplicationDeploymentJob.php 恰恰展示了一个何时必须自定义标签的典型反例——它的构造函数接收的是int主键而不是模型实例因此不会触发自动打标必须手动补上public function tags() { // Do not remove this one, it needs to properly identify which worker is running the job return [App\Models\ApplicationDeploymentQueue:.$this-application_deployment_queue_id]; } public function __construct(public int $application_deployment_queue_id) { $this-onQueue(deployment_queue()); }这段源码有两点值得注意标签格式保持与 Eloquent 自动打标一致ModelClass:id即使任务只接收主键也能模拟出模型级标签保证仪表盘过滤行为统一注释中的 Do not remove this one 表明该标签已不是纯粹的 UI 装饰而是被上游逻辑强依赖的标识见下一节。三、标签的消费端把标签变成可追踪的业务 ID标签并不只是仪表盘上的分类文字。Coolify 在 HorizonServiceProvider.php 中通过监听JobReserved事件把标签解析成业务主键实现Horizon 任务 ID ↔ 部署队列记录的双向关联Event::listen(function (JobReserved $event) { $payload $event-payload-decoded; $jobName $payload[displayName]; if ($jobName App\Jobs\ApplicationDeploymentJob) { $tags $payload[tags]; $id $payload[id]; $deploymentQueueId collect($tags)-first(function ($tag) { return str_contains($tag, App\Models\ApplicationDeploymentQueue); }); if (blank($deploymentQueueId)) { return; } $deploymentQueueId explode(:, $deploymentQueueId)[1]; $deploymentQueue ApplicationDeploymentQueue::find($deploymentQueueId); $deploymentQueue-update([ horizon_job_id $id, ]); } });从这段实现可以看出标签机制的实战威力任务入队时通过tags()写入的App\Models\ApplicationDeploymentQueue:id标签在任务被 worker 预留reserved时被反向解析回deployment_queue_id再写回ApplicationDeploymentQueue表的horizon_job_id字段从而打通用户侧部署状态与Horizon 侧执行详情两张视图。只要标签规则被改动或移除这段追踪逻辑就会静默失效——这正是源码注释强调标签不可删的原因。四、silenced按任务类隐藏已完成记录silenced是一组任务类名数组配置位置在 config/horizon.php/* |-------------------------------------------------------------------------- | Silenced Jobs |-------------------------------------------------------------------------- | | Silencing a job will instruct Horizon to not place the job in the list | of completed jobs within the Horizon dashboard. This setting may be | used to fully remove any noisy jobs from the completed jobs list. | */ silenced [ // App\Jobs\ExampleJob::class, ],使用要点写法以\App\Jobs\ExampleJob::class形式完整类名加入数组作用范围只影响 Horizon 仪表盘的已完成任务列表任务本身照常排队、执行、重试定位它是仪表盘降噪工具不是禁用任务的手段——若想不让某任务执行应移除其分发调用或调整队列分发逻辑而非依赖silenced适用场景周期性、高频率且无人需要逐条回看结果的任务如各类心跳检查、探活任务、频发的内部清理任务。以 Coolify 为例app/Jobs 目录下大量存在ServerCheckJob、ScheduledTaskJob、SendWebhookJob等高频任务若某一类任务在已完成列表里刷屏且无追溯价值即可放入该数组。当前 config/horizon.php 中该数组为空仅保留示例注释说明 Coolify 默认不静默任何任务全部执行记录都保留在仪表盘中。五、silenced_tags按标签批量隐藏一类任务silenced_tags与silenced的区别在于匹配维度从类名变为标签字符串任何携带匹配标签的任务都会从已完成列表隐藏。因此在配置时需要与第二节的自动打标规则、第三节的自定义tags()返回的标签字符串保持一致。典型用法silenced [ // 按任务类静默 // App\Jobs\NotificationJob::class, ], silenced_tags [ // 按标签静默所有携带 notifications 标签的任务都不出现在已完成列表 notifications, ],决策参考何时用哪一个噪声来自单一任务类→ 用silenced精确、直观、易维护噪声横跨多个任务类、但共享同一业务语义标签例如所有发送类任务统一打notifications标签→ 用silenced_tags一条规则覆盖整类无需随任务类新增而反复改配置两者可同时使用互为补充不会互相排斥。需要留意的是与silenced相同silenced_tags不会阻止任务执行它纯粹是 Horizon 前端展示层的过滤器。此外当前仓库的 config/horizon.php 中尚未声明silenced_tags键仍保持 Laravel Horizon 5.x 的默认行为说明这是留给使用方按需开启的能力动手前建议先检索官方文档中horizon silenced jobs以核对当前版本的选项名与默认值。六、与静默相关的仪表盘权限与运维提醒在实施标签与静默策略时还应一并确认谁有权限查看这些过滤后的仪表盘数据。Coolify 在 HorizonServiceProvider.php 中通过自定义viewHorizonGate 做了精细化授权protected function gate(): void { Gate::define(viewHorizon, function (User $user) { if ($user-id 0) { return true; } return str(config()-string(horizon.allowed_emails)) -lower() -explode(,) -map(fn (string $email) trim($email)) -contains($user-email); }); }其规则为id 0的超级管理员Coolify 的 root 用户始终放行其余用户只有在其邮箱命中 config/horizon.php 中HORIZON_ALLOWED_EMAILS环境变量配置的白名单逗号分隔、大小写不敏感时才能访问。配置静默策略前确认该 Gate可避免已经隐藏了任务却仍被无关人员观察队列的权限隐患。七、小结与落地清单回到.cursor/skills/configuring-horizon/references/tags.md的三个核心论断均可在 Coolify 仓库中得到实现级印证论断实现依据结论Eloquent 模型任务自动打ModelClass:id标签无需额外代码接收模型实例的 Job 自动获得标签Coolify 部署 Job 因只收主键故在 ApplicationDeploymentJob.php 手动补全同名格式标签只有需要自定义标签时才写tags()silenced仅从已完成列表隐藏任务不阻止执行config/horizon.php 注释明确 not place the job in the list of completed jobs它是降噪工具不是禁用开关silenced_tags按匹配标签隐藏所有携带任务与tags()返回的标签字符串联动生效适合按notifications等语义标签批量静默落地时的四步检查清单先盘点噪声来源打开 Horizon 仪表盘的已完成列表区分是单一类高频还是多类共享语义决定静默维度单一类用silenced共享标签用silenced_tags并在 config/horizon.php 的silenced [...]中维护校验标签一致性若使用silenced_tags确认目标 Job 的tags()返回字符串或 Eloquent 自动标签格式与数组条目完全一致确认权限模型通过 HorizonServiceProvider.php 的viewHorizonGate 与HORIZON_ALLOWED_EMAILS限制访问面并运行php artisan horizon后在仪表盘中验证过滤效果。【免费下载链接】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），仅供参考