Filebeat —— 轻量级日志采集与托运 Agent

分类：04 日志监控与分析 适用：每台 Linux/Windows 主机、容器节点、K8s DaemonSet；单主机数百 MB~数 GB/天日志 一句话：Go 编写的轻量托运器，负责"读文件、记住位移、至少一次投递"，把日志送给 ES/Logstash/Kafka 官方：https://www.elastic.co/beats/filebeat 授权：Elastic License 2.0（8.x 起；基础采集、modules、ingest pipeline、监控均免费）

1. 它解决什么问题

业务主机散落着 Nginx、应用、系统日志，需统一汇聚。每台装 Logstash 太重（JVM），脚本 tail 不可靠。Filebeat 提供：

• 轻量：Go 单二进制、无 JVM、常驻内存几十 MB，适合每台主机常驻。
• 可靠投递：registry 记录每个文件 offset，重启/中断后续传，至少一次（at-least-once）。
• 背压感知：下游慢时自动降速、暂停读取；可配内存/磁盘内部队列。
• 开箱解析 + 云原生：modules（nginx/mysql/system…）自带 filestream + ingest pipeline + dashboard；K8s autodiscover 按 Pod 动态生成输入并附加元数据。

它只做采集与轻加工（多行合并、加字段、加元数据），不做重解析/富化（交 Logstash 或 ingest pipeline），也不存储（交 ES/Loki）。

2. 核心概念与架构

术语表

两套链路中的位置与完整数据流（ASCII）

【ELK / EFK 链路 —— Filebeat 是"采集层"，位于每台主机】
  应用写日志文件 / 容器 stdout(json-file/containerd 落盘)
        │ ① 采集：★ Filebeat ★ 读文件、多行合并、记 registry offset
        ▼
  Filebeat(主机 Agent / K8s DaemonSet) ──► [可选 Kafka/Redis 缓冲]
        │ ② 输出
        ├──────────────────────────► Logstash(5044) ─► Elasticsearch ─► Kibana
        └──────────────────────────► Elasticsearch(9200) 直写（用 modules/ingest pipeline）
【PLG 链路 —— 不含 Filebeat】  说明：Fluentd/Fluent Bit 替代 Filebeat 时即 EFK；Filebeat 属 Beats 家族，常统称 ELK/Elastic Stack。
  文件 / stdout / journal ─► ★ Alloy(推荐) / Promtail(已 EOL) ★ ─► Loki(标签+压缩块) ─► Grafana(LogQL)
  对照：采集位同样在每台主机；PLG 采集器只加少量标签，不做全文索引；Filebeat 不在 PLG 链路。

日志从文件到可检索的完整路径（ELK）：

① 文件产生 → ② prospector 扫描发现 → ③ harvester 逐行读、多行合并、加 host/fields
→ ④ 经 processors 轻加工 → ⑤ output 批量送 ES(或 Logstash→ES)，registry 记 offset + ACK
→ ⑥ ES ingest pipeline(modules) 解析成结构化字段 → ⑦ refresh(1s) 后可被 Query DSL 检索
→ ⑧ Kibana Discover / Dashboard / Alerting

PLG 等价路径：文件 → Alloy 解析+加标签 → Loki 按标签分块 → Grafana 用 LogQL 查询。差异：ELK 写入前重解析并全字段索引；PLG 只加少量标签、检索时行过滤。

3. 安装与部署

版本差异：8.x 起 ES 默认开启安全与 TLS，直连 ES 时 output.elasticsearch 必须配 username/password 与 CA，否则 401/SSL 失败；7.x 无此要求。log input 已弃用，新配置一律用 filestream。具体版本号以官方最新稳定版为准。

3.1 环境准备

3.2 多种安装方式

A. 官方 APT/YUM 仓库（生产首选）

# Debian/Ubuntu（与 ES 共用 GPG key 与 8.x 仓库）
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elastic-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/elastic-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list
sudo apt update && sudo apt install -y filebeat
# RHEL/Rocky：复用 ES 的 elasticsearch.repo，sudo dnf install -y filebeat

B. Docker / docker compose（主机或容器日志）

docker run -d --name filebeat --user root \
  -v "$PWD/filebeat.yml:/usr/share/filebeat/filebeat.yml:ro" \
  -v "/var/log:/var/log:ro" -v "/var/lib/docker/containers:/var/lib/docker/containers:ro" \
  docker.elastic.co/beats/filebeat:<版本> filebeat -e --strict.perms=false   # tag 以官方最新稳定版为准；生产务必挂 registry 卷

