InfluxDB 与 Telegraf —— TICK 栈的时序存储引擎与采集代理

分类：01 指标采集与时序存储 适用：主机/容器/物联网/应用指标采集与高频写入；单机到中等规模，需 SQL 式或函数式时序查询 一句话：InfluxDB 负责高性能时序存储与查询，Telegraf 以插件化方式采集并处理指标后写入，两者合为 TICK 栈核心 官方：https://docs.influxdata.com/ ｜ https://github.com/influxdata/influxdb ｜ https://github.com/influxdata/telegraf 授权：InfluxDB OSS 与 Telegraf 均为开源（具体 LICENSE 以官方仓库为准），另有企业版与云服务

版本与镜像 tag 以官方最新稳定版为准：官方已提示 Docker latest 会指向 InfluxDB 3 Core，生产必须用具体版本 tag。本文以同时支持 InfluxQL 与 Flux 的 InfluxDB 2.x OSS 为主线。

1. 它解决什么问题

不负责：日志/链路追踪、跨集群全局 PromQL 视图、原生多租户集群（OSS 单机）。

2. 核心概念与架构

数据模型（务必分清 tag 与 field）

line protocol（严格结构）

measurement,tag_key=tag_value,tag2=v2 field_key=field_value,field2=v2 timestamp
# 例：
cpu,host=web01,region=cn usage_idle=57.5,usage_user=42.5 1690000000000000000

规则：measurement 与 tag 用逗号、tag 与 field 用空格分隔；空格/逗号/等号须转义；字符串 field 加双引号，tag 值一律不加；时间戳默认纳秒。

组件与数据流

  Exporter/主机/MQ/DB ──> Telegraf ───────────────┐
   /metrics(Prometheus) ─> inputs.prometheus ────┤
        [agent] 调度 + [[inputs.*]] 采集          │
        [[processors.*]] 清洗 + [[aggregators.*]] │
        [[outputs.influxdb_v2]] 输出              │
                              v                  v
                  POST /api/v2/write ──> InfluxDB(8086)
                    (org/bucket/token)    │ TSM 存储 + TSI 索引
                                          │ retention 自动过期
  Chronograf(8888)/Grafana ──InfluxQL/Flux──> InfluxDB
  Kapacitor(9092) ──告警──> Slack/邮件/Webhook/Alertmanager 网关

⚠️ 大版本间数据格式与查询语言不兼容，跨版本须走官方迁移工具，不能原地回滚。

3. 安装与部署

3.1 环境准备

3.2 多种安装方式

A. 包仓库（官方 repos.influxdata.com）

wget -qO- https://repos.influxdata.com/influxdata-archive_compat.key | gpg --dearmor > /etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg
echo "deb [signed-by=/etc/apt/trusted.gpg.d/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main" > /etc/apt/sources.list.d/influxdata.list
apt-get update && apt-get install -y influxdb2 telegraf

B. Docker / docker compose

services:
  influxdb:
    image: influxdb:<version>
    volumes: ["./influxdb2:/var/lib/influxdb2"]
    ports: ["8086:8086"]
  telegraf:
    image: telegraf:<version>
    volumes: ["./telegraf.conf:/etc/telegraf/telegraf.conf:ro"]
    depends_on: [influxdb]

⚠️ 镜像 tag 必须写具体版本，勿用 latest（官方已指向 InfluxDB 3 Core）。

C. 二进制 + systemd

# 下载页 https://portal.influxdata.com/downloads/ ，资产名以该页为准
curl -LO "https://dl.influxdata.com/influxdb/releases/influxdb2-<version>-linux-amd64.tar.gz"
install -m 0755 influxdb2-<version>/influxd /usr/local/bin/influxd
useradd -r -s /sbin/nologin influxdb
systemctl daemon-reload && systemctl enable --now influxdb telegraf

# /etc/systemd/system/influxdb.service
[Unit]
[Service]
User=influxdb
ExecStart=/usr/local/bin/influxd --engine-path=/var/lib/influxdb2/engine --bolt-path=/var/lib/influxdb2/influxd.bolt
Restart=on-failure
[Install]
WantedBy=multi-user.target

D. Kubernetes Helm

helm repo add influxdata https://helm.influxdata.com/ && helm repo update
helm install influx influxdata/influxdb2 -n monitoring --create-namespace
helm install telegraf influxdata/telegraf -n monitoring -f telegraf-values.yaml

E. 一键初始化（2.x）

influx setup --username <admin> --password <password> --org <org> --bucket <bucket> --retention 30d --token <token> --force

3.3 首次启动与验证

curl -s http://localhost:8086/health && echo
telegraf --config /etc/telegraf/telegraf.conf --test
curl -s -X POST 'http://localhost:8086/api/v2/write?org=<org>&bucket=<bucket>&precision=s' -H 'Authorization: Token <token>' --data-binary 'smoke,host=init value=1'

浏览器打开 http://<host>:8086 进入 InfluxDB UI（Data Explorer）。

4. 配置文件详解

