Telegraf 安装部署指南

‍‍‌> 目标：在 Ubuntu 22.04 LTS 服务器上从零完成 Telegraf 1.40.2 的安装与 systemd 托管，覆盖 apt 在线仓库、deb 离线包、tar.gz 二进制、Docker 镜像四种方案的完整安装、验证、升级与卸载；全部命令与回显均在 Ubuntu 22.04 LTS（x86_64）实测照抄，安装方式（在线/离线/镜像）各成一章，读者按需选读其一即可。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），实查 /etc/os-release：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

软件版本：Telegraf 1.40.2（2026-10-18 官方最新稳定版，apt 仓库内包名 telegraf 1.40.2-1）
版本回显（telegraf --version，实测）：

Telegraf 1.40.2 (git: HEAD@2e0a2ed1)

实测环境说明：一台 Ubuntu 22.04.5 主机 srv-ubuntu-2204（systemd 托管线，systemctl/journalctl 均可用）承担方案 A/B/C 实测；另一台无 systemd 的最小 Ubuntu 22.04 环境 cfg-ubuntu-2204 用于验证无 systemd 分支行为；Docker 镜像部署实测于宿主 Docker 29.8.1。
包安装涉及的关键路径：

/etc/telegraf/telegraf.conf          # 主配置文件
/etc/telegraf/telegraf.d/            # 额外配置目录（*.conf 自动并入）
/etc/default/telegraf                # 服务环境变量文件（TELEGRAF_OPTS）
/usr/bin/telegraf                    # 主程序
/usr/lib/telegraf/scripts/           # init.sh 与 systemd 单元模板
/var/lib/telegraf/                   # 运行状态目录
/var/log/telegraf/                   # 日志目录（logfile 模式）
/etc/logrotate.d/telegraf            # 日志轮转配置

二、前置条件

64 位 Linux（amd64/arm64/armel/i386 等官方均有包），具备 root 或 sudo 权限；
在线安装需可访问 repos.influxdata.com（apt 源）与 dl.influxdata.com（包下载）；内网环境走第五、六章离线方案；
系统需有 init：systemd 或 SysV 均可（官方 postinst 自动识别，见 4.3 节）；
端口规划：Telegraf 以 agent 方式运行时默认不监听任何端口，仅当启用服务型 input（如 statsd :8125、socket_listener、http_listener_v2 :8086）或输出端 exporter（如 prometheus_client :9273）时才占用端口；
磁盘与内存：静态二进制约 85MB 安装体积，常驻内存约 30MB（实测 systemctl status 回显 Memory: 28.8M）。

三、版本选型说明

官方发布渠道（据官方 INSTALL_GUIDE.md，2026-10-18 查询）：

渠道	形态	适用	版本节奏
InfluxData apt/yum 仓库	deb/rpm	常规服务器，推荐	每个正式版本即时入库
GitHub Releases / 下载页	deb/rpm/tar.gz 二进制	内网离线、无 root 也能解包	与仓库同步
Docker 官方镜像 `telegraf`	Debian 基底（`telegraf:alpine` 为 Alpine）	容器化交付	与仓库同步
Homebrew	brew formula	macOS	社区构建（CGO，与官方二进制略有差异）
Nightly	master 每日构建	测试新特性	非稳定，勿上生产

apt 仓库中的版本视图（实测 apt-cache policy telegraf，输出节选）：

telegraf:
  Installed: 1.40.2-1
  Candidate: 1.40.2-1
  Version table:
 *** 1.40.2-1 500
        500 https://repos.influxdata.com/debian stable/main amd64 Packages
        100 /var/lib/dpkg/status
     1.40.1-1 500

解读：stable/main 保留近期多个小版本（可见 1.40.2-1 与 1.40.1-1），Candidate 即最新稳定版；生产机安装时锁定到具体 x.y.z-1 版本可避免月度自动升级带来的行为变化（如 v1.40.0 起 processor 在 aggregator 之后的默认执行顺序变更，见第十一章 Q4）。

四、方案 A：apt 在线仓库安装（systemd 托管，推荐）

4.1 配置官方 GPG 密钥

本方案将 InfluxData 官方 apt 仓库加入系统源。第一步下载官方 GPG 公钥并用官方公布的指纹校验，防止供应链篡改（官方指纹：24C9 75CB A61A 024E E1B6 3178 7C3D 5715 9FC2 F927）：

