3
0

Elastic Stack Logstash 数据管道与 ELFK 项目实践

2026-11-02
Elastic Stack Logstash 数据管道与 ELFK 项目实践

Elastic Stack Logstash 数据管道与 ELFK 项目

1. Logstash Pipeline 架构

stdin / file / beats / TCP
Input
Filter
Output
stdout / Elasticsearch / Kafka

一个 Pipeline 固定由三部分组成:

阶段作用常见插件
Input数据从哪里来stdin、file、beats、tcp、kafka、redis
Filter数据如何处理mutate、date、grok、geoip、useragent、json
Output数据向哪里去stdout、elasticsearch、kafka

ELFK 的基本链路:

Nginx → Filebeat → Logstash → Elasticsearch → Kibana

职责建议:

  • Filebeat 部署在日志产生端,负责轻量采集。
  • Logstash 集中完成复杂解析、字段转换、地理分析和条件路由。
  • Elasticsearch 负责索引、存储、搜索和聚合。
  • Kibana 负责查询和可视化。

2. Input 插件概览

插件用途注意事项
stdin标准输入测试仅适合验证配置
file读取文本文件依赖 sincedb 记录读取位置
beats接收 Filebeat 数据默认端口常用 5044 或自定义端口
tcp接收原始 TCP 文本生产环境应启用 TLS 和访问控制
kafka从 Kafka 消费消息适合削峰、解耦和多消费者
redis从 Redis 列表或频道读取适合简单缓冲,需处理持久化与高可用

3. file input 的读取位置

3.1 sincedb

file 输入插件把已读取文件的位置记录在 sincedb 中。默认位置可能位于:

/usr/share/logstash/data/plugins/inputs/file/.sincedb_*

下一次启动时,Logstash 会依据记录继续读取,而不是从头开始。

建议显式指定独立状态文件:

input {
  file {
    path => ["/tmp/demo-app.log"]
    start_position => "beginning"
    sincedb_path => "/var/lib/logstash/sincedb-demo-app"
  }
}

3.2 start_position

  • beginning:首次发现文件时从头读取。
  • end:首次发现文件时从末尾读取,是默认值。
  • 文件已有 sincedb 记录时,start_position 不会覆盖原读取位置。

3.3 受控重放旧数据

测试环境需要重新读取旧数据时:

  1. 停止对应 Logstash 实例。
  2. 备份原 sincedb。
  3. 创建新的状态文件路径。
  4. 使用新的 sincedb_path 启动。
sudo install -d -o logstash -g logstash /var/lib/logstash
sudo cp -a \
  /var/lib/logstash/sincedb-demo-app \
  /var/backups/sincedb-demo-app.$(date +%Y%m%d%H%M%S)

新配置:

sincedb_path => "/var/lib/logstash/demo-replay/sincedb-app"

不要直接在共享目录中删除未知的 .sincedb_* 文件,这可能导致其他采集任务重复写入大量数据。

4. mutate filter 处理业务日志

假定业务日志格式固定:

INFO 2026-07-16 10:34:39,123 [com.example.main] - DAU|1001|pay|1|299.00

目标字段:

字段类型含义
user_idinteger用户编号
actionkeyword用户行为
vipintegerVIP 标记
pricefloat金额
datetimestring日志中的业务时间

4.1 按分隔符拆分

filter {
  mutate {
    split => {
      "message" => "|"
    }

    add_field => {
      "prefix" => "%{[message][0]}"
      "user_id" => "%{[message][1]}"
      "action" => "%{[message][2]}"
      "vip" => "%{[message][3]}"
      "price" => "%{[message][4]}"
    }
  }

  mutate {
    split => {
      "prefix" => " "
    }

    add_field => {
      "datetime" => "%{[prefix][1]} %{[prefix][2]}"
    }

    remove_field => ["message", "prefix", "@version"]
  }

  mutate {
    convert => {
      "price" => "float"
      "user_id" => "integer"
      "vip" => "integer"
    }
  }
}

