# 03-Fluent Bit日志收集

[toc]

Fluent Bit 是一个 CNCF 毕业的开源遥测数据采集代理，使用 C 语言编写，以极低资源占用（~1MB 内存、零依赖）著称，常用于 Kubernetes 集群中以 DaemonSet 方式部署在每个节点采集容器日志。

相比于 Fluentd（C + Ruby，>60MB 内存），Fluent Bit 性能高 10-40 倍，内置 70+ 插件编译进单一二进制文件，支持 Logs、Metrics、Traces 多信号采集，支持 OpenTelemetry 协议。

## Fluent Bit 架构

Fluent Bit 采用事件驱动的管道架构：

```
Input → Parser → Filter → Processor → Buffer → Output
```

| 阶段 | 说明 |
|---|---|
| **Input** | 从多种数据源采集数据（tail 文件、syslog、TCP/HTTP、K8s、Prometheus、OTel 等） |
| **Parser** | 将非结构化日志解析为结构化数据（JSON、Regex、LTSV、Logfmt 等） |
| **Filter** | 修改、增强或丢弃记录（K8s 元数据注入、多行合并等） |
| **Processor** | 条件逻辑数据转换（v4.0+ 新增） |
| **Buffer** | 内存和文件系统缓冲，支持背压处理 |
| **Output** | 路由到多个后端（ES、Loki、Kafka、S3、Prometheus 等），store-once, subscribe-many 模式 |

### 核心组件

- **70+ 内置插件**：Input、Filter、Output 编译进单一二进制
- **SQL Stream Processor**：对数据流做实时 SQL 查询和转换
- **Kubernetes Filter**：自动通过 API Server 获取 Pod 元数据（namespace、labels、annotations）追加到日志
- **可靠性机制**：背压处理、数据完整性校验、本地缓冲

## loongarch64 编译

Fluent Bit 官方未提供 loongarch64 预编译包，需要从源码编译。本编译基于 Kylin Linux Advanced Server V11 (Swan25)。

### 编译环境

| 组件 | 版本 |
|---|---|
| OS | Kylin Linux Advanced Server V11 |
| 架构 | loongarch64 |
| GCC | 12.3.1 |
| CMake | 3.27.9 |
| 内核 | 5.15+ |

### 安装编译依赖

```
[root@master2 ~]# yum install -y cmake flex bison openssl-devel libyaml-devel systemd-devel
```

> 1. `cmake`: 构建系统
> 2. `flex/bison`: 词法和语法分析器生成工具
> 3. `openssl-devel`: TLS/SSL 支持
> 4. `libyaml-devel`: YAML 配置文件解析
> 5. `systemd-devel`: journald 日志采集支持

### 下载源码

```
[root@master2 ~]# git clone --depth 1 --branch v4.2.6 https://github.com/fluent/fluent-bit.git
```

若 GitHub 直连不稳定，可本机下载后传至服务器：

```
$ tar czf fluent-bit-v4.2.6.tar.gz fluent-bit
$ scp fluent-bit-v4.2.6.tar.gz root@19.190.3.134:/root/
[root@master2 ~]# tar xzf fluent-bit-v4.2.6.tar.gz
```

### CMake 配置

```
[root@master2 ~]# cd fluent-bit && rm -rf build && mkdir build && cd build
[root@master2 build]# cmake \
    -DFLB_LUAJIT=OFF \
    -DFLB_FILTER_LUA=OFF \
    -DFLB_WASM=OFF \
    -DFLB_FILTER_WASM=OFF \
    ../
```

> **禁用组件的说明：**
> 1. `FLB_LUAJIT=OFF`：内置 LuaJIT 不包含 `vm_loongarch64.dasc` 后端文件。Kylin 系统虽有 `luajit-devel` loong64 包，但 Fluent Bit 的 cmake 脚本无法跳过内置 LuaJIT 编译（与 riscv64/s390x 处理方式一致）。
> 2. `FLB_WASM=OFF`：内部依赖的 WAMR（wasm-micro-runtime）无法识别 loongarch64 架构，会误判为 X86_64 导致 `MAP_32BIT` 未定义错误。

