# Uptime Kuma 推送通知到手机：宕机时响铃，恢复时静音

> 通过 Uptime Kuma 内置的 Webhook 通知，把宕机和恢复告警推送到 iPhone 和 Android。宕机以高优先级送达，恢复静默通知，证书过期单独推送，重试机制避免抖动的检测把手机刷爆。

*26.10.2026*

<!-- source: https://pocketalert.app/zh/blog/uptime-kuma-notifications -->

Uptime Kuma 很擅长发现服务宕机，但告警最后送到哪里是另一回事。大多数人把它发到 Telegram 群、Discord 频道或邮件文件夹，和一天里其他所有让手机震动的消息混在一起。而且"恢复"消息和"宕机"消息的提醒方式完全一样，几个晚上连续抖动之后，人们就会把频道静音，再也不看。

本指南把 Uptime Kuma 的告警以不同优先级推送到 Pocket Alert。监控宕机时以 `high` 发送，它能穿透 iPhone 的专注模式。恢复时以 `low` 发送：你看的时候它会出现在消息列表里，但不会打扰任何人。全部配置都使用 Uptime Kuma 内置的 **Webhook** 通知类型，无需额外安装任何东西。

以下所有步骤都在 Docker 中运行的 Uptime Kuma 2.5.8 上测试过。

## 准备工作

- Uptime Kuma 2.x。大部分内容在 1.23.x 上同样适用，差异会在最后说明。
- 手机上安装 Pocket Alert [应用](/get-app)，并拥有一个账户。如果还没有，请[注册](/signup)，免费套餐足够入门。
- 从 [API 密钥](/account/apikeys)获取一个 API 密钥（方式 1），或从 [Webhooks](/webhooks) 获取一个 webhook 地址（方式 2）。

## 两种连接方式

Uptime Kuma 的 Webhook 通知可以向任意 URL 发送请求，请求体可以用它自带的 JSON，也可以用你自己编写的内容。因此有两种方式：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th></th><th>方式 1：Pocket Alert API</th><th>方式 2：Pocket Alert webhook 地址</th></tr></thead>
<tbody>
<tr><th>发送地址</th><td><code>https://api.pocketalert.app/v1/messages</code></td><td><code>https://p4a.me/wh/&lt;slug&gt;</code></td></tr>
<tr><th>推送标题</th><td>自定义，例如 <strong>Down: Website</strong></td><td>固定为 <strong>Webhook &lt;name&gt;</strong></td></tr>
<tr><th>宕机响铃，恢复静音</th><td>支持</td><td>支持，需要自定义请求体；否则所有消息都是同一级别</td></tr>
<tr><th>Uptime Kuma 中保存的密钥</th><td>拥有账户完整权限的 API 密钥</td><td>一个只能通过该 webhook 创建推送的地址</td></tr>
<tr><th>Pocket Alert 中的请求日志</th><td>无</td><td>有，见 <a href="/zh/features/webhook-history">webhook 历史</a></td></tr>
</tbody>
</table>
</div>

**如果你想要可读性更好的标题、配置步骤最少，选方式 1。** 如果你不想在 Uptime Kuma 里保存完整的 API 密钥（它会把通知设置，包括请求头，以明文 JSON 存在数据库中），或者你希望在 Pocket Alert 端记录它发出的每一个请求以便调试，选方式 2。

## 方式 1：直接发送到 Pocket Alert API

在 Uptime Kuma 中打开 **设置 → 通知**，点击 **Set Up Notification**，按如下方式填写：

- **Notification Type：** Webhook
- **Friendly Name：** `Pocket Alert`
- **Post URL：** `https://api.pocketalert.app/v1/messages`
- **HTTP Method：** POST
- **Request Body：** Custom Body

把下面的内容粘贴到请求体字段中，并将 `kuma.example.com` 替换为你的 Uptime Kuma 地址：

```
{%- assign level = "default" -%}
{%- assign title = "Uptime Kuma" -%}
{%- assign text = msg -%}
{%- if heartbeatJSON -%}
  {%- assign text = heartbeatJSON.msg | default: msg -%}
  {%- if heartbeatJSON.status == 0 -%}
    {%- assign title = "Down: " | append: monitorJSON.name -%}
    {%- assign level = "high" -%}
    {%- for tag in monitorJSON.tags -%}
      {%- if tag.name == "critical" -%}{%- assign level = "critical" -%}{%- endif -%}
    {%- endfor -%}
  {%- else -%}
    {%- assign title = "Up: " | append: monitorJSON.name -%}
    {%- assign level = "low" -%}
  {%- endif -%}
{%- elsif msg contains "will expire" -%}
  {%- assign title = "Expiring soon" -%}
{%- endif -%}
{
  "title": {{ title | json }},
  "message": {{ text | json }},
  "level": "{{ level }}",
  "actions": [
    {
      "type": "view",
      "label": "Open in Uptime Kuma",
      "value": "https://kuma.example.com/dashboard/{{ monitorJSON.id }}"
    }
  ]
}
```

