4、Filebeat入门：Filebeat架构、安装配置、读取日志文件

好，咱们进入第四章。前面三章我们把日志采集的「为什么」和「是什么」讲清楚了，这一章开始动真格——上手 Filebeat。

Filebeat 是 Elastic 生态里最轻量的采集器。我最早接触它是在一个电商项目里，业务方要求采集 200 多台 Nginx 的访问日志，服务器配置又不高，2C4G 的机器跑 Logstash 直接撑不住。换成 Filebeat 之后，CPU 占用从 40% 降到 5%，那感觉，嗯，真香。

4.1 Filebeat 是什么？

Filebeat 是一个用 Go 写的轻量级日志采集器。它的核心任务就一个：读文件，发数据。

你想想看，如果每台机器都装一个 Logstash，内存先不说，光 JVM 的调优就能折腾死人。Filebeat 不需要 JVM，安装包才十几兆，跑起来内存占用通常不到 50MB。说白了，它就是为「边缘采集」这个场景量身定做的。

核心定位：Filebeat 只负责采集和转发，不负责解析和过滤。复杂的日志解析交给 Logstash 或 Elasticsearch 的 Ingest Pipeline 去做。

4.2 Filebeat 架构

咱们先看一张架构图，把 Filebeat 的内部模块理清楚。我个人习惯，学一个新工具先看它的数据流，比死记命令管用得多。