### 编译与安装

```
[root@master2 build]# make -j$(nproc)
[root@master2 build]# make install
```

编译产物：

| 文件 | 路径 |
|---|---|
| 主程序 | `/usr/local/bin/fluent-bit` |
| 共享库 | `/usr/local/lib64/fluent-bit/libfluent-bit.so` |
| 配置文件 | `/usr/local/etc/fluent-bit/` |
| 开发头文件 | `/usr/local/include/fluent-bit/` |
| systemd 服务 | `/usr/lib/systemd/system/fluent-bit.service` |

### 验证

```
[root@master2 ~]# fluent-bit --version
Fluent Bit v4.2.6

[root@master2 ~]# fluent-bit -i dummy -o stdout -f 1
Fluent Bit v4.2.6
...
[0] dummy.0: [[1783320910.506807152, {}], {"message"=>"dummy"}]
[0] dummy.0: [[1783320911.506930510, {}], {"message"=>"dummy"}]
```

## RPM 打包

### 编写 SPEC 文件

```
[root@master2 ~]# mkdir -p /root/rpmbuild/{SPECS,SOURCES,RPMS,SRPMS,BUILD,BUILDROOT}
[root@master2 ~]# cat > /root/rpmbuild/SPECS/fluent-bit.spec << 'EOF'
Name:           fluent-bit
Version:        4.2.6
Release:        2%{?dist}
Summary:        Fast data forwarder for Linux, BSD, OSX and Windows
License:        Apache-2.0
URL:            https://fluentbit.io

%description
Fluent Bit is a fast and lightweight telemetry agent for logs, metrics,
and traces. It collects, parses, filters, and routes data from various
sources to multiple destinations.

Built natively for loongarch64.
Note: Lua and WASM filters are disabled (no loongarch64 support upstream).

%pretrans
# Handle upgrade from v1 where /usr/local/etc/fluent-bit was a directory
if [ -d /usr/local/etc/fluent-bit ] && [ ! -L /usr/local/etc/fluent-bit ]; then
    rm -rf /usr/local/etc/fluent-bit
fi
exit 0

%install
rm -rf %{buildroot}
make -C /root/fluent-bit/build DESTDIR=%{buildroot} install
mkdir -p %{buildroot}/etc/fluent-bit
mv %{buildroot}/usr/local/etc/fluent-bit/*.conf %{buildroot}/etc/fluent-bit/
rm -rf %{buildroot}/usr/local/etc/fluent-bit
ln -s /etc/fluent-bit %{buildroot}/usr/local/etc/fluent-bit

%files
/usr/local/bin/fluent-bit
/usr/local/etc/fluent-bit
/usr/local/lib64/fluent-bit/libfluent-bit.so
/usr/local/include/fluent-bit/
/usr/local/include/fluent-bit.h
/usr/local/include/libco.h
/usr/local/include/settings.h
/usr/local/include/monkey/
/usr/lib/systemd/system/fluent-bit.service
%dir /etc/fluent-bit
%config(noreplace) /etc/fluent-bit/fluent-bit.conf
%config(noreplace) /etc/fluent-bit/parsers.conf
%config(noreplace) /etc/fluent-bit/plugins.conf

%post
%systemd_post fluent-bit.service

%preun
%systemd_preun fluent-bit.service

%postun
%systemd_postun_with_restart fluent-bit.service

%changelog
* Mon Jul 06 2026 - 4.2.6-2
- Fix config path: use /etc/fluent-bit matching service file

* Mon Jul 06 2026 - 4.2.6-1
- Initial loongarch64 native build
EOF
```

