Nightingale 生态 Zabbix 集成实战：Categraf Zabbix 插件与 HTTP 实时导出配置全解

本文以夜莺（Nightingale）仓库内置的 Zabbix 集成（integrations/Zabbix）为主体，系统讲解如何通过 Categraf 的 Zabbix 插件，以 HTTP 实时导出方式把 Zabbix 采集的历史数据接入统一监控体系：包括插件监听端口（endpoint）与 Zabbix Connector 的对接、Zabbix API 元数据拉取与指标转换规则（key_ 转指标名、单位与主机信息转标签）、完整配置项说明，以及配套 Prometheus 查询仪表盘的使用方法。读完本文，你将能独立完成「Zabbix → Categraf → 指标库 → 仪表盘」这条数据链路的配置、验证与排障。

一、集成背景：为什么需要 Zabbix 数据桥接

Zabbix 是业界广泛使用的传统监控系统，已有大量存量主机、模板与监控项（Item）。在引入以 Prometheus 数据模型为核心的现代监控体系时，往往不希望放弃 Zabbix 侧已有的采集资产。Nightingale 仓库的 integrations/Zabbix 目录正是为此准备的桥接方案：它随仓库提供 Categraf 插件配置、配套仪表盘与国际化资源，让 Zabbix 数据能够以标准指标形式进入统一监控平台。

该目录结构如下：

• collect/zabbix/zabbix.toml：Categraf 的 Zabbix 插件采集配置，内含大量预置的 Item key 兼容清单；
• dashboards/zabbix-host-detail-enhanced.json：面向 Zabbix 主机详情场景的增强版仪表盘；
• i18n/en_US.json：仪表盘文案的英文国际化；
• markdown/zabbix.md 与 markdown/README.en_US.md：中英文说明文档。

需要说明的是：插件本体运行在 Categraf（夜莺生态的采集 Agent）中，本仓库提供的是配套集成文件；下文所有配置路径均以本仓库根目录为基准。

二、工作原理：HTTP 实时导出 + API 元数据增强

在动手配置前，先理解这条链路的数据流。集成文档明确指出我们采用的是 HTTP 方式实时导出：

1. Categraf 的 zabbix 插件启动一个本地监听端口（如 :9101），该端口用于接收 Zabbix 推送的数据；
2. 该端口必须与 Zabbix Connector 中配置的端口保持一致，否则数据无法送达；
3. 收到推送的历史数据后，Categraf 会通过 Zabbix API 获取 Item 详细信息，用于正确转换数据；
4. 转换时遵循一条关键规则：推送的历史数据中，Item 的 key_ 比 name 更适合直接作为指标名称，而 Item 的单位、关联主机信息则用作标签，用来丰富指标的含义。

这条规则决定了最终指标的样子：指标名来自 Zabbix 的 key_（机械、稳定、唯一），而人可读的名称、单位、主机归属等信息全部下沉为标签，符合 Prometheus 的指标设计惯例，也便于后续按主机、业务组维度聚合查询。

从源码结构看，采集配置中同时提供了 endpoint 与 data_dir 两种数据接入方式的注释说明（见下文配置详解），HTTP 实时导出只是其中一种更实时的选择。

三、核心配置详解

3.1 最小可用配置

集成文档给出的核心配置如下（即 zabbix.md 中的示例）：

[[items]]
……


[[instances]]
endpoint=":9101"

[instances.zabbix]
server="http://192.168.10.222"
version="7.2"
api_token="xxxxx"
##name_as_tag=true

各关键配置说明：

配置项	含义	说明
endpoint	Categraf 监听端口，用于接收 Zabbix 推送的数据	格式为 :端口号，需与 Zabbix Connector 的推送端口保持一致
instances.zabbix.server	Zabbix 服务器地址	形如 http://192.168.10.222，Categraf 通过该地址调用 Zabbix API
instances.zabbix.version	Zabbix 版本	示例为 7.2，需按实际部署的 Zabbix 大版本填写
instances.zabbix.api_token	Zabbix API Token	在 Zabbix 前端创建的 Token，用于 API 鉴权
instances.zabbix.name_as_tag	是否将 Item 名称作为标签	调试时可启用，默认注释掉

3.2 完整配置：来自插件默认配置文件的扩展

仓库自带的 collect/zabbix/zabbix.toml 给出了更完整的选项，包括被注释掉的另一种接入方式与备用鉴权方式：

#[[instances]]
## choose either endpoint or data_dir
#endpoint=":91091"
#data_dir="/home/flashcat/zabbix/data"
##prefix="zabbix"