说明:

  • split 适合稳定的分隔符格式。
  • add_field 会先把值作为字符串加入事件,再通过 convert 转换为数字。
  • 字段名应与目标类型一致,例如数字使用 user_id,文本使用 action。
  • 处理失败时可检查 @timestamp、原始 message 和 Logstash 日志。

4.2 更适合生产的方式

对于严格固定的格式,dissect 比复杂正则更高效;对于半结构化日志,再使用 grok。

dissect {
  mapping => {
    "message" => "%{level} %{date} %{time},%{millis} [com.example.%{module}] - DAU|%{user_id}|%{action}|%{vip}|%{price}"
  }
}

之后仍需使用 date 和 mutate 转换时间与数值类型。

5. date filter 与时间戳

5.1 替换 @timestamp

日志里的业务时间需要转换成 Elasticsearch 日期类型,并用于 Kibana 时间筛选。

date {
  match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
  target => "@timestamp"
}

如果日志时间没有时区信息,应明确指定时区:

date {
  match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
  timezone => "Asia/Shanghai"
  target => "@timestamp"
}

5.2 保留原时间字段

若希望同时保留原始业务时间:

date {
  match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
  timezone => "Asia/Shanghai"
  target => "event.created"
}

5.3 没有指定 target 时

date 插件默认把解析结果写入 @timestamp。显式写出 target => "@timestamp" 更容易审阅,也能避免团队成员误解。

6. 写入 Elasticsearch 自定义索引

完整配置示例:/etc/logstash/config/04-business-to-es.conf

input {
  file {
    path => ["/tmp/demo-app.log"]
    start_position => "beginning"
    sincedb_path => "/var/lib/logstash/sincedb-demo-business"
  }
}

filter {
  mutate {
    split => {
      "message" => "|"
    }
    add_field => {
      "prefix" => "%{[message][0]}"
      "user_id" => "%{[message][1]}"
      "action" => "%{[message][2]}"
      "vip" => "%{[message][3]}"
      "price" => "%{[message][4]}"
    }
  }

  mutate {
    split => {
      "prefix" => " "
    }
    add_field => {
      "datetime" => "%{[prefix][1]} %{[prefix][2]}"
    }
    remove_field => ["message", "prefix", "@version"]
  }

  mutate {
    convert => {
      "price" => "float"
      "user_id" => "integer"
      "vip" => "integer"
    }
  }

  date {
    match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
    timezone => "Asia/Shanghai"
    target => "@timestamp"
  }
}

output {
  elasticsearch {
    hosts => [
      "http://192.0.2.11:9200",
      "http://192.0.2.12:9200",
      "http://192.0.2.13:9200"
    ]
    index => "demo-business-%{+yyyy.MM.dd}"
  }
}

索引命名要求:

  • 只能使用小写字母。
  • 可以使用数字、点、下划线和连字符。
  • 不要使用空格、反斜杠、斜杠、星号、问号、引号、尖括号、竖线、逗号或井号。
  • %{+yyyy.MM.dd} 使用事件的 @timestamp 生成日期后缀。

验证:

GET http://192.0.2.11:9200/_cat/indices/demo-business-*?v
GET http://192.0.2.11:9200/demo-business-*/_search?pretty&size=3

7. ELFK 解析 Nginx 访问日志

7.1 避免重复解析

有两条常见路线:

  1. Filebeat Nginx 模块 + Elasticsearch Ingest Pipeline:模块的字段解析通常依赖 Elasticsearch Ingest Pipeline,Filebeat 负责采集并携带相关元数据。若中间经过 Logstash,应确认 Pipeline 元数据能被正确传递,或者由 Logstash 完成相应解析。
  2. Logstash Grok 解析:Filebeat 只发送原始日志,由 Logstash 统一完成解析。

不建议在没有明确数据处理边界的情况下同时启用模块解析和 Logstash Grok,再对相同内容重复处理。这会导致字段覆盖、重复计算和排错困难。

7.2 原始 Nginx 日志格式

