企业官网建设流程全解析

• 日志分析
• 可观测性
• 运维
• DevOps

Filebeat 是 Elastic 生态中的轻量级日志采集器（shipper），以 Agent 形式部署在服务器上，监听指定日志文件或数据源、收集日志事件，并转发给 Elasticsearch 或 Logstash 进行索引。本指南基于 docker-elk 仓库的 Filebeat 扩展，讲解如何在 ELK 栈中启用 Filebeat、完成用户与权限初始化、逐段解读官方filebeat.yml配置，以及如何通过 Docker Autodiscover 自动发现容器日志。读完本文，你将掌握在 docker-elk 中以 Compose 叠加方式接入 Filebeat 的完整实战方案。

一、Filebeat 在 docker-elk 中的定位

在 docker-elk 默认栈中（docker-compose.yml），日志链路由 Logstash 承担；而 Filebeat 扩展 提供了另一条数据采集路径：由 Filebeat 作为轻量 Agent 直接读取 Docker 容器日志，再写入 Elasticsearch。两者可以并存，Filebeat 适合"从宿主机侧采集容器标准输出日志"的场景，且默认配置下它会把日志直接输出到 Elasticsearch（output.elasticsearch），不经由 Logstash。

Filebeat 扩展位于 extensions/filebeat，由四个文件组成：

• Dockerfile：基于官方镜像docker.elastic.co/beats/filebeat:${ELASTIC_VERSION:-9.5.4}构建，镜像版本跟随根目录.env中的ELASTIC_VERSION；
• filebeat-compose.yml：Compose 服务定义，负责挂载配置、绑定 Docker 套接字与容器日志目录、注入密码环境变量；
• config/filebeat.yml：Filebeat 核心配置，包括 Autodiscover、输出、监控与 HTTP 健康检查端点；
• README.md：本指南所依据的官方使用说明。

二、启用 Filebeat 扩展：前置条件与启动命令

2.1 前置条件：filebeat_internal与beats_system用户

该扩展要求filebeat_internal与beats_system两个用户已被创建并初始化密码。如果这两个用户尚未在栈的首次启动过程中初始化，需要参考 How to re-execute the setup 重新运行 setup 容器完成初始化。

这两个用户的分工如下：

• filebeat_internal：Filebeat 写入 Elasticsearch 时使用的服务账号，映射到自定义角色filebeat_writer；
• beats_system：Elasticsearch 内置用户，被monitoring（Beats 自身指标监控上报）配置所使用。

密码分别通过环境变量FILEBEAT_INTERNAL_PASSWORD与BEATS_SYSTEM_PASSWORD注入，均可在根目录.env文件中定义。

2.2 用户初始化背后的实现

用户与角色的创建逻辑在 setup/entrypoint.sh 中。脚本中声明了用户及对应角色：

filebeat_internal → filebeat_writer

随后调用 setup/lib.sh 中的ensure_role、check_user_exists、set_user_password、create_user等函数，通过 Elasticsearch 的/_security/role、/_security/userREST API 完成角色创建与用户创建/改密。filebeat_internal使用的角色权限定义在 setup/roles/filebeat_writer.json：

• 集群权限：manage_ilm、manage_index_templates、manage_ingest_pipelines、monitor、read_pipeline——分别对应索引生命周期管理（ILM）、索引模板、摄取管道的管理以及集群监控与管道读取；
• 索引权限：对filebeat-*索引授予create_doc（写入文档）与manage（管理索引）权限。

这意味着 Filebeat 写出的索引默认以filebeat-前缀命名，并具备创建索引模板与执行 ILM 的权限，与官方 Filebeat 的索引命名约定一致。

如果filebeat_internal用户尚未初始化，可以按主仓库 README 的说明重新执行 setup：

$ docker compose up setup

setup 服务通过非默认 profile（setup）排除在常规docker compose up之外，需要显式按名称启动或使用--profile=setup。重新运行时，脚本会重置.env中已定义密码的用户的密码，并同步内置角色权限。

