数据集成：Zabbix 数据实时导入到 Flashcat

本文介绍如何将 Zabbix 监控数据实时导入 Flashcat。Flashcat 是快猫星云以开源夜莺为内核打造的一体化可观测平台，预置故障发现定位最佳实践，支持指标、日志、链路追踪数据的统一采集、存储、告警和可视化分析。

通过 Categraf 的 Zabbix 插件，可以把 Zabbix 的监控数据转发到 Flashcat，实现监控数据统一存储和查询分析。

需要注意的是，本文所述 Zabbix 插件仅在企业版 Categraf v0.4.10 及以上版本支持，开源版尚不提供此功能。

核心要点摘要

• 本文目标是把 Zabbix 监控数据导入 Flashcat，用于统一查询、可视化和关联分析。
• Zabbix 7.2 可以通过 HTTP Connector 实时导出历史数据到 Categraf。
• Zabbix 7.0 以前版本可以使用文件方式导出历史数据，再由 Categraf 读取文件。
• Categraf 的 Zabbix 插件会通过 Zabbix API 获取 Item 元数据，并把历史数据转换成 Prometheus 格式时序数据。
• HTTP 方式要保持 Zabbix Connector 的 URL 端口与 Categraf endpoint 监听端口一致；文件方式要求 Categraf 与 Zabbix 部署在同一台机器上。

方案架构

整体链路可以理解为：

Zabbix Server
  -> HTTP Connector 或 history 文件导出
  -> Categraf Zabbix 插件
  -> 指标转换和标签补充
  -> Flashcat
  -> 查询、告警、仪表盘和关联分析

这条链路的核心不是重新采集所有监控对象，而是把 Zabbix 已经采集到的历史数据转储出来，再进入 Flashcat 的统一可观测体系。

快速部署 Zabbix

我们通过 Docker Compose 快速部署一个 Zabbix 环境。

$ git clone https://github.com/zabbix/zabbix-docker.git
$ cd zabbix-docker
$ docker compose up -d

我本机的 IP 是 192.168.10.222，浏览器访问 http://192.168.10.222 出现了熟悉的界面：

输入用户名 Admin、密码 zabbix 就可以登录。如果你想尝试二进制部署 Zabbix，可以参考这篇博客。

采集 Zabbix 数据前先理解几个概念

在配置数据采集前，先了解 Zabbix 中的几个关键概念。

Items（监控项）

Items 是 Zabbix 中最基本的监控单元，定义要收集的具体数据。每个 Item 包含：

• Name：人类可读的名称，如 CPU utilization。
• Key：标识数据采集方法的唯一键，如 system.cpu.util[all,user,avg1]。
• Type：数据类型，如数值型、字符串、日志等。
• Host：关联的主机。
• Applications：所属的应用分组。
• Tags：附加的标签信息。

Hosts（主机）

Hosts 代表被监控的设备或系统，可以是物理服务器、虚拟机或网络设备等。

Templates（模板）

Templates 是预定义的监控配置集合，可以包含多个 Items、Triggers、Graphs 等。

History（历史数据）

History 是 Zabbix 收集到的监控数据存储，包含时间戳、值、主机信息等。本文要导入 Flashcat 的，主要就是这类历史监控数据。

Zabbix 数据导出配置一：HTTP 方式

HTTP 方式适用于支持 Connector 导出的 Zabbix 版本。下面以 Zabbix 7.2 为例。

设置连接器最大限制

在 zabbix-docker 目录下找到 docker-compose_v3_alpine_mysql_latest.yaml 文件，在第 30 行：

image: "${ZABBIX_SERVER_MYSQL_IMAGE}:${ZABBIX_ALPINE_IMAGE_TAG}${ZABBIX_IMAGE_TAG_POSTFIX}"

之后添加如下两行。这个环境变量表示导出数据的连接器最大数量为 5 个，可以根据实际需要设置。

  environment:
   - ZBX_STARTCONNECTORS=5

接着执行如下命令，重建容器：

docker compose down
docker compose up -d

创建 API Token

Zabbix 7.2 的 Token 必须属于某个用户，且用户需要属于特定角色。配置步骤如下。

首先创建一个 monitor role，主要权限是 hosts 和 item。

再创建 monitor 用户。

创建 API Token。这里没有设置过期时间。

配置 Connector

进入 Administration -> General -> Connectors 配置界面，添加新的 Connector：

• 类型选择 Item values。
• URL 填写部署 Categraf 机器的地址：http://192.168.10.222:9101/v1/zabbix/history。
• 注意路径 /v1/zabbix/history 是固定的。

配置 Categraf

在 Flashcat 的数据采集页面上新建 Zabbix 插件配置。

