Categraf 部署实战——国产开源采集器的内网落地 • 七万号·数据平台实战手记

明朗北街七万号·数研工坊｜扎根雄安新区中关村科技园，专注受限环境下软件搭建与数据平台落地

为什么必须重视监控与可观测#

在讲具体怎么部署之前，我想先花点篇幅讲清楚一件事：为什么数据平台一定要有监控？

你搭好了数据库、Nginx、数据引擎，一切正常。但问题是——你永远不知道它什么时候会不正常。

一次内存泄漏、一次磁盘写满、一次网络抖动，都可能让平台在凌晨三点悄无声息地挂掉。没有监控，你发现问题的顺序永远是：

用户报障 → 你被叫醒 → 远程登录 → 翻日志 → 定位 → 修复

plaintext

这中间用户已经忍受了数小时的服务不可用。

有监控之后，顺序变成：

监控告警 → 你被通知 → 远程登录 → 修复

plaintext

问题在用户感知之前就被发现了。

监控的价值，一句话：把「事后救火」变成「事前预警」。

而「可观测性」是监控的升级版。监控回答「系统现在还活着吗」，可观测性回答「系统为什么变成这样」。一个完整的可观测体系包含三根支柱：

支柱	回答的问题	典型工具
Metrics（指标）	系统健康吗？	Prometheus、VictoriaMetrics
Logs（日志）	发生了什么？	ELK、Loki
Traces（链路）	为什么变慢？	Jaeger、SkyWalking

本系列三篇，先搭最核心的 Metrics 链路：采集（Categraf）→ 存储（VictoriaMetrics）→ 展示（Grafana）。

适用场景#

如果你属于以下任一种情况，这篇对你有用：

平台搭起来了，但「黑盒运行」——不知道机器负载、不知道磁盘剩多少、不知道服务还活着没

想用 Prometheus 体系但资源紧张（Prometheus 本体占内存不小）

需要采集主机指标（CPU/内存/磁盘/网络）和自定义应用指标

想给夜莺（Nightingale）或其他监控平台做数据采集

应用范围： 监控体系的数据采集层。在架构里，Categraf 是「眼睛」——它负责到处看，把看到的数据送给 VictoriaMetrics（第 10 篇）存储，再由 Grafana（第 11 篇）展示。

架构定位#

   ┌────────────┐    ┌────────────┐    ┌────────────┐
   │  主机指标    │    │  MySQL指标  │    │ 应用自定义  │
   └──────┬─────┘    └──────┬─────┘    └──────┬─────┘
          └────────┬────────┘                │
                   ▼                         │
           ┌──────────────┐                  │
           │  Categraf    │◄─────────────────┘  本篇主角：采集
           │  (采集器)     │
           └──────┬───────┘
                  ▼
           ┌──────────────┐
           │VictoriaMetrics│  第 10 篇：存储
           └──────┬───────┘
                  ▼
           ┌──────────────┐
           │   Grafana    │  第 11 篇：展示
           └──────────────┘

plaintext

一、问题#

平台上的每台服务器都是一个「黑盒」：

磁盘还剩多少？不知道
CPU 是不是被打满了？不知道
MySQL 的慢查询多不多？不知道
某个服务是不是悄悄挂了？不知道

你需要的是一套「眼睛」——到处盯着，把数据报回来。这就是采集器的工作。

二、约束#

无公网，需离线部署
资源受限，采集器本身要轻量（不能比被监控的服务还占资源）
需要同时采集主机、中间件、自定义应用指标
后续可能对接多种监控后端（Prometheus、VictoriaMetrics、Nightingale）

三、为什么选 Categraf#

采集器	特点	资源占用
node_exporter	只能采主机指标，采集中间件要装一堆 exporter	低但碎片化
Telegraf	插件丰富，但 Go 二进制 + 配置文件复杂	中
Categraf	国产开源，一个二进制搞定主机+中间件+自定义	低（单二进制）

Categraf 的核心优势：

单二进制文件，一个程序解决所有采集需求（替代 N 个 exporter）
原生支持 Prometheus 协议，数据直接推送到 VictoriaMetrics/Prometheus
支持夜莺（Nightingale）生态，国产监控平台友好
轻量，内存占用约 20-50MB

四、部署#

4.1 获取安装包#

# 外网下载（GitHub Releases 或国内镜像）
wget https://github.com/flashcatcloud/categraf/releases/download/v0.3.76/categraf-v0.3.76-linux-amd64.tar.gz

