InfluxDB 3 运维命令 100 条

前言

InfluxDB 3 是基于 Apache Arrow、DataFusion、Parquet 和对象存储构建的新一代时序数据库。与 InfluxDB 1.x/2.x 相比，它使用新的 influxdb3 CLI，支持 SQL 和 InfluxQL，但不支持 Flux，数据库、表、Token、缓存和处理引擎的管理方式也发生了明显变化。

下面整理 InfluxDB 3 Core 常用的 100 条命令，覆盖安装启动、数据库、表、Token、Line Protocol 写入、SQL、InfluxQL、缓存、Processing Engine、监控和备份检查。Enterprise 和 Cloud 提供的部分能力与 Core 不同，不能直接照搬。

本文以当前 InfluxDB 3 Core 文档为基线。Core 对查询时间范围、保留策略修改和集群能力存在产品边界，且不提供内置备份恢复命令。生产操作前应确认版本和 Edition。

一、安装、启动与连接

1. 查看 influxdb3 版本

Bash

1influxdb3 --version

2. 查看 CLI 帮助

Bash

1influxdb3 --help

3. 查看服务端参数

Bash

1influxdb3 serve --help

4. 使用本地文件存储启动

Bash

1influxdb3 serve \
2  --node-id node01 \
3  --object-store file \
4  --data-dir /var/lib/influxdb3

5. 使用内存存储启动测试实例

Bash

1influxdb3 serve \
2  --node-id test01 \
3  --object-store memory

内存存储重启后数据丢失，只适合测试。

6. 使用 S3 对象存储启动

Bash

1influxdb3 serve \
2  --node-id node01 \
3  --object-store s3 \
4  --bucket influxdb3-prod \
5  --aws-default-region ap-northeast-1

访问密钥应通过安全的环境变量或实例角色提供。

7. 使用 MinIO 启动

Bash

1influxdb3 serve \
2  --node-id node01 \
3  --object-store s3 \
4  --bucket influxdb3 \
5  --aws-endpoint http://minio:9000 \
6  --aws-allow-http

生产环境应使用 TLS。

8. 设置服务地址

Bash

1export INFLUXDB3_HOST_URL=http://127.0.0.1:8181

9. 检查健康状态

Bash

1curl -s http://127.0.0.1:8181/health

健康检查路径可能随版本调整，应以当前服务文档为准。

10. 查看 HTTP 响应头

Bash

1curl -I http://127.0.0.1:8181/health

二、Token 与认证

11. 创建初始 Operator Token

Bash

1influxdb3 create token --admin

Token 只在创建时显示一次，必须立即保存。

12. 设置认证 Token

Bash

1export INFLUXDB3_AUTH_TOKEN='apiv3_Replace_With_Token'

13. 创建命名 Admin Token

Bash

1influxdb3 create token \
2  --admin \
3  --name dba-admin \
4  --expiry 30d

14. 生成离线 Admin Token

Bash

1influxdb3 create token \
2  --admin \
3  --offline \
4  --name bootstrap-admin \
5  --output-file /secure/admin-token.json

应限制文件权限并安全保管。

15. 查看 Token

Bash

1influxdb3 show tokens

16. 删除 Token

Bash

1influxdb3 delete token dba-admin

17. 通过 HTTP Bearer Token 认证

Bash

1curl -s \
2  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
3  http://127.0.0.1:8181/health

18. 查看创建 Token 的帮助

Bash

1influxdb3 create token --help

19. 查看删除 Token 的帮助

Bash

1influxdb3 delete token --help

20. 清除当前 Shell 中的 Token

Bash

1unset INFLUXDB3_AUTH_TOKEN

三、数据库与表

21. 查看数据库

Bash

1influxdb3 show databases

22. 创建数据库

Bash

1influxdb3 create database sensors

23. 创建带保留期的数据库

Bash

1influxdb3 create database \
2  --retention-period 30d \
3  sensors_30d

InfluxDB 3 Core 的保留期创建后不可修改。

24. 查看数据库系统表

Bash

1influxdb3 show system \
2  --database sensors \
3  table databases

可用系统表随版本变化。

25. 使用 SQL 查看表

Bash

1influxdb3 query \
2  --database sensors \
3  "SHOW TABLES"

26. 使用 InfluxQL 查看 Measurement

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SHOW MEASUREMENTS"

