第 17 章 通知

17.通知Notifications

17.1.概述Overview

Proxmox VE 在存储复制失败、节点 fencing、备份完成 / 失败等情形会产生 通知事件（Notification Events）。每个事件含时间戳、严重性、类型与其他事件专属字段 ， 按全局通知设置处理。

• 通知匹配器（Matchers） 把事件路由到一或多个目标 —— 可按事件元数据匹配。
• 通知目标（Targets） 是事件的去处 ：邮件（Sendmail / SMTP）、 Gotify、 Webhook。

全局通知设置在 Datacenter → Notifications 配置 ， 存于 /etc/pve/notifications.cfg 与 /etc/pve/priv/notifications.cfg —— 后者含密码 / 令牌等敏感项 ， 仅 root 可读。

17.2.通知目标Notification Targets

17.2.1.Sendmail

Unix-like 系统常见的 sendmail 程序 —— CLI / 脚本可直接发邮件。 Sendmail 通知目标用它给一组配置的用户 / 地址发邮件。若把用户选作收件人 ， 会用用户设置中的邮箱（root@pam 用的是安装时填的邮箱）—— 邮箱在 Datacenter → Permissions → Users 配置；无邮箱则不发。

配置项：

mailto

收件邮箱 —— 可多次以容纳多收件人。

mailto-user

PVE 用户 —— 邮箱从 users.cfg 查；可多次。

author

邮件作者 —— 默认 Proxmox VE。

from-address

发件地址 —— 未设则回退 datacenter.cfg 的 email_from；再未设则 root@$hostname。 From 头为 $author <$from-address>。

comment

目标备注。

示例 /etc/pve/notifications.cfg：

sendmail: example
  mailto-user root@pam
  mailto-user admin@pve
  mailto max@example.com
  from-address pve1@example.com
  comment Send to multiple users/addresses

17.2.2.SMTP

SMTP 目标直接连 SMTP 中继发邮件 —— 不走系统 MTA。用户作收件人时同样使用其邮箱。

配置项：

mailto / mailto-user / author

同上。

from-address

发件地址 —— SMTP 中继可能要求属用户所有以防伪造。 From 头为 $author <$from-address>。

username

认证用户名 —— 未设则不认证。支持 PLAIN 与 LOGIN。

password

认证密码。

mode

加密 ：insecure / starttls / tls（默认 tls）。

server

SMTP 中继地址 / IP。

port

默认视 mode：25（insecure）、 465（tls）、 587（starttls）。

comment

备注。

示例 /etc/pve/notifications.cfg：

smtp: example
  mailto-user root@pam
  mailto-user admin@pve
  mailto max@example.com
  from-address pve1@example.com
  username pve1
  server mail.example.com
  mode starttls

与 /etc/pve/priv/notifications.cfg 中的密码项：

smtp: example
  password somepassword

17.2.3.Gotify

Gotify 是开源自托管通知服务器 —— 可向各种设备与应用推送通知。配置项：

server

Gotify 服务器基 URL ， 如 http://<ip>:8888。

token

认证令牌 —— 在 Gotify Web 界面生成。

comment

备注。

gotify: example
  server http://gotify.example.com:8888
  comment Send to multiple users/addresses

对应 /etc/pve/priv/notifications.cfg：

gotify: example
  token somesecrettoken

17.2.4.Webhook

对可配置 URL 发起 HTTP 请求。配置项：

url

目标 URL —— 支持模板注入消息、元数据与 secret。

method

POST / PUT / GET。

header

HTTP 头数组 —— 支持模板。

body

HTTP body —— 支持模板。

secret

secret 键值对数组 —— 存于受保护的、仅 root 可读的配置文件。 body / header / URL 模板中以 secrets 命名空间访问。

comment

备注。

模板支持 Handlebars 语法 ， 可用下列属性：

• {{ title }}：渲染后的通知标题
• {{ message }}：渲染后的通知正文
• {{ severity }}：info / notice / warning / error / unknown
• {{ timestamp }}：UNIX 时间戳（秒）
• {{ fields.<name> }}：通知元数据子命名空间（如 fields.type）
• {{ secrets.<name> }}：secret 子命名空间（如 secrets.token）

辅助函数：

• {{ url-encode <value> }}：URL 编码
• {{ escape <value> }}：转义不能安全出现在 JSON 字符串中的控制字符
• {{ json <value> }}：渲染为 JSON —— 可把整个子命名空间塞入 JSON 载荷（如 {{ json fields }}）

示例

ntfy.sh：