# 下载官方 key（注意域名是 repos.influxdata.com）
curl -sSL https://repos.influxdata.com/influxdata-archive.key -o influxdata-archive.key

实测回显（文件 6198 字节）：

-rw-r--r-- 1 root root 6198 Oct 18 03:20 influxdata-archive.key

指纹校验并安装到 apt 信任库（官方命令，校验通过才执行 dearmor）：

gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | \
  grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && \
  cat influxdata-archive.key | gpg --dearmor | \
  tee /etc/apt/trusted.gpg.d/influxdata-archive.gpg > /dev/null

实测回显（产物 4516 字节）：

-rw-r--r-- 1 root root 4516 Oct 18 03:20 /etc/apt/trusted.gpg.d/influxdata-archive.gpg

⚠️ 排障实录（2026-10-18 实测）：若沿用旧文档的 https://download.influxdata.com/influxdb/releases/influxdata-archive_compat.key 地址，现返回 307 重定向到 dl.influxdata.com，直连时落地为 0 字节文件；跟随重定向后又落到 Cloudflare 挑战页（<!doctype html>），随后 gpg --dearmor 报 gpg: no valid OpenPGP data found.。结论：必须使用官方 INSTALL_GUIDE 当前的 repos.influxdata.com/influxdata-archive.key 地址并做指纹校验。

4.2 配置 apt 源并安装

# 写入官方源定义
echo 'deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' | tee /etc/apt/sources.list.d/influxdata.list
# 刷新索引并安装
apt-get update && apt-get install -y telegraf

实测回显（apt-get update 相关行）：

Get:4 https://repos.influxdata.com/debian stable InRelease [6922 B]
Hit:5 http://archive.ubuntu.com/ubuntu jammy-backports InRelease
Fetched 6922 B in 1s (5383 B/s)
Reading package lists...

实测回显（apt-get install 输出节选）：

