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 AgentOpenTelemetry Collector每 30 秒抓取一次 exporter 的/pve端点同时启用cluster1与node1两组抓取参数——这同时覆盖了 exporter 默认开启的backup-info集群级与replication节点级收集器Collector 中的transform/pve-identity处理器把id标签拆分成三个可等值过滤的派生属性pve.scope/pve.type/pve.idresource处理器写入proxmox.cluster.name资源属性数据通过otlphttpexporterx-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.3id标签与派生属性Agent 采集的每条指标都带有一个id数据点标签标识该数据点所属的 Proxmox 资源id值资源node/name集群节点例如node/pve1qemu/vmidQEMU 虚拟机例如qemu/100lxc/vmidLXC 容器例如lxc/101storage/node/storage某节点上的存储卷例如storage/pve1/local两个例外复制系列指标pve_replication_*的id携带的是复制作业id如100-0集群级的pve_not_backed_up_total则完全没有id标签。由于监控判定条件和属性过滤器按等值而非前缀匹配Agent 额外将id拆分为三个可等值过滤的数据点属性内置告警模板依赖它们属性取值以qemu/100为例pve.scopenode、guest、storage、clusterqemu和lxc都映射为guestguestpve.typenode、qemu、lxc、storageqemupve.idid第一个/之后的所有内容pve1、100、pve1/local100实际拆分逻辑由 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否则为 0pve_uptime_seconds节点或客户机的运行时长秒pve_version_info元数据系列其 version/release 标签携带 Proxmox VE 版本值恒为 15.2 Node节点指标描述pve_node_info节点元数据值恒为 1——对其求和可统计集群中上报的节点数pve_cpu_usage_ratioCPU 使用率0–1 比例相对可用 CPUpve_cpu_usage_limit可用 CPU 核数客户机为分配的 vCPU 数pve_memory_usage_bytes已用内存字节pve_memory_size_bytes总内存字节5.3 Guest虚拟机 / LXC 容器指标描述pve_guest_info客户机元数据name、node、typeqemu或lxc以标签形式携带值恒为 1pve_network_receive_bytes客户机累计接收字节数——以速率rate方式绘图查看吞吐pve_network_transmit_bytes客户机累计发送字节数——以速率方式绘图查看吞吐pve_disk_read_bytes客户机累计磁盘读取字节数——以速率方式绘图pve_disk_write_bytes客户机累计磁盘写入字节数——以速率方式绘图pve_onboot_status客户机配置为随节点启动时为 1——一个onboot1却被停止的客户机通常意味着非预期的停机CPU 与内存系列pve_cpu_usage_ratio、pve_memory_usage_bytes等也会在qemu/*与lxc/*的 id 上按客户机粒度输出。5.4 Storage存储指标描述pve_disk_usage_bytes磁盘/存储已用字节数。对 QEMU 客户机除非安装了 QEMU guest agent否则读数为 0pve_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 Criteria6.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 TemplatesOneUptime 内置11 个针对常见 Proxmox 监控场景的模板。每个模板都会构建一个完整的监控器——指标查询、属性过滤、分组、触发条件与自动恢复条件——应用后仍可编辑。阈值为初始建议值。除非表格另有说明模板均评估过去 5 分钟的数据且条件必须在窗口内每一分钟都成立才会触发模板严重级别监控内容触发时机Node Offline节点离线Criticalpve_up过滤pve.scopenode按id取 Min任一节点报告值低于 1。每个节点一条事件恢复条件为 ≥ 1Guest Down客户机宕机Warningpve_up与pve_onboot_status过滤pve.scopeguest按id取 Min配置为随开机启动pve_onboot_status 1的客户机在整窗口内pve_up低于 1。刻意停止的客户机会被自动排除永不触发Cluster Quorum at Risk集群仲裁风险Critical公式pve_up÷pve_node_info× 100两侧均 Sumpve.scopenode 在线节点百分比在线节点 ≤ 50%——由于 pve-exporter 不暴露 corosync 指标这是诚实的仲裁代理指标High Node CPU Usage节点 CPU 高占用Warningpve_cpu_usage_ratio过滤pve.scopenode按id取 Avg 0.9节点 90% 的 CPU 核High Node Memory Usage节点内存高占用Warning公式pve_memory_usage_bytes÷pve_memory_size_bytes× 100pve.scopenode按id 节点内存的 85%——真实百分比无需逐节点调整字节阈值High Guest CPU Usage客户机 CPU 高占用Warningpve_cpu_usage_ratio过滤pve.scopeguest按id取 Avg过去 15 分钟 0.95分配 vCPU 的 95%且 15 分钟窗口内每一分钟都成立——客户机本就应该使用其配额因此只有始终不降下来的客户机才会触发Storage Near Full存储逼近满载Warning公式pve_disk_usage_bytes÷pve_disk_size_bytes× 100pve.scopestorage按id 存储卷容量的 85%Container Root Disk Near Full容器根盘逼近满载Warning同一磁盘比例公式过滤pve.typelxc按id 90%。QEMU 虚拟机被排除——其客户机内磁盘用量在未安装 QEMU guest agent 时读数为 0HA Resource in Error StateHA 资源处于错误状态Criticalpve_ha_state过滤stateerror按id取 Max 0——HA 无法恢复该资源恢复条件为 0Guest Not Backed Up客户机未备份Warningpve_not_backed_up_total取 Max单条集群级系列无分组 0——至少一个客户机未纳入任何备份作业恢复条件为 0。将pve_not_backed_up_info按id分组可列出具体客户机。仅覆盖作业成员关系——不反映备份是否运行或成功Replication Failing复制失败Criticalpve_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 monitoringpam oneuptime --privsep 1 pveum acl modify / --roles PVEAuditor --tokens monitoringpam!oneuptimeACL 必须挂在根路径/上因为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 实例 URLONEUPTIME_TELEMETRY_INGESTION_KEY是遥测采集密钥Project Settings → Telemetry Ingestion KeysPROXMOX_CLUSTER_NAME是集群标识作为proxmox.cluster.name资源属性打在每条指标上。保持稳定默认proxmox-clusterPVE_HOST是exporter 查询的 Proxmox VE API 主机集群任意节点PVE_EXPORTER_URL否prometheus-pve-exporter 地址host:port不带 scheme默认内置 exporterpve-exporter:9221PVE_API_TOKEN_ID/PVE_API_TOKEN_SECRET仅内置 exporterProxmox API token 完整 id 与密钥PVE_VERIFY_SSL否是否校验证书默认falsePVE 使用自签名证书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.namemy-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 的集群收集器cluster1抓取参数随附配置已启用。如果你自定义过 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收集器——两者默认开启由随附配置的cluster1/node1抓取参数覆盖。若自建 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），仅供参考
