Laravel 如何监控和管理失败的队列任务（Failing Jobs）

Laravel 对失败任务有 内置支持，并且可以扩展做监控、告警与后台管理。

1. 开启失败队列任务记录

Laravel 通过 failed_jobs 表记录失败任务。

步骤 ①：生成失败任务记录表

php artisan queue:failed-table
php artisan migrate

生成的表会记录：

• connection
• queue
• payload（任务内容）
• exception（错误堆栈）
• failed_at（失败时间）

2. 使任务自动进入失败队列

Laravel 在任务执行 达到最大重试次数 或 抛出异常 时，会将其写入 failed_jobs。

你可以在 Job 中定义最大尝试次数：

public $tries = 3;

或者设置最大执行时间：

public $timeout = 120;

3. 使用 failed() 方法处理任务失败回调

在 Job 类中添加 failed() 方法：

public function failed(\Throwable $exception)
{
    // 失败后的自定义操作
    Log::error('队列任务失败：', [
        'job' => static::class,
        'error' => $exception->getMessage()
    ]);

    // 也可以触发通知、钉钉告警、邮件告警等
}

失败后 Laravel 会自动调用它。

4. 查看失败任务

命令方式（开发阶段常用）

查看所有失败任务：

php artisan queue:failed

查看某个任务详情：

php artisan queue:failed {id}

5. 重试失败任务

重试单个任务：

php artisan queue:retry {id}

重试所有任务：

php artisan queue:retry all

6. 删除失败任务

删除所有失败任务：

php artisan queue:flush

删除单个：

php artisan queue:forget {id}

7. 队列实时监控方式（推荐）

Laravel 内置 horizon，可以做监控大屏。

📌 方案 A：使用 Laravel Horizon（Redis 队列推荐）

如果你使用 redis 队列，强烈推荐 Horizon：

composer require laravel/horizon
php artisan horizon:install
php artisan migrate

启动：

php artisan horizon

访问：

/horizon

Horizon 提供：

✔ 队列任务吞吐性能

✔ 失败任务统计

✔ 每分钟的失败率

✔ Worker 状态

✔ 自动重启

✔ 可配置预警（Slack/钉钉/Webhook）

这是 Laravel 官方唯一的企业级监控面板。

📌 方案 B：自定义管理后台（用于 PC 管理后台）

一般管理后台需要展示以下内容：

后台常见列表项

• 任务 ID
• 任务类型
• 所属队列
• 数据（payload）
• 错误堆栈（缩略展示）
• 创建时间 / 失败时间
• 操作：重试、删除、查看详情

获取失败任务数据

你可以直接访问数据库：

$jobs = DB::table('failed_jobs')->orderBy('failed_at', 'desc')->paginate(20);

重试任务：

Artisan::call("queue:retry", [
    'id' => $id
]);

删除失败任务：

Artisan::call("queue:forget", [
    'id' => $id
]);