27. 创建显式 Schema 表

Bash

1influxdb3 create table \
2  --database sensors \
3  --tags host,region \
4  --fields usage:float64,temp:float64 \
5  cpu

参数形式应使用当前 CLI 的 create table --help 复核。

28. 查看表字段

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT column_name, data_type
4   FROM information_schema.columns
5   WHERE table_name='cpu'"

29. 查看数据库 Schema

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT table_name
4   FROM information_schema.tables
5   WHERE table_schema='iox'"

30. 软删除表

Bash

1influxdb3 delete table \
2  --database sensors \
3  cpu

31. 硬删除表

Bash

1influxdb3 delete table \
2  --database sensors \
3  --hard-delete now \
4  cpu

硬删除不可恢复，执行前应确认目标和备份。

32. 软删除数据库

Bash

1influxdb3 delete database sensors

33. 立即硬删除数据库

Bash

1influxdb3 delete database \
2  --hard-delete now \
3  sensors

四、Line Protocol 数据写入

34. 写入单条数据

Bash

1influxdb3 write \
2  --database sensors \
3  'cpu,host=server01 usage=72.5,temp=61.2'

35. 写入带纳秒时间戳的数据

Bash

1influxdb3 write \
2  --database sensors \
3  --precision ns \
4  'cpu,host=server01 usage=72.5 1785148800000000000'

36. 使用秒级时间戳

Bash

1influxdb3 write \
2  --database sensors \
3  --precision s \
4  'cpu,host=server01 usage=72.5 1785148800'

37. 批量写入多行数据

Bash

1influxdb3 write \
2  --database sensors \
3  'cpu,host=server01 usage=72.5
4cpu,host=server02 usage=65.8
5memory,host=server01 used=78.2'

38. 从文件写入数据

Bash

1influxdb3 write \
2  --database sensors \
3  --file metrics.lp

39. 从标准输入写入

Bash

1printf '%s\n' \
2'cpu,host=server01 usage=72.5' |
3influxdb3 write --database sensors

40. 接受部分写入

Bash

1influxdb3 write \
2  --database sensors \
3  --accept-partial \
4  --file metrics.lp

应检查返回结果，避免忽略失败行。

41. 不等待 WAL 同步

Bash

1influxdb3 write \
2  --database sensors \
3  --no-sync \
4  'cpu,host=server01 usage=72.5'

--no-sync 以数据可靠性换取响应速度，不适合关键数据。

42. 使用 HTTP v3 写入接口

Bash

1curl -sS -X POST \
2  "http://127.0.0.1:8181/api/v3/write_lp?db=sensors" \
3  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
4  --data-binary \
5  'cpu,host=server01 usage=72.5'

43. 使用 v1 兼容写入接口

Bash

1curl -sS -X POST \
2  "http://127.0.0.1:8181/write?db=sensors&precision=s" \
3  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
4  --data-binary \
5  'cpu,host=server01 usage=72.5 1785148800'

44. 写入字符串和整数类型

Bash

1influxdb3 write \
2  --database sensors \
3  'service,host=server01 status="UP",connections=120i'

45. 写入布尔类型

Bash

1influxdb3 write \
2  --database sensors \
3  'health,host=server01 available=true'

五、SQL 查询

46. 查询最新数据

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT *
4   FROM cpu
5   ORDER BY time DESC
6   LIMIT 10"

47. 按时间范围查询

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT *
4   FROM cpu
5   WHERE time >= now() - INTERVAL '1 hour'"

48. 按 Tag 过滤

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT time, host, usage
4   FROM cpu
5   WHERE host='server01'
6   ORDER BY time DESC"

49. 计算平均值

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT host, avg(usage) AS avg_usage
4   FROM cpu
5   WHERE time >= now() - INTERVAL '1 hour'
6   GROUP BY host"

50. 按时间窗口聚合

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT date_bin(
4             INTERVAL '5 minutes',
5             time,
6             TIMESTAMP '1970-01-01T00:00:00Z'
7          ) AS window,
8          host,
9          avg(usage) AS avg_usage
10   FROM cpu
11   WHERE time >= now() - INTERVAL '1 hour'
12   GROUP BY window, host
13   ORDER BY window"

51. 查询最大值和最小值

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT host,
4          min(usage) AS min_usage,
5          max(usage) AS max_usage
6   FROM cpu
7   GROUP BY host"