#[instances.zabbix]
#server="http://192.168.10.222"
#version="7.2"
#username="Admin"
#password="zabbix"
##name_as_tag=true

这里透露出三个值得注意的扩展点：

• endpoint 与 data_dir 二选一：注释明确写着 choose either endpoint or data_dir。endpoint 对应 HTTP 实时推送模式；data_dir 则指定一个本地目录（如 /home/flashcat/zabbix/data），插件从该目录读取 Zabbix 导出的数据文件，适合 Zabbix 无法直接外推、只能落盘导出的受限网络场景。
• 两种鉴权方式：除了 api_token，还可以使用 username + password 走传统的用户口令鉴权调用 Zabbix API。
• 指标前缀：prefix="zabbix" 控制最终指标名的前缀，默认即为 zabbix，与下文仪表盘中大量 zabbix_* 指标一一对应。

3.3 [[items]] 段：预置 Item key 兼容清单

在 [[instances]] 之前，配置文件大篇幅列出了 [[items]] 段，每一项给出一个 Zabbix Item 的 key 模板及其 default_value 参数占位符。其作用是声明插件需要识别、并可为其填充默认参数的 Item key 形态，覆盖了 Zabbix 官方模板中的常见监控项，例如：

[[items]]
key="system.cpu.util[<cpu>,<type>,<mode>,<logical_or_physical>]"
default_value={cpu="all",type="user",mode="avg1",logical_or_physical="logical"}

[[items]]
key="vfs.fs.size[<fs>,<mode>]"
default_value={fs="",mode="total"}

[[items]]
key="net.if.in[<if>,<mode>]"
default_value={if="",mode="bytes"}

[[items]]
key="vm.memory.size[<mode>]"
default_value={mode="total"}

[[items]]
key="zabbix[queue,<from>,<to>]"
default_value={from = "6s"}

从清单可以看到其覆盖面非常广：

• 操作系统类：system.cpu.*、system.swap.*、system.uptime、system.users.num、proc.num、proc.cpu.util 等；
• 文件系统与磁盘：vfs.fs.*、vfs.dev.*、vfs.file.*、vfs.dir.*；
• 网络类：net.if.*、net.tcp.*、net.udp.*、icmpping、icmppingloss、icmppingsec；
• 数据库与中间件：mysql.*、pgsql.*、mongodb.*、redis.*、mssql.*、oracle.*、memcached.*、mqtt.get；
• 硬件与虚拟化：sensor[*]、smart.*、nvml.*（GPU）、web.certificate.get、docker.*、vm.vmemory.size；
• Zabbix 自监控：zabbix[queue,...]、zabbix[process,...]、zabbix[version]、zabbix[proxy,...]、zabbix[connector_queue] 等。

default_value 中的参数占位符（如 <file>、<fs>、<mode>）配合默认值（如 mode="total"、cpu="all"），用于在 Zabbix 推送的 key 未携带完整参数时补全，确保指标解析稳定。这意味着大部分标准模板监控项无需额外适配即可被正确转换。

四、Zabbix 侧的准备步骤

集成文档中的 api_token="xxxxx" 与注释「上面创建的 API Token」表明，配置插件前需要在 Zabbix 侧完成前置动作。结合文档上下文，Zabbix 侧需要准备两件事：

1. 创建 API Token：在 Zabbix 前端的管理界面中为 Categraf 创建 API Token（或复用具备只读权限的用户口令），用于后续插件调用 server 地址上的 API 拉取 Item 元数据；
2. 配置 Connector 推送端口：在 Zabbix Connector 中配置向 Categraf 推送历史数据的地址与端口，该端口必须与插件 endpoint 保持一致。文档明确指出：「这里这个端口要和 Zabbix connector 的端口保持一致」。

注意：api_token 与 username/password 是两种互斥的鉴权方案，按需选择其一即可；server 地址需要能被运行 Categraf 的机器访问。

五、指标转换规则与标签设计

这是集成设计的核心，文档用一句话做了精炼概括，值得展开：

推送的历史数据中，item 的 key_ 比 name 更适合直接作为指标名称，而 item 的单位、关联主机信息则用作标签，丰富指标的含义。

落到实际指标上，配合默认 prefix="zabbix"，key_ 会被转换为以 zabbix_ 开头的指标名。这一点在配套仪表盘 zabbix-host-detail-enhanced.json 的查询语句中得到了直接印证，例如：

max by(host_name,host,ident)(zabbix_agent_ping{group=~"$group",host_name=~"$host"})

(100 - max by(host_name,host,ident)(zabbix_system_cpu_util{group=~"$group",host_name=~"$host",cpu="all",mode="avg1",type="idle"}))
 or max by(host_name,host,ident)(zabbix_huawei_server_systemCpuUsage{group=~"$group",host_name=~"$host"})

