ARTICLE · 1202530

InfluxDB 3 Core 安装部署与入门教程

发布时间：2026-10-18 00:05:42 最近访问：2026-10-18 00:05:44

WECHAT ARTICLE2026-10-17

InfluxDB 3 Core 安装部署与入门教程

CONTENTS · 本期看点

一、InfluxDB 3 Core是什么

二、版本、限制与部署选择

三、Windows原生安装

— influxdb3-wechat-cover

[!abstract] 适用场景本教程以 InfluxDB 3 Core 3.12.0 为例，重点说明 Windows AMD64 原生部署，并补充 Linux 与 Docker 部署。示例围绕设备状态、温度、压力和振动数据展开，适合开发测试、设备监控和时序数据分析入门。

[!warning] 版本区别 InfluxDB 1.x、2.x和3.x的存储引擎、命令、查询语言与管理方式不同。本教程只针对 InfluxDB 3 Core，不要直接套用2.x教程中的influx setup、Organization、Bucket和Flux配置。

PART

一、InfluxDB 3 Core是什么

CHAPTER

InfluxDB 3 Core是一款面向时序数据的数据库，采用Apache Arrow、DataFusion和Parquet等技术，适合：

✓

设备运行状态和传感器数据；

◆

温度、压力、振动、电流、电压等连续指标；

●

服务器和应用监控数据；

按时间范围查询和窗口聚合；

✓

Grafana实时看板；

◆

告警、趋势和异常分析。

典型数据结构：

text

表/Measurement：device_status

Tag：device_id、factory_id、device_type、production_line

Field：temperature、pressure、vibration、online、alarm_code

Time：采集时间

整体数据链路：

— device-data-architecture

PART

二、版本、限制与部署选择

CHAPTER

截至2026年10月，官方文档示例版本为3.12.0，Windows提供AMD64二进制包：

<https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.12.0-windows_amd64.zip>

官方安装文档：<https://docs.influxdata.com/influxdb3/core/install/>

Core版重要限制

✓

单节点部署，不提供Enterprise的高可用和读副本能力；

◆

最多创建5个数据库；

●

数据库保留周期只能在创建时设置，之后不能直接修改；

默认保留周期为无限，即数据不会自动过期；

✓

默认HTTP监听端口为8181；

◆

Windows原生二进制适合开发和单机使用，正式生产优先Linux DEB/RPM或安全配置后的Docker。

部署方式选择

方式	适用场景	建议
Windows原生	本地开发、设备现场单机、小规模验证	本教程重点
Linux DEB/RPM	正式单机服务	生产首选
Docker Compose	测试、标准化交付	推荐
Core + MinIO/S3	数据量较大、存储独立	需压测
Enterprise/Clustered	高可用、扩展与企业管理	大型生产环境

PART

三、Windows原生安装

CHAPTER

1. 下载并校验

在PowerShell中执行：

powershell

$url = 'https://dl.influxdata.com/influxdb/releases/influxdb3-core-3.12.0-windows_amd64.zip'

$zip = "$env:USERPROFILE\Downloads\influxdb3-core-3.12.0-windows_amd64.zip"

Invoke-WebRequest -Uri $url -OutFile $zip

Get-FileHash -Algorithm SHA256 $zip

将输出值与官方下载页提供的.sha256文件核对。不要跳过生产安装包的完整性校验。

2. 解压并创建目录

powershell

New-Item -ItemType Directory -Path 'D:\influxdb3' -Force

Expand-Archive `

　-Path "$env:USERPROFILE\Downloads\influxdb3-core-3.12.0-windows_amd64.zip" `

　-DestinationPath 'D:\influxdb3\package' `

　-Force

找到解压后的influxdb3.exe并复制到固定目录：

powershell

Get-ChildItem 'D:\influxdb3\package' -Recurse -Filter 'influxdb3.exe'

最终建议目录：

text

D:\influxdb3

├─ influxdb3.exe

├─ data\

├─ plugins\

├─ logs\

└─ scripts\

创建数据目录：

powershell

New-Item -ItemType Directory -Force -Path `

　'D:\influxdb3\data', `

　'D:\influxdb3\plugins', `

