OneUptime Proxmox 监控实战：集群节点、QEMU/LXC 虚拟机、存储与 HA 高可用的指标采集与告警配置指南-港品优选

OneUptime Proxmox 监控实战：集群节点、QEMU/LXC 虚拟机、存储与 HA 高可用的指标采集与告警配置指南

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本文以 OneUptime 开源监控平台中的Proxmox Monitor功能为核心，系统讲解如何基于预配置的 OpenTelemetry Collector（即OneUptime Proxmox Agent）采集 Proxmox VE 集群的节点、虚拟机、容器、存储、HA 状态、备份覆盖与存储复制指标，并在 OneUptime 仪表盘中创建 Proxmox 监控器、配置指标查询与告警判定条件。读完本文，你将掌握从部署采集端到配置 11 个预置告警模板的完整链路，并理解pve_*指标体系的命名约定与id标签的派生属性用法。

一、Proxmox 监控能覆盖哪些场景

Proxmox 监控器使用来自你 Proxmox VE 集群的指标，为虚拟化工作负载提供可视化与告警能力，具体可以做到：

监控集群、单节点与每个客户机（guest）的健康状态；
跟踪节点与客户机的 CPU、内存、磁盘与网络使用情况；
发现离线节点以及被停止的虚拟机/容器；
关注存储卷容量逼近上限的风险；
对 HA 状态降级、未纳入任何备份作业的客户机、存储复制失败等异常发出告警。

在 OneUptime 中，Proxmox 数据采集由OneUptime Proxmox Agent完成：它是一个纯配置的 OpenTelemetry Collector，抓取 prometheus-pve-exporter 与 ProxmoxAgent/otel-collector-config.yaml。

二、数据链路：从 Proxmox VE API 到 OneUptime 监控器

在深入配置监控器之前，先理解整条数据链路，这有助于后续排查：

prometheus-pve-exporter将 Proxmox VE API 翻译为 Prometheus 指标（pve_*系列，覆盖节点、客户机、存储与 HA 状态）；
OneUptime Proxmox Agent（OpenTelemetry Collector）每 30 秒抓取一次 exporter 的/pve端点，同时启用cluster=1与node=1两组抓取参数——这同时覆盖了 exporter 默认开启的backup-info（集群级）与replication（节点级）收集器；
Collector 中的transform/pve-identity处理器把id标签拆分成三个可等值过滤的派生属性（pve.scope/pve.type/pve.id），resource处理器写入proxmox.cluster.name资源属性；
数据通过otlphttpexporter（x-oneuptime-token头携带采集密钥）上报到 OneUptime，集群据此自动注册；
Proxmox Monitor按你配置的指标查询、过滤与聚合规则对这些指标进行评估，触发告警。

从源码结构看，监控器配置表单实现在 App/FeatureSet/Dashboard/src/Components/Form/Monitor/ProxmoxMonitor/ProxmoxMonitorStepForm.tsx，而仪表盘 Proxmox 页面内置的安装指引则由 App/FeatureSet/Dashboard/src/Pages/Proxmox/Utils/DocumentationMarkdown.ts 动态生成。

三、创建 Proxmox 监控器

在 OneUptime 仪表盘中按以下步骤创建：

进入 OneUptime Dashboard 的Monitors（监控器）；
点击Create Monitor（创建监控器）；
选择Proxmox作为监控器类型；
选择要监控的 Proxmox 集群；
配置指标查询（metric queries）与聚合方式；
按需配置监控判定条件。

四、配置项详解

4.1 Proxmox Cluster（集群选择）

选择要监控的 Proxmox 集群。集群在 OneUptime Proxmox Agent 首次上报遥测数据时自动注册（以proxmox.cluster.name资源属性为唯一标识），无需手工创建。因此部署后只需等待约一分钟（首次抓取之后），集群即出现在选择器中。

需要特别注意的是，PROXMOX_CLUSTER_NAME必须保持稳定——改变它会注册成一个全新的集群，而不是重命名现有集群。该资源属性由 ProxmoxAgent/otel-collector-config.yaml 中的resource处理器通过upsert动作写入，同时会删除 Prometheus 接收器自动合成的service.name与service.instance.id，避免在 OneUptime 中注册出一个虚假的 "oneuptime-proxmox" Service 而破坏按集群路由与保留策略。

4.2 Metric Queries（指标查询）

为监控器配置一个或多个要评估的指标查询，每个查询包含：