以下日志使用 Nginx 常见格式:

192.0.2.10 - - [15/Jul/2026:14:32:55 +0800] "GET /pc HTTP/1.1" 200 263 "-" "Mozilla/5.0"

%{HTTPD_COMMONLOG} 可提取:

clientip
ident
auth
verb
request
rawrequest
response
bytes
referrer
agent
timestamp

7.3 Logstash Beats 输入

input {
  beats {
    port => 9999
  }
}

filter {
  grok {
    match => {
      "message" => "%{HTTPD_COMMONLOG}"
    }
    tag_on_failure => ["_nginx_parse_failure"]
  }

  geoip {
    source => "clientip"
    target => "geoip"
  }

  useragent {
    source => "agent"
    target => "user_agent"
  }

  date {
    match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
    target => "@timestamp"
  }

  mutate {
    remove_field => ["message", "@version"]
  }
}

output {
  elasticsearch {
    hosts => [
      "http://192.0.2.11:9200",
      "http://192.0.2.12:9200",
      "http://192.0.2.13:9200"
    ]
    index => "demo-nginx-%{+yyyy.MM.dd}"
  }
}

要点:

  • useragent.source 应使用 Grok 解析出的 agent,不要对整个 message 再次解析。
  • geoip.source 必须是可查询的 IP 地址。
  • geoip.target 的坐标字段需要在 Elasticsearch 中映射为 geo_point。
  • 日期格式包含 +0800 时,不需要再强制指定相同偏移;没有时区时要明确时区。
  • _nginx_parse_failure 标签可用于查找解析失败的文档。

8. Filebeat 输出到 Logstash

Filebeat 仅采集原始日志的配置:

filebeat.inputs:
  - type: filestream
    id: demo-nginx-raw
    paths:
      - /var/log/nginx/access.log

output.logstash:
  hosts:
    - "192.0.2.13:9999"

使用 Filebeat 模块并交给 Logstash 补充处理时:

filebeat.config.modules:
  path: ${path.config}/modules.d/*.yml
  reload.enabled: true
  reload.period: 5s

output.logstash:
  hosts:
    - "192.0.2.13:9999"

示例只使用明文传输,仅适合隔离的实验网络。生产环境应为 Filebeat 到 Logstash 的链路配置 TLS 和访问控制。

为避免旧采集状态影响实验,可以指定新的独立数据目录:

sudo install -d -o filebeat -g filebeat /var/lib/filebeat-elk-demo

sudo filebeat -e \
  -c /etc/filebeat/config/15-nginx-to-logstash.yml \
  --path.data /var/lib/filebeat-elk-demo

建议先用 output.console 检查 Filebeat 发出的事件,再切换到 Logstash。

9. 自定义 Grok Pattern

9.1 pattern 文件

例如创建 /etc/logstash/patterns/demo.pattern:

DEMO_SCHOOL [A-Za-z][A-Za-z0-9_-]*
DEMO_CLASS  [A-Za-z0-9_-]+
DEMO_YEAR   \d{4}

9.2 在 Grok 中引用

grok {
  patterns_dir => ["/etc/logstash/patterns"]
  match => {
    "message" => "%{DEMO_YEAR:year} %{DEMO_SCHOOL:school} %{DEMO_CLASS:class_name} %{IPV4:client_ip}"
  }
  tag_on_failure => ["_custom_parse_failure"]
}

对应测试日志:

2026 demo-school class-a 192.0.2.20

注意:

  • 自定义 Pattern 名通常使用大写字母和数字。
  • Pattern 必须写入独立的 .pattern 文件或正确配置的 patterns 目录。
  • 字段名使用小写、数字和下划线更便于查询。
  • 不要从用户输入中直接构造正则,避免性能和注入风险。

10. geoip 与 useragent

10.1 geoip

geoip {
  source => "client_ip"
  target => "geoip"
}

可用字段通常包括:

geoip.location
geoip.country_name
geoip.city_name
geoip.timezone

Kibana Maps 使用坐标字段,因此 Elasticsearch 中必须将 geoip.location 映射为 geo_point。

注意:

  • 私网 IP 通常无法得到可靠地理位置。
  • IP 地理定位只能作为近似结果。
  • 第三方 IP 数据的使用应遵守许可证和隐私要求。
  • 真实日志在共享或展示前应脱敏。

10.2 useragent

useragent {
  source => "agent"
  target => "user_agent"
}

可得到浏览器、操作系统、版本和设备类型等信息。常见字段:

user_agent.original
user_agent.name
user_agent.version
user_agent.device.name
user_agent.os.name

在 Kibana 中可对操作系统或设备名称做 Terms 聚合,制作设备类型分布图。

11. 多分支处理

11.1 使用输入类型分支

input {
  file {
    path => ["/tmp/demo-web.log"]
    start_position => "beginning"
    sincedb_path => "/var/lib/logstash/sincedb-demo-web"
    type => "web"
  }

  beats {
    port => 9999
    type => "beats"
  }

  tcp {
    port => 8888
    type => "tcp"
  }
}

filter {
  if [type] == "web" {
    grok {
      match => {
        "message" => "%{HTTPD_COMMONLOG}"
      }
      tag_on_failure => ["_web_parse_failure"]
    }

    date {
      match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
      target => "@timestamp"
    }
  } else if [type] == "beats" {
    mutate {
      remove_field => ["@version"]
    }
  } else {
    grok {
      patterns_dir => ["/etc/logstash/patterns"]
      match => {
        "message" => "%{DEMO_YEAR:year} %{DEMO_SCHOOL:school} %{DEMO_CLASS:class_name} %{IPV4:client_ip}"
      }
    }
  }
}

11.2 输出条件路由

output {
  if [type] == "web" {
    elasticsearch {
      hosts => ["http://192.0.2.11:9200"]
      index => "demo-web-%{+yyyy.MM.dd}"
    }
  } else if [type] == "beats" {
    elasticsearch {
      hosts => ["http://192.0.2.11:9200"]
      index => "demo-beats-%{+yyyy.MM.dd}"
    }
  } else {
    elasticsearch {
      hosts => ["http://192.0.2.11:9200"]
      index => "demo-tcp-%{+yyyy.MM.dd}"
    }
  }
}

建议:

  • 新设计优先使用明确的业务字段或 tags,减少对旧 type 字段的依赖。
  • 输入、过滤和输出条件应相互对应。
  • 每个事件只能进入预期的唯一索引。
  • 对解析失败的数据增加失败标签和独立处理路径,而不是静默丢弃。

12. Logstash 多实例

多实例表示启动多个独立 Logstash 进程。

每个实例应具有:

  • 独立配置文件。
  • 独立 --path.data。
  • 互不冲突的监听端口。
  • 独立的服务单元或进程管理方式。

示例:

sudo install -d -o logstash -g logstash /var/lib/logstash-file-a
sudo install -d -o logstash -g logstash /var/lib/logstash-file-b

logstash -r -f /etc/logstash/config/demo-a.conf \
  --path.data /var/lib/logstash-file-a

logstash -r -f /etc/logstash/config/demo-b.conf \
  --path.data /var/lib/logstash-file-b

不要用 /tmp/logstash-* 保存长期状态,因为临时目录可能被清理。

需要避免:

  • 两个实例监听相同 TCP/Beats 端口。
  • 两个实例读取相同文件却使用不同状态,造成重复数据。
  • 多个实例写入相同索引但字段结构不一致。
  • 误把 --path.data 当成输出数据目录,它主要保存内部状态和持久化数据。

13. 单进程多 Pipeline

13.1 pipelines.yml

Logstash 软件包通常使用:

/etc/logstash/pipelines.yml

示例:

- pipeline.id: demo_file
  path.config: "/etc/logstash/conf.d/02-file.conf"

- pipeline.id: demo_beats
  path.config: "/etc/logstash/conf.d/03-beats.conf"

启动:

sudo systemctl restart logstash
sudo journalctl -u logstash -f

注意:

  • pipeline.id 在同一进程内必须唯一。
  • path.config 必须指向对应配置文件。
  • 如果启动命令使用 -f,Logstash 会忽略 pipelines.yml。
  • 不同 Pipeline 的输入端口、输出索引和条件路由应清晰隔离。

13.2 Pipeline、分支和多实例的区别

概念本质示例
Pipeline一个完整的 input → filter → output 数据流Nginx 日志管道
多分支在同一 Pipeline 内使用 if/else按 type 或 tags 路由
单进程多 Pipeline一个 Logstash 进程加载多个 Pipelinepipelines.yml
多实例多个独立 Logstash 进程不同配置、端口和数据目录

一个 Pipeline 内可以包含多分支;一个进程可以运行多个 Pipeline;多实例则是多个进程。

14. Kibana 时区问题

14.1 时间的处理链路

正确的时间链路:

原始日志时间 → date filter → @timestamp → Elasticsearch 日期字段 → Kibana 时区显示

常见问题:

  • 原始日志没有时区,却被默认按 UTC 解析。
  • 业务时间和 @timestamp 不一致。
  • Kibana 时间范围与用户预期时区不一致。
  • 浏览器仍使用旧的时区设置。

14.2 设置 date filter 时区

日志时间没有偏移量时:

date {
  match => ["datetime", "yyyy-MM-dd HH:mm:ss"]
  timezone => "Asia/Shanghai"
  target => "@timestamp"
}

带偏移量的 Nginx 日志:

15/Jul/2026:14:32:55 +0800

可使用:

date {
  match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
  target => "@timestamp"
}

14.3 Kibana 显示时区

在 Kibana 的用户设置中选择:

Time zone for date formatting → Asia/Shanghai

或者选择浏览器时区。保存后刷新页面,并重新检查 Discover 的时间范围。

15. 完整 ELFK 配置示例

15.1 Filebeat

filebeat.inputs:
  - type: filestream
    id: demo-nginx-elk
    paths:
      - /var/log/nginx/access.log

output.logstash:
  hosts:
    - "192.0.2.13:9999"

15.2 Logstash

input {
  beats {
    port => 9999
  }
}

filter {
  grok {
    match => {
      "message" => "%{HTTPD_COMMONLOG}"
    }
    tag_on_failure => ["_nginx_parse_failure"]
  }

  geoip {
    source => "clientip"
    target => "geoip"
  }

  useragent {
    source => "agent"
    target => "user_agent"
  }

  date {
    match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
    target => "@timestamp"
  }
}

output {
  elasticsearch {
    hosts => [
      "http://192.0.2.11:9200",
      "http://192.0.2.12:9200",
      "http://192.0.2.13:9200"
    ]
    index => "demo-nginx-%{+yyyy.MM.dd}"
  }
}

15.3 验证链路

# 1. 检查 Logstash 是否监听 Beats 端口
sudo ss -ntlp | grep ':9999'

# 2. 测试 Logstash 配置
logstash -f /etc/logstash/config/15-nginx-elk.conf \
  --config.test_and_exit

# 3. 启动 Filebeat
sudo filebeat test config -c /etc/filebeat/config/15-nginx-to-logstash.yml
sudo filebeat test output -c /etc/filebeat/config/15-nginx-to-logstash.yml
sudo filebeat -e -c /etc/filebeat/config/15-nginx-to-logstash.yml

# 4. 追加请求
curl -s -o /dev/null http://192.0.2.11/

# 5. 查看索引
curl -s "http://192.0.2.11:9200/_cat/indices/demo-nginx-*?v"

16. 常见故障排查

16.1 Logstash 配置

logstash -f /etc/logstash/config/demo.conf \
  --config.test_and_exit
sudo journalctl -u logstash -f

重点检查:

  • 配置文件语法。
  • 插件是否已安装。
  • 输入端口是否被占用。
  • 输出 Elasticsearch 是否可达。
  • Pattern 文件路径和语法。
  • 字段引用是否使用正确格式,例如 [user_id]。

16.2 文件没有被重新读取

排查:

filebeat --version
sudo ls -la /var/lib/logstash/
sudo find /usr/share/logstash/data/plugins/inputs/file \
  -maxdepth 1 -name '.sincedb_*' -ls

处理:

  • 检查是否已有 sincedb。
  • 给测试任务使用新的 sincedb_path。
  • 保留原状态备份,不要在未知任务上直接删除。

16.3 Grok 解析失败

在 Kibana 中搜索:

tags: "_nginx_parse_failure" or tags: "_custom_parse_failure"

比较:

  • 原始 message。
  • 实际日志格式。
  • Pattern 对空格、方括号和引号的要求。
  • Grok Debugger 的测试结果。

16.4 地图没有坐标

检查:

GET http://192.0.2.11:9200/demo-nginx-*/_mapping