52. 使用窗口函数

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT time, host, usage,
4          avg(usage) OVER (
5            PARTITION BY host
6            ORDER BY time
7            ROWS BETWEEN 5 PRECEDING AND CURRENT ROW
8          ) AS moving_avg
9   FROM cpu"

53. 执行表连接

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT c.time, c.host,
4          c.usage, m.used
5   FROM cpu c
6   JOIN memory m
7     ON c.host=m.host AND c.time=m.time"

54. 查看 SQL 执行计划

Bash

1influxdb3 query \
2  --database sensors \
3  "EXPLAIN
4   SELECT avg(usage)
5   FROM cpu
6   WHERE time >= now() - INTERVAL '1 hour'"

55. 查看实际执行计划

Bash

1influxdb3 query \
2  --database sensors \
3  "EXPLAIN ANALYZE
4   SELECT avg(usage)
5   FROM cpu
6   WHERE time >= now() - INTERVAL '1 hour'"

56. 以 CSV 格式输出

Bash

1influxdb3 query \
2  --database sensors \
3  --format csv \
4  "SELECT * FROM cpu LIMIT 100"

57. 以 JSON 格式输出

Bash

1influxdb3 query \
2  --database sensors \
3  --format json \
4  "SELECT * FROM cpu LIMIT 10"

58. 从 SQL 文件执行查询

Bash

1influxdb3 query \
2  --database sensors \
3  --file report.sql

59. 通过 HTTP 执行 SQL

Bash

1curl -sS -G \
2  "http://127.0.0.1:8181/api/v3/query_sql" \
3  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
4  --data-urlencode "db=sensors" \
5  --data-urlencode "q=SELECT * FROM cpu LIMIT 10" \
6  --data-urlencode "format=json"

60. 查看 SQL 帮助

Bash

1influxdb3 query --help

六、InfluxQL 查询

61. 执行基本 InfluxQL 查询

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SELECT * FROM cpu LIMIT 10"

62. 查看字段

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SHOW FIELD KEYS FROM cpu"

63. 查看 Tag Key

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SHOW TAG KEYS FROM cpu"

64. 查看 Tag Value

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SHOW TAG VALUES FROM cpu WITH KEY=host"

65. 按时间窗口聚合

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "SELECT mean(usage)
5   FROM cpu
6   WHERE time > now() - 1h
7   GROUP BY time(5m), host"

66. 查看 InfluxQL 执行计划

Bash

1influxdb3 query \
2  --database sensors \
3  --language influxql \
4  "EXPLAIN SELECT mean(usage) FROM cpu"

67. 通过 HTTP 执行 InfluxQL

Bash

1curl -sS -G \
2  "http://127.0.0.1:8181/api/v3/query_influxql" \
3  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
4  --data-urlencode "db=sensors" \
5  --data-urlencode "q=SELECT * FROM cpu LIMIT 10"

Flux 在 InfluxDB 3 中不受支持，不要使用 InfluxDB 2.x 的 Flux 示例。

七、Last Cache 与 Distinct Cache

68. 创建 Last Value Cache

Bash

1influxdb3 create last_cache \
2  --database sensors \
3  --table cpu \
4  --key-columns host \
5  --value-columns usage,temp \
6  cpu_last

69. 查看 Last Cache

Bash

1influxdb3 show system \
2  --database sensors \
3  table last_caches

70. 查询 Last Cache

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT * FROM cpu_last"

缓存对应的系统表和查询名称应以创建结果为准。

71. 删除 Last Cache

Bash

1influxdb3 delete last_cache \
2  --database sensors \
3  --table cpu \
4  cpu_last

72. 创建 Distinct Value Cache

Bash

1influxdb3 create distinct_cache \
2  --database sensors \
3  --table cpu \
4  --columns host,region \
5  cpu_tags

73. 查看 Distinct Cache

Bash

1influxdb3 show system \
2  --database sensors \
3  table distinct_caches

74. 查询 Distinct Cache

Bash

1influxdb3 query \
2  --database sensors \
3  "SELECT * FROM cpu_tags"

75. 删除 Distinct Cache

Bash

1influxdb3 delete distinct_cache \
2  --database sensors \
3  --table cpu \
4  cpu_tags

缓存位于内存中，高基数配置会增加内存压力。