主配置路径：InfluxDB 2.x 无单一 conf（influxd flag：--engine-path / --bolt-path / --http-bind-address）；1.x 为 /etc/influxdb/influxdb.conf；Telegraf 为 /etc/telegraf/telegraf.conf + 分片目录 telegraf.d/（TOML）。

完整可运行最小示例

# /etc/telegraf/telegraf.conf
[agent]
  interval = "10s"
  flush_interval = "10s"
  metric_batch_size = 1000
  metric_buffer_limit = 10000
[[inputs.cpu]]
  percpu = false
  totalcpu = true
  fieldpass = ["usage_idle", "usage_user"]
[[inputs.disk]]
[[processors.rename]]
  [[processors.rename.replace]]
    tag = "host"
    dest = "hostname"
[[outputs.influxdb_v2]]
  urls = ["http://<influx>:8086"]
  token = "<token>"
  organization = "<org>"
  bucket = "metrics"

telegraf --config /etc/telegraf/telegraf.conf --test

5. 核心使用方法（CLI / HTTP API / InfluxQL / Flux / Telegraf 配置）

写入与查询 API / CLI

curl -s -X POST 'http://<influx>:8086/api/v2/write?org=<org>&bucket=<bucket>&precision=s' -H 'Authorization: Token <token>' --data-binary @metrics.lp
curl -s -X POST 'http://<influx>:8086/api/v2/query?org=<org>' -H 'Authorization: Token <token>' -H 'Content-Type: application/vnd.flux' --data @query.flux
curl -s -X POST 'http://<influx>:8086/query?db=<db>&q=SHOW+MEASUREMENTS'
curl -s -X POST 'http://<influx>:8086/write?db=<db>' --data-binary 'cpu,host=a usage=1'
influx write -b <bucket> -o <org> -t <token> -f metrics.lp --format lp
influx query 'from(bucket:"<bucket>") |> range(start:-1h)' -o <org> -t <token>
influx bucket list -o <org> -t <token>
influx bucket create -n <bucket> -o <org> -r 30d -t <token>
influx auth list -o <org> -t <token>
influx backup /backup/influx-$(date +%F) -t <token>

InfluxQL 示例（1.x 原生 / 2.x 兼容层）

CREATE DATABASE metrics WITH DURATION 30d NAME rp_30d
SHOW MEASUREMENTS
SHOW SERIES CARDINALITY
SELECT mean("usage_idle") FROM "cpu" WHERE "host" = 'web01' AND time > now() - 1h GROUP BY time(5m), "region" fill(null)
SELECT derivative(mean("usage_user"), 1m) FROM "cpu" WHERE time > now() - 6h GROUP BY time(5m)
SELECT * INTO "rp_long"."cpu_5m" FROM "cpu" GROUP BY time(5m), *

Flux 示例（2.x）

from(bucket: "metrics")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_idle" and r.host == "web01")
  |> aggregateWindow(every: 5m, fn: mean, createEmpty: false)
  |> yield(name: "mean")

Telegraf 配置与运维命令（inputs / outputs / processors / aggregators）

telegraf config > telegraf.conf
telegraf --input-filter cpu:mem:disk --output-filter influxdb_v2 config > telegraf.conf
telegraf --config telegraf.conf --test
telegraf --config telegraf.conf --config-directory /etc/telegraf/telegraf.d --test-warn
systemctl {start|stop|restart|status} telegraf
journalctl -u telegraf -f

UI：http://<host>:8086 的 Data Explorer 可切换 Flux/InfluxQL、建 dashboard、配 Checks；Chronograf http://<host>:8888 为经典 TICK UI。以上共 30+ 条可用命令。

6. 告警与通知

InfluxDB 2.x 内置 Checks（阈值/死人开关）+ Notification Endpoints/Rules（Slack、HTTP、PagerDuty、SMTP）；经典 TICK 栈用 Kapacitor 订阅数据并用 TICKscript 告警。

# /etc/kapacitor/cpu_alert.tick
stream
  |from()
    .measurement('cpu')
  |alert()
    .crit(lambda: "usage_idle" < 10)
    .webhook('<webhook-url>')

kapacitor define cpu_alert -tick cpu_alert.tick -dbrp telegraf.rp_30d
kapacitor enable cpu_alert

7. 实战场景

场景一：把现有 Prometheus 数据平滑接入 / 迁移到 InfluxDB（双跑零停机）

目标：不改现有 Prometheus 抓取，用 Telegraf 并行抓同样 exporter 写入 InfluxDB，验证后切读，随时可回退。

telegraf --config /etc/telegraf/telegraf.d/prom-to-influx.conf --test
systemctl restart telegraf
curl -s -X POST 'http://<influx>:8086/api/v2/query?org=<org>' -H 'Authorization: Token <token>' -H 'Content-Type: application/vnd.flux' --data 'from(bucket:"metrics") |> range(start:-10m) |> filter(fn:(r)=>r._measurement=="node_cpu_seconds_total") |> count()'

