时间序列数据库 InfluxDB 入门

FreeGuideOnline 最新 2026-07-08

bash

拉取官方镜像并运行，映射端口 8086

docker run --name influxdb -p 8086:8086 influxdb:2.7


启动后访问 `http://localhost:8086` 即可打开 Web 管理界面（首次需创建管理员账号、组织、桶）。

### 本地安装（以 Ubuntu 为例）

```bash
wget -qO- https://repos.influxdata.com/influxdata-archive_compat.key | sudo apt-key add -
echo "deb https://repos.influxdata.com/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/influxdb.list
sudo apt update
sudo apt install influxdb2
sudo systemctl start influxdb

安装完成后，可以通过命令行工具 influx 或浏览器访问 http://localhost:8086 进行配置。

初次设置

无论是 Docker 还是二进制安装，首次访问 Web UI 都需要完成初始化：

用户名：如 admin
密码：至少 8 位
初始组织名称：例如 my-org
初始桶（Bucket）名称：例如 my-bucket

这些信息会用于后续的认证和数据操作。记下生成的 API Token，它与用户名密码同等重要。

核心概念与数据模型

理解 InfluxDB 的数据组织方式是上手的关键。

组织、桶和测量

组织（Organization）：工作空间的隔离单位，一个账号可属于多个组织。
桶（Bucket）：数据存储的命名空间，具有明确的保留策略（数据保留多久）。一个桶可包含多种 测量（Measurement）。
测量（Measurement）：类似于关系型数据库中的表，用于存放一类数据。例如 temperature 测量可存储温度数据。

时间戳、字段和标签

InfluxDB 的每一条数据称为 点（Point），由以下部分构成：

时间戳（Timestamp）：数据发生的时间，精度支持纳秒级。
字段（Field）：存储实际数值，不可用于索引，如 temperature=23.5。
标签（Tag）：元数据，用于分组、过滤，会被索引，如 sensor_id=s1、location=lab。
测量名称（Measurement）：归属的数据分类。

一个点示例（以行协议表示）：

temperature,sensor_id=s1,location=lab temperature=23.5 1622547800000000000

之前为 测量名称 和 标签集合（逗号分隔）
空格后是 字段集合（逗号分隔）
最后是 纳秒级时间戳

桶与保留策略

每个桶可以设置 保留期（Retention Period），超过该时间的数据自动删除。例如设置为 30 天，则只保留最近 30 天的数据。这对于监控类场景非常实用。

写入数据

在 InfluxDB 2.x 中，写入数据需要提供组织、桶、API Token 及数据本身。支持多种方式：行协议、客户端库、Telegraf 插件、HTTP API 等。

通过行协议写入（使用 influx write）

进入容器或本地终端，使用 influx 命令行：

# 设置连接配置（或每次通过参数指定）
influx config create -n default-config \
  -u http://localhost:8086 \
  -o my-org \
  -t YOUR_API_TOKEN

# 写入单条数据
influx write -b my-bucket "temperature,sensor_id=s1,location=lab temp_c=23.5 $(date +%s%N)"

详解：

-b 指定桶名
数据遵循 行协议：测量名,标签集字段集时间戳
时间戳必须为纳秒级 Unix 时间戳，可以使用 $(date +%s%N) 生成当前时间戳。

批量写入只需将多条行协议用换行分隔。

使用 HTTP API (cURL)

curl -X POST "http://localhost:8086/api/v2/write?org=my-org&bucket=my-bucket&precision=ns" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  --data-binary "temperature,sensor_id=s1,location=lab temp_c=23.5 $(date +%s%N)"

使用 Python 客户端

安装库：

pip install influxdb-client

示例代码：

from influxdb_client import InfluxDBClient, Point
from influxdb_client.client.write_api import SYNCHRONOUS

client = InfluxDBClient(url="http://localhost:8086", token="YOUR_API_TOKEN", org="my-org")
write_api = client.write_api(write_options=SYNCHRONOUS)

p = Point("temperature").tag("sensor_id", "s1").tag("location", "lab").field("temp_c", 23.5)
write_api.write(bucket="my-bucket", record=p)

查询数据

InfluxDB 提供两种查询语言：Flux（2.x 默认）和 InfluxQL（类 SQL，兼容 1.x）。推荐学习 Flux，功能更强。

Flux 基础语法

一个典型的 Flux 查询由多个函数通过管道符 |> 连接而成：

from(bucket: "my-bucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "temperature")
  |> filter(fn: (r) => r._field == "temp_c")

from()：指定数据来源桶
range()：限定时间范围。支持相对时间 -1h、-30m，也支持绝对时间 2023-01-01T00:00:00Z
filter()：按测量、字段、标签等过滤

常用查询示例

获取最近 5 分钟的温度数据

from(bucket: "my-bucket")
  |> range(start: -5m)
  |> filter(fn: (r) => r._measurement == "temperature" and r._field == "temp_c")

按标签分组计算平均值

from(bucket: "my-bucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "temperature" and r._field == "temp_c")
  |> group(columns: ["sensor_id"])
  |> mean()

数据聚合与下采样

from(bucket: "my-bucket")
  |> range(start: -24h)
  |> filter(fn: (r) => r._measurement == "temperature")
  |> aggregateWindow(every: 10m, fn: mean)

在 Web UI 中查询

InfluxDB 自带的 Data Explorer (数据浏览器) 提供可视化查询构建器，也可直接编写 Flux 脚本。在 UI 左侧菜单进入 "Data Explorer"，选择桶和测量，拖动时间范围即可生成查询。

使用 Telegraf 采集数据

Telegraf 是 InfluxData 生态的数据采集代理，支持 200+ 输入插件（CPU、内存、MySQL、Redis 等），可将采集到的数据直接写入 InfluxDB。

安装与配置

sudo apt install telegraf

生成基础配置文件：

telegraf config > telegraf.conf

编辑 telegraf.conf，找到 [[outputs.influxdb_v2]] 部分，修改为：

[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "YOUR_API_TOKEN"
  organization = "my-org"
  bucket = "my-bucket"

添加所需输入插件，例如采集系统 CPU：

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

启动 Telegraf：

telegraf --config telegraf.conf

稍后在 InfluxDB 的 Data Explorer 中就会看到 cpu 测量下的数据。

可视化与仪表板

InfluxDB 自带仪表板功能，可以在 UI 中创建图表、监控面板。

进入 Dashboards，新建仪表板。
添加单元格，选择数据源（桶）和查询（可以直接使用 Flux 脚本或查询构建器）。
图表类型可选折线图、柱状图、单值统计、仪表盘等。
设置自动刷新间隔，实时查看趋势。

另外，也可通过 Grafana 等工具连接 InfluxDB，利用其更丰富的可视化能力。

数据保留与下采样任务

设置桶的保留策略

在 Load Data → Buckets 页面，点击桶名称，设置 Retention period。例如 30d 表示只保留 30 天数据。

创建下采样任务

长时间存储高精度原始数据成本较高，通常会进行下采样——按较大时间窗口聚合后存入另一个桶。可以使用 Task 功能自动化。

示例：每 10 分钟计算温度平均值，并写入 downsampled 桶。

option task = {name: "downsample_temp", every: 10m}

from(bucket: "my-bucket")
  |> range(start: -10m)
  |> filter(fn: (r) => r._measurement == "temperature")
  |> aggregateWindow(every: 10m, fn: mean)
  |> to(bucket: "downsampled", org: "my-org")