C. 二进制 tar.gz + systemd

tar -xzf filebeat-<版本>-linux-x86_64.tar.gz -C /opt
sudo /opt/filebeat-*/filebeat -e -c /opt/filebeat-*/filebeat.yml    # 前台调试；生产写 systemd unit（User=root、Restart=on-failure）

D. K8s（Helm / DaemonSet）：官方 deploy/kubernetes/filebeat-kubernetes.yaml 以 DaemonSet 部署（每节点一实例，挂 /var/log/containers hostPath），从官方仓库 deploy/kubernetes 目录获取；也可用 elastic/helm-charts，ECK 场景用 Beat CRD。具体清单/版本以官方文档为准。

3.3 首次启动与验证

sudo filebeat test config -e                       # 校验 filebeat.yml 语法（上线前必做）
sudo filebeat test output -e                       # 验证到 ES/Logstash 的连通与认证
sudo filebeat setup -e                             # 装载索引模板、ingest pipeline、Kibana dashboard
sudo systemctl enable --now filebeat && sudo systemctl status filebeat --no-pager
echo '127.0.0.1 - - [05/Nov/2026:10:00:00 +0800] "GET /api HTTP/1.1" 200 12' >> /var/log/nginx/access.log
curl -s -u elastic:<密码> --cacert <http_ca.crt> "https://<es>:9200/filebeat-*/_search?pretty"
curl -s http://localhost:5066/stats?pretty         # 需先开 http.enabled: true / http.port: 5066
tail -f /var/log/filebeat/filebeat

4. 配置文件详解（filebeat.yml）