> **SPEC 关键点说明：**
> 1. `%pretrans`：处理旧版本升级场景，旧版本中 `/usr/local/etc/fluent-bit` 为普通目录，新版本需替换为符号链接，需提前清理
> 2. `%install`：使用 cmake 构建目录中的 `make install` 安装到 buildroot，并手动将配置文件从 `/usr/local/etc/fluent-bit` 移至 `/etc/fluent-bit`，原路径创建符号链接
> 3. `%config(noreplace)`：配置文件标记为不可替换，rpm 升级时不会覆盖用户已修改的配置
> 4. `%post/%preun/%postun`：systemd 服务启停和重载

### 构建 RPM

```
[root@master2 ~]# rpmbuild -bb --target loongarch64 /root/rpmbuild/SPECS/fluent-bit.spec
```

### 构建产物

```
[root@master2 ~]# ls -lh /root/rpmbuild/RPMS/loongarch64/fluent-bit-4.2.6-2.ky11.loongarch64.rpm
-rw-r--r-- 1 root root 8.1M  7月 6日 15:18 fluent-bit-4.2.6-2.ky11.loongarch64.rpm

[root@master2 ~]# rpm -qpi /root/rpmbuild/RPMS/loongarch64/fluent-bit-4.2.6-2.ky11.loongarch64.rpm
Name        : fluent-bit
Version     : 4.2.6
Release     : 2.ky11
Architecture: loongarch64
Size        : 61879863
License     : Apache-2.0
URL         : https://fluentbit.io
Summary     : Fast data forwarder for Linux, BSD, OSX and Windows
```

### RPM 安装后文件结构

```
[root@master2 ~]# rpm -qpl fluent-bit-4.2.6-2.ky11.loongarch64.rpm
/etc/fluent-bit/
├── fluent-bit.conf          ← 主配置（noreplace，升级不覆盖）
├── parsers.conf
└── plugins.conf
/usr/local/bin/fluent-bit    ← 主程序
/usr/local/etc/fluent-bit → /etc/fluent-bit   ← 符号链接
/usr/local/lib64/fluent-bit/libfluent-bit.so  ← 共享库
/usr/local/include/fluent-bit/                ← 开发头文件
/usr/lib/systemd/system/fluent-bit.service    ← systemd 服务
```

## Docker 镜像制作

上述 RPM 包适合宿主机直接安装。若要在 Kubernetes 中以容器方式运行，需制作 Docker 镜像。

### 编写 Dockerfile

本镜像以 lcr.loongnix.cn/debian:latest 为基础，安装运行时依赖后拷贝编译产物。

```
[root@master2 ~]# mkdir -p /root/fluent-bit-image
[root@master2 ~]# cat > /root/fluent-bit-image/Dockerfile << 'EOF'
# Fluent Bit v4.2.6 loongarch64
FROM lcr.loongnix.cn/debian:latest

LABEL Description="Fluent Bit v4.2.6 for loongarch64"
LABEL Vendor="Fluent Organization"
LABEL Version="4.2.6"
LABEL maintainer="built from source, loongarch64 native"

# Debian 基础镜像已预装：libssl3t64, libsystemd0, liblz4-1, liblzma5, libzstd1, zlib1g
# 以下为额外需要的运行时库
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        libyaml-0-2 \
        libgcrypt20 \
        libcap2 \
        libgpg-error0 && \
    rm -rf /var/lib/apt/lists/*

# 编译产物
COPY fluent-bit /usr/local/bin/fluent-bit
COPY libfluent-bit.so /usr/local/lib64/fluent-bit/libfluent-bit.so
COPY fluent-bit.conf /fluent-bit/etc/fluent-bit/fluent-bit.conf
COPY parsers.conf /fluent-bit/etc/fluent-bit/parsers.conf
COPY plugins.conf /fluent-bit/etc/fluent-bit/plugins.conf

# 兼容旧镜像路径
RUN mkdir -p /fluent-bit/bin /etc/fluent-bit && \
    ln -s /usr/local/bin/fluent-bit /fluent-bit/bin/fluent-bit && \
    ln -s /fluent-bit/etc/fluent-bit /etc/fluent-bit

EXPOSE 2020

ENV PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

ENTRYPOINT ["/usr/local/bin/fluent-bit"]
CMD ["-c", "/fluent-bit/etc/fluent-bit/fluent-bit.conf"]
EOF
```