　'D:\influxdb3\logs', `

　'D:\influxdb3\scripts'

检查版本：

powershell

& 'D:\influxdb3\influxdb3.exe' --version

3. 启动服务

开发环境可直接启动：

powershell

& 'D:\influxdb3\influxdb3.exe' serve `

　--node-id windows-node01 `

　--object-store file `

　--data-dir 'D:\influxdb3\data' `

　--plugin-dir 'D:\influxdb3\plugins' `

　--http-bind '0.0.0.0:8181'

参数说明：

参数	说明
--node-id	节点唯一标识，确定后不要随意修改
--object-store file	使用本地文件系统保存Parquet数据
--data-dir	数据、WAL和元数据目录
--plugin-dir	Python处理插件目录
--http-bind	HTTP监听地址和端口

[!warning] 安全提示 0.0.0.0:8181允许局域网访问。首次创建管理员令牌前，建议仅监听127.0.0.1:8181，创建令牌后再按需开放网络和防火墙。不要将8181端口直接暴露到公网。

检查端口：

powershell

Test-NetConnection 127.0.0.1 -Port 8181

4. 创建首个管理员令牌

保持服务窗口运行，重新打开一个PowerShell窗口：

powershell

cd D:\influxdb3

.\influxdb3.exe create token --admin

第一次生成的管理员令牌是Operator Token。令牌只在创建时完整显示，必须立即保存到密码管理器，不要写进代码、普通笔记或Git仓库。

为当前PowerShell会话设置环境变量：

powershell

$env:INFLUXDB3_AUTH_TOKEN = '替换为刚生成的令牌'

验证令牌：

powershell

.\influxdb3.exe show tokens --token $env:INFLUXDB3_AUTH_TOKEN

5. 创建数据库

设备原始数据保留90天：

powershell

.\influxdb3.exe create database `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　--retention-period 90d `

　device_raw

创建长期汇总库：

powershell

.\influxdb3.exe create database `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　--retention-period none `

　device_archive

查看数据库：

powershell

.\influxdb3.exe show databases --token $env:INFLUXDB3_AUTH_TOKEN

保留周期支持：

text

1h 1小时

7d 7天

4w 4周

1mo 30天

1y 365天

none 永久保留

Core版的保留周期不可修改。如果需要从90天改为1年，应新建数据库并迁移数据。

PART

四、写入第一批设备数据

CHAPTER

— write-query-workflow

1. 理解Line Protocol

格式：

text

measurement,tag1=value1,tag2=value2 field1=value1,field2=value2 timestamp

示例：

text

device_status,device_id=DEV001,factory_id=F001 temperature=35.2,pressure=1.125,vibration=0.032,online=true,alarm_count=0i,status="RUNNING"

规则：

✓

第一个空格前是表名和Tag；

◆

第一个空格后是Field；

●

Tag和Field之间必须有空格；

整数添加i，例如0i；

✓

字符串Field使用双引号；

◆

不写时间戳时使用服务器接收时间；

●

同一字段的类型一旦确定，后续不能随意改为其他类型。

2. 使用CLI写入

powershell

cd D:\influxdb3

.\influxdb3.exe write `

　--database device_raw `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　'device_status,device_id=DEV001,factory_id=F001,device_type=vibration temperature=35.2,pressure=1.125,vibration=0.032,online=true,alarm_count=0i,status="RUNNING"'

首次写入时，InfluxDB会根据Line Protocol自动创建表和列。

3. 从文件批量写入

新建D:\influxdb3\device-data.lp：

text

device_status,device_id=DEV001,factory_id=F001 temperature=35.2,pressure=1.125,vibration=0.032,online=true,alarm_count=0i,status="RUNNING"

device_status,device_id=DEV002,factory_id=F001 temperature=36.8,pressure=1.090,vibration=0.058,online=true,alarm_count=1i,status="WARNING"

device_status,device_id=DEV003,factory_id=F002 temperature=28.3,pressure=0.980,vibration=0.012,online=false,alarm_count=1i,status="OFFLINE"

写入：

powershell

.\influxdb3.exe write `

　--database device_raw `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　--file 'D:\influxdb3\device-data.lp'

4. 使用HTTP API写入

PowerShell中明确调用curl.exe，避免使用curl别名：

