Prometheus + Grafana 监控

已经在用 Prometheus 生态、或者想要更灵活的告警规则和看板，这篇讲怎么把 PVE 接进去。

导出器是第三方项目，不是 Proxmox 官方产品

本文用到的 prometheus-pve-exporter 是社区维护的开源项目，托管在 GitHub（prometheus-pve/prometheus-pve-exporter），不属于 Proxmox 官方发行的软件。它的更新节奏、兼容性和对新版 PVE API 的支持，都以它自己的项目仓库为准，不受本站或 Proxmox 官方支持周期的约束。

为什么需要它

Prometheus 生态的优势是灵活的查询语言 (PromQL)、成熟的告警组件 (Alertmanager)，以及大量现成的 Grafana 看板模板。PVE 内置的外部指标服务器是「推送」模式，直接发给 InfluxDB/Graphite；Prometheus 习惯的是「拉取」模式，需要一个中间层把 PVE 的 API 数据转换成 Prometheus 能抓取的格式——这就是导出器 (Exporter) 的作用。

开始之前

• 已经有 Prometheus 和 Grafana 的部署（本文不讲怎么装它们）。
• 建议把导出器部署在一台独立的虚拟机或 LXC 容器里，而不是直接装在 PVE 宿主机上，避免给宿主机引入额外的 Python 依赖环境。
• 给导出器用的账号只给只读权限，不要用 root。

架构简述

Prometheus（定时抓取）→ prometheus-pve-exporter（转换）→ PVE API（提供数据）
                                                              ↓
                                                    Grafana（读 Prometheus，画图/告警）

导出器本身监听一个端口（默认 9221），Prometheus 定时向它发请求，它再实时调用 PVE 的 REST API 拿数据、转换成 Prometheus 格式返回。

操作步骤

1. 建一个专用的只读账号和 Token

参考用户、组、角色与权限路径和API Token 与最小权限，只给 PVEAuditor 角色：

# 宿主机 shell
pveum user add pve-exporter@pve --comment "只读账号，供 Prometheus 导出器使用"
pveum acl modify / --user pve-exporter@pve --roles PVEAuditor
pveum user token add pve-exporter@pve exporter-token --privsep 1
pveum acl modify / --tokens 'pve-exporter@pve!exporter-token' --roles PVEAuditor

记下弹出的 Token Secret，只显示这一次。

2. 部署导出器

用 Docker 是最省事的方式：

# 部署导出器的机器（建议是独立的虚拟机/容器，不是 PVE 宿主机）上执行
docker pull prompve/prometheus-pve-exporter

准备一份配置文件（占位符 <...> 替换成实际值）：

default:
  user: pve-exporter@pve
  token_name: exporter-token
  token_value: <刚才复制的Token Secret>
  verify_ssl: false

verify_ssl: false 只在 PVE 用自签证书时需要；给 Web UI 换过受信任证书（见宿主机加固）之后应该改回 true。

导出器跑起来之后监听 9221 端口，访问 http://<导出器地址>:9221/pve?target=<pve节点地址> 能看到一大段 Prometheus 格式的文本指标。

大规模环境关掉 config 采集器

默认的 config 采集器会对每一台虚拟机/容器单独发一次 API 请求取配置，客户机数量多时会拖慢每次抓取。用 --no-collector.config 关掉它，除非确实需要监控配置级别的信息。

3. 配置 Prometheus 抓取

在 prometheus.yml 里加一个 job（占位符替换成实际地址）：

scrape_configs:
  - job_name: 'pve'
    static_configs:
      - targets:
          - <pve节点地址>
    metrics_path: /pve
    params:
      module: [default]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: <导出器地址>:9221

重启 Prometheus 或触发热加载后，去 Prometheus 的 Targets 页面确认这个 job 的状态是 UP。

4. 在 Grafana 里接上

添加 Prometheus 作为数据源（指向已经在抓取 PVE 指标的那个 Prometheus 实例），然后搜索现成的 Proxmox VE Exporter 看板导入，或者自己按需要的指标（例如 pve_up 表示节点/客户机/存储是否在线）搭建面板。

检查结果

1. curl http://<导出器地址>:9221/pve?target=<pve节点地址>，确认返回一大段以 pve_ 开头的指标文本。
2. Prometheus 的 Targets 页面显示这个 job 状态为 UP，scrape_duration_seconds 在合理范围。
3. Grafana 面板上能看到实时数据，且时间范围拉长后历史数据也在。

常见问题

导出器报证书错误连不上 PVE。 PVE 默认用自签证书，配置里加 verify_ssl: false（仅限内网可信环境），或者把 PVE 的 CA 证书导入导出器所在机器的信任链，长期看后者更稳妥。

Prometheus 里这个 target 一直 DOWN。 先直接用 curl 测试导出器本身能不能访问，排除是导出器故障还是 Prometheus 抓取配置写错（relabel 部分最容易配错，认真核对 target 参数是否正确传递）。

客户机多的时候抓取经常超时。 关掉 config 采集器（见上文），或者把 Prometheus 的 scrape_timeout 适当调大。

导出器装在 PVE 宿主机上，升级 PVE 时把 Python 环境搞乱了。 这是不建议直接装宿主机的原因，优先用独立虚拟机/容器或者 Docker 隔离运行环境。

参考资料

• prometheus-pve-exporter（第三方项目，GitHub 仓库）
• Prometheus 官方文档
• Grafana 官方文档
• 外部指标服务器：InfluxDB 与 Graphite
• API Token 与最小权限