Categraf v0.4.5 日志采集终极配置与全流程指南（vlagent(代理)->VictoriaLogs（持久化））
日志流向是Categraf （采集）->vlagent(代理)->VictoriaLogs（持久化）
一、最终可运行配置（直接复制）
1. 主配置 conf/config.toml
toml
[global]
hostname = "shuai" # 替换为你的主机名
interval = 15
[agent]
debug = false
# 【v0.4.5 专属必填】必须在主配置中显式开启日志模块
# 否则即使 logs.toml 配置正确，日志模块也会静默不加载
[logs]
enable = true
2. 日志配置 conf/logs.toml（核心）
toml
[logs]
enable = true
scan_period = 5 # 扫描日志目录的周期，单位秒，默认10秒
# 【v0.4.5 最大的坑】绝对不能加 http:// 前缀！
# 加了会报 "too many colons in address" 错误，日志模块直接不加载
send_to = "192.168.88.201:9429"
send_type = "http"
use_compress = false
# 批量发送配置
batch_wait = 5
batch_max_size = 100
# 偏移文件存储路径（建议放在持久化目录）
run_path = "/var/lib/categraf/logs"
# Kafka 相关配置（不需要可注释）
sasl_enable = false
sasl_user = "admin"
sasl_password = "admin"
sasl_mechanism = "PLAIN"
sasl_version = 1
sasl_handshake = true
# 日志采集项示例：采集 /var/log/app/ 下所有 .log 文件
[[logs.items]]
type = "file"
path = "/var/log/app/*.log"
source = "syslog"
service = "my_syslog"
# 可添加多个采集项
# [[logs.items]]
# type = "file"
# path = "/var/log/syslog"
# source = "system"
# service = "system"
二、完整部署与启动流程
在目标机器部署，只需要 categraf 二进制、以及 conf 目录，conf 下有一个主配置文件：
- config.toml，定义机器名、全局采集频率、全局附加标签、remote write backend地址等；
- 另外就是各种采集插件的配置目录，以input.打头，categraf 会遍历这些文件下的插件配置执行采集任务，如果某个采集器 xx 不想启用，把 input.xx 改个其他前缀(或者删除这个目录)，比如 bak.input.xx，categraf 就会忽略这个采集器。
1. 安装 Categraf v0.4.5
bash
运行
# 下载二进制包wget https://github.com/flashcatcloud/categraf/releases/download/v0.4.5/categraf-v0.4.5-linux-amd64.tar.gz
# 解压到指定目录
tar -zxf categraf-v0.4.5-linux-amd64.tar.gz -C /opt/categraf/
# 创建偏移文件存储目录
mkdir -p /var/lib/categraf/logs
chown -R root:root /var/lib/categraf/logs
2. 启停
# 以service方式安装, 相当于添加service文件+systemctl daemon-reload sudo ./categraf --install # 以service方式卸载, 相当于systemctl stop categraf + 删除service文件 sudo ./categraf --remove # 以service方式启动categraf ，相当于systemctl start categraf # 如果之前有nohup启动的categraf进程，需要先人工停掉原来的categraf进程 sudo ./categraf --start # 以service方式停止categraf，相当于systemctl stop categraf sudo ./categraf --stop # 以service方式查看categraf，相当于systemctl status categraf sudo ./categraf --status
✅ 正常状态：
plaintext
Active: active (running)
三、核心踩坑总结（99% 的人都会遇到）
1. 启动参数错误导致服务崩溃
- 现象：服务启动失败，报
status=2或flag provided but not defined: -configs-dir - 原因：v0.4.5 版本只支持
-configs参数，不支持新版本的--configs-dir - 解决方案：使用
-configs参数指定配置目录
2. 主配置未显式开启日志模块
- 现象：服务正常运行，但没有任何日志模块相关日志，也不采集日志
- 原因：v0.4.5 版本的反人类设计，必须在主配置
config.toml中显式添加[logs] enable = true，否则即使logs.toml配置正确，日志模块也会被完全忽略 - 解决方案：在主配置末尾添加日志模块全局开关
3. send_to 加了 http:// 前缀
- 现象：日志模块解析失败，报
too many colons in address错误，然后静默不加载 - 原因：v0.4.0-v0.4.6 版本的史诗级 bug，
send_to参数绝对不能加http://前缀 - 解决方案：去掉
http://前缀，直接写IP:端口
4. 配置文件语法错误
- 现象：服务启动失败，报
parse config error或直接崩溃 - 原因：TOML 语法严格，字符串必须用双引号，不能有中文标点，不能有多余的逗号
- 解决方案：使用本文提供的配置模板，避免手动输入错误
5. systemd 启动次数限制
- 现象：服务无法启动，报
start-limit-hit - 原因：短时间内反复崩溃重启超过 5 次，触发了 systemd 的保护机制
- 解决方案：执行
systemctl reset-failed categraf重置启动限制
6. 偏移文件损坏导致不读新日志
- 现象：日志模块正常启动，但不采集新日志
- 原因：偏移文件记录了上次读到的位置，如果文件损坏或被修改，会导致永远不读新内容
- 解决方案：停止服务后删除偏移文件目录：
rm -rf /var/lib/categraf/logs/*
四、全链路验证方法
1. 验证日志模块是否加载
bash
journalctl -u categraf --since "1 minute ago" | grep -E "LogsAgent|watching file"
✅ 正常输出：
plaintext
I! [*agent.LogsAgent] started
I! [log agent] watching file: /var/log/app/*.log
2. 验证本地采集功能
bash
运行
# 写入测试日志
echo "CATEGRAF_TEST: 测试日志采集" >> /var/log/app/test.log
# 查看 vlagent 日志，确认是否收到
journalctl -u vlagent -f
✅ 正常会看到 vlagent 收到日志的日志。
3. 验证 VictoriaLogs 写入
bash
运行
# 查询 VictoriaLogs
curl "http://192.168.88.205:9428/select/logsql/query?query=CATEGRAF_TEST"
✅ 正常会返回测试日志的 JSON 数据。
Vlagent安装
vlagent是一个用于从各种来源收集日志并将其存储在多个 VictoriaLogs 实例中的代理。
vlagent位于日志来源和维多利亚日志之间： 它通过HTTP接受日志，如果远程存储不可用，将日志缓冲在磁盘上，并转发到一个或多个VictoriaLogs实例。 它还能直接从Kubernetes Pod日志文件收集日志，无需额外日志运输工具。
去github:Release v1.50.0 · VictoriaMetrics/VictoriaLogs
上传到代理服务器解压然后执行
/path/to/vlagent-prod -remoteWrite.url=http://<victoria-logs-host>:9428/insert/native
victoria-logs-host是你VictoriaLogs 服务器的地址
VictoriaLogs安装
-
下载
首先，从 VictoriaLogs 的官方 GitHub Releases 页面，下载对应操作系统和架构的压缩包。-
下载文件：
victoria-ls-<os>-<arch>-<version>.tar.gz
-
解压与运行
解压后，直接运行二进制文件即可启动服务：# 以 Linux amd64 为例 tar xzf victoria-logs-linux-amd64-<version>.tar.gz ./victoria-logs-prod -storageDataPath=/path/to/data/dir此命令会指定数据存储目录。服务启动后，默认会在
9428端口上监听，准备接收日志和响应查询。 -
验证
访问http://localhost:9428或http://<服务器IP>:9428，即可看到 VictoriaLogs 的 Web UI，部署成功。它也内置了一个用于查询日志的命令行工具，可以使用vlogscli进行交互式查询。
🔧 常用配置参数
启动时可以通过命令行参数调整运行行为，常用参数如下：
| 参数 | 说明 | 示例 | 参考 |
|---|---|---|---|
-storageDataPath |
数据存储目录路径，必须指定。 | ./victoria-logs-prod -storageDataPath=/var/lib/victorialogs |
|
-retentionPeriod |
数据保留周期，默认7天。支持 d (天), w (周), y (年)。 |
-retentionPeriod=30d (保留30天) |
|
-httpListenAddr |
监听地址和端口，默认 :9428。 |
-httpListenAddr=0.0.0.0:8080 |
- |
-memory.allowedBytes |
限制VictoriaLogs可以使用的内存上限。 | -memory.allowedBytes=1024MB |
- |
-retention.maxDiskSpaceUsageBytes |
限制日志存储占用的最大磁盘空间。 | -retention.maxDiskSpaceUsageBytes=100GiB |
📋 生产环境建议
-
搭配采集器使用：VictoriaLogs 本身只是一个存储和查询引擎。在生产环境中，需要配合日志采集器（如 Promtail、Fluentd、Vector 等）来转发日志。由于它兼容 Loki 的 API，可将采集器的目标地址直接配置为
http://<victorialogs-ip>:9428/loki/api/v1/push即可发送日志。 -
配置 systemd 服务：为了在 Linux 服务器上实现开机自启和进程守护，可以为其配置 systemd 服务。
-
接入监控：VictoriaLogs 暴露了 Prometheus 格式的健康指标，地址为
http://localhost:9428/metrics。可以通过 Grafana 等工具进行可视化监控。
⚠️ 特别注意事项
-
数据目录权限：确保运行 VictoriaLogs 的用户对通过
-storageDataPath指定的目录具有读写权限，否则服务将无法正常启动或写入日志。 -
文件句柄与文件系统：对于生产环境的大规模日志存储，建议增加系统的最大文件打开数，并推荐使用 ext4 作为数据存储的文件系统。
五、生产环境建议
-
强烈建议升级到 v0.4.40+ 版本
- 修复了所有已知的日志采集 bug
- 支持
http://前缀，配置更直观 - 性能和稳定性大幅提升
-
配置优化
- 增加
batch_max_size到 1000，减少发送次数 - 开启
use_compress = true，减少网络传输量 - 将
run_path放在独立的磁盘分区，避免磁盘占满
- 增加
-
监控告警
- 监控 Categraf 服务状态
- 监控 VictoriaLogs 写入延迟
- 监控日志采集量，避免漏采
六、总结
Categraf 作为轻量的可观测性采集器，功能强大且部署简单，但老版本确实存在很多坑。尤其是 v0.4.5 版本的日志模块，设计上有很多反人类的地方，导致排查起来非常困难。
如果你正在使用 v0.4.5 版本，建议直接按照本文的配置来，能帮你节省大量的时间。如果条件允许，最好直接升级到最新稳定版，体验会好很多。
希望这篇文章能帮到你，祝大家的日志系统都能稳定运行！
浙公网安备 33010602011771号