企业官网建设流程全解析

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent

本文以 OneUptime 仓库中的 Proxmox Monitor 文档为主线，完整讲解如何监控 Proxmox VE 集群的节点、QEMU 虚拟机、LXC 容器、存储、HA 状态、备份任务覆盖与存储复制，并深入 agent 的 OpenTelemetry Collector 配置与pve_*指标体系。读完本文，你将掌握 Proxmox Monitor 的创建流程、指标查询与公式配置、内置告警模板的原理，以及部署 Proxmox Agent 和排查问题的完整实战方案。

概述：Proxmox 监控能做什么

OneUptime 的 Proxmox 监控能力让你可以透视整个 Proxmox VE 集群的虚拟化工作负载。监控数据由OneUptime Proxmox Agent（一个预配置的 OpenTelemetry Collector）负责采集，再根据你在 OneUptime 中配置的指标标准进行评估。它能带来以下几类核心能力：

• 监控集群、节点以及每个 guest（虚拟机/容器）的健康状态
• 跨节点与 guest 追踪 CPU、内存、磁盘和网络的用量
• 及时发现离线节点与已停止的虚拟机/容器
• 观察接近容量上限的存储卷
• 对 HA 降级状态、未被任何备份任务覆盖的 guest、以及失败的存储复制发出告警

数据链路可以概括为：Proxmox VE API→prometheus-pve-exporter（把 API 翻译成pve_*Prometheus 指标）→Proxmox Agent（OTel Collector 抓取并打上集群身份标签）→OTLP上报 OneUptime。

创建 Proxmox Monitor

在 OneUptime Dashboard 中创建 Proxmox 监控的步骤如下：

1. 进入Monitors（监控器）页面
2. 点击Create Monitor（创建监控器）
3. 监控类型选择Proxmox
4. 选择要监控的 Proxmox 集群
5. 配置指标查询与聚合方式
6. 按需配置监控判定标准（criteria）

集群本身无需手动创建——集群会在 Proxmox Agent 第一次向其上报遥测数据时自动注册，注册的键是资源属性proxmox.cluster.name（见后文 agent 配置）。因此在创建监控之前，请先确保 Agent 已经部署并开始上报（详见本文「部署 Proxmox Agent」一节）。

配置选项详解

Proxmox 集群选择

在选择器中挑选要监控的集群即可。集群的自动注册机制由 Agent 的resource处理器实现——在 otel-collector-config.yaml 中，每个指标批次都会被写入proxmox.cluster.name属性：

resource: attributes: - key: proxmox.cluster.name value: "${env:PROXMOX_CLUSTER_NAME}" action: upsert

配置中特别强调：保持该值稳定，不要随意修改，否则会注册出一个全新的集群（与旧集群的数据割裂，也会影响按集群的保留期设置）。

指标查询（Metric Queries）

每个监控可以配置一个或多个指标查询，每个查询需要指定：

• 指标名称（Metric name）——要查询的 Proxmox 指标，即pve_*系列
• 聚合（Aggregation）——指标值的聚合方式：平均值、总和、最大值、最小值
• 过滤器（Filters）——基于属性过滤：可以直接过滤原始id标签，也可以过滤派生的pve.scope/pve.type/pve.id属性（见下节）
• Group By（分组）——可选地按id标签分组，使每个节点、guest、存储卷或复制任务被独立评估——每个受影响资源各产生一个事件

还可以创建公式（formulas），用数学表达式组合多个指标查询，例如用pve_memory_usage_bytes / pve_memory_size_bytes计算内存使用百分比。

id标签与派生属性

Agent 采集的每个指标都携带一个id数据点标签，用于标识该数据点所属的 Proxmox 资源。取值规则如下：

两个例外情况：复制系列指标（pve_replication_*）在id中携带的是复制任务的 id（例如100-0）；而集群级别的pve_not_backed_up_total则根本没有id标签。

由于监控判定标准和属性过滤器都按相等（equality）而非前缀匹配，Agent 额外把id拆分成三个可用相等匹配过滤的数据点属性，内置告警模板正是依赖它们：

这个拆分动作由 otel-collector-config.yaml 中的transform/pve-identity处理器完成，其核心逻辑是若干条set语句，例如：

