# Prometheus Alertmanager 告警推送到手机：按严重级别路由、告警分组与静默恢复通知

> 将 Prometheus Alertmanager 告警以手机推送通知的形式发送到 iPhone 和 Android。每个告警组推送一条，严重告警响亮提醒，警告为普通通知，恢复通知保持安静。附经过测试的 alertmanager.yml、示例规则，以及何时该选用 Alertmanager 0.32 的 payload 选项。

*29.10.2026*

<!-- source: https://pocketalert.app/zh/blog/prometheus-alertmanager-notifications -->

Prometheus 很擅长发现问题出了状况。把这个消息告诉真人，则是 Alertmanager 的工作。在很多部署里，这条消息最后只落进了一个没人会在凌晨 3 点去看的邮件文件夹或 Slack 频道。

Alertmanager 没有自己的推送应用，但它有一个通用的 Webhook 接收器，这就够用了，你可以把告警推送到手机上。本指南会配置严重级别路由：`critical` 告警以响亮的方式到达，警告以普通通知到达，"已恢复"则安静地到达。这里的所有内容都在 Docker 中使用 Alertmanager 0.34.2 和 Prometheus 3.15.1 测试过。负载内容已被捕获，并通过 Pocket Alert 自己的模板代码运行过。

## 你需要准备

- 完整配置需要 Alertmanager 0.31 或更高版本。较旧的版本在下文中也有说明。
- 你的 [iPhone 或 Android](/get-app) 手机上安装 Pocket Alert 应用，并在 [API 密钥](/account/apikeys) 页面获取一个 API 密钥。
- 三个 Webhook 的配置需要付费套餐，因为免费套餐只包含一个 Webhook。文末有单 Webhook 的版本。

## Alertmanager 发送什么

Alertmanager 不会为每条告警单独发送一次请求。它会按 `group_by` 中的标签把告警收集成组，每组发送一条通知：一个 POST 请求，请求体是固定的 JSON，其中 `"version": "4"`。当 `group_by: ['alertname']` 下两台主机同时宕机时，只会发出一次请求。下面是稍作裁剪后的内容：

```json
{
  "receiver": "pocketalert-critical",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {"alertname": "InstanceDown", "instance": "web-1:9100", "job": "node", "severity": "critical"},
      "annotations": {"summary": "web-1:9100 is down"},
      "startsAt": "2026-10-31T16:17:04.374Z",
      "generatorURL": "http://prometheus.example.com:9090/graph?g0.expr=up%7Bjob%3D%22node%22%7D+%3D%3D+0&g0.tab=1"
    },
    {
      "status": "firing",
      "labels": {"alertname": "InstanceDown", "instance": "web-2:9100", "job": "node", "severity": "critical"},
      "annotations": {"summary": "web-2:9100 is down"}
    }
  ],
  "notification_reason": "first notification",
  "groupLabels": {"alertname": "InstanceDown"},
  "commonLabels": {"alertname": "InstanceDown", "job": "node", "severity": "critical"},
  "commonAnnotations": {},
  "routeLabels": {},
  "externalURL": "http://alertmanager.example.com:9093",
  "version": "4",
  "groupKey": "{}/{severity=\"critical\"}:{alertname=\"InstanceDown\"}",
  "truncatedAlerts": 0
}
```

这种负载结构有四点会影响配置：

- **每组推送一条。** 各条告警位于 `alerts` 数组中，因此消息模板必须能处理数组。
- **`commonAnnotations` 经常是空的。** 它只包含组内每条告警都相同的注解。提到实例名的摘要在每条告警上都不同，所以不会出现在这里。
- **`status` 属于整个组。** 只有组内所有告警都已恢复时，它才是 `resolved`。当一台主机恢复而另一台仍在宕机时，状态保持为 `firing`，已恢复的告警会列在内部，并带有各自的 `"status": "resolved"`。
- **顶层没有 `level` 字段**，而 Pocket Alert 的 Webhook 正是从这里查找优先级。因此优先级来自 Webhook 的默认级别，这也是本指南为每种响亮程度各配一个 Webhook 的原因。

## 第 1 步：创建 Pocket Alert Webhook

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Webhook</th><th><code>default_level</code></th><th>接收内容</th></tr></thead>
<tbody>
<tr><th>Prometheus critical</th><td><code>2</code>（critical）</td><td>带有 <code>severity="critical"</code> 的触发中告警组</td></tr>
<tr><th>Prometheus warning</th><td><code>0</code>（默认）</td><td>所有其他触发中的告警组</td></tr>
<tr><th>Prometheus resolved</th><td><code>-1</code>（low）</td><td>组内所有告警均已恢复的告警组</td></tr>
</tbody>
</table>
</div>

按钮只能通过 API 设置，因此用一个脚本创建全部三个 Webhook：

