通知

概述

当发生存储复制失败、节点 fencing、备份完成/失败以及其他事件时，Proxmox VE 会发出通知事件。这些事件由通知系统处理。通知事件带有元数据，例如时间戳、严重级别、类型，以及其他可选元数据字段。
通知匹配器会将通知事件路由到一个或多个通知目标。匹配器可以配置匹配规则，根据通知事件的元数据进行选择性路由。
通知目标是匹配器将通知事件路由到的目的地。目标有多种类型，包括基于邮件的 Sendmail 和 SMTP，以及 Gotify。

备份任务可以配置通知模式。该模式允许在通知系统和旧版通知邮件发送方式之间选择。旧版模式等同于 Proxmox VE 8.1 之前处理通知的方式。

通知系统可以在 GUI 的 Datacenter → Notifications 下配置。配置存储在 /etc/pve/notifications.cfg 和 /etc/pve/priv/notifications.cfg 中，后者包含通知目标的密码或认证 token 等敏感配置选项，只能由 root 读取。

通知目标

Proxmox VE 提供多种类型的通知目标。

Sendmail

sendmail 二进制程序常见于类 Unix 操作系统，用于处理电子邮件消息的发送。它是一个命令行工具，允许用户和应用程序直接从命令行或脚本中发送电子邮件。

Sendmail 通知目标使用 sendmail 二进制程序向已配置的用户或电子邮件地址列表发送邮件。如果选择用户作为收件人，则使用该用户设置中配置的电子邮件地址。对于 root@pam 用户，这就是安装期间输入的电子邮件地址。用户的电子邮件地址可以在 Datacenter → Permissions → Users 中配置。如果用户没有关联电子邮件地址，则不会发送邮件。

在标准 Proxmox VE 安装中，sendmail 二进制程序由 Postfix 提供。可能需要配置 Postfix 才能正确投递邮件，例如设置外部邮件中继（smart host）。如果投递失败，请检查系统日志中 Postfix 守护进程记录的消息。

Sendmail 目标插件配置包含以下选项：

mailto: 通知应发送到的电子邮件地址。可设置多次以支持多个收件人。
mailto-user: 应接收邮件的用户。用户的电子邮件地址会从 users.cfg 中查找。可设置多次以支持多个收件人。
author: 设置电子邮件作者。默认为 Proxmox VE。
from-address: 设置电子邮件发件地址。如果未设置该参数，插件会回退到 datacenter.cfg 中的 email_from 设置。如果该设置也未设置，插件默认使用 root@$hostname，其中 $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

SMTP

SMTP 通知目标可以直接向 SMTP 邮件中继发送电子邮件。该目标不使用系统的 MTA 投递邮件。与 sendmail 目标类似，如果选择用户作为收件人，则使用该用户配置的电子邮件地址。

与 sendmail 目标不同，SMTP 目标在邮件投递失败时没有任何排队/重试机制。

SMTP 目标插件配置包含以下选项：

mailto: 通知应发送到的电子邮件地址。可设置多次以支持多个收件人。
mailto-user: 应接收邮件的用户。用户的电子邮件地址会从 users.cfg 中查找。可设置多次以支持多个收件人。
author: 设置电子邮件作者。默认为 Proxmox VE。
from-address: 设置电子邮件的 From 地址。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 中包含密钥 token 的对应条目：

smtp: example
        password somepassword

Gotify

Gotify 是一个开源的自托管通知服务器，允许向各种设备和应用程序发送并接收推送通知。它提供简单的 API 和 Web 界面，便于与不同平台和服务集成。

Gotify 目标插件配置包含以下选项：

server: Gotify 服务器的基础 URL，例如 http://<ip>:8888
token: 认证 token。可以在 Gotify Web 界面中生成 token。
comment: 此目标的注释。

Gotify 目标插件会遵循数据中心配置中的 HTTP 代理设置。

配置示例（/etc/pve/notifications.cfg）：

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

/etc/pve/priv/notifications.cfg 中包含密钥 token 的对应条目：

gotify: example
        token somesecrettoken

Webhook

Webhook 通知目标会向可配置的 URL 执行 HTTP 请求。

可用配置选项如下：