- set(attributes["pve.scope"], "guest") where attributes["id"] != nil and IsMatch(attributes["id"], "^qemu/") - set(attributes["pve.type"], "qemu") where attributes["id"] != nil and IsMatch(attributes["id"], "^qemu/") - set(attributes["pve.id"], attributes["id"]) where attributes["id"] != nil and IsMatch(attributes["id"], "/") - replace_pattern(attributes["pve.id"], "^[^/]+/", "") where attributes["pve.id"] != nil

配置中的注释明确警告：不要移除这个处理器，内置的 Proxmox 告警模板都依赖这些属性做过滤。原始的id标签会被原样保留，供 Group By 页面和细分视图使用。

使用建议：

• 用pve.scope或pve.type过滤，把查询限定到某一类资源；
• 用pve.id（或id）过滤，把查询限定到某一个具体资源；
• 按id分组，则每个资源被独立评估。

滚动时间窗口

指标评估的时间窗口可选：

• 过去 1 分钟
• 过去 5 分钟
• 过去 10 分钟
• 过去 15 分钟
• 过去 30 分钟
• 过去 60 分钟

采集的指标全集

Proxmox Agent 每30 秒抓取一次 prometheus-pve-exporter，同时启用 cluster 与 node 两类采集器——这同时也覆盖了 exporter 默认开启的backup-info（集群级）与replication（节点级）采集器。抓取配置见 otel-collector-config.yaml：

scrape_configs: - job_name: oneuptime-proxmox metrics_path: /pve params: target: ["${env:PVE_HOST}"] cluster: ["1"] node: ["1"] scrape_interval: 30s static_configs: - targets: ["${env:PVE_EXPORTER_URL}"]

配置注释说明了 30 秒间隔的取舍：pve-exporter 每次抓取都会对 Proxmox VE API 做一次实时往返，30 秒可以把 pveproxy 上的负载控制在可忽略的水平。

可用性

节点

Guest（虚拟机 / LXC 容器）

