生产环境应优先使用td-agent而非gem install fluentd，因其自带独立ruby运行时、预编译插件、systemd服务模板及受控升级机制，可避免系统ruby污染、插件编译失败与依赖冲突。
处理大规模日志流时，Fluentd 的安装和配置不能只求“能跑”，而要兼顾稳定性、吞吐能力、时间一致性与插件兼容性。生产环境强烈建议使用 td-agent（Treasure Data 官方发行版），它自带独立 Ruby 运行时、预编译插件、systemd 服务模板和受控升级机制，避免污染系统 Ruby 环境或因插件编译失败导致服务中断。
选对安装方式：按场景匹配部署形态
不同环境适用不同安装路径：
-
物理机/虚拟机（统信UOS、CentOS 7/8、Ubuntu 20.04+）：用 td-agent 官方脚本一键安装。例如 UOS 或 Ubuntu 20.04（Focal）执行：
curl -fsSL https://toolbelt.treasuredata.com/sh/install-ubuntu-focal-td-agent4.sh | sh
安装后服务名为td-agent，配置文件固定为/etc/td-agent/td-agent.conf，日志输出至/var/log/td-agent/td-agent.log。 -
容器化环境（Kubernetes / CI/CD）：用 Docker 官方镜像快速启动，避免宿主机依赖冲突：
docker run -d --name fluentd -v $(pwd)/fluent.conf:/fluentd/etc/fluent.conf -p 24224:24224 fluent/fluentd:v1.16.3-1.0 -
开发调试或需定制插件版本：仅限 Ruby 2.7+ 环境下用 gem 安装，但必须配合 RVM 管理 Ruby 版本，并通过
fluentd --setup ~/.fluentd初始化配置目录；注意该方式不注册 systemd 服务，需自行编写 unit 文件或使用 supervisord 托管。
关键配置项：支撑高并发日志流的核心设置
默认配置无法应对大规模日志，以下几处必须显式调优：
-
输入端启用 TCP + 显式 bind：Syslog 插件默认仅监听 UDP 514 且绑定 127.0.0.1，极易丢包且不可控。正确写法：
<source><br> @type syslog<br> port 514<br> bind 0.0.0.0<br> protocol_type tcp<br></source>
-
缓冲区必须持久化：内存缓冲在崩溃时丢失数据。推荐使用 file 类型缓冲，并指定 path 和 chunk_limit_size：
<buffer time><br> @type file<br> path /var/log/td-agent/buffer/app.*.buffer<br> chunk_limit_size 2M<br> flush_interval 3s<br></buffer>
-
标签（Tag）设计要具备路由语义：例如
app.prod.nginx.access比nginx更利于后续 match 规则分流，也方便在 Elasticsearch 中按 index pattern 自动创建索引。 -
时间戳校准前置：所有节点必须启用 NTP 同步（
timedatectl set-ntp yes），并在 input 插件中强制解析时间字段，避免日志乱序或延迟堆积。
插件管理与扩展：避免常见加载失败
td-agent 环境下，所有插件必须用 td-agent-gem 安装，而非系统 ruby 的 gem：
- 安装 Elasticsearch 输出插件：
sudo td-agent-gem install fluent-plugin-elasticsearch - 安装 Kafka 输出插件（适合中间缓冲）：
sudo td-agent-gem install fluent-plugin-kafka - 验证插件是否生效：
sudo td-agent-gem list | grep elasticsearch
切勿混用 gem install 和 td-agent-gem install，否则插件不会被 td-agent 加载，服务启动无报错但日志无法写出。
验证与可观测性：确认真正可用
安装完成后，不能只看 systemctl status td-agent 是否 active，还需实测链路：
- 发送测试事件：
echo '{"message":"test","level":"info"}' | curl -X POST -d @- http://localhost:8080/app.test - 检查 td-agent 日志是否有解析错误或 buffer full 告警：
sudo tail -f /var/log/td-agent/td-agent.log - 确认输出目标（如文件、Elasticsearch）已收到结构化 JSON 事件，且
time字段为 ISO8601 格式、非本地时区错乱值。