Metric name（指标名）：要查询的 Proxmox 指标（pve_*系列）；
Aggregation（聚合方式）：如何聚合指标值（Avg 平均、Sum 求和、Max 最大、Min 最小）；
Filters（过滤器）：基于原始id标签或派生属性pve.scope/pve.type/pve.id的属性过滤；
Group By（分组）：可选按id标签分组，使每个节点、客户机、存储卷或复制作业被独立评估——每个资源产生一条独立事件。

此外，还可以创建公式（formulas），用数学表达式组合多个指标查询，例如用pve_memory_usage_bytes / pve_memory_size_bytes计算内存百分比。公式两侧的指标来自同一次 exporter 抓取，抓取倍数相互抵消，结果即真实百分比。

4.3`id`标签与派生属性

Agent 采集的每条指标都带有一个id数据点标签，标识该数据点所属的 Proxmox 资源：

`id`值	资源
`node/<name>`	集群节点，例如`node/pve1`
`qemu/<vmid>`	QEMU 虚拟机，例如`qemu/100`
`lxc/<vmid>`	LXC 容器，例如`lxc/101`
`storage/<node>/<storage>`	某节点上的存储卷，例如`storage/pve1/local`

两个例外：复制系列指标（pve_replication_*）的id携带的是复制作业id（如100-0）；集群级的pve_not_backed_up_total则完全没有id标签。

由于监控判定条件和属性过滤器按等值（而非前缀）匹配，Agent 额外将id拆分为三个可等值过滤的数据点属性，内置告警模板依赖它们：

属性	取值	以`qemu/100`为例
`pve.scope`	`node`、`guest`、`storage`、`cluster`（`qemu`和`lxc`都映射为`guest`）	`guest`
`pve.type`	`node`、`qemu`、`lxc`、`storage`	`qemu`
`pve.id`	`id`第一个`/`之后的所有内容（`pve1`、`100`、`pve1/local`）	`100`

实际拆分逻辑由 ProxmoxAgent/otel-collector-config.yaml 中的transform/pve-identity处理器实现：它用IsMatch(attributes["id"], "^qemu/")之类的正则匹配前缀，分别set出pve.scope、pve.type，再用replace_pattern(attributes["pve.id"], "^[^/]+/", "")提取pve.id。原始id标签保持原样——分组页面与下钻仍使用它。注意：不要移除该处理器，否则内置 Proxmox 告警模板的过滤将失效。

用法总结：用pve.scope或pve.type把查询限定到某一类资源；用pve.id（或id）限定到单个资源；按id分组则让每个资源独立评估。

4.4 Rolling Time Window（滚动时间窗口）

选择指标评估的时间窗口，可选值包括：

Past 1 Minute（过去 1 分钟）
Past 5 Minutes（过去 5 分钟）
Past 10 Minutes（过去 10 分钟）
Past 15 Minutes（过去 15 分钟）
Past 30 Minutes（过去 30 分钟）
Past 60 Minutes（过去 60 分钟）

时间窗口决定聚合与判定基于多长的历史数据。

五、采集指标全览

Agent 每 30 秒抓取一次 exporter，并同时启用集群与节点两类收集器。以下按类别列出全部可用指标。

5.1 Availability（可用性）

指标	描述
`pve_up`	节点或客户机在线/运行时为 1，否则为 0
`pve_uptime_seconds`	节点或客户机的运行时长（秒）
`pve_version_info`	元数据系列，其 version/release 标签携带 Proxmox VE 版本（值恒为 1）

5.2 Node（节点）

指标	描述
`pve_node_info`	节点元数据（值恒为 1）——对其求和可统计集群中上报的节点数
`pve_cpu_usage_ratio`	CPU 使用率，0–1 比例（相对可用 CPU）
`pve_cpu_usage_limit`	可用 CPU 核数（客户机为分配的 vCPU 数）
`pve_memory_usage_bytes`	已用内存（字节）
`pve_memory_size_bytes`	总内存（字节）

5.3 Guest（虚拟机 / LXC 容器）

指标	描述
`pve_guest_info`	客户机元数据（name、node、type`qemu`或`lxc`以标签形式携带，值恒为 1）
`pve_network_receive_bytes`	客户机累计接收字节数——以速率（rate）方式绘图查看吞吐
`pve_network_transmit_bytes`	客户机累计发送字节数——以速率方式绘图查看吞吐
`pve_disk_read_bytes`	客户机累计磁盘读取字节数——以速率方式绘图
`pve_disk_write_bytes`	客户机累计磁盘写入字节数——以速率方式绘图
`pve_onboot_status`	客户机配置为随节点启动时为 1——一个`onboot=1`却被停止的客户机通常意味着非预期的停机