CPU 与内存系列（pve_cpu_usage_ratio、pve_memory_usage_bytes等）也会在每个 guest 上以qemu/*和lxc/*的 id 发布。

存储

HA 高可用

备份覆盖

来自 exporter 集群级的backup-info采集器（默认启用）。需要特别说明边界：这些指标只报告备份任务的覆盖情况——pve-exporter 并不暴露"备份最近是否运行或成功"的信息：

复制

来自 exporter 节点级的replication采集器（默认启用）。各系列在id标签中携带复制任务id（例如100-0）：

重要限制：判定引擎没有时钟运算（wall-clock math），因此无法直接对副本陈旧度（当前时间 − 上次同步）告警——Proxmox 集群的 Overview 页面是在客户端计算这一数值的。替代方案是对pve_replication_failed_syncs告警（使用下文"Replication Failing"模板）。

监控判定标准（Monitoring Criteria）

评估对象

Proxmox 监控器始终评估 Metric Value——即所配置指标查询或公式的值。因此判定表单没有 Filter Type 选择器，只显示Metric、Aggregation、Condition和Threshold。

聚合类型

条件

静态阈值——与你输入的 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（学习）状态，直到积累了至少等于所设 Baseline Window 长度的指标历史，在此之前不会产生任何告警。

11 个内置告警模板

OneUptime 为常见 Proxmox 监控场景内置了11 个模板。每个模板都会构建一个完整的监控器——包括指标查询、属性过滤器、分组、触发条件（fire criteria）与自动恢复条件（auto-recover criteria），应用后仍可编辑。阈值只是起点。模板默认评估过去 5 分钟（除非表中另有说明），且条件必须在其窗口内的每一分钟都成立才会触发：

模板背后的设计取舍

模板中蕴含了几条值得借鉴的监控设计原则：

• 下线/离线类模板用 Min（最小值）：单次下线抓取即可触发阈值，而不会被资源仍然在线时的抓取值掩盖。Guest Down额外要求同一id上有pve_onboot_status，因此故意停掉的 guest 永远不会打扰你。
• CPU 类模板用 Avg（平均值）：pve_cpu_usage_ratio本身就是 0–1 的比率，每分钟的平均值即持续利用率。
• 状态类模板（HA、备份、复制）用 Max（最大值）：一次坏抓取即可触发。
• 比率公式两侧都用 Sum 聚合：分子与分母来自同一次 exporter 抓取，抓取倍数相互抵消，结果才是真实百分比。
• 模板均预先用pve.scope/pve.type过滤并按id分组，因此每个受影响资源各自触发一条事件。

部署 Proxmox Agent

前置条件

• 任意能访问你的 Proxmox VE API（端口 8006）的机器，装有 Docker Engine 20.10+ 与 Docker Compose v2 插件
• 一个拥有PVEAuditor（只读）角色的 Proxmox VE API Token
• 一个OneUptime Telemetry Ingestion Key（在Project Settings → Telemetry Ingestion Keys创建）

创建 Proxmox API Token（两条命令）

在任意 PVE 节点上以 root 身份执行：

pveum user token add monitoring@pam oneuptime --privsep 1 pveum acl modify / --roles PVEAuditor --tokens 'monitoring@pam!oneuptime'

（如果monitoring@pam用户还不存在，先执行pveum user add monitoring@pam——API Token 自带独立密钥，因此该用户无需密码或系统账户。）

关键要点：ACL 必须挂在根路径/上，因为 PVEAuditor 需要读取 exporter 遍历的每个节点、guest 和存储对象的权限——若授予更窄的路径，集群其余部分会被隐藏并产生401/403 Permission check failed (/, Sys.Audit)错误。第一条命令只会打印一次 Token 密钥，之后在.env中对应为PVE_API_TOKEN_ID=monitoring@pam!oneuptime与PVE_API_TOKEN_SECRET=<打印出的密钥>。

也可以走 Proxmox Web UI（Datacenter → Permissions → API Tokens），记得在路径/上授予 PVEAuditor 角色，并取消 Privilege Separation。

部署位置建议

Agent 通过网络查询 PVE API，因此不必（也不建议）运行在集群节点上。最好放在能在节点故障时存活的机器上（独立硬件上的小监控 VM、管理主机），或者把PVE_HOST指向 VIP / round-robin DNS 而非单个节点地址——如果 Agent 的 API 目标正是刚宕掉的节点，你的监控也会跟着一起死。唯一的例外是可选的 journald 日志管线，它必须运行在 PVE 节点上。

Docker Compose 快速启动

从 agents/ProxmoxAgent 目录下载docker-compose.yml与otel-collector-config.yaml，在同目录创建.env：

ONEUPTIME_URL=https://oneuptime.com ONEUPTIME_TELEMETRY_INGESTION_KEY=your-telemetry-ingestion-key PROXMOX_CLUSTER_NAME=my-proxmox-cluster PVE_HOST=192.168.1.10 PVE_API_TOKEN_ID=oneuptime@pve!exporter PVE_API_TOKEN_SECRET=your-token-secret COMPOSE_PROFILES=pve-exporter

启动（pve-exporterprofile 会同时启动内置的 exporter 容器）：

docker compose up -d

集群会在一分钟左右自动出现在 OneUptime 的Proxmox区域。如果你已经在别处运行 pve-exporter，可以去掉COMPOSE_PROFILES、PVE_API_TOKEN_ID、PVE_API_TOKEN_SECRET，改用：

PVE_EXPORTER_URL=your-exporter-host:9221

环境变量一览

关于 Token 的拆分，docker-compose.yml 中有个实现细节：prometheus-pve-exporter 要求 Token 拆成用户部分（PVE_USER）与 Token 名部分（PVE_TOKEN_NAME），而.env中保存的是 UI 显示的完整 id（user@realm!tokenname），compose 文件通过 shell 参数展开把它拆开：

export PVE_USER="$${PVE_API_TOKEN_ID%%!*}" PVE_TOKEN_NAME="$${PVE_API_TOKEN_ID##*!}" && exec /usr/bin/pve_exporter

（$$用于屏蔽 docker compose 的插值；exporter 会忽略其他未知的PVE_*变量。）

验证安装

docker compose ps # 检查 agent 状态 docker logs -f oneuptime-proxmox-agent # 查看采集器日志

日志中应看到"Everything is ready. Begin running and processing data."，一分钟后集群即可在 Dashboard 中出现。

可选的日志上报（Proxmox 服务日志）

默认 Agent 只上报指标，Proxmox dashboard 的 Logs 页签需要额外启用日志接收器。PVE 控制面把日志写到 systemd journal 下的 8 个单元：pveproxy、pvedaemon、pve-firewall、pve-ha-crm、pve-ha-lrm、pvescheduler、pvestatd、qmeventd。启用步骤（详见 agents/ProxmoxAgent/README.md）：

1. 在 PVE 节点上运行 Agent（journal 按主机隔离，远端 agent 读不到）；
2. 取消 otel-collector-config.yaml 中journald接收器与logs管线的注释；
3. 在docker-compose.yml中挂载 journal 卷（/var/log/journal与/etc/machine-id）；
4. 替换镜像：官方otel/opentelemetry-collector-contrib镜像基于 scratch 构建，没有journalctl二进制且以非 root 运行，需换成包含 systemd 的包装镜像，或在节点上直接运行otelcol-contrib的.deb包。

不想换镜像也有备选：在节点上安装 rsyslog，用filelog接收器 tail/var/log/syslog（挂载整个/var/log目录而非单个文件，避免日志轮转钉住陈旧 inode），代价是失去按单元的过滤能力。

Proxmox VE 9+ 零安装替代方案

Proxmox VE 9.0+ 可以通过内置的 OpenTelemetry 指标服务器直接向 OneUptime 推送指标（Datacenter → Metric Server → Add → OpenTelemetry），无需 Agent 与 exporter：

• Server：你的 OneUptime 主机
• Port：443，Protocol：https
• Path：/otlp/v1/metrics
• Headers：{"x-oneuptime-token": "your-telemetry-ingestion-key"}

两个需要注意的权衡：

1. 集群发现：Agent 路径之所以能驱动集群自动注册，是因为它盖了proxmox.cluster.name资源属性。原生推送时需在 Resource Attributes 中设置proxmox.cluster.name=my-proxmox-cluster，否则指标会入库但不会出现 Proxmox 集群；
2. 指标名不同：原生推送发出的是proxmox_node_*/proxmox_vm_*/proxmox_storage_*系列，而 Agent 路径是 pve-exporter 的pve_*系列。OneUptime 内置的 Proxmox 监控目录与告警模板针对的是pve_*命名——因此本文的模板与指标目录适用于 Agent 路径。