从仪表盘大量查询中可以看到转换后指标的形态规律：

• 指标名：zabbix_ 前缀 + key_ 去括号归一化，如 system.cpu.util[...] → zabbix_system_cpu_util、vm.memory.size[...] → zabbix_vm_memory_size、agent.ping → zabbix_agent_ping、vfs.dev.read.rate[...] → zabbix_vfs_dev_read_rate；
• 维度标签：host_name（Zabbix 主机名）、host、ident、group（业务组）等主机归属信息；
• Item 语义标签：description（Item 描述）、item_parameters（Item 参数）、Application（应用分组）等；
• 参数标签：key 中的参数被拆为标签，如 cpu="all"、mode="avg1"、type="idle"、if（网卡名）、fs（文件系统）等。

其中 name_as_tag=true 的作用，就是把 Item 的 name（人可读名称，如 "CPU idle time"）也作为一个标签输出，便于在排查、看图时快速理解指标含义；文档建议在调试时启用，正式运行可按需关闭以减少标签基数。

六、配套仪表盘：Zabbix 主机详情增强版

集成目录提供了开箱即用的仪表盘 dashboards/zabbix-host-detail-enhanced.json（约 2800 行），可直接导入夜莺仪表盘使用。

仪表盘设计要点（均可从 JSON 中确认）：

• 数据源：所有面板 datasourceCate 均为 prometheus，通过模板变量 datasource（类型 datasource，definition 为 prometheus）选择 Prometheus 数据源；
• 主机变量体系：定义了两个联动查询变量——group（业务组），定义式为 label_values(zabbix_agent_ping, group)；host（主机），定义式为 label_values(zabbix_agent_ping{group=~"$group"}, host_name)。这意味着只要指标带有 group、host_name 标签，即可实现「先选业务组、再选主机」的联动筛选；
• 覆盖维度：从面板分组看，涵盖 CPU / 内存 / 系统负载、磁盘与文件系统、网络、硬件（含华为 iBMC 服务器传感器）、异常与原始状态（Problems）等；
• 指标兼容性：多处查询使用正则同时匹配 OS 原生指标与华为 iBMC 指标，例如内存使用率 zabbix_vm_memory_util|zabbix_vm_memory_utilization|zabbix_huawei_server_systemMemUsage，说明集成对华为服务器带外指标也做了适配；
• 面板类型：使用 stat（状态值）、时序图等夜莺面板类型，并配合阈值配色（如 ONLINE 状态 >=1 绿色、否则红色）与 valueMappings 展示主机在线/离线状态。

导入后只需选择 Prometheus 数据源，即可对已接入的 Zabbix 主机进行分组、筛选与可视化查看；仪表盘的英文文案由 i18n/en_US.json 提供（如 "Zabbix Host Detail Dashboard - Enhanced"），便于国际化环境使用。

七、验证与排障建议

1. 端口连通性：配置完成后，确认 Categraf 已在 endpoint 指定端口（如 :9101）监听，且 Zabbix Connector 推送的目标端口与之一致，否则数据无法到达；
2. API 鉴权：若指标元数据无法拉取（例如出现大量无标签或无法识别的指标），优先检查 server 可达性、version 是否与实际 Zabbix 版本匹配、api_token（或 username/password）是否具备权限；
3. 指标名与标签验证：在 PromQL 中直接查询 zabbix_* 指标并观察 description、host_name、item_parameters 等标签是否齐全，可快速判断元数据增强是否生效；
4. 调试利器 name_as_tag：当无法判断某个指标对应哪个 Item 时，临时启用 name_as_tag=true，将 Item 名称作为标签输出，能显著提升指标可读性，定位问题后按需关闭；
5. data_dir 兜底：若 Zabbix 侧无法开放外推端口、只能导出数据文件，可改用 data_dir 方式读取本地导出目录，保证受限网络下仍能完成数据接入。

八、总结

Zabbix 集成是夜莺生态中连接传统监控资产与现代化指标体系的典型方案。其核心价值可以概括为三点：一是通过 HTTP 实时导出实现低延迟数据流转，二是通过 Zabbix API 元数据增强让 key_ 到指标名、单位与主机信息到标签的转换规则清晰可控，三是开箱即用的主机详情仪表盘降低了落地成本。结合 zabbix.toml 中庞大的 Item key 兼容清单与 zabbix-host-detail-enhanced.json 的查询示例，你可以在不改造 Zabbix 采集体系的前提下，让存量监控数据无缝汇入新的统一监控视图。