然后开启 **Additional Headers**，粘贴：

```json
{
  "Token": "YOUR_API_KEY",
  "Content-Type": "application/json"
}
```

请求体的作用如下：

- **请求体是一个 Liquid 模板。** Uptime Kuma 会传入 `msg`（它现成的文本）、`monitorJSON`（监控项）和 `heartbeatJSON`（状态发生变化的检测）。`heartbeatJSON.status` 宕机时为 `0`，恢复时为 `1`。
- **`| json` 会输出一个完整的 JSON 字符串，包括引号。** 错误信息和监控名称里可能含有引号和反斜杠，使用这个过滤器后它们不会破坏请求。名为 `Bob's "main" site` 的监控项也能生成合法的 JSON。
- **宕机为 `high`，恢复为 `low`。** `high` 在 iPhone 上属于时效性通知，能穿透专注模式和定时摘要。`low` 送达时不会打断你。
- **给监控项打上 `critical` 标签可以让提醒更响。** 在 Uptime Kuma 中为最重要的监控项添加名为 `critical` 的标签，它们的宕机告警会以 `critical` 发送，即使开启静音开关或勿扰模式也会响。关键告警是付费功能；在免费套餐中会以 `high` 送达。
- **证书和测试消息没有检测记录。** 对于这些消息，推送会使用 Uptime Kuma 自带的文本作为内容。当检测消息为空时（例如 ping 监控恢复时），也会回退使用这段文本；API 会拒绝内容为空的推送。
- **按钮会打开监控项。** `/dashboard/<id>` 是 Uptime Kuma 中该监控项的页面。证书警告没有监控项 ID，此时按钮会改为打开控制台。操作按钮是付费功能；在免费套餐中，API 会丢弃按钮，推送仍会送达，只是不带按钮。关于操作按钮还能做什么，见[操作按钮](/features/action-buttons)。

**不要跳过 `Content-Type` 请求头。** Uptime Kuma 发送自定义请求体时，如果你不另外指定，它会标记为 `application/x-www-form-urlencoded`。这是我测试时它实际发送的类型。Pocket Alert API 只接受 JSON 或 multipart，遇到这种请求会返回 `400`。

点击 **Test**。几秒钟内应该会收到一条标题为 "Uptime Kuma"、内容为 "Pocket Alert Testing" 的推送。然后保存。

下面是 Uptime Kuma 2.5.8 实际发出的一次宕机和恢复的内容：

```json
{
  "title": "Down: Website",
  "message": "timeout of 4000ms exceeded",
  "level": "high",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
```

```json
{
  "title": "Up: Website",
  "message": "200 - OK",
  "level": "low",
  "actions": [
    { "type": "view", "label": "Open in Uptime Kuma", "value": "https://kuma.example.com/dashboard/1" }
  ]
}
```

建议为 Uptime Kuma 单独创建一个以它命名的 API 密钥，这样如果那台服务器被入侵，你可以单独撤销它。

## 方式 2：Pocket Alert webhook 地址

这种方式下，Uptime Kuma 把自己的 JSON 发送到 Pocket Alert webhook，由 Pocket Alert 端的模板把它转换成推送。

### 创建 webhook

按钮模板只能通过 API 设置，所以最快的方法是一次调用。它会创建一个名为 "Uptime Kuma" 的 webhook，带有消息模板、默认级别 `high`（`1`）和 "Open in Uptime Kuma" 按钮，然后输出接收地址：

```bash
PA_KEY='your-api-key'
KUMA_URL='https://kuma.example.com'

jq -n --arg kuma "$KUMA_URL" '{
  name: "Uptime Kuma",
  message: "%msg%",
  default_level: 1,
  actions: ([{type: "view", label: "Open in Uptime Kuma", value: ($kuma + "/dashboard/%monitor.id%")}] | tojson)
}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'
```