路径：主配置 /etc/filebeat/filebeat.yml；模块 /etc/filebeat/modules.d/*.yml；registry /var/lib/filebeat/registry；日志 /var/log/filebeat/。

完整可运行最小示例（直连 ES + nginx 模块 + 容器日志就绪）：

# /etc/filebeat/filebeat.yml
filebeat.inputs:
  - type: filestream
    id: nginx-access                     # 必填、唯一
    enabled: true
    paths: [ /var/log/nginx/access.log ]
    fields: { app: nginx, env: prod }
    fields_under_root: true
    parsers: [ { multiline: { type: pattern, pattern: '^[[:space:]]', negate: false, match: after } } ]   # 合并堆栈续行
  - type: filestream                     # K8s/容器日志单输入模式，DaemonSet 挂 /var/log/containers
    id: container-logs
    enabled: false
    prospector.scanner.symlinks: true    # /var/log/containers 是软链，必开
    parsers: [ { container: ~ } ]
    paths: [ /var/log/containers/*.log ]
processors:
  - add_host_metadata: ~
  - add_cloud_metadata: ~
  - drop_event.when.regexp.message: '^healthcheck'       # 丢弃健康检查噪声
  - rate_limit: { limit: "1000/s" }                      # 采集端限速
filebeat.config.modules:
  path: ${path.config}/modules.d/*.yml
  reload.enabled: true
  reload.period: 10s
setup.template.name: "filebeat"
setup.template.pattern: "filebeat-*"
setup.kibana.host: "https://<kibana>:5601"
output.elasticsearch:
  hosts: ["https://<es_host>:9200"]
  username: "<es_user>"                # 8.x 安全集群必填
  password: "<es_password>"
  index: "filebeat-%{[agent.version]}-%{+yyyy.MM.dd}"
  # 8.x 还需 CA/TLS 相关项，参数名随 output 插件版本变化，见官方文档
# 送 Logstash 时改用：output.logstash: { hosts: ["<logstash>:5044"], loadbalance: true }
logging.level: info
logging.to_files: true

5. 核心使用方法（CLI / filestream / modules / processors / autodiscover）

A. CLI 与校验

filebeat version ; filebeat test config -e ; filebeat test output -e
filebeat setup -e ; filebeat setup --index-management -e ; filebeat setup --pipelines -e ; filebeat setup --dashboards -e
filebeat export config ; filebeat export template  # 导出最终生效配置/模板
filebeat -e -c /etc/filebeat/filebeat.yml ; filebeat -e -d "harvester,publish"   # 前台/调试
filebeat modules list ; filebeat modules enable nginx system ; filebeat modules disable nginx
filebeat keystore create ; filebeat keystore add ES_PWD ; filebeat keystore list ; systemctl start|stop|restart|status filebeat

B. inputs / filestream（8.x 推荐）

filebeat.inputs:
  - type: filestream
    id: app-json                                   # 所有 filestream 必须唯一 id
    paths: [ /var/log/app/*.json ]
    prospector.scanner.check_interval: 10s
    ignore_older: 72h                              # 忽略 3 天未改动文件
    close.on_state_change.inactive: 5m
    parsers: [ { container: ~ } ]                  # 解析 Docker/CRI 日志格式
    fields: { service: checkout, env: prod }
  - type: filestream
    id: app-stack                                  # 多行合并示例
    paths: [ /var/log/app/stack.log ]
    parsers: [ { multiline: { type: pattern, pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}', negate: true, match: after } } ]

filebeat -e -d harvester 看 Harvester started for file 判断是否采到；registry 位于 path.data/registry，⚠️ 删除 registry 会导致全量重采（日志重复）。

C. modules（开箱即用解析）

filebeat modules list                              # nginx/mysql/system/kafka/aws…
filebeat modules enable nginx system ; filebeat modules disable nginx
filebeat setup --pipelines --index-management -e   # 装载模块所需 ingest pipeline 与模板

# /etc/filebeat/modules.d/nginx.yml
- module: nginx
  access:
    enabled: true
    var.paths: ["/var/log/nginx/access.log*"]
  error:
    enabled: true
    var.paths: ["/var/log/nginx/error.log*"]
  ingress_controller:
    enabled: false

模块 = filestream 配置 + ES ingest pipeline（把 message 解析出 http.response.status_code、source.ip、user_agent.*）+ Kibana dashboard。⚠️ output 为 Logstash 时 ingest pipeline 不自动生效，需改用 Logstash Grok 或让 Logstash 指定 pipeline 参数。

D. processors（本地轻加工）

processors:
  - add_host_metadata: { netinfo.enabled: true }
  - add_cloud_metadata: ~
  - add_docker_metadata: { host: "unix:///var/run/docker.sock" }
  - add_kubernetes_metadata: { host: "${NODE_NAME}" }      # K8s 附加 pod/container/namespace
  - decode_json_fields: { fields: ["message"], target: "json", overwrite_keys: true }
  - add_fields: { target: "", fields: { cluster: "prod-a" } }
  - drop_fields: { fields: ["agent.ephemeral_id", "ecs.version"] }
  - drop_event.when.regexp.message: '^healthcheck' ; - rate_limit: { limit: "1000/s" } ; - fingerprint: { fields: ["message"], target_field: "@metadata.fp" }

E. K8s autodiscover + hints（DaemonSet 动态采集）

# 单输入模式（推荐 containerd/CRI-O）：一个 filestream 采所有容器日志
filebeat.inputs:
  - type: filestream
    id: kubernetes-container-logs
    prospector.scanner.symlinks: true              # /var/log/containers 是软链，必开
    parsers: [ { container: ~ } ]
    paths: [ /var/log/containers/*.log ]
processors:
  - add_kubernetes_metadata:                     # 按 pod_uid 匹配 /var/log/pods 附加 Pod 元数据
      host: "${NODE_NAME}"
      default_indexers.enabled: false
      default_matchers.enabled: false
      indexers: [ pod_uid: ]
      matchers: [ logs_path: { logs_path: "/var/log/pods/", resource_type: "pod" } ]
---
# 每容器一输入模式：autodiscover 按 Pod 动态生成 filestream（hints 读注解 co.elastic.logs/*）
filebeat.autodiscover:
  providers:
    - type: kubernetes
      node: "${NODE_NAME}"
      hints.enabled: true
      hints.default_config:
        type: filestream
        id: container-${data.kubernetes.container.id}
        prospector.scanner.symlinks: true
        parsers: [ { container: ~ } ]
        paths: [ /var/log/containers/*-${data.kubernetes.container.id}.log ]
# Pod hints 注解示例：co.elastic.logs/multiline.type: "pattern"、.pattern: "^[0-9]{4}-"、.negate: "true"、.match: "after"

kubectl apply -f filebeat-kubernetes.yaml        # 官方 DaemonSet 清单，版本以官方文档为准
kubectl -n kube-system get pods -l k8s-app=filebeat ; kubectl -n kube-system logs <filebeat-pod> | grep -i error

filestream + container parser + symlinks 是 K8s 容器日志三要素；hints 注解由 autodiscover 读取，不会自动变成 Logstash 多行规则。

6. 告警与通知

Filebeat 自身不产生告警，由下游/监控侧告警：

告警条件：events.acked 5 分钟为 0（Agent 挂）、output 日志出现 401/connection refused、harvester 打开文件数突增、registry 磁盘 > 85%。通知渠道：Kibana Connector（Email/SMTP、Webhook、Slack、Teams、PagerDuty）与 Grafana Contact Point（Email、Webhook、钉钉、企业微信、Slack）；企业微信/钉钉用 Webhook 指向机器人 URL，消息体按各自 JSON 拼装（{"msgtype":"text","text":{"content":"告警内容"}}）。

7. 实战场景

7.1 Nginx/应用日志接入并做状态码统计

目标：Nginx access log → Filebeat nginx 模块 → 结构化 → ES 按状态码统计 → Kibana 展示。

步骤 + 命令/配置：

filebeat modules enable nginx                      # 在 modules.d/nginx.yml 配 var.paths（见 5.C）
filebeat test config -e && filebeat test output -e
filebeat setup --pipelines --index-management --dashboards -e
systemctl restart filebeat
echo '127.0.0.1 - - [05/Nov/2026:10:00:00 +0800] "GET /api HTTP/1.1" 500 123 "-" "curl"' >> /var/log/nginx/access.log

状态码统计（ES 聚合 → Kibana 可视化）与验证：

curl -s -u elastic:<密码> --cacert <ca> "https://<es>:9200/filebeat-*/_search?pretty&q=http.response.status_code:500"
curl -s -u elastic:<密码> --cacert <ca> -X POST "https://<es>:9200/filebeat-*/_search?size=0&pretty" \
  -H 'Content-Type: application/json' \
  -d '{"query":{"range":{"@timestamp":{"gte":"now-24h"}}},"aggs":{"by_status":{"terms":{"field":"http.response.status_code","size":10}},"trend":{"date_histogram":{"field":"@timestamp","fixed_interval":"1h"}}}}'