确认:

  • geoip.location 是否存在。
  • 字段类型是否为 geo_point。
  • IP 是否为可定位的公网地址。
  • Kibana 是否选择了坐标字段。

16.5 时间显示相差 8 小时

依次检查:

  1. 原始日志是否带时区。
  2. date filter 是否指定 timezone。
  3. @timestamp 是否被正确覆盖。
  4. Kibana 用户时区是否为 Asia/Shanghai。
  5. 浏览器是否刷新了新设置。

16.6 多条日志重复

可能原因:

  • Filebeat 多实例共用数据目录。
  • Logstash 多实例读取同一文件。
  • sincedb 被清理或更换。
  • 同时启用 Filebeat 模块和手工输入。

17. ELFK 可视化项目练习

17.1 目标

部署一个实验业务站点,使用 ELFK 分析访问日志:

  • 可选 WordPress 或 Kodcloud。
  • Web 服务产生访问日志。
  • Filebeat 采集日志。
  • Logstash 完成解析、时间和 User-Agent 处理。
  • Elasticsearch 存储结构化数据。
  • Kibana 制作 Dashboard。

17.2 Dashboard 指标

指标字段与聚合
真实客户端 IPclientip 或 source.ip 的 Cardinality
PV文档 Count
带宽bytes 或 send_bytes 的 Sum
VIP 用户对 vip 做 Terms,统计 0/1 分布
设备类型user_agent.device.name 的 Terms
城市分布geoip.city_name 的 Terms
地理分布geoip.location 的 Maps 图层
状态码response 或 status 的 Terms
热门 URIrequest 或 uri 的 Terms
访问趋势基于 @timestamp 的 Date Histogram