```bash
PA_KEY='your-api-key'

FIRING='%groupLabels.alertname%: %alerts.#(status=="firing")#|#% firing
%alerts.#(status=="firing").annotations.summary%
Firing: %alerts.#(status=="firing")#.labels.instance%'

RESOLVED='Resolved: %groupLabels.alertname% (%commonLabels.severity%)
%alerts.#.labels.instance%'

BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"}]'

create_webhook() {
  jq -n --arg name "$1" --argjson level "$2" --arg message "$3" --arg actions "$4" \
    '{name: $name, default_level: $level, message: $message, actions: $actions}' |
  curl -sS https://api.pocketalert.app/v1/webhooks \
    -H "Token: $PA_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- |
  jq -r '"\(.name): https://p4a.me/wh/\(.url)"'
}

create_webhook 'Prometheus critical' 2 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus warning' 0 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus resolved' -1 "$RESOLVED" ''
```

脚本会输出三个接收 URL。请保留每个 URL 末尾的 slug，你之后要把这些 slug 填入 `alertmanager.yml`。

`%...%` 占位符是 [GJSON 路径](https://info.pocketalert.app/api/webhooks/settings)，而 GJSON 可以查询数组：

- `alerts.#(status=="firing")#|#` 统计组内仍在触发的告警数量。
- `alerts.#(status=="firing").annotations.summary` 是第一条触发中告警的摘要。
- `alerts.#(status=="firing")#.labels.instance` 列出所有触发中告警的实例。它会渲染为 JSON 数组，例如 `["web-1:9100","web-2:9100"]`，因为没有字符串拼接函数。

不存在的路径会渲染为空字符串，所以路径写错只会得到一个空行，而不会丢失告警。Pocket Alert 会把每条 Webhook 推送的标题设为 `Webhook <name>`，因此标题显示为 "Webhook Prometheus critical"，告警名称则位于消息的第一行。`critical` 需要付费套餐，而这个配置本来就需要付费套餐才能使用三个 Webhook。在 iPhone 上，它会无视静音开关和勿扰模式播放；在 Android 上则会占满屏幕。如果你不希望告警覆盖勿扰模式，改用 `1`（high）。

## 第 2 步：alertmanager.yml

把三个 `*_SLUG` 占位符替换为你的 slug：

```yaml
route:
  receiver: pocketalert-warning
  group_by: ['alertname']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h
  routes:
    - matchers: ['severity="critical"']
      receiver: pocketalert-critical
      group_wait: 10s
      repeat_interval: 1h
    - matchers: ['severity="info"']
      receiver: blackhole

receivers:
  - name: pocketalert-critical
    webhook_configs:
      - url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}CRITICAL_SLUG{{ end }}'
        send_resolved: true
        max_alerts: 20
  - name: pocketalert-warning
    webhook_configs:
      - url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}WARNING_SLUG{{ end }}'
        send_resolved: true
        max_alerts: 20
  - name: blackhole

inhibit_rules:
  - source_matchers: ['severity="critical"']
    target_matchers: ['severity="warning"']
    equal: ['alertname', 'instance', 'mountpoint']
```

各部分的工作方式如下：

- **按严重级别路由。** `severity="critical"` 进入响亮的接收器，`info` 被丢弃，其他所有告警（包括没有 `severity` 标签的告警）都落到警告接收器。
- **URL 决定使用哪个 Webhook。** 从 0.31.0 开始，Webhook 的 `url` 是模板。状态为 `resolved` 的告警组会发往安静的 Webhook，其他一切都发往该接收器自己的 Webhook。Webhook 的 `send_resolved` 默认就是 `true`，这里把它写出来，是为了让人不会在不知情的情况下把它关掉。
- **`max_alerts: 20`** 限制一次请求中包含的告警数量。在测试中，25 台主机同时宕机，结果产生了一条显示 "20 firing" 的推送，负载中的 `truncatedAlerts: 5` 表示还有 5 条被省略。
- **抑制。** 当某文件系统的 critical `DiskSpaceLow` 触发时，同一 `alertname`、`instance` 和 `mountpoint` 的警告会被静音。`amtool alert query --inhibited` 会将其显示为 `suppressed`。

重新加载前，先检查配置和路由：

```bash
amtool check-config alertmanager.yml
amtool config routes test --config.file=alertmanager.yml severity=critical alertname=Test
```

第二条命令会输出 `pocketalert-critical`。

启动 Alertmanager 时，请将 `--web.external-url` 设为你能在手机上打开的地址。如果不设置，`externalURL` 就只是裸主机名。在 Docker 中，它是 `http://de48ea5ffc29:9093`，这样生成的按钮毫无用处。

### 先检查版本

`alertmanager --version` 必须显示 0.31 或更高版本，模板化 URL 才能生效。0.30.1 版本可以接受这份完全相同的配置，`amtool check-config` 也会报告 SUCCESS，但它不会渲染模板。它会把请求发送到 `/wh/%7B%7B%20if%20eq%20.Status...`，而这与任何 Webhook 都不匹配。在较旧的版本上，请为每个接收器填写其对应 Webhook 的普通 URL。这样恢复通知就会以该 Webhook 的级别到达。

## 第 3 步：带有 severity 标签的规则

上面的路由只有在你的规则设置了 `severity` 时才有效。这里给出两个示例（更多值得监控的内容可参考[服务器监控](/use-cases/server-monitoring)页面）。其中 `DiskSpaceLow` 设置了两个阈值，这样抑制规则才有作用：

```yaml
groups:
  - name: node
    rules:
      - alert: InstanceDown
        expr: up{job="node"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: '{{ $labels.instance }} is down'

      - alert: DiskSpaceLow
        expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 15
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'

      - alert: DiskSpaceLow
        expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 5
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'
```

`promtool check rules rules.yml` 可以校验该文件。在 `prometheus.yml` 中让 Prometheus 指向该文件以及 Alertmanager：

```yaml
rule_files: [rules.yml]
alerting:
  alertmanagers:
    - static_configs:
        - targets: ['alertmanager:9093']
```

## 用 amtool 测试

触发一条测试告警，等待 `group_wait`（critical 路由上为 10 秒），然后将其恢复：

```bash
amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
  --annotation='summary="Test alert from amtool"'

amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
  --annotation='summary="Test alert from amtool"' --end="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
```

注解中的内层双引号要保留，否则 amtool 会警告它已回退到旧的解析器。恢复推送会在下一个 `group_interval` 周期到达，在此配置下最多可能需要 5 分钟。

## 手机上会收到什么

以下是 Pocket Alert 根据测试中的真实负载渲染出的消息。测试中 Prometheus 观察到 `web-1` 和 `web-2` 宕机并恢复：

```text
Webhook Prometheus critical
InstanceDown: 2 firing
web-1:9100 is down
Firing: ["web-1:9100","web-2:9100"]
```

当 `web-1` 恢复时，Alertmanager 会在下一个 `group_interval` 发送一次更新。该组仍在触发，因此它会发往 critical Webhook：

```text
Webhook Prometheus critical
InstanceDown: 1 firing
web-2:9100 is down
Firing: ["web-2:9100"]
```

两者都恢复后，会收到一条低优先级推送：

```text
Webhook Prometheus resolved
Resolved: InstanceDown (critical)
["web-1:9100","web-2:9100"]
```

## 计时器：避免推送风暴

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>设置</th><th>作用</th><th>本配置中的值</th></tr></thead>
<tbody>
<tr><th><code>group_wait</code></th><td>新告警组在发出第一条推送前等待更多告警的时长</td><td>30s，critical 为 10s</td></tr>
<tr><th><code>group_interval</code></th><td>告警内容发生变化的告警组，两次推送之间的最短间隔</td><td>5m</td></tr>
<tr><th><code>repeat_interval</code></th><td>仍在触发且内容未变化的告警组的提醒间隔</td><td>4h，critical 为 1h</td></tr>
</tbody>
</table>
</div>

一个告警组每个 `group_interval` 最多推送一次，因此一个反复抖动的告警在 5m 间隔下每小时最多产生 12 条推送。持续一天的故障，在 1h 的 `repeat_interval` 下会产生 24 次提醒。分组承担了大部分工作：一台交换机故障导致 40 台主机宕机，只会产生一条推送，而不是 40 条。不要使用 `group_by: ['...']`，它会按每个标签分组，这样又会退回到每条告警一条推送。各套餐都有[每日消息上限](https://info.pocketalert.app/features/daily-limits)（Starter 为每天 1,000 条），而每一次生成消息的 Webhook 请求都会计入上限。

## 按钮：Alertmanager 与 Grafana

上面的 `BUTTONS` 模板会添加一个 "Alertmanager" 按钮。你最多可以添加三个[操作按钮](/features/action-buttons)。下面这个示例会为第一个触发中的实例打开 Grafana 仪表板：

```bash
BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"},{"type":"view","label":"Grafana","value":"https://grafana.example.com/d/YOUR_DASHBOARD?var-instance=%alerts.#(status=="firing").labels.instance%"}]'
```

占位符内未转义的引号看起来有问题，但实际可以正常工作：Pocket Alert 会先替换占位符，之后再解析 JSON。

注意空值。`value` 为空的按钮会从该条推送中被丢弃，其他按钮和消息仍会正常到达。`%alerts.0.generatorURL%`（Prometheus 图表链接）很适合用于来自 Prometheus 的告警，但通过 amtool 发送的告警没有 generator URL，因此不会带有该按钮。操作按钮是付费功能。

## Alertmanager 0.32+：直接调用 API

较旧的指南说 Alertmanager 无法修改 Webhook 请求体。这一点在 0.32.0 中发生了变化，该版本为 `payload` 新增了 `webhook_configs` 选项。再配合可以发送 `http_config.http_headers` 请求头的 `Token`，Alertmanager 就可以直接 POST 到 `https://api.pocketalert.app/v1/messages`，并使用它自己的标题和级别。

这里有一个陷阱。Alertmanager 会把渲染后的每个值当作 YAML 解析。在测试中，逐字段构造的负载 `message: '{{ range .Alerts }}{{ .Annotations.summary }}...'` 把摘要 `web-1:9100: / has 12% free` 变成了对象 `{"web-1:9100": "/ has 12% free"}`。API 会以 `400` 拒绝它。Alertmanager 不会立即重试 `4xx`，而是在每个 `group_interval` 反复发送同一个错误的请求体，因此告警永远不会到达。

使用 `dict` 和 `toJson` 构造整个请求体可以避免这个问题：

```yaml
receivers:
  - name: pocketalert-api
    webhook_configs:
      - url: https://api.pocketalert.app/v1/messages
        http_config:
          http_headers:
            Token:
              files: [/etc/alertmanager/pocketalert.key]
        payload: >-
          {{ $msg := "" }}{{ range .Alerts }}{{ $msg = printf "%s%s: %s\n" $msg .Status .Annotations.summary }}{{ end }}
          {{ $level := "default" }}{{ if eq .Status "resolved" }}{{ $level = "low" }}{{ else if eq .CommonLabels.severity "critical" }}{{ $level = "critical" }}{{ end }}
          {{ dict "title" (printf "[%s] %s" (toUpper .Status) .GroupLabels.alertname) "message" $msg "level" $level | toJson }}
```

当摘要中包含冒号和引号时，它发送了：

```json
{"level":"critical","message":"firing: web-1:9100: / has 4% free, \"quoted\"\nfiring: web-2:9100 / has 3% free\n","title":"[FIRING] DiskSpaceLow"}
```

恢复版本则以 `"level":"low"` 到达。

那么该选哪一种？直接调用 API 可以为每条通知提供真实的标题和级别，所有通知都来自同一个接收器，且不需要 Webhook。Webhook 方式在 Alertmanager 中完全不需要 API 密钥，并且可在任何版本上运行（即普通 URL 的变体）。错误的路径会渲染为空行，而不是被拒绝的请求，而且每个请求都会出现在 [Webhook 历史](/features/webhook-history)中。Alertmanager 自己的文档将 `payload` 标注为"风险自担"，因此在依赖它之前，请先用 amtool 测试。

## 免费套餐

免费套餐包含一个 Webhook、每天 50 条消息、没有按钮，并且 `critical` 会以 `high` 级别投递。创建一个 `default_level: 1` 的 Webhook，将其普通 URL 填入单个接收器，并删除严重级别路由。这样恢复通知也会以 `high` 级别到达，除非你设置 `send_resolved: false`。在 Alertmanager 0.32+ 上，免费套餐更适合使用上面的直接 API 配置，因为它不需要 Webhook，并且可以为每条通知设置级别。

## 如果没有收到任何消息

- **查看 Alertmanager 日志。** 投递失败时会记录 `Notify for alerts failed` 以及状态码。`404` 表示 slug 错误，或者在 0.31 之前的版本上使用了模板化 URL。
- **打开 Pocket Alert 中的 Webhook 历史。** 如果请求在那里，问题出在模板。如果不在，说明 Alertmanager 根本没有发送。
- **空行**意味着某个路径与负载不匹配。字段名区分大小写。
- **紧挨占位符前的 `%` 需要双写。** `%` 后面跟空格时是普通文本，因此 `CPU over 90% on %groupLabels.alertname%` 可以正常工作。当 `%%` 紧贴其他文本时需要写成 `%`，例如 `%commonLabels.usage%%%`。
- 在编写模板之前，使用 [Webhook 测试工具](/tools/webhook)捕获你的 Alertmanager 实际发送的内容。

## 常见问题

### 这能用于 kube-prometheus-stack 吗？

可以。接收器是普通的 Alertmanager 配置，因此像其他接收器一样放入 chart 的 Alertmanager 配置中即可。在使用模板化 URL 或 `payload` 之前，请先确认该 chart 部署的是哪个 Alertmanager 版本。集群相关内容见 [Kubernetes 告警](/use-cases/kubernetes-alerts)。

### 我用的是 Grafana 告警，而不是 Alertmanager，有什么不同？

Grafana 会发送它自己的 Webhook 格式。请参阅 [Grafana 指南](/blog/how-to-integrate-grafana-into-pocketalert)。

[创建免费账户](/signup)，运行脚本，将三个 slug 填入 `alertmanager.yml`，下一次 `InstanceDown` 就会到达你的手机。
