openiamdocker/filebeat

Filebeat Docker镜像文档

镜像概述

Filebeat是Elastic Stack生态中的轻量级日志托运人（log shipper），专为在资源受限环境中高效收集、转发日志数据而设计。作为Docker镜像，它可快速部署于容器化环境，实现对物理机、虚拟机或容器日志的统一采集，并将数据可靠传输至Elasticsearch、Logstash、Kafka等后端系统，支持日志集中存储、分析与可视化。

核心功能与特性

轻量级设计

• 低资源占用：极小的CPU、内存消耗，适合边缘节点或资源受限环境部署
• 无依赖架构：独立运行，无需复杂依赖，简化容器化部署流程

多源日志收集

• 多类型输入支持：文件日志、标准输出（stdout/stderr）、系统日志、容器日志（Docker/Kubernetes）等
• 灵活配置：通过filebeat.yml自定义日志路径、过滤规则、标签及元数据

可靠传输机制

• 断点续传：内置数据缓冲区，网络中断后自动恢复传输，避免日志丢失
• 背压处理：根据下游服务负载动态调整发送速率，防止数据拥塞

与Elastic Stack深度集成

• 原生对接Elasticsearch：直接索引日志数据，结合Kibana实现可视化分析
• 兼容Logstash：支持作为Logstash输入源，实现日志过滤、转换后再存储

使用场景

服务器日志监控

• 收集物理机/虚拟机系统日志（如/var/log/syslog、/var/log/auth.log），实时监控系统状态与异常行为

容器日志收集

• 在Docker/Kubernetes环境中，采集容器标准输出及容器内文件日志，统一管理容器化应用日志

分布式系统日志聚合

• 跨多节点、多服务收集日志，解决分布式系统日志分散问题，支持全链路追踪与故障排查

安全审计日志转发

• 收集应用访问日志、认证日志，转发至安全分析平台，满足合规审计需求

使用方法与配置说明

前提条件

• Docker环境（1.13.0+）或Kubernetes集群
• 目标输出服务（如Elasticsearch、Logstash）已部署并可访问
• Filebeat配置文件（filebeat.yml），用于定义日志输入源与输出目标（配置示例见下文）

基本运行命令

1. 挂载本地配置文件运行

Filebeat需通过配置文件指定输入与输出，建议将本地filebeat.yml挂载至容器内：

bash
docker run -d \
  --name filebeat \
  -v /path/to/your/filebeat.yml:/usr/share/filebeat/filebeat.yml:ro \
  -v /var/log:/var/log:ro \  # 挂载主机日志目录（只读）
  -v /path/to/filebeat-data:/usr/share/filebeat/data \  # 持久化状态数据（避免重复收集）
  docker.elastic.co/beats/filebeat:8.11.3  # 使用官方镜像，版本号可替换

说明：

• filebeat.yml需设置权限为chmod 600（容器内Filebeat用户ID为1000）
• /var/log挂载为只读（:ro），防止容器修改主机日志文件

2. Docker Compose配置示例

结合Elasticsearch与Kibana的完整部署示例（docker-compose.yml）：

yaml
version: '3'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.3
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
    networks:
      - elastic

  kibana:
    image: docker.elastic.co/kibana/kibana:8.11.3
    ports:
      - "5601:5601"
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200
    depends_on:
      - elasticsearch
    networks:
      - elastic

  filebeat:
    image: docker.elastic.co/beats/filebeat:8.11.3
    volumes:
      - ./filebeat.yml:/usr/share/filebeat/filebeat.yml:ro
      - /var/log:/var/log:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro  # 收集Docker容器日志
      - /var/run/docker.sock:/var/run/docker.sock:ro  # 获取容器元数据
      - filebeat-data:/usr/share/filebeat/data  # 持久化状态数据
    user: root  # 需root权限访问Docker sock及部分日志文件
    depends_on:
      - elasticsearch
    networks:
      - elastic

networks:
  elastic:
    driver: bridge

volumes:
  filebeat-data:  # 命名卷，持久化Filebeat状态数据

核心配置说明

配置文件（filebeat.yml）

核心配置项示例（输出至Elasticsearch）：

yaml
filebeat.inputs:
  - type: log  # 日志输入类型
    paths:
      - /var/log/*.log  # 收集/var/log下所有.log文件
      - /var/log/nginx/access.log  # 收集Nginx访问日志（需额外挂载对应目录）
    tags: ["server-logs"]  # 添加标签，便于后续过滤
    fields:  # 自定义字段，丰富日志元数据
      service: "web-server"

output.elasticsearch:
  hosts: ["elasticsearch:9200"]  # Elasticsearch地址（与docker-compose网络一致）
  index: "filebeat-%{+yyyy.MM.dd}"  # 按日期生成索引

setup.kibana:
  host: "kibana:5601"  # Kibana地址，用于导入默认仪表板
  setup.dashboards.enabled: true  # 自动导入Filebeat默认仪表板

环境变量配置

可通过环境变量动态调整配置（需在filebeat.yml中引用）：

在filebeat.yml中引用环境变量示例：

yaml
output.elasticsearch:
  hosts: ["${ELASTICSEARCH_HOSTS}"]
  index: "${INDEX_NAME}-%{+yyyy.MM.dd}"

logging.level: "${LOG_LEVEL:info}"  # 默认为info级别

配置验证

启动前可通过以下命令验证配置文件有效性：

bash
docker run --rm \
  -v /path/to/your/filebeat.yml:/usr/share/filebeat/filebeat.yml:ro \
  docker.elastic.co/beats/filebeat:8.11.3 \
  test config -c /usr/share/filebeat/filebeat.yml

注意事项

1. 权限问题：收集Docker日志或系统日志时，容器需以root用户运行（或添加CAP_DAC_READ_SEARCH权限）以访问日志文件与Docker sock
2. 版本兼容性：Filebeat版本需与Elasticsearch、Kibana版本保持一致（如8.11.3），避免兼容性问题
3. 资源限制：根据日志量调整容器资源限制（如--memory=512m --cpus=0.5），防止资源占用过高
4. 安全配置：生产环境中需启用Elasticsearch安全认证，通过output.elasticsearch.username与password配置认证信息