17.3 Grafana 扩展

可通过 Elasticsearch 数据源在 Grafana 中展示:

  • IP 数。
  • 带宽。
  • VIP 用户分布。
  • PV。
  • 设备类型。
  • 城市分布。
  • 状态码和访问趋势。

安全建议:

  • 使用只读且权限范围受限的 Elasticsearch 账号。
  • 不要在 Grafana 面板中公开真实用户 IP。
  • 查询大范围数据时设置合理时间范围、过滤条件和缓存。

18. 总结

  • file input 的 start_position 只在首次读取新文件时生效。
  • sincedb 保存读取位置,重放旧数据应使用独立状态路径。
  • mutate 适合拆分和转换已知结构的字段。
  • 固定格式优先考虑 dissect,复杂文本再使用 grok。
  • date 负责把业务时间写入 @timestamp 或指定日期字段。
  • 无时区时间必须明确指定 timezone。
  • geoip 和 useragent 应使用已经解析出的 IP、User-Agent 字段。
  • Filebeat 模块解析和 Logstash Grok 不应重复处理同一日志。
  • 多分支使用 if/else 条件控制 Filter 和 Output。
  • 单进程可运行多个 Pipeline,多实例是多个独立进程。
  • 多实例必须隔离配置、端口和 path.data。
  • Kibana 时区问题要同时检查原始时间、date filter 和显示设置。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!