> **Dockerfile 关键点说明：**
> 1. 基础镜像 `lcr.loongnix.cn/debian:latest` 为 Debian forky/sid 的 loongarch64 版本
> 2. 基础镜像已预装 `libssl3t64`、`libsystemd0`、`liblz4-1`、`liblzma5` 等核心库，仅需补齐 4 个额外依赖
> 3. `/fluent-bit/` 目录及符号链接保留了与官方 1.8.11 镜像的路径兼容，方便迁移
> 4. ENTRYPOINT 设置为 fluent-bit 二进制，CMD 提供默认配置文件路径，便于 `docker run` 时覆盖参数
> 5. EXPOSE 2020 为 Fluent Bit 内建 HTTP 监控端口

### 准备构建上下文

```
[root@master2 ~]# cd /root/fluent-bit-image
[root@master2 fluent-bit-image]# cp /usr/local/bin/fluent-bit ./fluent-bit
[root@master2 fluent-bit-image]# cp /usr/local/lib64/fluent-bit/libfluent-bit.so ./libfluent-bit.so
[root@master2 fluent-bit-image]# cp /etc/fluent-bit/fluent-bit.conf ./fluent-bit.conf
[root@master2 fluent-bit-image]# cp /etc/fluent-bit/parsers.conf ./parsers.conf
[root@master2 fluent-bit-image]# cp /etc/fluent-bit/plugins.conf ./plugins.conf

# strip 去除调试符号，减小镜像体积
[root@master2 fluent-bit-image]# strip ./fluent-bit ./libfluent-bit.so
[root@master2 fluent-bit-image]# ls -lh
总计 55M
-rw-r--r-- 1 root root 1.3K  7月 6日 15:56 Dockerfile
-rwxr-xr-x 1 root root  27M  7月 6日 15:56 fluent-bit
-rw-r--r-- 1 root root 2.4K  7月 6日 15:56 fluent-bit.conf
-rwxr-xr-x 1 root root  27M  7月 6日 15:56 libfluent-bit.so
-rw-r--r-- 1 root root 6.4K  7月 6日 15:56 parsers.conf
-rw-r--r-- 1 root root   45  7月 6日 15:56 plugins.conf
```

### 构建镜像

```
[root@master2 fluent-bit-image]# docker build --network host -t fluent-bit:4.2.6-loong64 .
```

> **注意**：若 Docker 容器内 DNS 无法解析外网域名，需使用 `--network host` 参数让构建过程使用宿主机网络安装依赖包。

### 验证镜像

```
[root@master2 ~]# docker images fluent-bit:4.2.6-loong64
REPOSITORY    TAG               IMAGE ID       CREATED         SIZE
fluent-bit    4.2.6-loong64     0835f14fc394   2 minutes ago   199MB

[root@master2 ~]# docker run --rm fluent-bit:4.2.6-loong64 --version
Fluent Bit v4.2.6

[root@master2 ~]# docker run --rm fluent-bit:4.2.6-loong64 -i dummy -o stdout -f 1
[0] dummy.0: [[1783325285.507510844, {}], {"message"=>"dummy"}]
[0] dummy.0: [[1783325286.506940346, {}], {"message"=>"dummy"}]
```

### 导出与分发

```
[root@master2 ~]# docker save fluent-bit:4.2.6-loong64 -o fluent-bit-4.2.6-loong64.tar
[root@master2 ~]# ls -lh fluent-bit-4.2.6-loong64.tar
-rw------- 1 root root 194M  7月 6日 16:08 fluent-bit-4.2.6-loong64.tar
```

在其他节点加载镜像：

```
[root@node ~]# docker load -i fluent-bit-4.2.6-loong64.tar
Loaded image: fluent-bit:4.2.6-loong64
```

### 与旧版本镜像对比