powershell

curl.exe "http://127.0.0.1:8181/api/v3/write_lp?db=device_raw" `

　--header "Authorization: Bearer $env:INFLUXDB3_AUTH_TOKEN" `

　--data-raw 'device_status,device_id=DEV004,factory_id=F002 temperature=30.1,pressure=1.005,vibration=0.021,online=true,alarm_count=0i,status="RUNNING"'

成功通常返回HTTP 204 No Content。

PART

五、使用SQL查询

CHAPTER

查询最近数据：

powershell

.\influxdb3.exe query `

　--database device_raw `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　'SELECT * FROM device_status ORDER BY time DESC LIMIT 20'

查询单台设备：

sql

SELECT

　　time,

　　device_id,

　　temperature,

　　pressure,

　　vibration,

　　status

FROM device_status

WHERE device_id = 'DEV001'

　AND time >= NOW() - INTERVAL '1 day'

ORDER BY time DESC;

按小时聚合：

sql

SELECT

　　device_id,

　　date_bin(INTERVAL '1 hour', time) AS hour,

　　AVG(temperature) AS avg_temperature,

　　MAX(vibration) AS max_vibration,

　　COUNT(*) AS report_count

FROM device_status

WHERE time >= NOW() - INTERVAL '7 days'

GROUP BY device_id, date_bin(INTERVAL '1 hour', time)

ORDER BY hour DESC;

查找异常设备：

sql

SELECT

　　device_id,

　　MAX(time) AS last_report_time,

　　MAX(vibration) AS max_vibration

FROM device_status

WHERE time >= NOW() - INTERVAL '10 minutes'

GROUP BY device_id

HAVING MAX(vibration) > 0.05;

直接执行SQL文件：

powershell

.\influxdb3.exe query `

　--database device_raw `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　--file 'D:\influxdb3\query.sql'

导出CSV：

powershell

.\influxdb3.exe query `

　--database device_raw `

　--token $env:INFLUXDB3_AUTH_TOKEN `

　--format csv `

　'SELECT * FROM device_status ORDER BY time DESC LIMIT 100' `

　| Set-Content -Encoding UTF8 'D:\influxdb3\device-status.csv'

PART

六、设备表结构设计

CHAPTER

适合作为Tag

Tag适合经常作为过滤和分组条件、取值相对稳定的字段：

text

device_id

factory_id

production_line

device_type

region

适合作为Field

Field适合连续变化的测量值和状态值：

text

temperature

pressure

vibration

voltage

current

online

alarm_code

status

设计原则

✓

一次上报中的多个指标写在同一个Point中；

◆

不要把温度、压力、随机流水号等持续变化值设计成Tag；

●

设备ID可作为Tag，便于按设备过滤；

同一列始终使用相同数据类型；

✓

采集程序批量提交，避免每个指标单独请求；

◆

所有设备统一时间标准，推荐UTC；

●

原始数据和长期汇总数据使用不同数据库或不同表。

PART

七、Windows开机运行

CHAPTER

Windows原生方式没有Linux systemd。可创建启动脚本并通过任务计划程序在开机时运行。

创建D:\influxdb3\scripts\start-influxdb3.ps1：

powershell

$ErrorActionPreference = 'Stop'

& 'D:\influxdb3\influxdb3.exe' serve `

　--node-id windows-node01 `

　--object-store file `

　--data-dir 'D:\influxdb3\data' `

　--plugin-dir 'D:\influxdb3\plugins' `