验证：_cat/indices/filebeat-* 有数据；_search 命中 500；Kibana [Filebeat Nginx] Overview 出图。 回滚：filebeat modules disable nginx；清理数据 POST /filebeat-*/_close 或先快照再 DELETE ⚠️。

7.2 日志暴增导致磁盘打满的处置

目标：日志突增冲垮 ES/采集端磁盘 → 止血 → 恢复 → 根治。

# ① 定位暴涨文件、Agent 磁盘、ES 水位；② 采集端限速+丢弃低价值行（改 yml 后 restart）
du -sh /var/log/* | sort -rh | head ; df -h /var/lib/filebeat
# processors: - rate_limit: { limit: "500/s" }  /  - drop_event.when.regexp.message: '^(healthcheck|DEBUG)'
# ③ ES 侧止血：最旧索引降副本、删最旧索引（同 elasticsearch.md 7.2）
curl -s -u elastic:<密码> --cacert <ca> "https://<es>:9200/_cat/allocation?v"
curl -s -u elastic:<密码> --cacert <ca> -X PUT "https://<es>:9200/filebeat-2025-*/_settings" -d '{"index.number_of_replicas":0}'
# ④ 根治：应用降日志级别/采样、logrotate 加 compress、ILM 缩短 delete.min_age、扩容

验证：df -h 回落；_cat/allocation < 85%；filebeat -e -d publish 中 events.acked 恢复；ES 回 green。 回滚：去掉限速/drop 处理器并 restart；恢复副本 PUT /filebeat-*/_settings {"index.number_of_replicas":1}；⚠️ 已删索引只能从快照恢复。

7.3 K8s 容器日志按命名空间分流

目标：DaemonSet 采集所有 Pod 日志，按 namespace 写不同 ES 索引。

# autodiscover 段复用 5.E 的 hints.default_config（filestream + symlinks + container parser）
processors:
  - add_kubernetes_metadata: { host: "${NODE_NAME}" }
