# Proxmox 手机推送通知：备份、节点隔离、复制与磁盘错误

> 通过内置的 Webhook 目标，把 Proxmox VE 和 Proxmox Backup Server 的通知发送到 iPhone 和 Android。备份失败时强提醒，成功时静默；节点被隔离时叫醒你；smartd 和 ZFS 警告不再躺在 root 的邮箱里。

*25.10.2026*

<!-- source: https://pocketalert.app/zh/blog/proxmox-alerts -->

大多数 Proxmox 主机的通知都发给 `root@pam`，也就是多年前在安装程序里填的一个邮箱地址，邮件由一个从未配置过中继的 Postfix 投递。夜间备份失败，邮件进入本地队列，等你三周后要恢复虚拟机时才发现问题。

另一种常见做法虽然能用，却很快被忽略。每个备份任务每晚都发一封长邮件，内容全是“成功”，而那封“失败”的邮件混在另外三十封里，看起来一模一样。

从 Proxmox VE 8.3 和 Proxmox Backup Server 3.3 开始，通知系统新增了通用的 **Webhook** 目标。它可以调用任何 HTTP API，请求体由你自己编写，因此能直接把推送发到手机上，并且为失败和成功设置不同的优先级。不需要在主机上运行脚本，也不需要维护中继。

## 准备工作

- Proxmox VE 8.3 或更新版本（任何 9.x 都可以），或 Proxmox Backup Server 3.3 或更新版本。更早的版本见后文。
- 在 [iPhone 或 Android](/get-app) 上安装 Pocket Alert 应用，并在 [API Keys](/account/apikeys) 获取一个 API 密钥。
- 以 `root@pam` 身份，或以拥有 `Mapping.Modify` 上 `/mapping/notifications` 权限的用户，访问 Datacenter → Notifications。

## Proxmox 能告诉你什么

Proxmox VE 会发出以下事件，每个事件都带有 `type`、严重级别和一些元数据字段：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>事件</th><th><code>type</code></th><th>严重级别</th></tr></thead>
<tbody>
<tr><th>备份成功</th><td><code>vzdump</code></td><td><code>info</code></td></tr>
<tr><th>备份失败</th><td><code>vzdump</code></td><td><code>error</code></td></tr>
<tr><th>存储复制任务失败</th><td><code>replication</code></td><td><code>error</code></td></tr>
<tr><th>集群节点被隔离</th><td><code>fencing</code></td><td><code>error</code></td></tr>
<tr><th>有可用的系统更新</th><td><code>package-updates</code></td><td><code>info</code></td></tr>
<tr><th>发给 root 的邮件（smartd、ZFS ZED 等）</th><td><code>system-mail</code></td><td><code>unknown</code></td></tr>
</tbody>
</table>
</div>

最后一行比看上去更重要。`smartd` 每 30 分钟检查一次磁盘，磁盘开始出问题时会给 root 发邮件；ZFS 事件守护进程也会就降级的存储池和 scrub 错误给 root 发邮件（默认设置为 `ZED_EMAIL_ADDR="root"`）。Proxmox 会把这些邮件转为 `system-mail` 事件，因此同一个 Webhook 既能报告备份，也能报告快要坏掉的磁盘。

## 设置 Webhook 目标

在网页界面中进入 **Datacenter → Notifications**，在 **Notification Targets** 下点击 **Add → Webhook**。按如下方式填写：

- **Endpoint Name：** `pocketalert`
- **Method/URL：** `POST` 和 `https://api.pocketalert.app/v1/messages`
- **Headers：** `Content-Type` = `application/json`，以及 `Token` = `{{ secrets.token }}`
- **Secrets：** `token` = 你的 Pocket Alert API 密钥

然后填写 **Body**：

```
{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}
```

这里有几点需要注意：

- **`{{ json title }}` 会把值渲染为完整的 JSON 字符串**，包括引号。备份报告是多行表格，如果把 `{{ message }}` 直接放在引号之间，JSON 会在第一个换行处断开。Proxmox 还提供 `{{ escape message }}`，效果相同，但不带外层引号。
- **密钥属于机密信息。** Secrets 保存在 `/etc/pve/priv/notifications.cfg` 中，只有 root 可读，API 也从不返回它们的值。Proxmox 还会在错误信息中对它们进行隐藏。
- **级别跟随严重程度。** Proxmox 使用 Handlebars 渲染请求体，它支持 `if`、`eq` 和 `or`。备份失败、复制失败、节点隔离和磁盘邮件会以 `high` 发送，可以突破 iPhone 的专注模式。备份成功和更新通知则以 `low` 发送：它们仍会出现在消息列表中，但不会震动。

保存目标后点击 **Test**。测试通知应在几秒内到达。

在匹配器将事件路由到该目标之前，它不会做任何事。在 **Notification Matchers** 下点击 **Add**，命名为 `pocketalert-all`，然后在 **Targets to notify** 选项卡中勾选 `pocketalert`。没有规则的匹配器会匹配所有事件。

