> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/zh/mo-kuai-9-jian-kong-yu-gu-zhang-pai-chu/04-prometheus-grafana.md).

# Prometheus 与 Grafana 集成

## 外部指标为何重要

VergeOS 仪表板提供实时健康状况和分析，但企业监控策略通常需要一个集中式、时序型存储，用于跨多个系统汇总指标、保留超过 UI 内 45 天窗口的数据，并触发复杂的告警规则。 **vergeos-exporter** 通过以 Prometheus 格式公开 VergeOS 指标来弥补这一差距——这也是云原生监控的事实标准。

运行导出器后，您将获得长期趋势分析、跨系统关联能力以及与现有告警流水线的集成——而这一切都无需修改 VergeOS 系统本身。

```mermaid
graph LR
    subgraph vergeos["VergeOS 环境"]
        API["VergeOS REST API"]
    end

    subgraph monitoring["监控栈"]
        EXP["vergeos-exporter<br/>:9888/metrics"]
        PROM["Prometheus<br/>抓取与存储"]
        GRAF["Grafana<br/>仪表板"]
        ALERT["AlertManager<br/>通知"]
    end

    API -->|"API 调用<br/>(list/read)"| EXP
    EXP -->|"基于拉取的<br/>抓取"| PROM
    PROM --> GRAF
    PROM --> ALERT
    ALERT -->|"电子邮件、Slack、<br/>PagerDuty"| OPS["运维团队"]

    style vergeos fill:#f0f4ff,stroke:#336
    style monitoring fill:#f0fff4,stroke:#363
```

## vergeos-exporter