CPU 与内存系列（pve_cpu_usage_ratio、pve_memory_usage_bytes等）也会在qemu/*与lxc/*的 id 上按客户机粒度输出。

5.4 Storage（存储）

指标	描述
`pve_disk_usage_bytes`	磁盘/存储已用字节数。对 QEMU 客户机，除非安装了 QEMU guest agent，否则读数为 0
`pve_disk_size_bytes`	磁盘/存储总容量（字节）
`pve_storage_info`	存储元数据（值恒为 1）——对其求和可统计存储卷数量

5.5 HA（高可用）

指标	描述
`pve_ha_state`	高可用状态以枚举式系列呈现：每个可能状态（`started`、`stopped`、`error`等）一条系列，当前状态值为 1——用`state`标签过滤即可针对特定状态告警

5.6 Backup Coverage（备份覆盖）

来自 exporter 集群级的backup-info收集器（默认开启）。需要明确边界：这些指标只反映备份作业的覆盖情况——备份最近是否运行、是否成功，pve-exporter 并不暴露：

指标	描述
`pve_not_backed_up_total`	未被任何备份作业覆盖的客户机数量。这是一个集群级系列，没有`id`标签
`pve_not_backed_up_info`	每个未覆盖客户机一条系列（值恒为 1），以该客户机的`id`作为标签。按`id`分组可列出未覆盖客户机——一旦客户机加入备份作业，该系列即消失

5.7 Replication（存储复制）

来自 exporter 节点级的replication收集器（默认开启）。系列的id标签携带复制作业id（如100-0）：

指标	描述
`pve_replication_failed_syncs`	该作业连续失败的同步尝试次数——只要大于 0，就说明副本正在变陈旧
`pve_replication_duration_seconds`	作业最近一次同步的耗时
`pve_replication_last_sync_timestamp_seconds`	最近一次成功同步的 Unix 时间戳
`pve_replication_last_try_timestamp_seconds`	最近一次同步尝试的 Unix 时间戳——若晚于 last-sync，说明最近一次尝试失败了
`pve_replication_next_sync_timestamp_seconds`	下次计划同步的 Unix 时间戳
`pve_replication_info`	作业元数据（值恒为 1），带 type、source、target 与 guest 标签

注意：判定引擎没有墙钟（wall-clock）数学运算，因此副本陈旧度（now − last_sync）无法直接告警——Proxmox 集群总览页是在客户端计算它的。应改为对pve_replication_failed_syncs告警（即下文"Replication Failing"模板）。

六、监控判定条件（Monitoring Criteria）

6.1 评估对象

Proxmox 监控器始终评估Metric Value——即所配置指标查询或公式的取值。判定表单没有Filter Type 选择器，只显示Metric（指标）、Aggregation（聚合）、**Condition（条件）**与Threshold（阈值）。

6.2 聚合类型

聚合	描述
Average	时间窗口内的平均值
Sum	所有值的总和
Maximum Value	时间窗口内的最高值
Minimum Value	时间窗口内的最低值
All Values	所有值都必须满足条件
Any Value	至少一个值满足条件

6.3 条件

静态阈值——与你输入的Threshold比较：

Greater Than（大于）、Less Than（小于）、Greater Than or Equal To（大于等于）、Less Than or Equal To（小于等于）、Equal To（等于）

基线异常检测——无需阈值，表单改为显示 **Sensitivity（敏感度）**与Baseline Window（基线窗口），将每个样本与由该窗口构建的"同小时同星期"基线比较：

Anomalously High（异常偏高）——数值超出预期范围；
Anomalously Low（异常偏低）——数值低于预期范围；
Anomalous（异常）——数值向任一方向离开预期范围。

异常条件在积累至少一个所选基线窗口的历史指标之前，会一直处于 **"Learning"（学习）**状态，不产生任何告警。

七、预置告警模板（Pre-built Alert Templates）

OneUptime 内置11 个针对常见 Proxmox 监控场景的模板。每个模板都会构建一个完整的监控器——指标查询、属性过滤、分组、触发条件与自动恢复条件——应用后仍可编辑。阈值为初始建议值。除非表格另有说明，模板均评估过去 5 分钟的数据，且条件必须在窗口内每一分钟都成立才会触发：

模板	严重级别	监控内容	触发时机
Node Offline（节点离线）	Critical	`pve_up`过滤`pve.scope=node`，按`id`取 Min	任一节点报告值低于 1。每个节点一条事件；恢复条件为 ≥ 1
Guest Down（客户机宕机）	Warning	`pve_up`与`pve_onboot_status`过滤`pve.scope=guest`，按`id`取 Min	配置为随开机启动（`pve_onboot_status`= 1）的客户机在整窗口内`pve_up`低于 1。刻意停止的客户机会被自动排除，永不触发
Cluster Quorum at Risk（集群仲裁风险）	Critical	公式：`pve_up`÷`pve_node_info`× 100（两侧均 Sum，`pve.scope=node`）= 在线节点百分比	在线节点 ≤ 50%——由于 pve-exporter 不暴露 corosync 指标，这是诚实的仲裁代理指标
High Node CPU Usage（节点 CPU 高占用）	Warning	`pve_cpu_usage_ratio`过滤`pve.scope=node`，按`id`取 Avg	> 0.9（节点 90% 的 CPU 核）
High Node Memory Usage（节点内存高占用）	Warning	公式：`pve_memory_usage_bytes`÷`pve_memory_size_bytes`× 100，`pve.scope=node`，按`id`	> 节点内存的 85%——真实百分比，无需逐节点调整字节阈值
High Guest CPU Usage（客户机 CPU 高占用）	Warning	`pve_cpu_usage_ratio`过滤`pve.scope=guest`，按`id`取 Avg，过去 15 分钟	> 0.95（分配 vCPU 的 95%），且 15 分钟窗口内每一分钟都成立——客户机本就应该使用其配额，因此只有始终不降下来的客户机才会触发
Storage Near Full（存储逼近满载）	Warning	公式：`pve_disk_usage_bytes`÷`pve_disk_size_bytes`× 100，`pve.scope=storage`，按`id`	> 存储卷容量的 85%
Container Root Disk Near Full（容器根盘逼近满载）	Warning	同一磁盘比例公式，过滤`pve.type=lxc`，按`id`	> 90%。QEMU 虚拟机被排除——其客户机内磁盘用量在未安装 QEMU guest agent 时读数为 0
HA Resource in Error State（HA 资源处于错误状态）	Critical	`pve_ha_state`过滤`state=error`，按`id`取 Max	> 0——HA 无法恢复该资源；恢复条件为 0
Guest Not Backed Up（客户机未备份）	Warning	`pve_not_backed_up_total`，取 Max（单条集群级系列，无分组）	> 0——至少一个客户机未纳入任何备份作业；恢复条件为 0。将`pve_not_backed_up_info`按`id`分组可列出具体客户机。仅覆盖作业成员关系——不反映备份是否运行或成功
Replication Failing（复制失败）	Critical	`pve_replication_failed_syncs`，按`id`（复制作业 id）取 Max	> 0——作业副本正在变陈旧；恢复条件为 0

关于模板内置选择的说明：宕机/离线类模板使用Min，使单次宕机抓取即可触发阈值，而不会被资源仍然在线的抓取掩盖——Guest Down还额外要求同一id上的pve_onboot_status，确保主动停机的客户机永远不会被寻呼；CPU 类模板使用Avg，因为pve_cpu_usage_ratio本身就是 0–1 比例，按分钟平均即持续利用率；状态类模板（HA、备份、复制）使用Max，使一次坏抓取即可触发。比例公式两侧都用Sum聚合——分子分母来自同一次 exporter 抓取，抓取倍数相互抵消，结果是真实百分比。所有模板均预先用pve.scope/pve.type过滤并按id分组，因此每个受影响的资源产生一条独立事件。

八、部署前置要求（Setup Requirements）

使用 Proxmox 监控前需要完成：

在能访问 Proxmox VE API 的机器上安装 OneUptime Proxmox Agent——完整指引见 App/FeatureSet/Docs/Content/en/telemetry/proxmox.md。所需的只读 API token是两行pveum命令（同样在该文档中）：
```
pveum user token add monitoring@pam oneuptime --privsep 1 pveum acl modify / --roles PVEAuditor --tokens 'monitoring@pam!oneuptime'
```
ACL 必须挂在根路径/上，因为PVEAuditor需要读取 exporter 遍历到的每个节点、客户机与存储对象——收窄路径会隐藏集群其余部分并产生401/403 Permission check failed (/, Sys.Audit)错误。
通过环境变量传入ONEUPTIME_URL、ONEUPTIME_TELEMETRY_INGESTION_KEY、PROXMOX_CLUSTER_NAME以及 Proxmox API 细节（PVE_HOST、PVE_API_TOKEN_ID、PVE_API_TOKEN_SECRET；已有 exporter 时用PVE_EXPORTER_URL指向它）；
等待集群自动注册（首次抓取后约一分钟）。

关键环境变量速查（完整说明见 ProxmoxAgent/README.md）：

变量	必填	说明
`ONEUPTIME_URL`	是	OneUptime 实例 URL
`ONEUPTIME_TELEMETRY_INGESTION_KEY`	是	遥测采集密钥（Project Settings → Telemetry Ingestion Keys）
`PROXMOX_CLUSTER_NAME`	是	集群标识，作为`proxmox.cluster.name`资源属性打在每条指标上。保持稳定（默认`proxmox-cluster`）
`PVE_HOST`	是	exporter 查询的 Proxmox VE API 主机（集群任意节点）
`PVE_EXPORTER_URL`	否	prometheus-pve-exporter 地址（`host:port`，不带 scheme），默认内置 exporter（`pve-exporter:9221`）
`PVE_API_TOKEN_ID`/`PVE_API_TOKEN_SECRET`	仅内置 exporter	Proxmox API token 完整 id 与密钥
`PVE_VERIFY_SSL`	否	是否校验证书（默认`false`，PVE 使用自签名证书）
`COMPOSE_PROFILES`	否	设为`pve-exporter`以启动内置 exporter 容器

Proxmox VE 9+ 零安装替代方案：PVE 9.0 及以上可通过内置的 OpenTelemetry metric server 原生推送指标（Datacenter → Metric Server → Add → OpenTelemetry），服务器填 OneUptime 主机、端口443、协议https、路径/otlp/v1/metrics、请求头{"x-oneuptime-token": "你的采集密钥"}。两个注意事项：一是必须把 Resource Attributes 设为proxmox.cluster.name=my-proxmox-cluster才能自动注册集群；二是原生推送的指标名是proxmox_*（proxmox_node_*/proxmox_vm_*/proxmox_storage_*）而非pve_*——本文及模板、指标目录均针对 Agent 采集路径。