output.elasticsearch:
  hosts: ["https://<es>:9200"]
  username: "<u>"  password: "<p>"
  indices:
    - index: "k8s-prod-%{+yyyy.MM.dd}"
      when.equals: { kubernetes.namespace: "prod" }
    - index: "k8s-other-%{+yyyy.MM.dd}"

验证：kubectl logs <filebeat-pod> 无 error；_cat/indices/k8s-*?v 出现两类索引；prod Pod 打日志可查到。 回滚：删除 indices 条件路由改回单 index: 并 kubectl rollout restart ds/filebeat；⚠️ 确认 registry 卷保留，避免重复采集。

8. 日常运维与故障排查

故障「现象 → 原因 → 处置」表

9. 性能、容量与高可用

容量估算公式：

日事件数 ≈ Σ(文件日增量 / 平均行字节)；带宽 ≈ 日事件数 × 平均事件字节 × (1 + 重试系数)
内存 ≈ 打开文件数 × 单行缓冲 + queue.mem.events × 事件字节；registry 磁盘 ≈ 文件数 × 数百字节
经验：单实例采数百文件、数千 EPS 无压力；超大规模按节点拆 DaemonSet

Filebeat 无分片/副本概念：分片与副本在下游 ES 规划（单分片 30–50GB、1 主 1 副、ILM rollover）；采集侧对应 harvester 数、内部队列、多实例 HA。

10. 安全加固、备份与升级

认证鉴权 / TLS / 最小权限

output.elasticsearch:
  hosts: ["https://<es>:9200"]
  username: "filebeat_svc"  password: "${ES_PWD}"   # 密码用 keystore，勿写明文
  # 8.x 安全集群还需 CA/TLS 相关项，参数名随 output 插件版本变化，见官方文档

filebeat keystore create ; filebeat keystore add ES_PWD ; filebeat keystore list

• 最小权限：ES 端采集账号仅 create_index + write + view_index_metadata 与所需 pipeline 权限；勿用 elastic 超管。只读挂载日志目录；:5066 仅内网可达；filebeat.yml 权限 600 且属主 root（--strict.perms 检查）。

备份：Filebeat 基本无状态，备份配置与 registry：/etc/filebeat/filebeat.yml、modules.d/、path.data/registry、keystore。⚠️ 丢失 registry 会导致重采（重复），务必随主机/卷备份。数据最终在 ES，用 SLM 快照备份恢复（见 elasticsearch.md 10），恢复前先 _close 目标索引。

滚动升级顺序与回滚：① 备份配置 + registry → ② 逐台停（等 in-flight ACK）→ ③ 升级包/镜像 → ④ test config -e + test output -e → ⑤ 启动看 events.acked 恢复 → ⑥ 下一台；K8s 用 kubectl rollout restart ds/filebeat 分批。回滚：装回旧版本并恢复备份配置与 registry（⚠️ registry 版本兼容性以官方为准，回滚前另存）；下游 ES 升级另按其滚动顺序。

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选 Filebeat：已用 Elastic Stack、需要 modules 开箱解析、要与 Logstash/ingest 紧密配合、需要可靠 registry 断点续传。何时不选：资源极度受限的 K8s 边缘 → Fluent Bit；已用 Grafana/Loki → Alloy；要一个组件替代采集+ETL → Vector；不接受 Elastic License → Fluent Bit/Vector。边界：Filebeat 在 ELK/EFK 是采集层（EFK 中用 Fluentd/Fluent Bit 替代），PLG 链路不含 Filebeat（由 Alloy 承担），二者不是串联关系。

14. 参考链接

• 官网 / 文档：https://www.elastic.co/beats/filebeat 、https://www.elastic.co/guide/en/beats/filebeat/current/index.html
• filestream input / K8s 部署：https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-input-filestream.html 、https://www.elastic.co/guide/en/beats/filebeat/current/running-on-kubernetes.html
• autodiscover / modules / processors：https://www.elastic.co/guide/en/beats/filebeat/current/configuration-autodiscover.html 、https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-modules.html
• output.elasticsearch / 命令：https://www.elastic.co/guide/en/beats/filebeat/current/elasticsearch-output.html
• 源码 / 包仓库：https://github.com/elastic/beats 、https://artifacts.elastic.co/packages/8.x/apt

8.x 起 ES 安全/TLS 默认开启、log input 弃用改 filestream；9.x 新增 compression: auto 等选项。具体版本与参数以官方最新稳定版文档为准。