Method: POST
URL:    https://ntfy.sh/{{ secrets.channel }}
Headers:
  Markdown: Yes
Body:
  ```
  {{ message }}
  ```
Secrets:
  channel: <your ntfy.sh channel>

Discord：

Method: POST
URL:    https://discord.com/api/webhooks/{{ secrets.token }}
Headers:
  Content-Type: application/json
Body:
  {
    "content": "``` {{ escape message }}```"
  }
Secrets:
  token: <token>

Slack：

Method: POST
URL:    https://hooks.slack.com/services/{{ secrets.token }}
Headers:
  Content-Type: application/json
Body:
  {
    "text": "``` {{escape message}}```",
    "type": "mrkdwn"
  }
Secrets:
  token: <token>

17.3.通知匹配器Notification Matchers

匹配器按规则把通知路由到目标。规则可匹配时间戳（match-calendar）、严重性（match-severity）、元数据字段（match-field）。命中则配置的所有目标都收到通知。可创建任意数量的匹配器 —— 每目标对每通知 最多收到一次， 即便被多个匹配器引用。

无任何规则的匹配器始终为真 —— 配置的目标总是会收到：

matcher: always-matches
  target admin
  comment This matcher always matches

17.3.1.匹配器选项

target

命中时要通知的目标 —— 可多次。

invert-match

对整个匹配器取反。

mode

all（全部规则须命中）或 any（任一命中即可）， 默认 all。

match-calendar

时间戳匹配 schedule。

match-field

匹配元数据字段。

match-severity

匹配严重性。

comment

备注。

17.3.2.日历匹配规则

match-calendar 8-12
match-calendar 8:00-15:30
match-calendar mon-fri 9:00-17:00
match-calendar sun,tue-wed,fri 9-17

17.3.3.字段匹配规则

通知有若干元数据字段可匹配。用 exact 模式时 , 作分隔 —— 字段值是列表中任一即命中：

match-field exact:type=vzdump                   # 仅匹配备份相关
match-field exact:type=replication,fencing       # 复制与 fencing
match-field regex:hostname=^.+\.example\.com$    # 按主机名匹配

17.3.4.严重性匹配规则

match-severity error
match-severity warning,error

已有严重性 ：info / notice / warning / error / unknown。

17.3.5.示例

matcher: workday
  match-calendar mon-fri 9-17
  target admin
  comment Notify admins during working hours

matcher: night-and-weekend
  match-calendar mon-fri 9-17
  invert-match true
  target on-call-admins
  comment Separate target for non-working hours

matcher: backup-failures
  match-field exact:type=vzdump
  match-severity error
  target backup-admins

matcher: cluster-failures
  match-field exact:type=replication,fencing
  target cluster-admins

17.4.通知事件Notification Events

字段说明：

17.5.系统邮件转发System Mail Forwarding

部分本地守护进程（如 smartd）会给本地 root 发邮件 —— 这些邮件被转为 type=system-mail、严重性 unknown 的通知事件 ， 按全局设置处理。转发到 sendmail 目标时邮件内容与头按原样转发；其他目标则尝试从邮件提取主题与正文 —— 仅含 HTML 时会转为纯文本。

17.6.权限Permissions

修改 / 查看通知目标配置需 /mapping/notifications ACL 节点的 Mapping.Modify / Mapping.Audit。测试目标需 Mapping.Use / Mapping.Audit / Mapping.Modify。

17.7.通知模式Notification Mode

备份 job 的 notification-mode 可选：

• notification-system：按全局通知设置发送。
• legacy-sendmail：用系统 sendmail 发到 job 里配置的邮箱 ， 并可选「总是」或「仅失败」发。忽略 全局目标 / 匹配器；等同 PVE 8.1 之前的行为 —— 未来版本可能移除。

17.8.自定义通知模板Overriding Notification Templates

PVE 用 Handlebars 模板渲染通知 —— 原模板位于 /usr/share/pve-manager/templates/default/。可在 /etc/pve/notification-templates/default/ 提供同名覆写文件；渲染时 PVE 先尝试 override 目录 ， 加载失败或不存在才回退到原模板。

文件命名 ：<type>-<body|subject>.<html|txt>.hbs。例如 vzdump-body.html.hbs 渲染备份通知 HTML 版； package-updates-subject.txt.hbs 渲染包更新通知的主题行。

邮件类目标（sendmail / smtp）总是发 multipart（HTML + 纯文本）—— 两个 <type>-body.html.hbs 与 <type>-body.txt.hbs 都会用。其他目标只用 <type>-body.txt.hbs。