八、Processing Engine

76. 查看已加载插件

Bash

1influxdb3 show plugins

77. 安装 Python 插件依赖

Bash

1influxdb3 install package requests

安装方式和可用依赖受当前版本及部署策略限制。

78. 创建定时触发器

Bash

1influxdb3 create trigger \
2  --database sensors \
3  --plugin-filename hourly_check.py \
4  --trigger-spec "every:1h" \
5  hourly_check

79. 创建写入触发器

Bash

1influxdb3 create trigger \
2  --database sensors \
3  --plugin-filename alert.py \
4  --trigger-spec "all_tables" \
5  write_alert

Trigger Spec 的支持形式应以当前 Processing Engine 文档为准。

80. 禁用触发器

Bash

1influxdb3 disable trigger \
2  --database sensors \
3  hourly_check

81. 启用触发器

Bash

1influxdb3 enable trigger \
2  --database sensors \
3  hourly_check

82. 更新触发器

Bash

1influxdb3 update trigger \
2  --database sensors \
3  --plugin-filename hourly_check_v2.py \
4  hourly_check

83. 删除触发器

Bash

1influxdb3 delete trigger \
2  --database sensors \
3  hourly_check

84. 强制删除活动触发器

Bash

1influxdb3 delete trigger \
2  --database sensors \
3  --force \
4  hourly_check

85. 查看触发器系统表

Bash

1influxdb3 show system \
2  --database sensors \
3  table triggers

九、系统信息与诊断

86. 查看全部系统表

Bash

1influxdb3 show system \
2  --database sensors

87. 查看服务器日志

Bash

1journalctl -u influxdb3 \
2  --since "30 minutes ago"

88. 实时跟踪日志

Bash

1journalctl -u influxdb3 -f

89. 查看服务状态

Bash

1systemctl status influxdb3

90. 查看监听端口

Bash

1ss -lntp | grep 8181

91. 查看进程资源

Bash

1ps -eo pid,cmd,%cpu,%mem,rss \
2  | grep '[i]nfluxdb3'

92. 查看存储容量

Bash

1du -sh /var/lib/influxdb3
2df -h /var/lib/influxdb3

对象存储部署还应检查 Bucket 容量、请求错误和生命周期策略。

93. 查看文件句柄限制

Bash

1ulimit -n

94. 查看 CLI 调试命令

Bash

1influxdb3 debug --help

95. 查看 Docker 容器状态

Bash

1docker ps \
2  --filter name=influxdb3

十、备份恢复与快速巡检

96. 停止 InfluxDB 3 服务

Bash

1systemctl stop influxdb3

97. 按官方顺序备份本地对象存储

Bash

1rsync -a \
2  /var/lib/influxdb3/node01/ \
3  /backup/influxdb3/node01/

InfluxDB 3 Core 没有内置备份命令。为保证一致性，应按官方文档规定的顺序复制 Catalog Checkpoint、Catalog、WAL、数据库文件和 Snapshot，并优先在停库或低负载窗口执行。

98. 启动 InfluxDB 3 服务

Bash

1systemctl start influxdb3

99. 校验恢复后的数据

Bash

1influxdb3 show databases
2influxdb3 query \
3  --database sensors \
4  "SELECT count(*) FROM cpu"

还应抽样验证最近时间点、Tag、字段类型、缓存和触发器。

100. 执行快速巡检

Bash

1systemctl status influxdb3
2curl -s http://127.0.0.1:8181/health
3influxdb3 show databases
4influxdb3 show tokens
5influxdb3 show system --database sensors
6df -h /var/lib/influxdb3
7journalctl -u influxdb3 --since "1 hour ago"

每日巡检应同时关注写入错误、查询延迟、WAL、对象存储、磁盘容量、Token 到期、缓存内存、触发器失败和备份可恢复性。

结语

InfluxDB 3 已经不是 InfluxDB 2.x 的简单升级版。运维时应围绕对象存储、Parquet、WAL、SQL/InfluxQL 和新 influxdb3 CLI 建立知识体系，避免继续套用 Bucket、Organization 和 Flux 的旧命令。

Core、Enterprise 与 Cloud 的功能边界变化较快，尤其是查询范围、Token 权限、备份、集群和 Processing Engine。生产使用前应固定版本，并用对应版本官方文档逐项核对。