　--http-bind '0.0.0.0:8181' `

　*>> 'D:\influxdb3\logs\influxdb3.log'

在“任务计划程序”中创建任务：

text

触发器：系统启动时

程序：powershell.exe

参数：-NoProfile -ExecutionPolicy Bypass -File D:\influxdb3\scripts\start-influxdb3.ps1

起始于：D:\influxdb3

选项：使用最高权限运行

创建后重启测试，并检查：

powershell

Get-Process influxdb3 -ErrorAction SilentlyContinue

Test-NetConnection 127.0.0.1 -Port 8181

Get-Content 'D:\influxdb3\logs\influxdb3.log' -Tail 100

PART

八、Docker Compose部署

CHAPTER

创建compose.yaml：

yaml

services:

　influxdb3-core:

　　image: influxdb:3.12.0-core

　　container_name: influxdb3-core

　　restart: unless-stopped

　　ports:

　　　- "8181:8181"

　　command:

　　　- influxdb3

　　　- serve

　　　- --node-id=node0

　　　- --object-store=file

　　　- --data-dir=/var/lib/influxdb3/data

　　　- --plugin-dir=/var/lib/influxdb3/plugins

　　volumes:

　　　- ./data:/var/lib/influxdb3/data

　　　- ./plugins:/var/lib/influxdb3/plugins

启动：

powershell

docker compose pull

docker compose up -d

docker compose logs -f influxdb3-core

创建令牌：

powershell

docker exec -it influxdb3-core influxdb3 create token --admin

生产环境固定具体镜像版本，不建议直接依赖持续变化的influxdb:3-core标签。

PART

九、Linux生产部署

CHAPTER

官方更推荐使用DEB或RPM包，安装包自带systemd隔离配置。

Ubuntu/Debian安装：

bash

curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key

gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \

　| grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \

　&& cat influxdata-archive.key \

　| gpg --dearmor \

　| sudo tee /usr/share/keyrings/influxdata-archive.gpg >/dev/null

echo 'deb [signed-by=/usr/share/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \

　| sudo tee /etc/apt/sources.list.d/influxdata.list

sudo apt-get update

sudo apt-get install influxdb3-core

默认配置文件：

text

/etc/influxdb3/influxdb3-core.conf

核心配置示例：

toml

object-store = "file"

data-dir = "/var/lib/influxdb3/data"

plugin-dir = "/var/lib/influxdb3/plugins"

node-id = "primary-node"

启动与日志：

bash

sudo systemctl start influxdb3-core

sudo systemctl enable influxdb3-core

sudo systemctl status influxdb3-core

sudo journalctl --unit influxdb3-core -n 100 --no-pager

修改配置后必须重启，influxdb3 serve不支持配置热加载：

bash

sudo systemctl restart influxdb3-core

PART

十、图形客户端连接

CHAPTER

1. InfluxDB 3 Explorer

InfluxDB 3 Explorer是官方图形化管理界面，适合浏览数据库、执行SQL和检查查询结果。Explorer通过Docker运行时，与Windows原生InfluxDB的连接关系如下：

— explorer-connection

下载并启动Explorer：

powershell

docker pull influxdata/influxdb3-ui:1.11.0

docker run -d `

　--name influxdb3-explorer `

　-p 127.0.0.1:8888:8080 `