Selecting previously unselected package influxdata-archive-keyring.
Preparing to unpack .../influxdata-archive-keyring_2026.01.09_all.deb ...
Unpacking influxdata-archive-keyring (2026.01.09) ...
Selecting previously unselected package telegraf.
Preparing to unpack .../telegraf_1.40.2-1_amd64.deb ...
Unpacking telegraf (1.40.2-1) ...
Setting up telegraf (1.40.2-1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/telegraf.service → /lib/systemd/system/telegraf.service.
Setting up influxdata-archive-keyring (2026.01.09) ...

说明：apt 仓库同时安装了 influxdata-archive-keyring 包（2026.01.09），它是官方仓库签名密钥的常驻包，后续密钥轮换由它随包更新，无需再手动维护 trusted.gpg.d 下的 keyring 文件。

4.3 包安装行为说明（systemd 单元如何来的）

官方 deb 包内并未直接打包 /lib/systemd/system/telegraf.service，而是把单元模板放在 /usr/lib/telegraf/scripts/，由 postinst 脚本按 init 类型自动落位（实测查看 /var/lib/dpkg/info/telegraf.postinst 关键逻辑）：

if [ -d /run/systemd/system ]; then
    install_systemd /lib/systemd/system/telegraf.service   # 复制单元并 enable + daemon-reload
    deb-systemd-invoke try-restart telegraf.service >/dev/null || true
else
     install_init                                          # SysV：安装 /etc/init.d/telegraf
     ...
fi

单元模板 telegraf.service（556 字节，实测照录）：

[Unit]
Description=Telegraf
Documentation=https://github.com/influxdata/telegraf
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
NotifyAccess=all
EnvironmentFile=-/etc/default/telegraf
User=telegraf
ImportCredential=telegraf.*
ExecStart=/usr/bin/telegraf -config /etc/telegraf/telegraf.conf -config-directory /etc/telegraf/telegraf.d $TELEGRAF_OPTS
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartForceExitStatus=SIGPIPE
KillMode=mixed
LimitMEMLOCK=8M:8M
PrivateMounts=true

[Install]
WantedBy=multi-user.target

要点：服务以非 root 的 telegraf 用户（uid/gid 999）运行；EnvironmentFile=-/etc/default/telegraf 前置 - 表示文件缺失不报错；ExecStart 同时加载主配置与 telegraf.d 目录；崩溃后由 Restart=on-failure 自动拉起。

4.4 启动与验证

安装时若由包管理器自动拉起失败（或想手动控制），执行：

systemctl start telegraf     # 启动
systemctl enable telegraf    # 开机自启

实测回显：

active
enabled

服务状态（systemctl status telegraf --no-pager，实测节选）：

● telegraf.service - Telegraf
     Loaded: loaded (/lib/systemd/system/telegraf.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-18 03:21:32 UTC
   Main PID: 5192 (telegraf)
      Tasks: 13 (limit: 5753)
     Memory: 28.8M
        CPU: 60ms
     CGroup: /system.slice/.../system.slice/telegraf.service
             └─5192 /usr/bin/telegraf -config /etc/telegraf/telegraf.conf -config-directory /etc/telegraf/telegraf.d

启动日志与配置加载记录（journalctl -u telegraf，实测节选）：

Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z W! Strict environment variable handling is the new default starting with v1.38.0! If your configuration does not work with strict handling please explicitly add the --non-strict-env-handling flag to switch to the previous behavior!
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Loading config: /etc/telegraf/telegraf.conf
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Starting Telegraf 1.40.2 brought to you by InfluxData the makers of InfluxDB
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Available plugins: 244 inputs, 9 aggregators, 35 processors, 26 parsers, 68 outputs, 8 secret stores
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Loaded inputs: cpu disk diskio kernel mem processes swap system
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Loaded outputs: file
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! Tags enabled: host=srv-ubuntu-2204
Oct 18 03:21:32 srv-ubuntu-2204 telegraf[5192]: 2026-10-18T03:21:32Z I! [agent] Config: Interval:10s, Quiet:false, Hostname:"srv-ubuntu-2204", Flush Interval:10s

解读：1.40.2 deb 包的默认配置已启用 8 个系统 input（cpu/disk/diskio/kernel/mem/processes/swap/system）与 outputs.file（默认打到标准输出，被 journald 收进 journal），开箱即有指标产出；把 [[outputs.file]] 换成 [[outputs.influxdb_v2]] 即接入时序库（配置详解与实战见《Telegraf 1.40 插件配置详解》《Telegraf 集成实战》）。

指标真实产出验证（journal 中直接可见 Line Protocol 行，实测节选）：

Oct 18 03:21:52 srv-ubuntu-2204 telegraf[5192]: cpu,cpu=cpu0,host=srv-ubuntu-2204 usage_softirq=9.599254426841906,usage_steal=0,usage_guest=0,usage_system=3.8210624417521917,usage_user=6.057781919854033,usage_idle=80.52190121158154 1792293710000000000
Oct 18 03:21:52 srv-ubuntu-2204 telegraf[5192]: cpu,cpu=cpu1,host=srv-ubuntu-2204 usage_user=8.142999006942802,usage_idle=83.91261171788707 1792293710000000000

方案 A 至此闭环：仓库配置 → 安装 → systemd 托管 → 日志确认 → 指标产出，五步均有实测回显。

五、方案 B：deb 离线包安装（内网/断网服务器）

5.1 下载与校验

从官方下载站取与系统架构匹配的 deb 包，校验 sha256 后拷贝到内网服务器（实测下载与校验回显）：

curl -sSL -o telegraf_1.40.2-1_amd64.deb https://dl.influxdata.com/telegraf/releases/telegraf_1.40.2-1_amd64.deb
sha256sum telegraf_1.40.2-1_amd64.deb

实测回显：

-rw-r--r-- 1 root root 85912724 Oct 18 03:22 /opt/data/telegraf/telegraf_1.40.2-1_amd64.deb
08968d96e764819cb7c16649e8e9e13d4f24b641edb9883b06b8daf321c9e877  /opt/data/telegraf/telegraf_1.40.2-1_amd64.deb

💡 说明：dl.influxdata.com/telegraf/releases/ 目录下保留全部历史版本（命名规则 telegraf_<版本>-1_<架构>.deb），离线安装时建议连同 sha256 一起归档保存，升级前先校验再安装。

5.2 dpkg -i 安装（systemd 服务器）

dpkg -i telegraf_1.40.2-1_amd64.deb

实测回显（已在 systemd 环境重演，输出节选）：

(Reading database ... 7388 files and directories currently installed.)
Preparing to unpack .../telegraf_1.40.2-1_amd64.deb ...
Unpacking telegraf (1.40.2-1) over (1.40.2-1) ...
Setting up telegraf (1.40.2-1) ...
/usr/sbin/policy-rc.d returned 101, not running 'try-restart telegraf.service'

安装产物核对（单元文件由 postinst 从 scripts 目录复制，实测）：

-rw-r--r-- 1 root root  556 Oct 18 03:23 /lib/systemd/system/telegraf.service

/usr/lib/telegraf/scripts/:
-rwxr-xr-x 1 root root 6008 Oct 12 14:25 init.sh
-rw-r--r-- 1 root root  556 Oct 12 14:25 telegraf.service

随后与方案 A 相同执行 systemctl start telegraf、systemctl enable telegraf 并按 4.4 验证。首次安装全新服务器时，把 4.1 节的 GPG key 操作省去，其余步骤（启动/验证/配置）与在线安装完全一致。

5.3 无 systemd 环境的回退行为

在无 systemd 的最小 Ubuntu 22.04 环境执行同一 dpkg -i，postinst 自动走 SysV 分支（实测回显节选）：

Unpacking telegraf (1.40.2-1) over (1.40.2-1) ...
Setting up telegraf (1.40.2-1) ...
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of restart.

此时系统内仅有 SysV 脚本 /etc/init.d/telegraf（dpkg -L telegraf | grep -i init 实测回显 /usr/lib/telegraf/scripts/init.sh），可用 service telegraf start 或直接命令行驱动（配置驱动运行方式见《Telegraf 1.40 插件配置详解》）。

六、方案 C：tar.gz 二进制安装（免包管理，多版本共存）

6.1 下载、校验与解压

适用于无 root、需多版本共存或不想引入 apt 源的场景。官方 tar.gz 解包后为 usr/bin/telegraf 等 FHS 目录结构：

curl -sSL -O https://dl.influxdata.com/telegraf/releases/telegraf-1.40.2_linux_amd64.tar.gz
sha256sum telegraf-1.40.2_linux_amd64.tar.gz
mkdir -p /opt/telegraf && tar xzf telegraf-1.40.2_linux_amd64.tar.gz -C /opt/telegraf --strip-components=1

实测回显：

fcdc579a09227fa3e2e3e208d3cf75cfd03d42ae141a4b23b18659a94428bfa3  /opt/data/telegraf/telegraf-1.40.2_linux_amd64.tar.gz
/opt/telegraf/usr/bin/
telegraf

6.2 直跑验证（--once 模式）

先写一份最小配置（CPU+内存采集、结果写文件），用 --once 采集一轮即退出，验证二进制可用：

cat > /opt/telegraf/telegraf-min.conf <<'EOF'
[agent]
  interval = "2s"
  hostname = "tar-ubuntu-2204"

[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[inputs.mem]]

[[outputs.file]]
  files = ["/opt/data/telegraf/once.out"]
EOF
/opt/telegraf/usr/bin/telegraf --config /opt/telegraf/telegraf-min.conf --once

实测回显（启动段）：

2026-10-18T03:23:59Z I! Loading config: /opt/telegraf/telegraf-min.conf
2026-10-18T03:23:59Z I! Starting Telegraf 1.40.2 brought to you by InfluxData the makers of InfluxDB
2026-10-18T03:23:59Z I! Available plugins: 244 inputs, 9 aggregators, 35 processors, 26 parsers, 68 outputs, 8 secret stores
2026-10-18T03:23:59Z I! Loaded inputs: cpu mem
2026-10-18T03:23:59Z I! Loaded outputs: file
2026-10-18T03:23:59Z I! Tags enabled: host=tar-ubuntu-2204
2026-10-18T03:24:07Z I! [agent] Hang on, flushing any cached metrics before shutdown
2026-10-18T03:24:07Z I! [agent] Stopping running outputs

输出文件实测（cat /opt/data/telegraf/once.out，节选）：

mem,host=tar-ubuntu-2204 used=23395913728i,available_percent=30.384444239418134,total=33607307264i,used_percent=69.61555576058187 1792293847000000000
cpu,cpu=cpu-total,host=tar-ubuntu-2204 usage_irq=0,usage_user=5.723905724023266,usage_idle=90.23569023826379 1792293847000000000

6.3 手写 systemd 单元托管

tar.gz 安装不自动注册服务，需手写单元（推荐以 telegraf 用户运行；deb 安装已自动创建该用户，纯 tar 环境需 useradd -r -s /usr/sbin/nologin telegraf 手动创建）：

# /etc/systemd/system/telegraf-tar.service
[Unit]
Description=Telegraf (tar.gz standalone)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=telegraf
ExecStart=/opt/telegraf/usr/bin/telegraf --config /opt/telegraf/telegraf-min.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable telegraf-tar.service
systemctl start telegraf-tar.service
systemctl is-active telegraf-tar.service

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/telegraf-tar.service → /etc/systemd/system/telegraf-tar.service.
active

6.4 排障实录：非 root 运行时输出文件权限

首次启动后 journal 报错（实测照录）：

E! [agent] Failed to connect to [outputs.file], retrying in 15s, error was "open /opt/data/telegraf/once.out: permission denied"

定位：once.out 由 root 创建（644），而单元以 User=telegraf 运行，无写权限。解决：把输出文件/目录属主交给 telegraf 用户后重启：

chown telegraf:telegraf /opt/data/telegraf/once.out
systemctl restart telegraf-tar.service

复验（实测）：systemctl is-active 回显 active，journal 中 20 秒内 permission denied 计数为 0，输出文件持续追加新指标行。生产上更推荐把输出指向 /var/log/telegraf/（该目录属主即 telegraf）。

七、方案 D：Docker 镜像部署（容器方式对照）

7.1 镜像选型

官方 telegraf 镜像是 Docker Official Image（自动跟进安全更新），基于 Debian；另有 telegraf:alpine 精简基底。实测拉取：

docker pull telegraf:1.40.2

实测回显（节选）：

Digest: sha256:aedc74ac64c623b6e6760545a8ff56a63b99a798bba3d361279a2887642798cf
Status: Downloaded newer image for telegraf:1.40.2
docker.io/library/telegraf:1.40.2

7.2 配置文件准备

与包安装不同，容器方式必须自带配置（镜像内无默认可用配置），先在宿主机准备一份（本例演示 CPU/内存采集 + Docker 引擎指标，指标打印到标准输出）：

[agent]
  interval = "5s"
  hostname = "docker-host-2204"

[[inputs.cpu]]
  percpu = false
  totalcpu = true

[[inputs.mem]]

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"

[[outputs.file]]
  files = ["stdout"]

7.3 运行与验证

docker run -d --name telegraf-1.40-docker-config \
  -v /opt/data/telegraf/telegraf-docker.conf:/etc/telegraf/telegraf.conf:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  telegraf:1.40.2

启动后查看日志确认配置加载与指标产出（docker logs 实测节选）：

2026-10-18T03:25:47Z I! Loading config: /etc/telegraf/telegraf.conf
2026-10-18T03:25:47Z I! Starting Telegraf 1.40.2 brought to you by InfluxData the makers of InfluxDB
2026-10-18T03:25:47Z I! Available plugins: 244 inputs, 9 aggregators, 35 processors, 26 parsers, 68 outputs, 8 secret stores
2026-10-18T03:25:47Z I! Loaded inputs: cpu docker mem
2026-10-18T03:25:47Z I! Loaded outputs: file
2026-10-18T03:25:47Z I! Tags enabled: host=docker-host-2204
2026-10-18T03:25:47Z I! [agent] Config: Interval:5s, Quiet:false, Hostname:"docker-host-2204", Flush Interval:10s

指标真实产出（日志内 Line Protocol 行，实测节选——注意 docker 引擎与逐容器状态指标均已采到）：

mem,host=docker-host-2204 used=23300308992i,available_percent=30.668920276873273,total=33607307264i 1792293950000000000
docker,engine_host=ops,host=docker-host-2204,server_version=29.8.1 n_cpus=12i,n_containers=61i,n_containers_running=60i,n_images=314i 1792293950000000000
docker_container_status,container_image=dind-ubuntu2204-systemd,container_name=nezha-v2.3.18-dashboard,container_status=running,engine_host=ops,host=docker-host-2204,server_version=29.8.1 uptime_ns=27946114961064i 1792293950000000000

⚠️ 注意：docker.sock 挂载进容器等价于授予该容器 root 级 Docker 管理权限，生产环境应限定可信网络域并考虑用 TCP+TLS 或 proxy 管道收敛权限面。

7.4 方案 D 补充说明

升级：更换镜像 tag（如 telegraf:1.40.3）重建容器即可，配置文件在宿主机不变；
多实例：不同配置文件 + 不同 --name 即可并存，注意服务型 input 的端口不要冲突（-p 8125:8125/udp 等）；
入口参数：镜像 ENTRYPOINT 为 /entrypoint.sh，CMD 为 telegraf，需要追加参数时在 docker run 镜像名后直接写（如 ... telegraf --once）。

八、方案对比与选择建议

维度	A：apt 仓库	B：deb 离线包	C：tar.gz 二进制	D：Docker 镜像
是否需联网	是（repos.influxdata.com）	否（拷包即装）	否（拷包即装）	首次拉镜像需联网
安装方式	apt-get	dpkg -i	tar 解包	docker run
systemd 托管	自动注册	自动注册	手写单元	无（容器生命周期）
自动升级	随 apt upgrade	手动换包	手动换目录	手动换 tag
多版本共存	弱（同版本号覆盖）	弱	强（/opt/telegraf-<版本>）	强（多 tag 并存）
运行身份	telegraf 用户	telegraf 用户	自定（推荐 telegraf 用户）	镜像内置用户
适用场景	常规服务器首选	内网/断网服务器	无 root、灰度共存	容器化环境/临时采集

选择建议：可联网的服务器一律选 A（升级、依赖、卸载都由 apt 托管）；内网服务器选 B；需要多版本并存的灰度环境选 C；已全面容器化的交付链路选 D。四方案共享同一套配置文件体系与插件体系（见第九章与《Telegraf 1.40 插件配置详解》），迁移无成本。

九、服务配置说明（各方案共用）

9.1 配置文件体系

/etc/telegraf/telegraf.conf：主配置。1.40.2 deb 附带的默认文件为全量样例（实测 605229 字节），含全部 390 个插件的注释模板与参数说明，未注释生效的插件为 cpu/disk/diskio/kernel/mem/processes/swap/system 与 outputs.file；
/etc/telegraf/telegraf.d/：分片配置目录，服务以 --config-directory 并入加载，建议把各 input 拆成独立文件（如 docker.conf、mysql.conf）便于管理；
配置校验与调试：telegraf --config <文件> --test 单轮采集打印到终端、--once 采集一轮退出、--config-directory 指定分片目录，均见《Telegraf 1.40 插件配置详解》。

9.2 /etc/default/telegraf 与启动参数

systemd 单元通过 EnvironmentFile=-/etc/default/telegraf 加载环境变量，$TELEGRAF_OPTS 会拼接到 ExecStart。实测该文件默认为空文件（cat /etc/default/telegraf 无输出）。常用注入示例（改完 systemctl daemon-reload && systemctl restart telegraf）：

# /etc/default/telegraf 示例：追加命令行参数与调试开关
TELEGRAF_OPTS="--debug"

9.3 日志与轮转

默认日志走标准输出（journald 收集，journalctl -u telegraf 查看）；配置 [agent] logfile = "/var/log/telegraf/telegraf.log" 后落盘，deb 包已自带轮转配置 /etc/logrotate.d/telegraf（实测照录）：

/var/log/telegraf/telegraf.log
{
    rotate 6
    daily
    missingok
    dateext
    copytruncate
    notifempty
    compress
}

9.4 运行身份与目录

uid=999(telegraf) gid=999(telegraf) groups=999(telegraf)
drwxrwx--- 2 root     telegraf 4096 /var/lib/telegraf
drwxr-xr-x 2 telegraf telegraf 4096 /var/log/telegraf

以 telegraf 用户运行意味着：采集 Docker 需把 telegraf 加入 docker 组、采集部分系统文件需加 CAP 或改用 root 运行（改法：单元内 User=root 后 daemon-reload + restart）。

十、升级、降级与多版本

升级（apt）：apt-get update && apt-get install -y telegraf，仓库内 Candidate 即最新（实测见第三章 policy 输出，1.40.1-1 → 1.40.2-1 即走此路径）；升级仅替换二进制与默认样例，/etc/telegraf/telegraf.conf 不会被覆盖；
锁定版本：apt-mark hold telegraf，解除 apt-mark unhold telegraf；
降级：apt-get install -y telegraf=1.40.1-1（允许降级）或 apt-get install -y --allow-downgrades telegraf=1.39.3-1；
tar 方案多版本：解包到 /opt/telegraf-1.40.2/、/opt/telegraf-1.39.3/ 各自独立，systemd 单元里 ExecStart 指向对应目录即可灰度切换；
Docker 方案：换镜像 tag 重建容器，配置不变。

十一、常见问题（FAQ）

Q1：apt update 报 NO_PUBKEY DA61C26A0585BD3B 怎么处理？ 实测现象：源已写入但 GPG key 未就绪时，apt-get update 报：

W: GPG error: https://repos.influxdata.com/debian stable InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY DA61C26A0585BD3B

处理：按 4.1 节重新下载 repos.influxdata.com/influxdata-archive.key 并完成指纹校验与 dearmor，再 apt-get update 即恢复正常（实测复现并解决）。

Q2：下载 key 后 gpg: no valid OpenPGP data found？ 下载到的不是 key 而是 Cloudflare 挑战页 HTML（head 可见 <!doctype html>）。原因与处理见 4.1 节排障实录：改用 repos.influxdata.com 域名下载。

Q3：apt purge 之后进程还在跑？ 实测：apt-get purge -y telegraf 回显 Removing telegraf (1.40.2-1) ... 与 Purging configuration files for telegraf (1.40.2-1) ...，/usr/bin/telegraf 已不存在，但此时 systemctl is-active telegraf 仍回显 active（进程持有已删除的二进制继续运行）。规范做法：卸载前先 systemctl stop telegraf，再 purge；必要时 systemctl daemon-reload 清理残留单元引用。

Q4：启动日志里的两条 W! 警告要处理吗？ Strict environment variable handling ... v1.38.0：v1.38 起配置内 ${VAR} 采用严格解析（未定义变量直接报错），若沿用旧配置可临时加 --non-strict-env-handling；skip_processors_after_aggregators will change ... v1.40.0：v1.40 起 processor 默认不在 aggregator 之后重复执行，依赖旧行为的显式置 false 即可。两条均为前瞻性提示，当前版本不影响默认配置运行（实测默认配置正常采集）。

Q5：journal 里 Unknown key name 'ImportCredential' in section 'Service' 报警？ systemd 版本低于 254（Ubuntu 22.04 为 249）不认识 ImportCredential 指令，systemd 直接忽略该键，服务功能不受影响，无需处理（实测忽略后服务长期 active）。

Q6：inputs.diskio 刷 Unable to gather disk name for "loop6" 警告？ 实测现象（journal 照录）：W! [inputs.diskio] Unable to gather disk name for "loop6": error reading /dev/.udev/db/block:loop6: stat /dev/.udev/db/block:loop6: no such file or directory。在无 udev 数据库的环境（部分精简系统/虚拟机）出现，仅影响「块设备名映射」展示，指标本身正常产出；介意的话在配置中用 name_exclude = "loop*" 排除回环设备。

Q7：deb 装完服务没自动启动？ 若系统存在 /usr/sbin/policy-rc.d 且返回 101（常见于自动化环境），包管理器会跳过 try-restart（实测回显 /usr/sbin/policy-rc.d returned 101, not running 'try-restart telegraf.service'），手动 systemctl start telegraf 即可。

十二、卸载与清理

apt/deb 方案：systemctl stop telegraf && systemctl disable telegraf && apt-get purge -y telegraf（purge 实测回显见第十一章 Q3），随后可清理数据目录 rm -rf /var/lib/telegraf /var/log/telegraf；
tar 方案：systemctl disable --now telegraf-tar.service && rm -rf /opt/telegraf /etc/systemd/system/telegraf-tar.service && systemctl daemon-reload；
Docker 方案：docker rm -f telegraf-1.40-docker-config && docker rmi telegraf:1.40.2；
重装：离线场景 dpkg -i telegraf_1.40.2-1_amd64.deb 即完整复原（实测：purge 后重装回显 Setting up telegraf (1.40.2-1) ...、Created symlink ... multi-user.target.wants/telegraf.service，telegraf --version 复验 Telegraf 1.40.2 (git: HEAD@2e0a2ed1)，服务回到 active）。

十三、参考链接

官方安装指南：https://github.com/influxdata/telegraf/blob/master/docs/INSTALL_GUIDE.md
官方下载站：https://www.influxdata.com/downloads/
包下载目录：https://dl.influxdata.com/telegraf/releases/
apt 源：https://repos.influxdata.com/debian
Docker 镜像：https://hub.docker.com/_/telegraf
站内系列：《Telegraf 介绍与选型指南》《Telegraf 1.40 插件配置详解》《Telegraf 集成实战》