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

> 为什么从家庭实验室向 iPhone 推送如此困难，可靠的推送链路应该是什么样子，以及如何把 Grafana、Uptime Kuma、n8n、cron 任务和 shell 脚本连接到手机上的紧急与关键告警。

*04.11.2026*

<!-- source: https://pocketalert.app/zh/blog/self-hosted-iphone-push-notifications -->

凌晨 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](/blog/how-push-notifications-work-apns-fcm)。

### 自己运行发送方比想象中复杂

你完全可以自己与 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)
```

职责分工如下：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>你的技术栈负责</th><th>Pocket Alert 负责</th></tr></thead>
<tbody>
<tr><td>检测故障，并判断什么才重要</td><td>接收请求，并校验你的 API 密钥或 Webhook URL</td></tr>
<tr><td>格式化文本，或发送自己的 JSON</td><td>映射字段、设置优先级，并投递到 APNs</td></tr>
<tr><td>在事件发生时发送一次</td><td>推送到账户下的每台设备，或推送到你指定的设备</td></tr>
<tr><td>保留自己的日志</td><td>保存消息历史，并为每个 Webhook 保存请求日志，方便你查看收到了什么、哪些失败了</td></tr>
</tbody>
</table>
</div>

## 用 curl 发送第一条告警

在 [pocketalert.app/signup](/signup) 注册，打开 [API 密钥](/account/apikeys)，然后点击 **Create New Key**。密钥只显示一次，请把它妥善保存。

将密钥保存到环境变量中，然后发送一条消息：

```bash
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](/tools/cli) 是把告警接入现有脚本最快的方式。可以通过 shell 脚本、Homebrew 或 Go 安装：

```bash
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`。

发送一条消息：

```bash
pocketalert send "Deploy finished" "v2.4.0 is live" --level high
```

也可以把命令输出直接通过管道发送为告警：

```bash
df -h | pocketalert send "Disk report" --level default
```

或者用 `exec` 包装一条命令。它会照常运行命令，然后发送一条推送，其中包含退出状态、耗时以及输出的最后几行，并原样返回退出码：

```bash
pocketalert exec -t "Database dump" -- ./dump.sh
```

使用 `-q` 时只输出消息 ID，便于编写脚本。给任意命令加上 `--json`，即可获得机器可读的输出。

## 带字段映射的 Webhook

如果你的数据源已经发送 JSON，比如 Grafana、Uptime Kuma 或自定义服务，就不需要自己编写发送程序。在 [Webhook](/webhooks) 控制台中创建一个 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.#%` 用于计数
- 将 `*` 作为整个模板，即可发送完整的请求体

例如，对于如下传入的负载：

```json
{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}
```

模板可以写成：

```
[%state%] %service%: %check%
%detail%
```

路径不存在的占位符会渲染为空字符串，因此拼写错误只会在文本中留下空白，而不会报错。

在编写模板之前，先捕获真实的负载。打开 [Webhook 测试工具](/tools/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 指南](/blog/how-to-integrate-grafana-into-pocketalert)。

### 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 指南](/blog/uptime-kuma-notifications)展示了一种自定义请求体，可以在故障时发送 `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 指南](/blog/n8n-push-notifications)提供了可直接导入的现成工作流。

## 定时与周期性检查

cron 任务会静默失败，而漏掉告警恰恰在最糟糕的时候。请把告警直接放进任务本身：

```bash
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 任务监控指南](/blog/cron-job-monitoring-healthchecks)。

如果你不确定某个调度表达式，可以将它粘贴到免费的 [cron 表达式工具](/tools/cron)中。它会把每个字段解释为通俗的英文，并列出接下来的运行时间。下次运行时间使用你浏览器的时区，这可能与服务器的时区不同。

## 优先级与关键告警

共有五个级别，从安静到响亮：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>级别</th><th>值</th><th>在 iPhone 上</th><th>典型用途</th></tr></thead>
<tbody>
<tr><th><code>silent</code></th><td>-2</td><td>无声音，直接进入通知中心</td><td>"已恢复"事件，以及你之后可能会查看的日志</td></tr>
<tr><th><code>low</code></th><td>-1</td><td>被动通知，不会点亮屏幕</td><td>信息类通知</td></tr>
<tr><th><code>default</code></th><td>0</td><td>带声音的普通通知</td><td>例行结果，例如备份完成</td></tr>
<tr><th><code>high</code></th><td>1</td><td>时效性通知，可穿透专注模式</td><td>需要尽快关注</td></tr>
<tr><th><code>critical</code></th><td>2</td><td>关键告警，即使静音也会发出声音</td><td>需要立即关注。仅限付费套餐</td></tr>
</tbody>
</table>
</div>

在免费套餐中，`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. [注册](/signup)，并在你的 iPhone 上安装应用。
2. 在 [API 密钥](/account/apikeys)页面创建一个 API 密钥。
3. 运行本指南中的 curl 命令。

确认这一步可行后，再接入一个真实的数据源：Grafana 联系点、Uptime Kuma 通知或 cron 任务。更多家庭实验室数据源请参阅[家庭实验室告警](/use-cases/homelab-alerts)和 [Proxmox 指南](/blog/proxmox-alerts)。其他集成请参阅 [Webhook 通知](/use-cases/webhook-notifications)和 [Grafana 告警](/use-cases/grafana-alerts)。如果你正在比较各种方案，[替代方案页面](/alternatives)列出了它们之间的差异。
