Uptime Kuma 推送通知到手机:宕机时响铃,恢复时静音

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 应用,并拥有一个账户。如果还没有,请注册,免费套餐足够入门。
- 从 API 密钥获取一个 API 密钥(方式 1),或从 Webhooks 获取一个 webhook 地址(方式 2)。
两种连接方式
Uptime Kuma 的 Webhook 通知可以向任意 URL 发送请求,请求体可以用它自带的 JSON,也可以用你自己编写的内容。因此有两种方式:
| 方式 1:Pocket Alert API | 方式 2:Pocket Alert webhook 地址 | |
|---|---|---|
| 发送地址 | https://api.pocketalert.app/v1/messages | https://p4a.me/wh/<slug> |
| 推送标题 | 自定义,例如 Down: Website | 固定为 Webhook <name> |
| 宕机响铃,恢复静音 | 支持 | 支持,需要自定义请求体;否则所有消息都是同一级别 |
| Uptime Kuma 中保存的密钥 | 拥有账户完整权限的 API 密钥 | 一个只能通过该 webhook 创建推送的地址 |
| Pocket Alert 中的请求日志 | 无 | 有,见 webhook 历史 |
如果你想要可读性更好的标题、配置步骤最少,选方式 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,粘贴:
{
"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 会丢弃按钮,推送仍会送达,只是不带按钮。关于操作按钮还能做什么,见操作按钮。
不要跳过 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 实际发出的一次宕机和恢复的内容:
{
"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" }
]
}
{
"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" 按钮,然后输出接收地址:
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 页面创建:名称填 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 对象实际有大约一百个字段):
{
"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 天。提醒会发送到与该监控项宕机告警相同的通知渠道,文本类似:
[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 次,只发出了一条警告。
防止抖动的监控项刷屏
有三个监控项设置决定了一个不稳定的服务会产生多少噪音:
| 设置 | 作用 | 建议值 |
|---|---|---|
| Retries | 检测失败后先标记为 Pending,达到次数后才判定监控项宕机。Pending 状态的检测不发送通知。 | 2 或 3 |
| Heartbeat Retry Interval | 处于 pending 状态时,两次检测之间的秒数。 | 20 到 60 |
| Resend Notification if Down X times consecutively | 连续失败达到这个次数后,重新发送宕机告警。0 表示只发送一次。 | 0,或换算后约为 30 到 60 分钟的值 |
在我的测试中,Retries 设为 2 时,前两次失败检测被标记为 pending,只有第三次才发送 "Down"。Resend 设为 3 时,宕机告警每再失败三次就会重发一次,直到服务恢复。重发次数以检测次数计,而不是分钟。如果检测间隔是 60 秒,设为 30 就意味着每半小时提醒一次。
每次宕机、每次恢复、每次重发都算一条消息。免费套餐每天允许 50 条,因此一个没有设置重试的抖动监控项,一个下午就能用完配额。重试是最省事的解决方法。
如果没有收到消息
- 测试返回 HTTP 400。 方式 1 中,检查 Additional Headers 是否包含
"Content-Type": "application/json"。没有它,请求会以表单数据的形式发出。 - HTTP 401。
Token请求头缺失,或者密钥已被撤销。请在 API 密钥页面重新创建一个。 - 测试能收到,但宕机告警收不到。 打开该监控项,确认已勾选此通知。另外,如果监控项在首次检测时就是正常的,Uptime Kuma 不会发送通知,所以新建的监控项会一直保持安静,直到状态发生变化。
- 方式 2 没有任何显示。 在控制台中打开该 webhook 的历史记录。如果请求存在但有错误,错误信息会说明原因:JSON 无效,或者模板生成了空消息。如果完全没有记录,说明 Uptime Kuma 从未连接到
p4a.me。你也可以把请求发送到 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 无法报告自身的宕机,所以需要在它之外运行一个能发现问题的监控,例如从另一台机器检测,或使用托管监控服务。运行时监控页面列出了可以配合 Pocket Alert webhook 使用的托管监控服务。
能把不同的监控项发送到不同的手机吗?
可以,但需要付费套餐。为每组监控项创建一个通知:方式 1 在请求体中使用不同的 device_id,方式 2 使用绑定了不同设备的 webhook。然后在每个监控项上勾选对应的通知。免费套餐只有一个设备和一个 webhook,因此只能发送到一部手机。
这适用于 ping、端口和 DNS 监控吗?
适用。请求体只使用监控项的名称和 ID,以及检测的状态和消息,这些在每种监控类型中都存在。有些类型(包括 ping)在检测成功时消息为空,这时请求体会回退使用 Uptime Kuma 自带的文本。按钮链接到 Uptime Kuma 中该监控项的页面,而不是被检测的地址,因此即使地址不是 URL 也能正常工作。
我已经在用它接收 Proxmox 的消息了,能共用一个 API 密钥吗?
可以,但建议给 Uptime Kuma 单独一个密钥,这样撤销其中一个不会影响另一个。Proxmox 指南介绍了同一个家庭实验室中的备份和磁盘告警。
创建免费账户,把请求体粘贴到 Webhook 通知中,让下一次宕机直接送达你的手机,而恢复消息安静地待在消息列表里。