url: 执行 HTTP 请求的 URL。支持通过模板注入消息内容、元数据和 secret。
method: 要使用的 HTTP Method（POST/PUT/GET）。
header: 请求应设置的 HTTP 头数组。支持通过模板注入消息内容、元数据和 secret。
body: 应发送的 HTTP body。支持通过模板注入消息内容、元数据和 secret。
secret: secret 键值对数组。它们会存储在仅 root 可读的受保护配置文件中。可以在 body/header/URL 模板中通过 secrets 命名空间访问 secret。
comment: 此目标的注释。

对于支持模板的配置选项，可以使用 Handlebars 语法访问以下属性：

{{ title }}: 渲染后的通知标题。
{{ message }}: 渲染后的通知正文。
{{ severity }}: 通知严重级别（info、notice、warning、error、unknown）。
{{ timestamp }}: 通知时间戳，以 UNIX epoch 表示（秒）。
{{ fields.<name> }}: 通知任意元数据字段的子命名空间。例如，fields.type 包含通知类型；所有可用字段请参见通知事件。
{{ secrets.<name> }}: secret 的子命名空间。例如，名为 token 的 secret 可通过 secrets.token 访问。

为方便使用，提供以下 helper：

{{ url-encode <value/property> }}: 对属性/字面量进行 URL 编码。
{{ escape <value/property> }}: 转义无法安全表示为 JSON 字符串的控制字符。
{{ json <value/property> }}: 将值渲染为 JSON。将整个子命名空间（例如 fields）作为 JSON payload 的一部分传递时很有用，例如 {{ 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>

通知匹配器

screenshot/gui-datacenter-notification-matcher.png

通知匹配器根据匹配规则将通知路由到通知目标。这些规则可以匹配通知的特定属性，例如时间戳（match-calendar）、通知严重级别（match-severity）或元数据字段（match-field）。如果通知被某个匹配器匹配，该匹配器配置的所有目标都会收到通知。

可以创建任意数量的匹配器，每个匹配器都可以有自己的匹配规则和要通知的目标。即使某个目标被多个匹配器使用，每条通知最多也只会向该目标发送一次。

没有任何匹配规则的匹配器始终为 true；其配置的目标始终会被通知。

matcher: always-matches
        target admin
        comment 该匹配器始终匹配

匹配器选项

target: 确定匹配器命中时应通知哪个目标。可多次使用以通知多个目标。
invert-match: 反转整个匹配器的结果。
mode: 确定如何评估各个匹配规则以计算整个匹配器的结果。设置为 all 时，所有匹配规则都必须匹配。设置为 any 时，至少一个规则匹配即可。默认为 all。
match-calendar: 将通知时间戳与日程匹配。
match-field: 匹配通知的元数据字段。
match-severity: 匹配通知严重级别。
comment: 此匹配器的注释。

日历匹配规则

日历匹配器会将通知发送时间与可配置日程进行匹配。

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

字段匹配规则

通知包含若干可匹配的元数据字段。使用 exact 作为匹配模式时，可以使用 , 作为分隔符。只要元数据字段具有任意一个指定值，该匹配规则即匹配。

match-field exact:type=vzdump 仅匹配与备份相关的通知。
match-field exact:type=replication,fencing 匹配 replication 和 fencing 通知。
match-field regex:hostname=^.+\.example\.com$ 匹配节点主机名。

如果被匹配的元数据字段不存在，则通知不会匹配。例如，match-field regex:hostname=.* 指令只会匹配具有任意 hostname 元数据字段的通知；如果该字段不存在，则不会匹配。

严重级别匹配规则

通知具有关联的严重级别，可用于匹配。

match-severity error: 仅匹配错误。
match-severity warning,error: 匹配警告和错误。

当前使用以下严重级别： info, notice, warning, error, unknown.

示例

matcher: workday
        match-calendar mon-fri 9-17
        target admin
        comment 工作时间通知管理员

matcher: night-and-weekend
        match-calendar mon-fri 9-17
        invert-match true
        target on-call-admins
        comment 非工作时间使用独立目标

matcher: backup-failures
        match-field exact:type=vzdump
        match-severity error
        target backup-admins
        comment 将备份失败通知发送给一组管理员

matcher: cluster-failures
        match-field exact:type=replication,fencing
        target cluster-admins
        comment 将集群相关通知发送给另一组管理员

通知事件

事件	type	严重级别	元数据字段（除 type 外）
系统更新可用	package-updates	info	hostname
集群节点被 fencing	fencing	error	hostname
存储复制任务失败	replication	error	hostname, job-id
备份成功	vzdump	info	hostname, job-id（仅备份任务）
备份失败	vzdump	error	hostname, job-id（仅备份任务）
root 邮件	system-mail	unknown	hostname

事件

type

严重级别

元数据字段（除 type 外）

系统更新可用

package-updates

info

hostname

集群节点被 fencing

fencing

error

hostname

存储复制任务失败

replication

error

hostname, job-id

备份成功

vzdump

info

hostname, job-id（仅备份任务）

备份失败

vzdump

error

hostname, job-id（仅备份任务）

root 邮件

system-mail

unknown

hostname

字段名	说明
type	通知类型
hostname	不含域名的主机名（例如 pve1）
job-id	任务 ID

字段名

说明

type

通知类型

hostname

不含域名的主机名（例如 pve1）

job-id

任务 ID

只有根据调度自动执行的备份任务通知才会设置 job-id；如果通过 UI 中的 Run now 按钮手动触发，则不会设置该字段。

系统邮件转发

某些本地系统守护进程（例如 smartd）会生成通知邮件，这些邮件最初发送给本地 root 用户。Proxmox VE 会将这些邮件送入通知系统，并作为类型为 system-mail、严重级别为 unknown 的通知处理。

当电子邮件转发到 sendmail 目标时，邮件内容和头部会按原样转发。对于所有其他目标，系统会尝试从邮件内容中提取主题行和正文文本。如果邮件只包含 HTML 内容，则会在此过程中转换为纯文本格式。

权限

要修改/查看通知目标配置，需要在 /mapping/notifications ACL 节点上具备 Mapping.Modify/Mapping.Audit 权限。

测试目标需要在 /mapping/notifications 上具备 Mapping.Use、Mapping.Audit 或 Mapping.Modify 权限。

通知模式

备份任务配置包含 notification-mode 选项，可取以下三个值之一。

auto: 如果在 mailto/Send email to 字段中输入了电子邮件地址，则使用 legacy-sendmail 模式。如果未输入电子邮件地址，则使用 notification-system 模式。
legacy-sendmail: 通过系统的 sendmail 命令发送通知邮件。通知系统会被绕过，所有已配置的目标/匹配器都会被忽略。该模式等同于 Proxmox VE 8.1 之前版本的通知行为。
notification-system: 使用新的灵活通知系统。

如果未设置 notification-mode 选项，Proxmox VE 默认使用 auto。

legacy-sendmail 模式可能会在 Proxmox VE 未来版本中移除。

覆盖通知模板

Proxmox VE 使用 Handlebars 模板渲染通知。Proxmox VE 提供的原始模板存储在 /usr/share/pve-manager/templates/default/。

可以通过在覆盖目录 /etc/pve/notification-templates/default/ 中提供自定义模板文件来覆盖通知模板。渲染指定类型的通知时，Proxmox VE 会首先尝试从覆盖目录加载模板。如果该模板不存在或渲染失败，则使用原始模板。

模板文件遵循 <type>-<body|subject>.<html|txt>.hbs 命名约定。例如， vzdump-body.html.hbs 包含用于渲染备份通知 HTML 版本的模板，而 package-updates-subject.txt.hbs 用于渲染可用软件包更新通知的主题行。

基于电子邮件的通知目标（例如 sendmail 和 smtp）始终发送同时包含 HTML 和纯文本部分的 multi-part 消息。因此，渲染电子邮件消息时会同时使用 <type>-body.html.hbs 和 <type>-body.txt.hbs 模板。所有其他通知目标类型只使用 <type>-body.txt.hbs 模板。

常用命令示例

查看通知配置文件：

# cat /etc/pve/notifications.cfg

查看包含敏感字段的私有通知配置文件权限：

# ls -l /etc/pve/priv/notifications.cfg