返回博客

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

自托管环境中可靠的 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 会根据通知的打断级别、你的专注模式以及应用设置,决定每条通知的提醒力度。对告警而言,有三件事最关键:

  1. 必须允许该应用发送通知。 先在 iOS 设置中检查这一点。被静音的应用无论服务器表现如何,都不会显示你的告警。
  2. 时效性通知可以穿透专注模式。 在 Pocket Alert 中,high 级别的消息会以时效性通知的形式送达,较低级别的消息则会等到专注模式结束后才显示。
  3. 关键告警会忽略静音开关和勿扰模式。 它们需要 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被动通知,不会点亮屏幕信息类通知
default0带声音的普通通知例行结果,例如备份完成
high1时效性通知,可穿透专注模式需要尽快关注
critical2关键告警,即使静音也会发出声音需要立即关注。仅限付费套餐

在免费套餐中,critical 消息会以 high 级别投递。它仍会立即以时效性通知的形式送达,但会遵守静音开关。

对于触发告警及其恢复,一个合理的映射是:

  • 触发时:high,或者只对少数值得立即被唤醒的事件使用 critical
  • 恢复时:silent

可以通过 Webhook 的默认级别设置,也可以在数据源能够发送时,通过负载中的 level 字段设置。

检查清单:确保你的告警能够送达

  1. 允许通知。 在 iOS 设置中为 Pocket Alert 应用开启通知,包括时效性通知,以及付费套餐上的关键告警。
  2. 开启专注模式进行测试。 打开你常用的专注模式,使用上面的 curl 命令发送一条 high 测试消息,确认它能送达。如果送达失败,请检查该专注模式下应用的通知设置。
  3. 确认调用已到达 Pocket Alert。 API 消息会显示在应用和网页控制台的消息历史中。Webhook 调用(包括被拒绝的调用)会显示在该 Webhook 的请求日志中。如果调用已在其中,问题出在手机端;如果没有,问题出在你的数据源。
  4. 检查数据源的日志,查看外发请求的 URL、状态码和响应体。
  5. 关注每日上限。 免费套餐每天允许 50 条通知。一个抖动的检查可能在一小时内就把额度用完,因此在扩大规模之前,请先调整阈值和等待时间。pocketalert usage 可以显示你今天还剩多少额度。

如果告警仍然没有送达,请按顺序排查:先看数据源日志,再看 Pocket Alert 历史,最后检查级别和设备设置。这个顺序能帮你快速定位出问题的环节。

常见问题

没有自己的 Apple 开发者配置,也能向 iPhone 发送推送通知吗?
可以。已经连接 APNs 的托管服务会处理 Apple 那一侧的工作。你用 API 密钥发送一次 HTTP 请求,服务再将其投递到它的 iPhone 应用。自己运行发送方则需要签名密钥、应用注册和你自己的 iOS 应用。

为什么我的自托管告警延迟到达,或者根本收不到?
通常是以下三种情况之一:没有允许该应用发送通知,当前的专注模式压制了告警的级别,或者请求从未到达服务。先检查消息历史或 Webhook 日志,看看是哪种情况。

开启专注模式时,告警能送达吗?
允许通知后,high 消息会以时效性通知的形式送达,并可以穿透专注模式。付费套餐上的 critical 消息走得更远,即使手机静音也会发出声音。较低的级别则会等待。在依赖它之前,请先测试你自己的专注模式设置。

有免费套餐吗?
有。免费套餐包括每天 50 条通知、1 台设备、1 个应用和 1 个 Webhook。免费套餐上的关键消息以高优先级投递。

后续步骤

大约五分钟,你就可以收到第一条 iPhone 告警:

  1. 注册,并在你的 iPhone 上安装应用。
  2. 在 API 密钥页面创建一个 API 密钥。
  3. 运行本指南中的 curl 命令。

确认这一步可行后,再接入一个真实的数据源:Grafana 联系点、Uptime Kuma 通知或 cron 任务。更多家庭实验室数据源请参阅家庭实验室告警和 Proxmox 指南。其他集成请参阅 Webhook 通知和 Grafana 告警。如果你正在比较各种方案,替代方案页面列出了它们之间的差异。

分享这篇文章