故障排查

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

集群靠 Agent 的遥测自动注册。请检查 Agent 是否在运行并在上报（见上面的验证安装），以及PROXMOX_CLUSTER_NAME是否已设置。docker logs oneuptime-proxmox-agent中的401表示接入密钥错误，connection refused 表示ONEUPTIME_URL不对。

缺少 guest 指标

guest 系列来自 exporter 的集群采集器（cluster=1抓取参数，随附配置已启用）。如果你自定义过采集器配置，请恢复它。

"High Node CPU Usage" 不触发

模板对按id标签分组的pve_cpu_usage_ratio取平均值，每个节点独立检查。如果你改用了自定义查询，务必按id分组——不加分组地对所有节点取平均值会被空闲节点稀释，很难越过阈值。

缺少备份或复制指标

pve_not_backed_up_*来自 exporter 集群级backup-info采集器，pve_replication_*来自节点级replication采集器——两者默认启用，并受随附配置中cluster=1/node=1抓取参数覆盖。如果你自己运行 exporter，检查是否禁用了这些采集器。另外pve_replication_*系列只在集群配置了存储复制任务时才存在。

pve_network_receive_bytes等计数器只增不减

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

深入阅读

• 监控文档（本主题）：packages/App/FeatureSet/Docs/Content/en/monitor/proxmox-monitor.md
• Agent 安装与运维指南：agents/ProxmoxAgent/README.md
• Agent 的 OTLP Collector 配置（含transform/pve-identity与抓取参数）：agents/ProxmoxAgent/otel-collector-config.yaml
• 内置 exporter 的 Compose 编排：agents/ProxmoxAgent/docker-compose.yml
• 遥测接入文档（Token 创建与安装细节）：packages/App/FeatureSet/Docs/Content/en/telemetry/proxmox.md

• 可观测性
• 后端
• 运维
• 前端
• 云原生
• 微服务
• AI Agent