### 通过命令行完成同样的设置

如果你更习惯使用 CLI，或者要管理多个集群，可以用 `pvesh` 完成同样的操作。请求头的值、请求体和密钥均以 base64 编码传递：

```bash
PA_KEY='your-api-key'
BODY='{
  "title": {{ json title }},
  "message": {{ json message }},
  "level": "{{#if (or (eq severity "error") (eq severity "unknown"))}}high{{else}}low{{/if}}"
}'
b64() { printf '%s' "$1" | base64 -w0; }

pvesh create /cluster/notifications/endpoints/webhook \
  --name pocketalert --method post \
  --url https://api.pocketalert.app/v1/messages \
  --header "name=Content-Type,value=$(b64 application/json)" \
  --header "name=Token,value=$(b64 '{{ secrets.token }}')" \
  --secret "name=token,value=$(b64 "$PA_KEY")" \
  --body "$(b64 "$BODY")"

pvesh create /cluster/notifications/matchers --name pocketalert-all --target pocketalert
pvesh create /cluster/notifications/targets/pocketalert/test
```

结果会写入 `/etc/pve/notifications.cfg`，该文件在整个集群中共享，因此一次设置即可覆盖所有节点（此处省略了较长的 base64 请求体）：

```
webhook: pocketalert
	method post
	url https://api.pocketalert.app/v1/messages
	header name=Content-Type,value=YXBwbGljYXRpb24vanNvbg==
	header name=Token,value=e3sgc2VjcmV0cy50b2tlbiB9fQ==
	body ewogICJ0aXRsZSI6IHt7IGpzb24gdGl0bGUgfX0s...

matcher: pocketalert-all
	target pocketalert
```

密钥本身保存在 `/etc/pve/priv/notifications.cfg` 中，格式为 `secret name=token,value=<base64>`。

## 进阶：节点被隔离时应该叫醒你

备份失败可以等到早上再处理，但节点被隔离意味着 HA 刚刚强制关闭了一台主机，这值得发送一条能穿透勿扰模式的 `critical` 推送。匹配器可以在不修改请求体模板的情况下实现这一点。

创建第二个 Webhook 目标 `pocketalert-critical`，与第一个完全相同，只是请求体中多一行：

```
  "level": "critical"
```

然后用两个按事件类型拆分的匹配器替换原来的全量匹配器：

```
matcher: pocketalert-all
	match-field exact:type=fencing
	invert-match true
	target pocketalert

matcher: pocketalert-fencing
	match-field exact:type=fencing
	target pocketalert-critical
```