| 对比项 | 1.8.11（官方旧镜像） | 4.2.6（本次制作） |
|---|---|---|
| 版本 | 1.8.11 (2021) | 4.2.6 (2025) |
| 镜像大小 | 180MB | 199MB |
| 基础镜像 | Debian sid | Debian sid |
| libyaml 支持 | 未链接，无法解析 YAML 配置 | 已链接 |
| libssl 支持 | 未链接，无法 TLS 加密传输 | 已链接 |
| libsystemd 支持 | 未链接，无法采集 journald | 已链接 |
| 路径兼容 | `/fluent-bit/` | 标准路径 + `/fluent-bit/` 符号链接 |
| ENTRYPOINT | 无 | 有，支持命令行覆盖 |
| 开发头文件 | 包含（冗余） | 无，纯运行时镜像 |
| systemd 服务 | 无 | RPM 包提供 |

> **升级建议**：旧镜像缺少 yaml/ssl/systemd 依赖，实际上很多插件不可用。新镜像 v4.2.6 补齐了所有运行时依赖，DaemonSet 中将 `image: lcr.loongnix.cn/library/fluent-bit:1.8.11` 替换为 `image: fluent-bit:4.2.6-loong64` 即可完成升级。

## 使用方式

### 安装 RPM

```
[root@master2 ~]# rpm -ivh fluent-bit-4.2.6-2.ky11.loongarch64.rpm
[root@master2 ~]# systemctl enable fluent-bit --now
[root@master2 ~]# systemctl status fluent-bit
● fluent-bit.service - Fluent Bit
     Loaded: loaded (/usr/lib/systemd/system/fluent-bit.service; enabled; preset: disabled)
     Active: active (running) since Mon 2026-07-06 15:19:01 CST; 2s ago
   Main PID: 162918 (fluent-bit)
```

### 命令行基本用法

采集 CPU 指标并输出到标准输出：

```
[root@master2 ~]# fluent-bit -i cpu -o stdout -f 5
```

tail 文件并输出到标准输出：

```
[root@master2 ~]# fluent-bit -i tail -p path=/var/log/messages -o stdout
```

查看帮助：

```
[root@master2 ~]# fluent-bit --help
Usage: fluent-bit [OPTION]

  -c  --config=FILE     指定配置文件
  -i, --input=INPUT     设置输入插件
  -o, --output=OUTPUT   设置输出插件
  -f, --flush=SECONDS   刷新间隔（秒，默认: 1）
  -F, --filter=FILTER   设置过滤器
  -m, --match=MATCH     设置插件匹配规则
  -p, --prop="A=B"      设置插件配置属性
  -v, --verbose         增加日志详细程度
  -H, --http            启用 HTTP 监控服务（默认端口 2020）
```

### 配置文件方式

Fluent Bit 支持经典 INI 格式和 YAML 格式两种配置文件。

**经典格式** `/etc/fluent-bit/fluent-bit.conf`：

```
[SERVICE]
    flush        5
    daemon       off
    log_level    info
    parsers_file /etc/fluent-bit/parsers.conf

[INPUT]
    name         cpu
    tag          my_cpu

[OUTPUT]
    name         stdout
    match        my_cpu
```

**YAML 格式**（v4.2+）：

```yaml
service:
  flush: 5
  log_level: info

pipeline:
  inputs:
    - name: cpu
      tag: my_cpu

  outputs:
    - name: stdout
      match: my_cpu
```

### Kubernetes DaemonSet 部署

Fluent Bit 在 K8s 中最常用的部署方式为 DaemonSet，每个节点运行一个 Pod 采集该节点所有容器的日志。