# ARM 架构
wget https://github.com/flashcatcloud/categraf/releases/download/v0.3.76/categraf-v0.3.76-linux-arm64.tar.gz

plaintext

4.2 解压部署#

tar xzf categraf-v0.3.76-linux-amd64.tar.gz
mv categraf-v0.3.76-linux-amd64 /usr/local/categraf
cd /usr/local/categraf

# 目录结构
# ├── categraf          主程序
# ├── conf/             配置目录
# │   ├── config.toml   主配置（上报地址等）
# │   └── input.*/      各采集插件配置
# └── ...

plaintext

4.3 配置主文件#

编辑 conf/config.toml，配置数据上报地址（指向 VictoriaMetrics）：

[global]
  hostname = "node-01"
  interval = 15s          # 采集间隔

[writers]
  urls = ["http://192.168.1.100:8428/prometheus/api/v1/write"]

plaintext

8428 是 VictoriaMetrics 的写入端口，/prometheus/api/v1/write 是兼容 Prometheus 的写入路径。

4.4 启用采集插件#

Categraf 的插件按目录管理，默认只启用主机采集（input.system 等）。常用的：

# 主机基础指标（默认启用）
conf/input.system/
conf/input.cpu/
conf/input.mem/
conf/input.disk/
conf/input.net/

# 中间件指标（按需启用）
conf/input.mysql/
conf/input.redis/
conf/input.nginx/
conf/input.kafka/

# 自定义应用指标
conf/input.prometheus/

plaintext

启用某个插件：编辑对应目录下的 conf.toml，去掉注释或填入配置。

例如 MySQL 采集：

# conf/input.mysql/conf.toml
[[instances]]
  address = "127.0.0.1:3306"
  username = "monitor"
  password = "MonitorPass!2026"
  labels = { instance = "mysql-master" }

plaintext

4.5 启动#

# 前台测试（确认配置无错）
./categraf --test

# 后台运行
nohup ./categraf > /var/log/categraf.log 2>&1 &

# 或用 systemd 管理
cat > /etc/systemd/system/categraf.service << 'EOF'
[Unit]
Description=Categraf Agent
After=network.target

[Service]
ExecStart=/usr/local/categraf/categraf
Restart=always

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now categraf

plaintext

4.6 验证采集是否成功#

数据有没有送到 VictoriaMetrics，直接在 VM 上查：

# 在 VictoriaMetrics 机器上（第 10 篇部署后）
curl 'http://127.0.0.1:8428/api/v1/query?query=cpu_usage_active'

plaintext

有数据返回，说明采集链路通了。

五、自定义应用指标采集#

这是 Categraf 相对 node_exporter 最大的优势——应用自己暴露指标，Categraf 直接抓。

5.1 应用侧暴露指标#

Java 应用引入 Micrometer + Prometheus registry，或者任何 Prometheus SDK，在 /metrics 端点暴露指标。Spring Boot：

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: prometheus

yaml

5.2 Categraf 抓取#

# conf/input.prometheus/conf.toml
[[instances]]
  urls = ["http://127.0.0.1:8080/actuator/prometheus"]
  labels = { app = "user-service" }

plaintext

重启 Categraf 后，应用的指标就进入了监控体系。

六、常见坑#

坑	症状	解决
数据没上报	查询无数据	先 `./categraf --test` 本地测试
写入失败	日志有 4xx	确认 writers 的 URL 路径写对
时间戳错乱	图上数据忽前忽后	确认服务器时钟同步（内网要配 NTP）
MySQL 采集失败	无 mysql 指标	确认 monitor 账号权限：`GRANT PROCESS, REPLICATION CLIENT ON . TO 'monitor'`
磁盘采集重复	挂载点重复	input.disk 里配置 mount_point 过滤

七、总结#

环节	关键动作	一句话
选型	Categraf 单二进制	一个采集器替代一堆 exporter
部署	解压即用	注意架构 x64/aarch64
配置	writers 指到 VM	上报地址是关键
插件	按需启用目录	MySQL/Redis/自定义各就各位
验证	`--test` + VM 查数据	链路通了才算部署完

数据采回来只是第一步——得有个地方存。下一篇部署 VictoriaMetrics，把数据接住。

本文首发于掘金 · 作者：七万号扎根雄安新区中关村科技园，专注受限环境下软件搭建与数据平台落地