# /etc/telegraf/telegraf.d/prom-to-influx.conf
[[inputs.prometheus]]
  urls = ["http://<node-exporter>:9100/metrics", "http://<app-exporter>:8080/metrics"]
  metric_version = 2
[[outputs.influxdb_v2]]
  urls = ["http://<influx>:8086"]
  token = "<token>"
  organization = "<org>"
  bucket = "metrics"

验证：Flux count() 持续增长；Grafana 双数据源曲线重合；telegraf --test 输出含目标 measurement。 回滚：删该 .conf 并重启 Telegraf；Grafana 数据源改回 Prometheus；已写数据保留不删，源 Prometheus 全程未改动。

场景二：主机指标全链路采集 + 标签治理 + 类型清洗

目标：CPU/内存/磁盘统一采集，入口改标签、转类型、聚合，写入带 30 天保留的 bucket。

[agent]
  interval = "10s"
  flush_interval = "10s"
  metric_buffer_limit = 10000
[[inputs.cpu]]
  percpu = false
  totalcpu = true
[[inputs.mem]]
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]
[[processors.rename]]
  [[processors.rename.replace]]
    tag = "host"
    dest = "hostname"
[[processors.converter]]
  [[processors.converter.fields]]
    integer = ["bytes_sent", "bytes_recv"]
[[outputs.influxdb_v2]]
  urls = ["http://<influx>:8086"]
  token = "<token>"
  organization = "<org>"
  bucket = "metrics"

telegraf --config telegraf.conf --test | head -20
systemctl restart telegraf

验证：--test 输出含 hostname 标签且字段为整型；Data Explorer 能查到点。回滚：切回备份 telegraf.conf 并重启，bucket 数据按保留期自动过期。

场景三：降采样 + 分级保留，控制长期成本

目标：热 bucket 留 30 天原始点，冷 bucket 存 5 分钟均值留 1 年。

influx bucket create -n metrics_long -o <org> -r 365d -t <token>
influx task create -o <org> -t <token> -f downsample.flux
curl -s -X POST 'http://<influx>:8086/query?db=metrics' --data-urlencode 'q=CREATE CONTINUOUS QUERY cq_5m ON metrics BEGIN SELECT mean(usage_idle) INTO "rp_long"."cpu_5m" FROM "cpu" GROUP BY time(5m), * END'

option task = {name: "downsample_5m", every: 5m}
from(bucket: "metrics")
  |> range(start: -task.every)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> aggregateWindow(every: 5m, fn: mean)
  |> to(bucket: "metrics_long", org: "<org>")

验证：influx task list 状态 active；metrics_long 有 5m 间隔点。回滚：influx task delete --id <task-id> -t <token>，冷数据保留。

8. 日常运维与故障排查

systemctl restart influxdb telegraf
journalctl -u telegraf -f | grep -iE 'error|warn'
curl -s http://<influx>:8086/health
curl -s http://<influx>:8086/metrics | grep -E 'influxdb_(write|query)'
telegraf --config /etc/telegraf/telegraf.conf --test
influx bucket list -o <org> -t <token>

9. 性能、容量与高可用

• 高可用：OSS 为单机（无原生集群 HA）；用 Telegraf 多 [[outputs.influxdb_v2]] 双写到两个实例 + 反代读均衡，或选企业版/云集群；Telegraf 无状态可水平扩展。
• 降采样 / 保留：bucket -r 自动过期；Flux task（2.x）/ 连续查询 + RP（1.x）把高频明细聚合成 5m/1h 冷数据；多 bucket 分层。

10. 安全加固、备份与升级

influx backup /backup/influx-$(date +%F) -t <token>
systemctl stop influxdb && cp -a /var/lib/influxdb2 /backup/influxdb2-$(date +%F)
systemctl start influxdb && curl -s http://localhost:8086/health
influx restore /backup/<date> -t <token>

11. 常见坑

12. 速查表

13. 选型建议与同类对比

何时选：多源异构指标（主机/IoT/MQ）、需要 SQL 式或函数式查询、想要采集端强 ETL、团队熟悉 TICK 栈。 何时不选：纯 Kubernetes/Prometheus 生态且要全局 PromQL 视图（选 VictoriaMetrics/Thanos）；tag 基数极高；需要 OSS 原生多机 HA；核心诉求是日志/链路追踪。

14. 参考链接

• 官方文档：https://docs.influxdata.com/
• 下载页：https://portal.influxdata.com/downloads/
• 官方包仓库：https://repos.influxdata.com/
• InfluxDB 仓库：https://github.com/influxdata/influxdb
• Telegraf 仓库：https://github.com/influxdata/telegraf
• Telegraf 文档：https://docs.influxdata.com/telegraf/
• InfluxDB 2.x 文档：https://docs.influxdata.com/influxdb/v2/
• InfluxDB 1.x 文档：https://docs.influxdata.com/influxdb/v1/
• Telegraf 插件目录：https://github.com/influxdata/telegraf/tree/master/plugins/inputs