如果你更习惯点击操作，可以在控制台的 [Webhooks](/webhooks) 页面创建：名称填 **Uptime Kuma**，**Default priority** 选 High，消息填 `%msg%`。这样得到的推送与上面相同，只是没有按钮。

### 让 Uptime Kuma 指向它

新建一个类型为 **Webhook** 的通知，将接收地址粘贴为 **Post URL**，并把 **Request Body** 设为 **Preset - application/json**。不需要任何请求头：这个 URL 本身就是密钥，请像对待密码一样保管它。不要选择 multipart 预设；Pocket Alert webhook 只读取 JSON。

监控项宕机时，我的测试环境中 Uptime Kuma 发送了以下内容（已裁剪；`monitor` 对象实际有大约一百个字段）：

```json
{
  "heartbeat": {
    "monitorID": 1,
    "status": 0,
    "time": "2026-10-31 16:09:56.331",
    "msg": "timeout of 4000ms exceeded",
    "important": true,
    "localDateTime": "2026-10-31 16:09:56"
  },
  "monitor": {
    "id": 1,
    "name": "Website",
    "url": "http://tls-target/",
    "type": "http",
    "tags": []
  },
  "msg": "[Website] [🔴 Down] timeout of 4000ms exceeded"
}
```

模板 `%msg%` 使用顶层的 `msg`，因为它是每个请求中都存在的唯一字段。对于证书警告和测试消息，`heartbeat` 和 `monitor` 为 `null`，只有 `msg` 有值。推送的标题为 "Webhook Uptime Kuma"，内容为 "[Website] [🔴 Down] timeout of 4000ms exceeded"。路径缺失的占位符会渲染为空字符串，因此在证书警告中，按钮会指向 `/dashboard/`，仍然可以正常使用。

### 方式 2 中的宕机响铃，恢复静音

使用 JSON 预设时，每个请求都会使用 webhook 的默认级别，因此恢复和宕机的提醒强度一样。要解决这个问题，把 **Request Body** 改为 **Custom Body**，并自己发送 `level` 字段。Pocket Alert webhook 会先读取负载中顶层的 `level`，没有时才回退到默认级别：

```
{
  "level": "{% if heartbeatJSON %}{% if heartbeatJSON.status == 0 %}high{% else %}low{% endif %}{% else %}default{% endif %}",
  "msg": {{ msg | json }},
  "monitor": { "id": "{{ monitorJSON.id }}" }
}
```

请求体保留了 `msg` 和 `monitor.id` 这两个字段名，因此 webhook 的消息模板和按钮模板无需修改即可使用。无论 `Content-Type` 是什么，Pocket Alert webhook 都会把请求体当作 JSON 读取，所以这种方式不需要额外的请求头。

## 为每个监控项启用

通知不会自动生效，必须有监控项使用它才行。在通知表单底部有两个开关：

- **Default enabled** 会让此通知在你之后创建的每个监控项上默认勾选。
- **Apply on all existing monitors** 会把它添加到你已有的所有监控项上。它只在保存时执行一次，之后不会记住这个设置。

第一次保存时两个都打开。如果想让某个监控项不使用此通知，打开它的编辑表单，取消勾选该通知即可。

## 证书过期提醒

Uptime Kuma 可以在 TLS 证书过期前提醒你。打开一个 HTTP(s) 监控项（关键词监控和 JSON 查询监控同样支持），在 **Advanced** 下勾选 **Certificate Expiry Notification**。如果开启了 **Ignore TLS/SSL errors for HTTPS websites**，这个选项会变灰不可用。

提醒的时间阈值是全局设置，位于 **设置 → 通知 → TLS Certificate Expiry**，默认为 7、14 和 21 天。提醒会发送到与该监控项宕机告警相同的通知渠道，文本类似：

```text
[TLS site][https://tls-target/] server certificate tls-target will expire in 4 days
```

方式 1 的请求体会通过 `msg contains "will expire"` 识别它，并以 `default` 级别将标题设为 "Expiring soon"。Uptime Kuma 每个阈值只发送一次，而不是每次检测都发送。在我的测试中，当证书还有四天过期时，该监控项被检测了 119 次，只发出了一条警告。

## 防止抖动的监控项刷屏

