自托管环境中可靠的 iPhone 推送通知

凌晨 3 点,你的 Grafana 告警触发了。服务器日志显示 Webhook 调用成功,但你的 iPhone 一直没有动静。自托管监控很擅长发现故障,真正的难点在于把消息送到手机上,而这正是大多数家庭实验室配置出问题的地方。
本指南将解释为什么自托管环境中的 iPhone 推送通知如此困难,可靠的推送链路应该是什么样子,以及如何连接 Grafana、Uptime Kuma、n8n、cron 任务和 shell 脚本。第一条能正常工作的告警大约只需五分钟。
为什么自托管环境中的 iOS 推送会失败
只有 APNs 能触达 iPhone
发往 iPhone 的每条推送都要经过 Apple 推送通知服务(APNs)。你的服务器无法直接与手机建立连接并发送数据。手机会与 Apple 保持一条长期连接,你的服务器则通过 HTTP/2 把每条消息发送到 APNs,并使用你 Apple 开发者账户中的密钥进行身份验证。随后,APNs 沿着手机已有的连接把消息投递过去。
这意味着你的技术栈中间需要一个能够与 APNs 通信的发送方。手机不会轮询你的服务器,因此局域网里一个普通的 Webhook 端点没有任何可以投递的目标。想深入了解投递路径,可以参阅推送通知如何到达 iPhone。
自己运行发送方比想象中复杂
你完全可以自己与 APNs 通信。你需要一个签名密钥(用于令牌认证的 .p8 文件,它不会每年过期;或者每个应用一份 TLS 客户端证书,这种证书会过期),一个已注册的应用,一种存储设备令牌的方式,以及处理 APNs 错误和重试的代码。你还需要一个注册设备并展示告警的 iOS 应用。每个部分单独看都不难,真正的成本在于在密钥轮换和 Apple 政策变化之后,让所有部分持续正常工作。
大多数自托管用户需要的是结果,而不是底层管道。一个已经运行好 APNs 部分的托管服务,能让你的技术栈保持简单:每条告警只需一次 HTTP 请求。
专注模式、静音与打断级别
iOS 会根据通知的打断级别、你的专注模式以及应用设置,决定每条通知的提醒力度。对告警而言,有三件事最关键:
- 必须允许该应用发送通知。 先在 iOS 设置中检查这一点。被静音的应用无论服务器表现如何,都不会显示你的告警。
- 时效性通知可以穿透专注模式。 在 Pocket Alert 中,
high级别的消息会以时效性通知的形式送达,较低级别的消息则会等到专注模式结束后才显示。 - 关键告警会忽略静音开关和勿扰模式。 它们需要 Apple 审核后授予的特殊权限。Pocket Alert 已获得该权限:付费套餐上的
critical消息即使手机处于静音状态也会播放提示音,前提是你已为该应用允许关键告警。如果你关闭了这项权限,这些消息会以时效性通知的形式送达。
下面的优先级部分说明了如何设置级别。
可靠的配置是什么样子
你的技术栈检测到问题,发送一次 HTTP 请求,之后的工作交给托管服务:
Grafana / Uptime Kuma / n8n / cron + CLI
│ HTTPS (API call or webhook)
▼
Pocket Alert ──► APNs ──► iPhone (Pocket Alert app)
职责分工如下:
| 你的技术栈负责 | Pocket Alert 负责 |
|---|---|
| 检测故障,并判断什么才重要 | 接收请求,并校验你的 API 密钥或 Webhook URL |
| 格式化文本,或发送自己的 JSON | 映射字段、设置优先级,并投递到 APNs |
| 在事件发生时发送一次 | 推送到账户下的每台设备,或推送到你指定的设备 |
| 保留自己的日志 | 保存消息历史,并为每个 Webhook 保存请求日志,方便你查看收到了什么、哪些失败了 |
用 curl 发送第一条告警
在 pocketalert.app/signup 注册,打开 API 密钥,然后点击 Create New Key。密钥只显示一次,请把它妥善保存。
将密钥保存到环境变量中,然后发送一条消息:
export PA_KEY="YOUR_API_KEY"
curl -X POST "https://api.pocketalert.app/v1/messages" \
-H "Token: $PA_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Backup finished",
"message": "nightly-backup on nas01 completed in 14m",
"level": "high"
}'
调用成功时,会返回包含 tid、title、message、application、device 和 created_at 的 JSON。如果之后想把某条推送与日志行对应起来,请保留 tid。
有三件事容易出错:
- 设置 Content-Type。 API 接受 JSON 或
multipart/form-data,会拒绝application/x-www-form-urlencoded。如果省略请求头,curl -d默认发送的就是这种格式。JSON 请求体请使用-H "Content-Type: application/json",表单字段请使用-F。 title和message为必填项。 其他字段都是可选的。- 省略
device_id即可触达账户下的所有设备。 当你有多部手机,并且想发送给特定一部时,再添加它。
从命令行发送告警
Pocket Alert CLI 是把告警接入现有脚本最快的方式。可以通过 shell 脚本、Homebrew 或 Go 安装:
curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest
运行一次 pocketalert auth,然后粘贴你的密钥。密钥会保存在 ~/.pocketalert/config.json 中,且只有你本人可以读取。在服务器、容器和 CI 中,请改为设置 POCKETALERT_API_KEY。
发送一条消息:
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
也可以把命令输出直接通过管道发送为告警:
df -h | pocketalert send "Disk report" --level default
或者用 exec 包装一条命令。它会照常运行命令,然后发送一条推送,其中包含退出状态、耗时以及输出的最后几行,并原样返回退出码:
pocketalert exec -t "Database dump" -- ./dump.sh
使用 -q 时只输出消息 ID,便于编写脚本。给任意命令加上 --json,即可获得机器可读的输出。
带字段映射的 Webhook
如果你的数据源已经发送 JSON,比如 Grafana、Uptime Kuma 或自定义服务,就不需要自己编写发送程序。在 Webhook 控制台中创建一个 Webhook,Pocket Alert 会为你生成类似 https://p4a.me/wh/1234abcd 的接收 URL。该 slug 无法被猜到,并且每个 URL 只对应一个 Webhook 和一个应用。将数据源以 POST 方式指向这个 URL 即可。
推送的标题为 "Webhook" 加上 Webhook 的名称,因此请以数据源来命名,例如 Grafana。消息模板使用 GJSON 路径从传入的 JSON 中提取值:
%object.field%用于嵌套字段%items.0.name%用于数组元素%users.#%用于计数- 将
*作为整个模板,即可发送完整的请求体
例如,对于如下传入的负载:
{
"service": "api-gateway",
"check": "tls-expiry",
"state": "warning",
"detail": "certificate expires in 6 days"
}
模板可以写成:
[%state%] %service%: %check%
%detail%
路径不存在的占位符会渲染为空字符串,因此拼写错误只会在文本中留下空白,而不会报错。
在编写模板之前,先捕获真实的负载。打开 Webhook 测试工具,复制测试 URL,然后将数据源指向它。测试工具会显示请求方法、请求头和请求体,方便你根据数据源实际发送的内容来编写路径。不要把生产环境的密钥发送到公开的测试 URL。任何知道该 URL 的人都可以读取到达那里的内容。
优先级有两种设置方式:为 Webhook 设置默认级别,或在负载中加入顶层的 level 字段,它会覆盖默认值。有效值为 silent、low、default、high、critical,或数字 -2 到 2。无效的 level 会被忽略,并使用 Webhook 的默认值。
集成
Grafana 告警
在控制台中创建一个名为 Grafana 的 Webhook,并使用以下消息模板:
[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%
复制它的接收 URL。在 Grafana 中,进入 Alerting → Contact points → Add contact point,选择 Webhook 集成,并设置:
Integration: Webhook
URL: https://p4a.me/wh/1234abcd
Method: POST
将该联系点挂载到某个通知策略上,使匹配的告警路由到它,然后点击联系点的 Test 按钮。一条标签为 HighCPU、名为 severity="critical" 的触发告警会显示为 [firing] HighCPU (critical)。告警恢复时,同一条推送会在方括号中带上 resolved 送达。
有三点说明。除非你的规则设置了该标签,否则 severity 部分为空。模板只读取分组中的第一条告警(alerts.0),因此如果一条通知包含多条告警,你只会看到第一条的摘要。另外,为每条规则设置等待时间(例如 5 分钟),是防止抖动指标每分钟都把手机吵醒的最低成本方法。更多字段请参阅 Grafana 指南。
Uptime Kuma
Uptime Kuma 会在每次状态变化时发送一个 Webhook。添加一个类型为 Webhook 的通知,将 Post URL 设置为你的接收 URL,并将 JSON 预设保留为请求体。
在 Pocket Alert 中,使用 %msg% 作为模板。msg 是 Uptime Kuma 发出的每个请求中都存在的唯一字段,包括证书警告和测试消息,而且它本身已经读起来很清楚,例如 "[Website] [🔴 Down] timeout of 4000ms exceeded"。将 Webhook 的默认级别设置为 high。
使用预设请求体时,恢复通知和故障通知的提醒力度相同,因为 Uptime Kuma 不会自行添加 level 字段。Uptime Kuma 指南展示了一种自定义请求体,可以在故障时发送 high,恢复时发送 low。
n8n
在 n8n 工作流中,在检测到问题的步骤之后添加一个 HTTP Request 节点:
- Method:
POST - URL:
https://api.pocketalert.app/v1/messages - Authentication: Generic Credential Type,然后选择 Header Auth。名称填
Token,值填你的 API 密钥。 - Send Body: 开启,Body Content Type 选择 JSON,Specify Body 选择 Using JSON,并使用一个表达式构建整个对象:
{{ JSON.stringify({
title: 'Disk almost full on ' + $json.host,
message: $json.detail,
level: 'high'
}) }}
JSON.stringify 会转义值中的引号和换行符,而在 JSON 字符串中直接写 "{{ $json.detail }}" 则做不到这一点。若要捕获所有工作流的失败,请设置一个以 Error Trigger 开始的错误工作流:失败工作流的名称位于 $json.workflow.name,错误信息位于 $json.execution.error.message。n8n 指南提供了可直接导入的现成工作流。
定时与周期性检查
cron 任务会静默失败,而漏掉告警恰恰在最糟糕的时候。请把告警直接放进任务本身:
POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh
cron 不会加载你的 shell 配置文件,因此开头的两行为任务提供了密钥,以及一个包含 CLI 的 PATH。成功运行时,会以默认级别收到 "✓ Nightly backup"。失败时,会以 high 级别收到 "✗ Nightly backup (exit 1)",消息中包含输出的最后几行。如果你只想收到失败通知,请添加 --on failure。
exec 能告诉你任务何时失败,但无法告诉你任务何时没有运行。要覆盖这种情况,请配合"死人开关"使用,具体方法见 cron 任务监控指南。
如果你不确定某个调度表达式,可以将它粘贴到免费的 cron 表达式工具中。它会把每个字段解释为通俗的英文,并列出接下来的运行时间。下次运行时间使用你浏览器的时区,这可能与服务器的时区不同。
优先级与关键告警
共有五个级别,从安静到响亮:
| 级别 | 值 | 在 iPhone 上 | 典型用途 |
|---|---|---|---|
silent | -2 | 无声音,直接进入通知中心 | "已恢复"事件,以及你之后可能会查看的日志 |
low | -1 | 被动通知,不会点亮屏幕 | 信息类通知 |
default | 0 | 带声音的普通通知 | 例行结果,例如备份完成 |
high | 1 | 时效性通知,可穿透专注模式 | 需要尽快关注 |
critical | 2 | 关键告警,即使静音也会发出声音 | 需要立即关注。仅限付费套餐 |
在免费套餐中,critical 消息会以 high 级别投递。它仍会立即以时效性通知的形式送达,但会遵守静音开关。
对于触发告警及其恢复,一个合理的映射是:
- 触发时:
high,或者只对少数值得立即被唤醒的事件使用critical - 恢复时:
silent
可以通过 Webhook 的默认级别设置,也可以在数据源能够发送时,通过负载中的 level 字段设置。
检查清单:确保你的告警能够送达
- 允许通知。 在 iOS 设置中为 Pocket Alert 应用开启通知,包括时效性通知,以及付费套餐上的关键告警。
- 开启专注模式进行测试。 打开你常用的专注模式,使用上面的 curl 命令发送一条
high测试消息,确认它能送达。如果送达失败,请检查该专注模式下应用的通知设置。 - 确认调用已到达 Pocket Alert。 API 消息会显示在应用和网页控制台的消息历史中。Webhook 调用(包括被拒绝的调用)会显示在该 Webhook 的请求日志中。如果调用已在其中,问题出在手机端;如果没有,问题出在你的数据源。
- 检查数据源的日志,查看外发请求的 URL、状态码和响应体。
- 关注每日上限。 免费套餐每天允许 50 条通知。一个抖动的检查可能在一小时内就把额度用完,因此在扩大规模之前,请先调整阈值和等待时间。
pocketalert usage可以显示你今天还剩多少额度。
如果告警仍然没有送达,请按顺序排查:先看数据源日志,再看 Pocket Alert 历史,最后检查级别和设备设置。这个顺序能帮你快速定位出问题的环节。
常见问题
没有自己的 Apple 开发者配置,也能向 iPhone 发送推送通知吗?
可以。已经连接 APNs 的托管服务会处理 Apple 那一侧的工作。你用 API 密钥发送一次 HTTP 请求,服务再将其投递到它的 iPhone 应用。自己运行发送方则需要签名密钥、应用注册和你自己的 iOS 应用。
为什么我的自托管告警延迟到达,或者根本收不到?
通常是以下三种情况之一:没有允许该应用发送通知,当前的专注模式压制了告警的级别,或者请求从未到达服务。先检查消息历史或 Webhook 日志,看看是哪种情况。
开启专注模式时,告警能送达吗?
允许通知后,high 消息会以时效性通知的形式送达,并可以穿透专注模式。付费套餐上的 critical 消息走得更远,即使手机静音也会发出声音。较低的级别则会等待。在依赖它之前,请先测试你自己的专注模式设置。
有免费套餐吗?
有。免费套餐包括每天 50 条通知、1 台设备、1 个应用和 1 个 Webhook。免费套餐上的关键消息以高优先级投递。
后续步骤
大约五分钟,你就可以收到第一条 iPhone 告警:
确认这一步可行后,再接入一个真实的数据源:Grafana 联系点、Uptime Kuma 通知或 cron 任务。更多家庭实验室数据源请参阅家庭实验室告警和 Proxmox 指南。其他集成请参阅 Webhook 通知和 Grafana 告警。如果你正在比较各种方案,替代方案页面列出了它们之间的差异。