```
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit
  namespace: kube-system
  labels:
    k8s-app: fluent-bit-logging
spec:
  selector:
    matchLabels:
      name: fluent-bit
  template:
    metadata:
      labels:
        name: fluent-bit
    spec:
      tolerations:
      - key: node-role.kubernetes.io/master
        operator: Exists
        effect: NoSchedule
      containers:
      - name: fluent-bit
        image: fluent-bit:4.2.6-loong64
        volumeMounts:
        - name: varlog
          mountPath: /var/log
          readOnly: true
        - name: varlibdockercontainers
          mountPath: /var/lib/docker/containers
          readOnly: true
        - name: config
          mountPath: /fluent-bit/etc/
      terminationGracePeriodSeconds: 10
      volumes:
      - name: varlog
        hostPath:
          path: /var/log
      - name: varlibdockercontainers
        hostPath:
          path: /var/lib/docker/containers
      - name: config
        configMap:
          name: fluent-bit-config
```

> **挂载说明：**
> 1. `/var/log`：宿主机系统日志目录，包含 `/var/log/containers/` 等容器 stdout/stderr 日志
> 2. `/var/lib/docker/containers`：Docker 容器日志的 JSON 文件所在路径，Containerd 环境对应 `/var/log/pods`
> 3. ConfigMap `fluent-bit-config`：包含 fluent-bit.conf 配置文件

### Fluent Bit + Elasticsearch + Kibana 方案

Fluent Bit 可以替代 Logstash，以更低的资源消耗将日志直接推送到 Elasticsearch：

**fluent-bit.conf 配置示例：**

```
[SERVICE]
    flush        5
    daemon       off
    log_level    info
    parsers_file /fluent-bit/etc/parsers.conf

[INPUT]
    name             tail
    path             /var/log/containers/*.log
    parser           docker
    tag              kube.*
    mem_buf_limit    5MB
    skip_long_lines  on
    refresh_interval 10

[FILTER]
    name                kubernetes
    match               kube.*
    kube_url            https://kubernetes.default.svc:443
    kube_ca_file        /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
    kube_token_file     /var/run/secrets/kubernetes.io/serviceaccount/token
    merge_log           on
    keep_log            off

[OUTPUT]
    name            es
    match           *
    host            elasticsearch
    port            9200
    index           fluent-bit-%Y.%m.%d
    type            _doc
```

> **与 ELK 传统架构对比：**
> 1. Logstash 基于 JVM，内存占用大（通常 > 1GB），DaemonSet 部署在每个节点上对资源压力较大
> 2. Fluent Bit 基于 C 语言，内存占用 ~1MB，适合在节点级以 DaemonSet 方式部署
> 3. Fluent Bit 内置 Kubernetes Filter 插件，无需额外配置即可自动注入 Pod 元数据
> 4. 替代方案为 `Fluent Bit → Elasticsearch → Kibana`，省去 Logstash 层，降低资源消耗

### Fluent Bit + Loki + Grafana 方案

若不需要全文检索，也可对接 Loki 实现轻量日志存储：

```
[OUTPUT]
    name            loki
    match           *
    host            loki
    port            3100
    labels          job=fluentbit, namespace=$kubernetes['namespace_name']
    auto_kubernetes_labels  on
```

对应的技术栈：`Fluent Bit → Loki → Grafana`，Promtail 角色由 Fluent Bit 替代。

## 验证日志采集

部署后验证 DaemonSet 运行状态：

```
[root@master2 ~]# kubectl get daemonset -n kube-system fluent-bit
NAME         DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
fluent-bit   3         3         3       3            3           <none>          5m

[root@master2 ~]# kubectl get pod -n kube-system -l name=fluent-bit
NAME               READY   STATUS    RESTARTS   AGE
fluent-bit-abcde   1/1     Running   0          5m
fluent-bit-fghij   1/1     Running   0          5m
fluent-bit-klmno   1/1     Running   0          5m
```

查看 Fluent Bit 自身日志确认采集正常：

```
[root@master2 ~]# kubectl logs -n kube-system fluent-bit-abcde | tail -5
[info] [input:tail:tail.0] inotify_fs_add(): inode=xxx watch_fd=1 name=/var/log/containers/xxx.log
[info] [output:es:es.0] connection #0 to elasticsearch:9200 is established
```