# 就在 任务抛出异常的瞬间 。

> 后台任务或 Worker 失败时，立刻收到推送通知。把 Pocket Alert 接入 Sidekiq、Celery、Laravel 队列或 BullMQ，Worker 失败的告警会第一时间送达你的手机。

<!-- source: https://pocketalert.app/zh/use-cases/background-job-alerts -->

最后更新：2026-08-11

在 Sidekiq、Celery、Laravel 或 BullMQ 的任务失败钩子中调用 Pocket Alert。worker 抛出异常时，任务名称、参数和异常信息会一并推送到你的手机；关键任务完成时，也会收到完成通知。

## 三步搞定后台任务告警

1. **获取 API 密钥或 CLI** — 创建 API 密钥，或为基于 shell 的 worker 安装 Pocket Alert CLI。
2. **接入失败钩子** — 在队列框架的失败钩子中调用 Pocket Alert，并传入任务名称和错误信息。
3. **捕获失效的 worker** — 触发一次失败的任务。你的手机会震动，告诉你哪个 worker 挂了以及原因。

## 不再错过任何失效的 worker

悄无声息死掉的 worker 会连带拖垮你的任务。worker 一旦抛出异常，你就会收到通知。

- **接入任意队列** — Sidekiq、Celery、Laravel、BullMQ 和 Hangfire 都可以通过你已有的失败钩子调用 Pocket Alert。
- **失败时告警** — 接入死亡处理器后，只有失败的任务才会通知你。
- **完整的失败上下文** — 任务类、参数和异常信息都包含在消息中，无需打开追踪工具就能快速排查。
- **确认任务已执行** — 为关键任务发送完成通知。如果每晚的导入没有通知，说明它已经停止运行。
- **每个 worker 一个频道** — 为每个 worker 分配独立的应用，卡住的队列会出现在一眼就能识别的频道中。
- **抛出即时通知** — worker 抛出异常后，推送几乎立刻到达你的手机，远早于你想起去查看日志的时候。

## 直接从任务处理器发送告警

### Laravel 队列 —— failed() 钩子

```
public function failed(Throwable $e): void
{
    Http::withHeaders(['Token' => 'YOUR_API_KEY'])
        ->post('https://api.pocketalert.app/v1/messages', [
            'title' => 'Job failed: ' . class_basename($this),
            'message' => $e->getMessage(),
            'level' => 'critical',
        ]);
}
```

### Sidekiq —— 死亡处理器

在 `config/initializers/sidekiq.rb` 中，重试次数耗尽后触发：

```
Sidekiq.configure_server do |config|
  config.death_handlers << ->(job, ex) do
    Net::HTTP.post(
      URI('https://api.pocketalert.app/v1/messages'),
      { title: "Job died: #{job['class']}",
        message: "jid #{job['jid']}: #{ex.message}" }.to_json,
      'Token' => 'YOUR_API_KEY', 'Content-Type' => 'application/json')
  end
end
```

### Celery —— task_failure 信号

```
import requests
from celery.signals import task_failure

@task_failure.connect
def notify_failure(sender=None, task_id=None, exception=None, **kw):
    requests.post(
        'https://api.pocketalert.app/v1/messages',
        headers={'Token': 'YOUR_API_KEY'},
        json={'title': f'Task failed: {sender.name}',
              'message': f'{task_id}: {exception}'})
```

### BullMQ —— worker 的 failed 事件

```
worker.on('failed', async (job, err) => {
  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { 'Token': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: `Job failed: ${job?.name}`,
      message: `${job?.id}: ${err.message}`,
    }),
  });
});
```

[文档](https://info.pocketalert.app/getting-started.html)介绍了如何指定特定应用或设备。

## 常见问题

### 如何为失败的后台任务设置告警？

在任务的失败处理器或 rescue 代码块中调用 Pocket Alert API 或 CLI。worker 抛出异常时，会向你的手机发送一条推送通知，附带任务名称和错误信息。

### 能否接入队列框架？

可以。大多数队列框架都提供失败回调，例如 Sidekiq 的死亡处理器、Celery 的 task_failure，以及 Laravel 的 failed()。把 Pocket Alert 的调用放在这些位置，只有真正的失败才会通知你。

### 能否附带任务和错误信息？

在消息正文中包含任务类、参数和异常信息。告警会告诉你哪个任务失败了以及原因，通常无需再去错误追踪工具里翻找。

### 支持哪些队列系统？

Sidekiq、Resque、Celery、RQ、Laravel 队列、BullMQ、Hangfire 和 Kubernetes Jobs 都可以通过失败钩子或非零退出码接入。

### 能否确认任务确实执行了？

为关键任务发送完成通知。如果每晚的导入任务一直没有发来通知，worker 很可能在没有报错的情况下停止了处理。

### worker 失效告警能否突破勿扰模式？

可以。在失败钩子中传入 level=critical，Android 会通过绕过勿扰模式的通道发送推送，iPhone 则以时间敏感通知的形式投递，可穿透专注模式。日常任务的完成通知可以使用 level=silent，仅保留在历史记录中，不发出声音。