九、故障排查

集群未出现在监控器的集群选择器中

集群由 Agent 的遥测数据自行注册。检查 Agent 是否在运行并正常上报（参考 App/FeatureSet/Docs/Content/en/telemetry/proxmox.md 中的"Verify the Installation"），并确认PROXMOX_CLUSTER_NAME已设置。

客户机指标缺失

客户机系列来自 exporter 的集群收集器（cluster=1抓取参数，随附配置已启用）。如果你自定义过 collector 配置，请恢复它。仅见节点指标、无客户机指标时，重点检查otel-collector-config.yaml中的cluster: ["1"]参数是否还在。

"High Node CPU Usage"不触发

该模板评估按id标签分组的pve_cpu_usage_ratio的Avg，每个节点独立检查。如果你自建了查询，务必按id分组——未分组的全集群平均值会被空闲节点稀释，很难越过阈值。

备份或复制指标缺失

pve_not_backed_up_*来自 exporter 集群级backup-info收集器，pve_replication_*来自其节点级replication收集器——两者默认开启，由随附配置的cluster=1/node=1抓取参数覆盖。若自建 exporter，确认没有禁用这两个收集器。另外，pve_replication_*系列只在集群配置了存储复制作业时才会存在。

计数器类指标（如`pve_network_receive_bytes`）只增不减

网络与磁盘 I/O 系列是累计计数器（cumulative counter）。应基于其变化速率告警（或用滚动窗口上的公式），而不是针对原始值。

十、总结

Proxmox Monitor 把 OneUptime 的监控能力延伸到了整个 Proxmox VE 虚拟化栈：从节点与客户机的可用性、资源用量，到存储水位、HA 状态、备份覆盖与存储复制，全部统一为pve_*指标并通过 OTLP 汇集。掌握id标签与pve.scope/pve.type/pve.id派生属性的等值过滤语义，是正确配置指标查询与分组评估的关键；而 11 个预置模板则提供了经过权衡的成熟起点（Min/Avg/Max 的选取逻辑、真实百分比公式、逐资源独立事件），可在其上继续调优。下一步可以结合 App/FeatureSet/Docs/Content/en/telemetry/proxmox.md 完成采集端部署，并参考 ProxmoxAgent/otel-collector-config.yaml 理解处理器细节。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析