　--restart unless-stopped `

　influxdata/influxdb3-ui:1.11.0

浏览器打开http://localhost:8888，然后填写：

配置项	值
Server Name	Windows InfluxDB
Server URL	http://host.docker.internal:8181
Token	create token --admin 生成的令牌
Database	例如device_raw

Explorer容器中的localhost指向容器自身，因此不能填写http://localhost:8181。Windows上的InfluxDB应使用--http-bind '0.0.0.0:8181'启动，才能由Docker容器访问。

2. Grafana连接

官方当前建议使用Grafana 12.2或更高版本，并启用新版InfluxDB数据源配置界面。

在Grafana中进入：

text

Connections → Data sources → Add new data source → InfluxDB

配置：

项目	值
URL	http://InfluxDB服务器IP:8181
Product	InfluxDB Enterprise 3.x ，当前界面可能没有Core选项
Query language	SQL或InfluxQL
Database	device_raw
Token	具有读取权限的令牌
Insecure Connection	未配置TLS时开启

SQL查询通过Flight SQL使用HTTP/2。如果前面有Nginx、HAProxy或负载均衡器，必须确认代理支持HTTP/2；InfluxQL使用HTTP/1.1，不受此项影响。

Grafana绘制时序图时，SQL结果中应包含time列：

sql

SELECT

　　time,

　　vibration

FROM device_status

WHERE device_id = 'DEV001'

　AND time >= NOW() - INTERVAL '1 hour'

ORDER BY time;

PART

十一、容量与保留策略

CHAPTER

推荐分层保留：

text

秒级原始数据：保留30～90天

分钟汇总数据：保留1～2年

小时或日汇总：长期保留

重要告警和故障事件：长期保留

容量估算：

text

总记录数 = 设备数 × 每台每天上报次数 × 保留天数

每天上报次数 = 86400 ÷ 上报间隔秒数

预计容量 = 总记录数 × 实测压缩后平均字节数 × 1.5～2安全系数

最可靠的方法是用真实数据连续写入一周，再根据数据目录实际增量估算全年容量。

PART

十二、备份与安全

CHAPTER

最低要求：

✓

管理员令牌存放在密码管理器或安全密钥服务中；

◆

应用使用独立令牌，不直接使用Operator Token；

●

防火墙只允许采集端和查询端访问8181；

公网传输必须配置TLS或通过安全反向代理；

✓

定期备份数据目录和Catalog；

◆

备份前遵循官方一致性要求，不直接复制正在变化的文件；

●

定期测试恢复，不把“复制成功”等同于“备份可用”；

生产环境监控磁盘、内存、CPU、写入延迟和查询延迟。

PART

十三、常见故障

CHAPTER

8181端口无法访问

powershell

Get-Process influxdb3 -ErrorAction SilentlyContinue

Get-NetTCPConnection -LocalPort 8181 -ErrorAction SilentlyContinue

Test-NetConnection 127.0.0.1 -Port 8181

检查--http-bind、Windows防火墙和程序是否异常退出。

401 Unauthorized

原因通常是令牌缺失、复制不完整或环境变量只在另一个终端中设置。

powershell

$env:INFLUXDB3_AUTH_TOKEN.Length

不要打印完整令牌到共享终端或截图中。

写入提示字段类型冲突

例如第一次写入：

text

temperature=35.2

后续不要写成：

text

temperature="35.2"

前者是浮点数，后者是字符串。应在采集程序中统一类型。

查询不到刚写入的数据

检查：

✓

写入和查询是否使用同一数据库；

◆

时间戳单位是否正确；

●

时间戳是否超出数据库保留周期；

查询时间范围和时区是否正确；

✓

写入是否收到HTTP 204或CLI成功响应。

数据目录越来越大

默认数据库无限保留。应在创建数据库时设置--retention-period，并通过汇总表保存长期趋势。Core不能直接修改既有数据库保留周期，需要新建数据库并迁移数据。

Windows重启后服务没有启动

检查任务计划程序的运行账户、最高权限、脚本路径、工作目录和日志文件。也可改用Docker Desktop或Linux服务器统一管理。

PART

十四、上线检查清单

TOOLKIT

✓

[ ] 使用明确版本的安装包或Docker镜像

◆

[ ] node-id固定且唯一

●

[ ] 数据目录位于容量充足的SSD或对象存储

[ ] 已创建并安全保存Operator Token

✓

[ ] 应用使用独立令牌

◆

[ ] 数据库保留周期经过确认

●

[ ] Tag与Field设计经过评审

[ ] 同一Field的数据类型保持一致

✓

[ ] 采集端支持批量写入、断线缓存和失败重试

◆

[ ] 8181端口未暴露到公网

●

[ ] Grafana和反向代理支持所选查询协议

[ ] 已完成真实写入、查询和容量压测

✓

[ ] 已完成备份与恢复演练

PART

十五、建议学习路线

CHAPTER

Windows启动InfluxDB 3 Core；

创建Operator Token和90天保留数据库；

用CLI写入三条设备状态；

使用SQL查询和按小时聚合；

编写采集程序批量调用/api/v3/write_lp；

接入Grafana显示设备趋势；

实现采集端断网缓存与补传；

用一周真实数据评估容量与性能；

将正式环境迁移到Linux或Docker；

完成备份、恢复和监控告警。

PART

参考资料

CHAPTER

✓

安装InfluxDB 3 Core

◆

配置并启动Core

●

创建数据库

使用CLI写入数据

✓

使用CLI执行SQL查询

◆

安装InfluxDB 3 Explorer

●

使用Grafana可视化

数据保留机制

我是 Zora，明天又是新的一天，财富满满的一天，元气满满的一天。

如果你觉得今天这篇有收获，欢迎点赞、在看、转发三连，我们下篇见。

相关学习资料