[[instances]]
endpoint=":9101"

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

关键配置说明：

• endpoint：Categraf 监听端口，用于接收 Zabbix 推送的数据。
• instances.zabbix.server：Zabbix 服务器地址。
• instances.zabbix.version：Zabbix 版本。
• instances.zabbix.api_token：前面创建的 API Token。
• instances.zabbix.name_as_tag：是否将 Item 名称作为标签，调试时可启用。

本文选择 HTTP 方式实时导出，所以只需要配置 endpoint 部分。可以理解为 Categraf 的 Zabbix 插件会启动一个 9101 端口，用于接收 Zabbix 数据推送。这个端口要和 Zabbix Connector 中配置的端口保持一致。

Categraf 会通过 Zabbix API 获取 Item 详细信息，以便正确转换数据。推送的历史数据中，item 的 key_ 比 name 更适合直接作为指标名称，而 item 的单位、关联主机信息则用作标签，用来丰富指标含义。

Zabbix 数据导出配置二：文件方式

对于 Zabbix 7.0 以前的版本，只能通过文件方式导出数据。下面介绍具体配置方式。

配置 Zabbix 文件导出

同样在 docker-compose_v3_alpine_mysql_latest.yaml 文件中，第 30 行后添加：

  environment:
   - ZBX_EXPORTDIR=/etc/zabbix/data/
   - ZBX_EXPORTFILESIZE=100M
   - ZBX_EXPORTTYPE=history
  volumes:
   - /etc/timezone:/etc/timezone:ro
   - /home/flashcat/zabbix-docker/data:/etc/zabbix/data

这些配置表示：

• 导出数据到容器内的 /etc/zabbix/data 目录。
• 每个导出文件最大为 100MB。
• 导出数据类型为历史数据。
• 将容器内目录挂载到宿主机的 /home/flashcat/zabbix-docker/data。

完成配置后，重建容器：

docker compose down
docker compose up -d

配置 Categraf 读取文件

针对文件方式，Categraf 配置如下：

[[instances]]
data_dir="/home/flashcat/zabbix-docker/data"

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

重要提示：使用文件导出方式时，Categraf 必须与 Zabbix 部署在同一台机器上，data_dir 必须与 Docker 挂载目录保持一致。

HTTP 方式和文件方式怎么选

如果版本支持 HTTP Connector，优先使用 HTTP 方式，链路更直接。旧版本环境则使用文件方式。

工作原理

Categraf 的 Zabbix 插件主要完成四类工作。

1. 元数据缓存

通过 ItemCache 组件，定期从 Zabbix API 获取所有监控项信息。

2. 数据处理

• HTTP 方式：HTTP 处理器接收 NDJSON 格式的历史数据。
• 文件方式：监控指定目录中的 NDJSON 文件变化。

3. 数据转换

• 将 Zabbix 的 item key 转换为规范化指标名称。
• 将主机信息、参数、标签等转换为标签键值对。
• 将不同类型的值，如整数、浮点数、字符串等，做标准化处理。

4. 指标输出

生成符合 Prometheus 格式的时序数据点，发送到 Flashcat。

最终效果

利用 Zabbix 自身指标做一个简单的大盘来验证效果：

通过这种方式，我们实现了将 Zabbix 监控数据实时导入 Flashcat，方便统一数据串联分析。

常见问题

Categraf 的 endpoint 和 Zabbix Connector URL 有什么关系？

HTTP 方式下，Categraf 通过 endpoint=":9101" 监听端口，Zabbix Connector 的 URL 需要指向这个端口和固定路径 /v1/zabbix/history。

为什么 Categraf 还需要 Zabbix API Token？

因为 Categraf 不只接收历史数据，还需要通过 Zabbix API 获取 Item 元数据。没有元数据，就很难把 item key、单位、主机信息和标签正确转换成可用指标。

文件方式为什么要求 Categraf 和 Zabbix 在同一台机器？

文件方式依赖读取 Zabbix 导出的 history 文件。Categraf 需要直接访问 data_dir，所以通常要求与 Zabbix 部署在同一台机器，或者至少能访问同一个挂载目录。

总结

把 Zabbix 数据导入 Flashcat，适合已经有 Zabbix 存量监控、又希望统一查询和关联分析的团队。HTTP 方式适合支持 Connector 的新版本 Zabbix，文件方式适合 Zabbix 7.0 以前版本。

这套方案的核心是：Zabbix 继续负责已有监控采集，Categraf 负责接收或读取 Zabbix 历史数据并转换为 Prometheus 格式，Flashcat 负责统一存储、查询、告警和可视化分析。这样可以复用 Zabbix 存量资产，同时为后续统一可观测打基础。