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

大多数 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 上安装 Pocket Alert 应用,并在 API Keys 获取一个 API 密钥。
- 以
root@pam身份,或以拥有Mapping.Modify上/mapping/notifications权限的用户,访问 Datacenter → Notifications。
Proxmox 能告诉你什么
Proxmox VE 会发出以下事件,每个事件都带有 type、严重级别和一些元数据字段:
| 事件 | type | 严重级别 |
|---|---|---|
| 备份成功 | vzdump | info |
| 备份失败 | vzdump | error |
| 存储复制任务失败 | replication | error |
| 集群节点被隔离 | fencing | error |
| 有可用的系统更新 | package-updates | info |
| 发给 root 的邮件(smartd、ZFS ZED 等) | system-mail | unknown |
最后一行比看上去更重要。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 编码传递:
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 上的具体效果,见优先级说明。
匹配器还有以下几种常见用法:
- 只推送失败。 在
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 推送最多可以携带三个操作按钮。在请求体中加入一个按钮后,备份失败的推送只需轻点一下,就能打开 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 的比较。
Proxmox VE 8.2 及更早版本
升级是最好的解决办法,因为 Webhook 目标需要 8.3。如果暂时无法升级,可以用 vzdump 钩子脚本覆盖最重要的场景,也就是备份。以 root 身份在节点上安装 Pocket Alert CLI,运行 pocketalert auth,然后把以下内容保存为 /usr/local/bin/vzdump-pocketalert:
#!/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 呢?
思路相同,只是发送方不同。家庭实验室告警页面介绍了家庭服务器机架的常见组成部分,备份告警页面则涵盖 Proxmox 之外的备份工具。
免费创建账户,把请求体粘贴到 Webhook 目标中,让下一次备份失败主动找到你,而不是等你去翻收件箱。