2.3 启动 Filebeat 服务

在仓库根目录执行 Docker Compose，并追加指向filebeat-compose.yml的命令行参数：

$ docker compose -f docker-compose.yml -f extensions/filebeat/filebeat-compose.yml up

docker compose -f支持一次传入多个 Compose 文件，后加载的 filebeat-compose.yml 会与根目录 docker-compose.yml 合并，在其基础上追加filebeat服务。该服务：

• 加入elk网络，并depends_on: elasticsearch，确保 Elasticsearch 先就绪；
• 声明了FILEBEAT_INTERNAL_PASSWORD、BEATS_SYSTEM_PASSWORD两个环境变量（取自.env）。

三、逐段解读 Filebeat 配置文件

Filebeat 配置存放在 config/filebeat.yml，修改时可参考官方 Filebeat 配置参考文档（Configuration reference）按需调整。下面按配置块逐一拆解。

3.1 基础标识与模块配置

name: filebeat filebeat.config: modules: path: ${path.config}/modules.d/*.yml reload.enabled: false

• name：Beats 实例名称，出现在监控数据与部分文档字段中；
• filebeat.config.modules.path：指向modules.d/目录下的模块配置，支持通配符加载；
• reload.enabled: false：关闭模块配置热加载，修改模块配置后需重启容器生效。

3.2 Docker Autodiscover：自动发现容器日志

filebeat.autodiscover: providers: - type: docker hints.enabled: true hints.default_config: type: container paths: - /var/lib/docker/containers/${data.container.id}/*-json.log templates: - condition: contains: docker.container.image: elasticsearch config: - module: elasticsearch server: input: type: container paths: - /var/lib/docker/containers/${data.container.id}/*-json.log

这是整个配置最核心的部分：

• type: docker：使用 Docker Autodiscover Provider。它会订阅 Docker 事件流，在容器启动/停止时自动发现日志源；
• hints.enabled: true：开启 Hints 机制，允许通过 Docker 标签（如co.elastic.logs/enabled）按容器定制采集行为；
• hints.default_config：未设置任何 hint 标签的容器使用的默认采集配置——type: container表示按容器日志读取，paths指向 Docker 标准 JSON 日志文件位置，其中${data.container.id}是 Autodiscover 注入的变量，会被替换为实际容器 ID；
• templates：对匹配条件的容器应用专门的模块配置。示例中当容器镜像包含elasticsearch时，启用elasticsearch模块，以容器日志方式解析 Elasticsearch 的 JSON 格式日志，从而获得字段化的日志文档（如日志级别、节点名等）。

3.3 处理器与云元数据

processors: - add_cloud_metadata: ~

add_cloud_metadata处理器自动从部署环境（AWS、GCP、Azure 等）读取实例元数据并附加到事件中，便于跨云环境定位日志来源；在非云环境（如本机 Docker）下它只是静默跳过，不影响采集。

3.4 Beats 自身监控上报

monitoring: enabled: true elasticsearch: username: beats_system password: ${BEATS_SYSTEM_PASSWORD}

• enabled: true：开启 Beats 自身的指标监控，将 Filebeat 的运行状态（CPU、内存、吞吐等）上报到 Elasticsearch；
• 上报时使用beats_system内置用户与${BEATS_SYSTEM_PASSWORD}环境变量中配置的密码，这也是扩展要求初始化beats_system用户的原因。

3.5 输出到 Elasticsearch

output.elasticsearch: hosts: [ http://elasticsearch:9200 ] username: filebeat_internal password: ${FILEBEAT_INTERNAL_PASSWORD}

• hosts：Elasticsearch 地址列表。这里使用 Compose 网络内的服务名elasticsearch，端口 9200，无需暴露到宿主机；
• 认证使用filebeat_internal用户及${FILEBEAT_INTERNAL_PASSWORD}密码，与 2.2 节创建的账号一一对应。

如果需要改走 Logstash 链路（例如希望先经过 Logstash 管道处理），可将该块替换为output.logstash，指向logstash:5044（Logstash 的 Beats 输入端口见 docker-compose.yml）。

3.6 HTTP 健康检查端点

http: enabled: true host: 0.0.0.0

开启 HTTP 端点用于健康检查：Filebeat 会在0.0.0.0:5066（Beats 默认 HTTP 端口）提供状态查询接口，容器编排或监控系统可据此判断 Filebeat 是否存活。

四、Compose 服务定义：为什么以 root 运行并绑定 Docker 套接字

filebeat-compose.yml 中的关键设计值得展开说明：

services: filebeat: build: context: extensions/filebeat/ args: ELASTIC_VERSION: ${ELASTIC_VERSION} user: root command: - -e - --strict.perms=false volumes: - ./extensions/filebeat/config/filebeat.yml:/usr/share/filebeat/filebeat.yml:ro,Z - type: bind source: /var/lib/docker/containers target: /var/lib/docker/containers read_only: true - type: bind source: /var/run/docker.sock target: /var/run/docker.sock read_only: true

• user: root：官方 filebeat 镜像默认以 uid 1000 的filebeat用户运行；此处改用 root，是为了能够读取宿主机的 Docker 套接字与容器日志目录（docker.sock和/var/lib/docker/containers属 root 权限）；
• -e：日志输出到 stderr，便于被 Docker 日志驱动捕获，配合栈内其他组件统一查看；
• --strict.perms=false：关闭配置文件的权限检查，允许挂载宿主上非 root 属主的filebeat.yml，避免因文件属主不符导致启动失败；
• 三个卷：配置文件以只读方式挂载到镜像内默认路径/usr/share/filebeat/filebeat.yml；/var/lib/docker/containers只读挂载供 Autodiscover 按 3.2 节的路径读取 JSON 日志；/var/run/docker.sock只读挂载供 Autodiscover 订阅 Docker 事件流、探测容器元数据。

五、修改配置与重启生效

由于reload.enabled: false且配置以只读卷挂载，任何对filebeat.yml的修改都需要重启 Filebeat 容器才能生效：

$ docker compose -f docker-compose.yml -f extensions/filebeat/filebeat-compose.yml restart filebeat

注意重启命令必须与启动命令保持一致，同时传入根 Compose 文件与扩展 Compose 文件，否则 Compose 会因找不到filebeat服务而报错。修改配置前建议先在官方配置参考中核对参数名与取值范围，避免因拼写或缩进错误导致容器启动失败。

六、验证与排障思路

• 检查健康端点：在栈内网络访问http://filebeat:5066/（或从宿主机执行docker exec进入 filebeat 容器后curl localhost:5066），确认 HTTP 端点响应正常；
• 确认用户已初始化：若启动日志出现认证失败（401）或提示用户不存在，说明filebeat_internal/beats_system尚未初始化，回到 2.2 节重新执行docker compose up setup；
• 确认日志读取：Filebeat 以 stderr 输出运行日志，docker compose logs filebeat可查看是否发现容器、是否有读取错误；
• 确认索引写入：在 Kibana 的 Discover 中检索filebeat-*索引模式，或在 Elasticsearch 中查询GET /filebeat-*/_count，验证日志是否已成功落库。索引写入依赖 filebeat_writer.json 中授予的filebeat-*索引权限。

七、进一步阅读

• Filebeat 扩展说明（本指南所依据的原始文档）
• Filebeat 配置文件
• Filebeat Compose 服务定义
• Filebeat 镜像构建定义
• setup 服务与用户初始化
• filebeat_internal 用户角色权限
• 如何重新执行 setup（主仓库 README）
• 若需了解如何在 Docker 容器中运行与配置 Filebeat 的更多细节，可参考 Elastic 官方文档的 "Run Filebeat on Docker" 与 Filebeat 配置参考页面；在栈内也可对照 extensions/filebeat/config/filebeat.yml 的注释链接继续深入。

• 日志分析
• 可观测性
• 运维
• DevOps