该 **vergeos-exporter** 是 Verge 维护的一个开源工具，位于 [verge-io/vergeos-exporter](https://github.com/verge-io/vergeos-exporter) GitHub 仓库中。它连接到 VergeOS REST API，收集基础设施指标，并通过一个 HTTP 端点公开这些指标，Prometheus 会按可配置的时间间隔抓取该端点。

### 公开的指标

该导出器收集三类指标：

### vSAN 层级指标

每个层级的容量、使用量和分配。事务和修复计数。驱动器状态监控（在线、离线、修复中、初始化中、验证中、无冗余、空间不足）。驱动器温度和健康数据。读/写操作和 IOPS。

### 集群指标

每个集群的节点数量。RAM、CPU 和磁盘利用率。同步状态和健康状况。

### 节点指标

每个节点的 CPU 和内存使用率。网络吞吐量和延迟。每个节点的服务状态。

完整的指标参考可在导出器仓库中的 `metrics.md` 文件里找到。

### 架构：基于拉取的抓取

vergeos-exporter 采用标准的 Prometheus 拉取模型。Prometheus 通过按配置的时间间隔抓取导出器上的 `/metrics` 端点来发起连接（通常为 15–60 秒）。这种方式意味着：

* **不需要入站防火墙规则** 在 VergeOS 系统本身上
* 导出器可以运行在 **任何主机上** 只要该主机能访问 VergeOS API 的网络
* 多个 Prometheus 实例可以抓取同一个导出器，以实现高可用
* 该导出器 **兼容 AlertManager** ——Prometheus 告警规则可原生使用这些公开的指标

## 服务账户配置

在部署导出器之前，请在 VergeOS 中创建一个权限最小化的专用服务账户。

### 分步说明：创建导出器服务账户

1. 导航至 **系统 → 用户** 在 VergeOS UI 中
2. 单击 **新建** 创建新用户
3. 填写 **新用户** 表单：
   * **用户名：** `prometheus-exporter` （或类似的描述性名称）
   * **类型：** `API`
   * **密码：** 一个强随机生成的值
   * **双因素认证：** 保持 **未勾选** ——导出器通过 API 用户名/密码进行身份验证
4. 单击 **提交** 以保存

新的 Normal/API 用户默认获得 **对所有内容的 list/read 权限** ，这正是导出器所需要的。若要进一步收紧范围，可在 **系统 → 权限** 下缩小授权范围，前提是用户已创建。

{% hint style="warning" %}
**安全最佳实践**

切勿为导出器使用管理员账户。服务账户只需要用于查询指标的 list 和 read 访问权限，因此保留默认设置即可，或者在 **系统 → 权限** 下进一步收紧——同时通过使用强随机生成的密码并限制对导出器主机的网络访问，来弥补机器到机器凭据的风险。
{% endhint %}

## 部署选项

vergeos-exporter 支持多种部署模式。请选择最适合您监控基础设施的一种。

### 选项 1：独立二进制文件

可从 [GitHub Releases](https://github.com/verge-io/vergeos-exporter/releases) 页面下载适用于 Linux、Windows 和 macOS（amd64 和 arm64）的预编译二进制文件。

```bash
# 下载并解压（Linux amd64 示例）
wget https://github.com/verge-io/vergeos-exporter/releases/latest/download/vergeos-exporter-linux-amd64.tar.gz
tar xzf vergeos-exporter-linux-amd64.tar.gz

# 使用必需的标志运行
./vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
```

默认情况下，导出器监听端口 **9888** 。如有需要，可通过 `-web.listen-address` 标志进行覆盖。

### 选项 2：Linux systemd 服务

对于生产环境中的 Linux 部署，请将导出器作为受管理的 systemd 服务运行：

```ini
# /etc/systemd/system/vergeos-exporter.service
[Unit]
Description=VergeOS Prometheus Exporter
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=vergeos_exporter
ExecStart=/usr/local/bin/vergeos-exporter \\
  -verge.url https://your-vergeos-host \\
  -verge.username prometheus-exporter \\
  -verge.password 'YourStrongPassword'
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
# 创建服务用户，启用并启动
sudo useradd -r -s /usr/sbin/nologin vergeos_exporter
sudo systemctl daemon-reload
sudo systemctl enable --now vergeos-exporter
```

### 选项 3：Windows 服务（NSSM）

在 Windows 监控主机上，使用 [NSSM（Non-Sucking Service Manager）](https://nssm.cc/) 将导出器作为 Windows 服务运行：

1. 下载 NSSM 并将 `nssm.exe` 放在一个永久位置（例如， `C:\\Program Files\\nssm\\`)
2. 注册该服务：

```powershell
nssm install vergeos-exporter "C:\\monitoring\\vergeos-exporter.exe"
nssm set vergeos-exporter AppParameters "-verge.url https://your-vergeos-host -verge.username prometheus-exporter -verge.password YourStrongPassword"
nssm set vergeos-exporter Start SERVICE_AUTO_START
nssm start vergeos-exporter
```

### 选项 4：Docker Compose

仓库中包含一个现成的 Docker Compose 示例，位于 `examples/docker-compose/` ，它将导出器、Prometheus 和 Grafana 打包到一个单独的栈中——非常适合快速评估或实验室环境。

```yaml
# 简化的 docker-compose.yml 结构
services:
  vergeos-exporter:
    image: vergeos-exporter:latest
    ports:
      - "9888:9888"
    environment:
      - VERGE_URL=https://your-vergeos-host
      - VERGE_USERNAME=prometheus-exporter
      - VERGE_PASSWORD=YourStrongPassword

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
```

该 Docker Compose 示例会自动为您的架构获取正确的平台专用二进制文件。

## Prometheus 配置

将导出器添加为您的 `prometheus.yml`:

```yaml
中的抓取目标
  - job_name: "vergeos"
    scrape_interval: 30s
    scrape_timeout: 30s
    static_configs:
      - targets: ["exporter-host:9888"]
        labels:
          environment: "production"
          cluster: "site-a"
```

要监控多个 VergeOS 环境，请为每个环境部署一个导出器，并将每个导出器作为单独的目标添加（或者使用 Prometheus relabeling 进行动态发现）。

## Grafana 仪表板

vergeos-exporter 附带一个预配置的 Grafana 仪表板（`examples/grafana-dashboard.json`），开箱即用地涵盖 vSAN、集群和节点指标。

### 仪表板面板包括

| 类别          | 面板                        |
| ----------- | ------------------------- |
| **vSAN 性能** | 层级容量和使用率仪表、IOPS 图表、读/写吞吐量 |
| **集群健康状况**  | 节点数量、同步状态、CPU 和 RAM 总体利用率 |
| **节点详情**    | 每个节点的 CPU、内存、网络吞吐量和温度     |
| **存储健康状况**  | 驱动器状态、修复状态、错误计数器          |

### 导入仪表板

1. 打开 Grafana 并导航到 **仪表板 → 导入**
2. 单击 **上传 JSON 文件** 并选择 `grafana-dashboard.json` 来自导出器仓库的文件
3. 选择您的 **Prometheus 数据源** 从下拉菜单中选择
4. 单击 **导入**

一旦 Prometheus 开始接收导出器指标，该仪表板就会立即可用。

## 验证

部署后，验证导出器是否正在收集指标：

```bash
# 直接测试指标端点
curl -s http://localhost:9888/metrics | head -20

# 预期输出包含如下行：
# HELP vergeos_vsan_tier_capacity_bytes 每个 vSAN 层级的总容量
# TYPE vergeos_vsan_tier_capacity_bytes gauge
# vergeos_vsan_tier_capacity_bytes{tier="1"} 1.234567e+12
```

如果端点返回指标，Prometheus 将在下一个间隔自动抓取它们。请查看 Prometheus 的 **目标** 页面（`http://prometheus:9090/targets`）以确认 `vergeos` 任务显示状态为 **UP**.

### 故障排查清单

| 症状                 | 查看                                           |
| ------------------ | -------------------------------------------- |
| 未返回指标              | 验证 VergeOS 的 URL、用户名和密码是否正确                  |
| 连接被拒绝              | 确认导出器进程正在运行并监听 9888                          |
| 身份验证错误             | 确认该服务账户的 **Type = API** 并且彼此之间 **双因素认证** 未勾选 |
| 部分指标               | 验证服务账户是否具有 **list 和 read** 权限                |
| Prometheus 目标 DOWN | 检查 Prometheus 与导出器主机之间的网络连通性                 |
| 抓取超时               | 增加 `-scrape.timeout` （大型环境默认 30 秒）           |

## 与 AlertManager 集成

由于该导出器公开的是标准 Prometheus 指标，您可以编写在阈值被突破时触发的告警规则：

```yaml
# vergeos 指标示例告警规则
groups:
  - name: vergeos_alerts
    rules:
      - alert: VSANTierNearCapacity
        expr: vergeos_vsan_tier_usage_bytes / vergeos_vsan_tier_capacity_bytes > 0.85
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "vSAN 层级 {{ $labels.tier }} 已超过 85% 容量"

      - alert: DriveOffline
        expr: vergeos_vsan_drive_state{state="offline"} > 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "驱动器 {{ $labels.drive }} 在节点 {{ $labels.node }} 上处于离线状态"
```

AlertManager 可以将这些告警路由到电子邮件、Slack、PagerDuty、OpsGenie 或任何 webhook 端点——将 VergeOS 监控集成到您现有的事件管理工作流中。

## 替代方案：直接通过 Zabbix 集成 API

如果您的组织使用的是 Zabbix 而不是 Prometheus，您可以使用 Zabbix HTTP Agent 项直接查询 VergeOS REST API：

1. 通过以下方式创建 API 令牌： **系统 → API 文档** （Swagger UI）
2. 使用 Zabbix HTTP Agent 项轮询如下端点： `/api/v4/vms`, `/api/v4/nodes`, `/api/v4/vnets`
3. 通过 POST 到以下地址进行身份验证： `/api/sys/tokens` 并在 `x-yottabyte-token` 头中传递会话令牌

由于其更丰富的指标集和预置仪表板，Prometheus 导出器仍然是大多数环境的推荐方案。

{% hint style="info" %}
**来自 VMware 或 Nutanix？**

VergeOS 通过 **vergeos-exporter**公开平台指标，该端点以标准 Prometheus 格式呈现 vSAN、集群和节点数据。Prometheus 从端口 **9888** 拉取抓取导出器，而 Grafana 渲染捆绑的仪表板——因此 VergeOS 指标会流入许多团队已经与其现有平台并行运行的同一个 Prometheus + Grafana 栈中。
{% endhint %}

## 要点总结

* 该 **vergeos-exporter** 以标准 Prometheus 格式公开 vSAN、集群和节点指标，端口为 **9888** ，采用标准 Prometheus 格式
* 创建一个 **专用的 API 类型服务账户** ——对于新的 Normal/API 用户，list/read 对所有内容是默认权限
* 可部署为独立二进制文件、systemd 服务、Windows 服务（NSSM）或 Docker Compose 栈
* 捆绑的 **Grafana 仪表板** 可立即查看存储、集群和节点健康状况
* Prometheus **AlertManager** 集成可对容量、驱动器健康状况和性能阈值进行主动告警
* 该导出器使用 **基于拉取的抓取** ——VergeOS 系统上无需更改入站防火墙


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-9-jian-kong-yu-gu-zhang-pai-chu/04-prometheus-grafana.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.