有三个监控项设置决定了一个不稳定的服务会产生多少噪音：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>设置</th><th>作用</th><th>建议值</th></tr></thead>
<tbody>
<tr><th>Retries</th><td>检测失败后先标记为 <strong>Pending</strong>，达到次数后才判定监控项宕机。Pending 状态的检测不发送通知。</td><td><code>2</code> 或 <code>3</code></td></tr>
<tr><th>Heartbeat Retry Interval</th><td>处于 pending 状态时，两次检测之间的秒数。</td><td><code>20</code> 到 <code>60</code></td></tr>
<tr><th>Resend Notification if Down X times consecutively</th><td>连续失败达到这个次数后，重新发送宕机告警。<code>0</code> 表示只发送一次。</td><td><code>0</code>，或换算后约为 30 到 60 分钟的值</td></tr>
</tbody>
</table>
</div>

在我的测试中，**Retries** 设为 2 时，前两次失败检测被标记为 pending，只有第三次才发送 "Down"。**Resend** 设为 3 时，宕机告警每再失败三次就会重发一次，直到服务恢复。重发次数以检测次数计，而不是分钟。如果检测间隔是 60 秒，设为 30 就意味着每半小时提醒一次。

每次宕机、每次恢复、每次重发都算一条消息。免费套餐每天允许 50 条，因此一个没有设置重试的抖动监控项，一个下午就能用完配额。重试是最省事的解决方法。

## 如果没有收到消息

- **测试返回 HTTP 400。** 方式 1 中，检查 **Additional Headers** 是否包含 `"Content-Type": "application/json"`。没有它，请求会以表单数据的形式发出。
- **HTTP 401。** `Token` 请求头缺失，或者密钥已被撤销。请在 [API 密钥](/account/apikeys)页面重新创建一个。
- **测试能收到，但宕机告警收不到。** 打开该监控项，确认已勾选此通知。另外，如果监控项在首次检测时就是正常的，Uptime Kuma 不会发送通知，所以新建的监控项会一直保持安静，直到状态发生变化。
- **方式 2 没有任何显示。** 在控制台中打开该 webhook 的历史记录。如果请求存在但有错误，错误信息会说明原因：JSON 无效，或者模板生成了空消息。如果完全没有记录，说明 Uptime Kuma 从未连接到 `p4a.me`。你也可以把请求发送到 [webhook 测试工具](/tools/webhook)，看看 Uptime Kuma 到底发出了什么。
- **恢复消息似乎没有收到。** `low` 推送是静默的。请在应用的消息列表中查看。

## 常见问题

### 这需要哪个版本的 Uptime Kuma？

本文在 2.5.8 上测试，这是撰写时的最新版本。1.23.x 也支持带自定义请求体和附加请求头的 Webhook 类型，其模板同样可以使用 `msg`、`monitorJSON` 和 `heartbeatJSON` 变量。我用 1.23.16 自带的模板引擎渲染了方式 1 的请求体，得到的 JSON 相同，但完整的端到端测试只在 2.5.8 上做过。

### 如果运行 Uptime Kuma 的服务器宕机了怎么办？

那时就没有任何东西会发送告警。Uptime Kuma 无法报告自身的宕机，所以需要在它之外运行一个能发现问题的监控，例如从另一台机器检测，或使用托管监控服务。[运行时监控](/use-cases/uptime-monitoring)页面列出了可以配合 Pocket Alert webhook 使用的托管监控服务。

### 能把不同的监控项发送到不同的手机吗？

可以，但需要付费套餐。为每组监控项创建一个通知：方式 1 在请求体中使用不同的 `device_id`，方式 2 使用绑定了不同设备的 webhook。然后在每个监控项上勾选对应的通知。免费套餐只有一个设备和一个 webhook，因此只能发送到一部手机。

### 这适用于 ping、端口和 DNS 监控吗？

适用。请求体只使用监控项的名称和 ID，以及检测的状态和消息，这些在每种监控类型中都存在。有些类型（包括 ping）在检测成功时消息为空，这时请求体会回退使用 Uptime Kuma 自带的文本。按钮链接到 Uptime Kuma 中该监控项的页面，而不是被检测的地址，因此即使地址不是 URL 也能正常工作。

### 我已经在用它接收 Proxmox 的消息了，能共用一个 API 密钥吗？

可以，但建议给 Uptime Kuma 单独一个密钥，这样撤销其中一个不会影响另一个。[Proxmox 指南](/blog/proxmox-alerts)介绍了同一个家庭实验室中的备份和磁盘告警。

[创建免费账户](/signup)，把请求体粘贴到 Webhook 通知中，让下一次宕机直接送达你的手机，而恢复消息安静地待在消息列表里。