Filebeat 内部架构与数据流 Filebeat 内部架构与数据流 日志文件 /var/log/*.log Harvester 逐行读取 Input 发现/管理文件 Registry 偏移量记录 内部队列 内存/磁盘缓冲 Output Elasticsearch / Logstash 关键说明 • Harvester 负责读文件 • Input 负责发现文件 • Registry 记录读取位置 数据流方向 文件 → Harvester → 队列 → Output Registry 全程记录偏移量

这张图里几个关键模块，我挨个说一下：

  • Harvester（收割者）：每个日志文件对应一个 Harvester，它负责打开文件、逐行读取内容。文件被删除或重命名时，Harvester 会自动关闭。
  • Input（输入）：负责发现哪些文件需要被采集。它会根据配置文件里的路径规则，找到匹配的文件并启动对应的 Harvester。
  • Registry（注册表）：这是 Filebeat 的「记忆」模块。它记录每个文件当前读到了哪个位置（偏移量）。Filebeat 重启后，能从断点续读，不会重复也不会遗漏。
  • 内部队列：Harvester 读到的数据先放进队列，Output 再从队列里取。队列可以配成内存模式或磁盘模式，防止突发流量打爆 Output。
  • Output（输出）：把数据发到下游，常见的有 Elasticsearch、Logstash、Kafka、Redis 等。

我的经验：Registry 文件默认存在 data/registry/filebeat/log.json。千万别手欠删它，否则 Filebeat 会重新读一遍所有历史日志，造成数据重复。我曾经在测试环境干过这事，结果 ES 集群被重复数据冲了一脸。

4.3 安装 Filebeat

安装方式很多，我推荐用包管理器或者直接下载二进制包。咱们以 Linux 为例，走一遍流程。

4.3.1 下载与安装

# 下载 Filebeat 8.x（以 8.12.0 为例）
wget https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.12.0-linux-x86_64.tar.gz

# 解压
tar -xzf filebeat-8.12.0-linux-x86_64.tar.gz

# 进入目录
cd filebeat-8.12.0-linux-x86_64/

解压完就能用，不需要编译，不需要装依赖。你想想看，一个 Go 编译出来的单二进制文件，配上配置文件就能跑，多省心。

4.3.2 验证安装

# 查看版本
./filebeat version

# 输出示例
filebeat version 8.12.0 (amd64), libbeat 8.12.0

看到版本号就说明装好了。嗯，就这么简单。

4.4 配置 Filebeat 读取日志文件

配置是 Filebeat 的核心。咱们先从一个最简单的场景开始：读取 /var/log/syslog 并输出到控制台。

4.4.1 最小配置示例

创建一个配置文件 filebeat.yml：

filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/syslog

output.console:
  enabled: true
  pretty: true

这个配置干了三件事：

  • 定义了一个 log 类型的 input，读取 /var/log/syslog
  • 把输出设为控制台（console）
  • 开启 pretty 模式，让 JSON 输出更易读

启动看看效果：

./filebeat -e -c filebeat.yml

-e 表示日志输出到 stderr（默认是 syslog），-c 指定配置文件。你会看到一行行 JSON 格式的日志刷刷地往外冒。

注意：Filebeat 默认不会读取已经采集过的文件。如果你想强制重新读取，需要删除 Registry 文件或者用 --strict.perms=false 配合调试模式。生产环境千万别乱删 Registry。

4.4.2 多文件路径配置

实际项目中，一个 input 往往要读多个文件。你可以用通配符：

filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/nginx/access.log*
    - /var/log/nginx/error.log*
  fields:
    service: nginx
    env: production

这里我加了一个 fields 字段。它会给每条日志打上标签，方便下游区分数据来源。我个人习惯在每个 input 里都加 service 和 env 字段，后期排查问题能省不少时间。

4.4.3 多行日志处理

Java 异常栈、Python Traceback 这类多行日志，Filebeat 默认一行一条事件，会把堆栈拆得七零八落。怎么办？用 multiline 配置：

filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/app/error.log
  multiline:
    type: pattern
    pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}'
    negate: true
    match: after

这个配置的意思是：如果一行不匹配日期格式（negate: true），就把这行合并到上一行的后面（match: after）。说白了，只要不是新日志的开头，都算上一行的续行。

避坑指南：我曾经在一个 Java 微服务项目里，因为 multiline 的正则写得太宽泛，把两条不同的异常栈合并成了一条，导致排查问题时漏掉了关键信息。正则一定要精确匹配日志的开头特征，宁严勿宽。

4.5 常用配置参数速查

下面这个表格是我平时用得最多的参数，你直接拿来参考：

参数 默认值 说明
paths 无 日志文件路径，支持通配符 * 和 ?
encoding plain 文件编码，中文日志常用 utf-8 或 gbk
exclude_lines 无 排除匹配正则的行，比如排除 ^DEBUG
include_lines 无 只采集匹配正则的行，优先级高于 exclude
harvester_buffer_size 16384 每次读取的缓冲区大小（字节）
max_bytes 10485760 单条日志最大长度（10MB），超长会被截断
scan_frequency 10s 扫描文件系统发现新文件的间隔
close_inactive 5m 文件超过 5 分钟没有新内容，关闭对应的 Harvester
clean_inactive 0 从 Registry 中移除长时间不活跃的文件记录

4.6 实战：采集 Nginx 访问日志

咱们来一个完整的例子。假设你要采集 Nginx 的访问日志，输出到 Elasticsearch。

filebeat.inputs:
- type: log
  enabled: true
  paths:
    - /var/log/nginx/access.log
  fields:
    service: nginx
    type: access
  fields_under_root: true
  # 排除健康检查的请求
  exclude_lines: ['^.*"GET /health.*"']

output.elasticsearch:
  hosts: ["http://192.168.1.100:9200"]
  index: "nginx-access-%{+yyyy.MM.dd}"
  username: "elastic"
  password: "changeme"

setup.kibana:
  host: "http://192.168.1.100:5601"

这个配置里我加了几个实用技巧：

  • fields_under_root: true 把自定义字段放到 JSON 顶层，方便 ES 做聚合
  • exclude_lines 过滤掉健康检查的请求，减少无用数据
  • index 按日期滚动索引，方便管理

启动之后，Filebeat 会自动创建索引模板，你打开 Kibana 就能看到数据了。

重要提醒：第一次连接 Elasticsearch 时，Filebeat 会尝试加载仪表板和索引模板。如果 ES 需要安全认证，记得配好 username 和 password，否则会报 401 Unauthorized。

4.7 本章小结

这一章咱们把 Filebeat 的核心概念过了一遍：

  • 架构上记住 Harvester、Input、Registry 三个模块的协作关系
  • 安装就是解压即用，没什么门槛
  • 配置重点掌握 paths、multiline、fields 三个部分
  • 实战中注意过滤无用日志和配置 ES 认证
← 上一章 📖 返回目录 下一章 →