`invert-match` 会反转第一个匹配器的条件，因此隔离事件只会发送到 critical 目标，同一事件不会让你收到两条推送。通过勿扰模式投递 `critical` 级别是付费套餐的功能；在免费套餐中它会以 `high` 投递。各级别在 iOS 和 Android 上的具体效果，见[优先级说明](https://info.pocketalert.app/features/priority-levels.html)。

匹配器还有以下几种常见用法：

- **只推送失败。** 在 `match-severity error,unknown` 中加入 `pocketalert-all`，成功的备份就不会再发送任何通知。我们建议保留它们并设为 `low`：每晚一条安静的“备份成功”，是发现通知停止送达的最简单方式。
- **只针对一个任务。** `match-field exact:job-id=backup-abc123` 会把匹配器限制在某个定时任务上。通过 **Run now** 启动的备份没有 `job-id`，因此不会匹配。
- **非工作时间。** `match-calendar mon..fri 9-17` 会把匹配器限制在工作时间，而 `invert-match` 则可以得到其余时间段。

### 打开网页界面的按钮

Pocket Alert 推送最多可以携带三个[操作按钮](https://info.pocketalert.app/features/action-buttons.html)。在请求体中加入一个按钮后，备份失败的推送只需轻点一下，就能打开 Proxmox 界面：

```
  "actions": [
    {"type": "view", "label": "Open Proxmox", "value": "https://pve1.lan:8006"}
  ]
```

手机会直接打开该 URL，因此只要你处于家庭网络或 VPN 中，局域网地址就能正常使用。

## Proxmox Backup Server

PBS 3.3 及更新版本在 **Configuration → Notifications** 下提供相同的通知系统，包括相同的 Webhook 目标、相同的请求体和相同的 Handlebars 辅助函数。其配置保存在 `notifications.cfg` 下的 `notifications-priv.cfg` 和 `/etc/proxmox-backup/` 中。

事件有所不同，对备份服务器来说更有用：垃圾回收（`gc`）、`prune`、`sync`、`verification`、`tape-backup` 和 `tape-load`，以及 `acme` 证书续期失败和 `package-updates`。`acme` 只报告失败，`tape-load` 的级别为 `notice`；其余事件都有 `info` 和 `error` 两种版本，因此请求体中的同一个 `if` 无需修改即可使用。数据存储相关事件（`gc`、`prune`、`sync`、`verification`、`tape-backup`）还带有 `datastore` 字段，因此可以用 `match-field regex:datastore=^offsite-.*$` 把异地数据存储的通知发送到另一个目标。

有两个 PBS 细节需要检查。在通知系统出现之前创建的数据存储，其 `notification-mode` 可能仍为 `legacy-sendmail`；请在数据存储选项中将其切换为通知系统。另外，PBS 只会在拥有有效订阅的主机上发送 `package-updates` 通知。

## 诚实的局限

- **主机必须在线才能上报。** Webhook 由 Proxmox 主机本身发出，因此如果它失去了上行网络或已关机，就不会有任何通知发出。如果要监控“整台机器都挂了”的情况，你需要一个外部检查，例如另一台机器上的正常运行时间监控。
- **长备份报告在推送中会被截断。** 一次包含二十台虚拟机的备份会生成很长的表格。推送只显示大约前 3 KB，完整内容在应用的消息历史中。
- **`system-mail` 包含所有发给 root 的邮件。** 其中有 smartd 和 ZFS 的邮件，也有 cron 输出以及系统上其他发给 root 的任何邮件。如果通知变得太吵，可以为这些事件单独设置一个匹配器：`match-field exact:type=system-mail`，并指向一个更安静的目标。
- **不支持 Gotify 兼容。** Proxmox 也内置了 Gotify 目标，一些旧教程用它来发送手机推送。Pocket Alert 没有实现 Gotify API，因此该目标无法指向我们。请使用上面的 Webhook 目标，或参阅 [Pocket Alert 与 Gotify 的比较](/alternatives/gotify)。

## Proxmox VE 8.2 及更早版本

升级是最好的解决办法，因为 Webhook 目标需要 8.3。如果暂时无法升级，可以用 vzdump 钩子脚本覆盖最重要的场景，也就是备份。以 root 身份在节点上安装 [Pocket Alert CLI](/tools/cli)，运行 `pocketalert auth`，然后把以下内容保存为 `/usr/local/bin/vzdump-pocketalert`：

```bash
#!/bin/sh
case "$1" in
  backup-abort) pocketalert send -t "Backup failed: $3 on $(hostname)" -m "Mode: $2" -l high ;;
  job-end)      pocketalert send -t "Backup job finished on $(hostname)" -m "Check the task log for details" -l low ;;
esac
exit 0
```

为它添加可执行权限，并在 `script: /usr/local/bin/vzdump-pocketalert` 中加入 `/etc/vzdump.conf`。vzdump 会在每个阶段调用该脚本；对于 `backup-abort`，第二和第三个参数分别是备份模式和虚拟机 ID。

## 如果没有收到任何通知

- **先运行 Test。** 如果测试推送能收到，但真实事件收不到，说明目标本身没有问题，问题出在路由上：请检查是否有匹配器指定了该目标，以及它的规则是否匹配。
- **检查备份任务的通知模式。** 如果任务的通知设置中填写了邮箱地址，且模式为默认的 `auto`，它会使用旧版 sendmail，完全跳过通知系统。请清空该地址，或将模式设为通知系统；在 `/etc/pve/jobs.cfg` 中，对应配置为 `notification-mode notification-system`。
- **查看系统日志。** `journalctl --since "1 hour ago" | grep -i notif` 可以显示失败的请求。`401` 表示密钥错误；`400` 通常表示请求体不是有效的 JSON，请检查是否使用了 `{{ json message }}`，而不是裸的 `{{ message }}`。
- **在应用中查看消息流。** `low` 级别的推送不会发出声音，因此成功的备份看起来像是从未送达。它其实保存在消息历史中。

## 常见问题

### 我需要 Proxmox 订阅吗？

不需要。通知系统和 Webhook 目标都属于免费软件源的一部分。唯一依赖订阅的是 PBS 的 `package-updates` 通知。

### 对于没有集群的单节点，这个方案可用吗？

可以。单节点同样读取 `/etc/pve/notifications.cfg`。在集群中该文件是共享的，因此只需设置一次。

### 我也能收到邮件吗？

可以。在对应的匹配器中保留默认的 `mail-to-root` 目标，并在它旁边加入 `pocketalert`。一个匹配器可以通知多个目标，每个目标对每个事件最多只会收到一次通知。

### 这会消耗多少条推送？

每个事件一条。一个夜间备份任务对整个任务只产生一条通知，而不是每台虚拟机一条，因此典型的家庭实验室每天只会发出几条。免费套餐每天可在一台设备上接收 50 条消息。

### TrueNAS、UPS 电源事件或 Uptime Kuma 呢？

思路相同，只是发送方不同。[家庭实验室告警](/use-cases/homelab-alerts)页面介绍了家庭服务器机架的常见组成部分，[备份告警](/use-cases/backup-alerts)页面则涵盖 Proxmox 之外的备份工具。

[免费创建账户](/signup)，把请求体粘贴到 Webhook 目标中，让下一次备份失败主动找到你，而不是等你去翻收件箱。
