1. 为什么我劝你用 InfluxDB 之前先把这几条命令背熟两三年前我第一次在监控项目里接触 InfluxDB当时最大的困惑不是它能不能存数据而是它和 MySQL、MongoDB 那套直觉完全不搭。表不叫表叫 measurement行不叫行叫 point字段还分 tag 和 field写入数据也不是 insert 语句而是看起来像日志的一行文本。那段时间我几乎每天都要敲help翻命令踩了不少坑时间范围查不出数据、field 字段当成 tag 用导致基数爆炸、删了数据但磁盘占用一点没降。后来我才慢慢意识到InfluxDB 的基础命令并不只是几条语法而是一整套围绕时间序列数据设计的思维方式。这篇东西我整理了很久会把我在实际项目里反复用到的 InfluxDB 基础命令、关键概念和踩坑经验一次性讲清楚。适合刚接触时序数据库的开发者也适合已经用了一段时间但总感觉命令不够熟、查询写得不够顺的人。我会以 InfluxDB 1.x 的命令行工具 influx CLI 为主线来展开因为 1.x 到现在依然有大量生产环境在用而且理解 1.x 的命令逻辑之后再去看 2.x 的 Flux 语言会轻松很多。2. 数据模型先行measurement、tag、field、time 到底是什么在敲任何命令之前我建议你先花十分钟搞懂 InfluxDB 的四要素。很多命令之所以写得别扭不是因为语法难而是因为你脑子里还挂着关系型数据库的模型。2.1 四要素与 SQL 概念的对照如果把 InfluxDB 的一个 point数据点类比成关系型数据库的一行那么measurement 对应表名比如cpu、memory、sensor_datatag 对应带索引的列通常存放离散、可枚举的元信息比如主机名 host、区域 region、设备编号 device_idfield 对应真正随时间变化的数值列比如 value、temperature、usage_ratetime 是主键和时间戳默认纳秒精度。这里最关键的区别是tag 有索引field 没有索引。这意味着你在WHERE里过滤 tag 是高效的而直接对 field 做过滤性能会差很多。我见过不少人把温度、湿度这种连续值塞进 tag结果基数cardinality瞬间爆炸内存被吃满查询也肉眼可见地变慢。反过来把主机名塞进 field又会导致按主机过滤时必须全表扫描明明一分钟能出的报表跑了十分钟。2.2 为什么 InfluxDB 要用行协议写入InfluxDB 的命令行写入不是 SQL 的INSERT INTO ... VALUES ...而是行协议line protocol格式如下measurement[,tag_keytag_value...] field_keyfield_value[,field_key2field_value2...] [timestamp]比如cpu,hostweb01,regioncn-east usage_rate62.3,idle37.7 1680000000000000000这个设计看起来很朴素但正是这个一行一条记录的格式让 InfluxDB 在写入路径上做足了优化字符串解析一次字段类型固定时间戳有序追加。你一旦理解了行协议后面看写入性能问题、看官方文档里的示例都会顺畅很多。3. 环境准备与进入 influx 命令行3.1 连接 InfluxDB 的几种方式不管你是刚装好 InfluxDB还是要排查一个存量实例第一步基本都是进入命令行客户端。最常用的方式是在服务器上直接执行influx默认连接本机的 8086 端口以管理员身份进入。如果你的服务跑在别的机器或端口可以用参数指定influx -host 192.168.1.10 -port 8086 -username admin -password xxxxxx如果没有配置认证可以只写influx -host x.x.x.x。我建议养成一个习惯进命令行之后先敲基础的help看当前版本支持的语法因为 1.7 和 1.8 在部分细节上有一点点差异碰到陌生环境时这是最稳的探路方式。3.2 命令行里常用快捷操作命令行里的一些非查询类命令也很基础但很常用help # 查看帮助 exit # 退出客户端 clear # 清空当前输入的 buffer pretty # 切换输出格式让查询结果竖排展示pretty这个命令我重点说一下。默认查询结果在终端里是横向表格字段一多就挤成一团根本看不清。敲一下pretty再执行查询结果会按行竖排展开排查数据时非常舒服。你要是不想在会话里切换也可以直接在查询语句后面加tty参数比如 select * from cpu tty这在输出内容很宽时特别好用。4. 数据库与表结构的常用操作命令4.1 数据库的增删查数据库层面的命令和 MySQL 很像容易记 show databases create database mydb drop database mydb use mydb建议项目启动时把数据库名作为隔离的基本单位一个业务一个库不要全部堆在默认库_internal或者telegraf里。库存量大了以后备份、权限控制、数据清理都会清晰很多。drop database 这个命令我建议你在生产环境谨慎再谨慎它不会问你确认回车就没了而且 InfluxDB 删除数据库不会立刻释放磁盘空间后面我会讲这个问题。4.2 查看表结构show measurements 与 show field/tag keys进入一个库之后最常用的查看命令有三条 show measurements show field keys show tag keysshow measurements列出当前数据库里所有 measurement相当于 MySQL 的show tables。show field keys和show tag keys分别告诉你每个 measurement 下面的字段类型分布这对你判断这个字段到底能不能聚合、能不能 group by很有帮助。我还经常用show series来查看一个 measurement 下所有 tag 组合的基数情况 show series on mydb from cpu如果返回的行数远超预期说明 tag 设计可能有问题比如某个高基数标签混进来了。4.3 查看分片与保留策略相关命令如果你需要确认数据落到了哪些 shard可以用 show shards show shard groups这两个命令在排查为什么查询这么慢为什么旧数据还没被清理时很关键。InfluxDB 是按时间分片的数据保留策略和分片组shard group的持续时间是强相关的理解了分片机制很多保留策略的坑就能提前避开。5. 数据写入从 insert 到批量导入5.1 用 insert 手动写入一条数据命令行里写入数据用insert后面直接跟行协议。比如 use mydb insert sensor,devicedevice_01,roomroom_a temperature25.6,humidity65.2不指定时间戳时InfluxDB 会使用服务端当前时间。如果需要指定过去某个时间点的数据直接加纳秒时间戳 insert sensor,devicedevice_01 temperature24.8 1672531200000000000这里有一个新手最容易犯的错时间戳精度。默认 InfluxDB 存储和显示用的是纳秒但如果你拿的是秒级或毫秒级时间戳就要在 HTTP 写入接口或客户端参数里声明精度否则写入的数据时间会完全错乱。命令行 CLI 里默认也是纳秒但可以通过环境变量或参数调整。5.2 批量导入influx -import实际项目里很少一条条 insert更多是把历史数据批量导进去。常用的是influx -importinflux -import -path/data/history.txt -databasemydb -precisionns导入文件的格式就是一行的行协议文件里还可以用# DDL注释来写建库语句。我踩过的坑是文件里如果同时包含建库语句和数据行-database参数可能会被文件里的CREATE DATABASE覆盖或者反过来插入的库不对。建议建库语句和数据分开数据文件统一指定-database和-precision这样导入过程可控性最好。还有一个细节-import默认是遇到错误继续执行但你最好先在小样本文件上跑一遍确认没有类型冲突或时间戳问题再上全量。我已经不止一次因为源数据里有几条格式异常导致导入完成后统计出来的数量和预期对不上。5.3 写入时的常见错误对照错误现象原因解决办法unable to parse行协议格式不对常见是 field 和 tag 写反检查逗号、等号、空格位置field type conflict同一个 field 在不同时间点被写入了不同数据类型统一 field 类型或换 field 名时间错乱时间戳精度单位不对确认数据源精度与写入参数保持一致数据基数过大把高基数数据放到了 tag将高基数连续值放入 field6. 数据查询InfluxQL 基础命令实战6.1 最基础的查询结构InfluxQL 的查询语句长得像 SQL但有一些自己的规矩。比如 select * from cpu select usage_rate, idle from cpu where hostweb01 select * from cpu limit 10默认返回的数据按时间正序排列也就是最早的在最上面。如果你想要最新的数据在前要加order by time desc select * from cpu order by time desc limit 10我建议任何查看最近状态的查询都养成order by time desc的习惯默认正序在数据量大时你会一直拉到最旧的记录。6.2 时间范围过滤理解 InfluxDB 的灵魂操作时序数据库几乎每一次查询都会带上时间范围。InfluxDB 里时间过滤用的是time字段支持相对时间和绝对时间 select * from cpu where time now() - 1h select * from cpu where time 2024-01-01T00:00:00Z and time 2024-01-02T00:00:00Z select * from cpu where time now() - 7d这个语法里最容易踩的坑是时区。如果你直接用本地时间的字符串不带时区后缀InfluxDB 会默认按 UTC 处理。我调试过一个报表数据总是差 8 个小时后来发现就是因为查询串里的时间是北京时间而 InfluxDB 按 UTC 存储和解析。解决方法有两种一是写入时统一用 UTC显示时再转换二是在查询里明确带时区比如time 2024-01-01T00:00:0008:00。相对时间写法里的单位也值得注意s秒、m分钟、h小时、d天、w周。now() - 1d表示 24 小时前而不是今天凌晨很多人在这里理解有偏差。6.3 group by time聚合查询的正确姿势InfluxDB 最核心的优势就是时间维度聚合。要把原始数据按分钟、小时、天聚合用group by time select mean(usage_rate) from cpu where time now() - 24h group by time(1h) select max(temperature) from sensor where time now() - 7d group by time(1d)group by time(1h)的括号里可以是任意时间长度比如30m、1h、1d。它会把数据按时间窗口切分然后对每个窗口执行聚合函数。聚合函数常用的有mean、max、min、sum、count、median、percentile。这个操作很多人一开始会困惑的地方是group by time和普通 SQL 的group by不一样它不需要把时间字段显式写在 select 里。InfluxDB 会自动按窗口对齐。如果你同时要按 tag 分组可以用 select mean(usage_rate) from cpu where time now() - 1h group by time(10m), host返回结果会是每个 host 在每个 10 分钟窗口的平均值。这种查询在监控面板里非常常见。6.4 聚合结果为空时的 fill 处理聚合查询里一个经典坑是某个时间窗口内没有任何数据结果里这个窗口默认是空的图表上会断线。要补值就要用fill select mean(usage_rate) from cpu where time now() - 6h group by time(1h) fill(0) select mean(usage_rate) from cpu where time now() - 6h group by time(1h) fill(null) select mean(usage_rate) from cpu where time now() - 6h group by time(1h) fill(previous)fill(0)会把没有数据的窗口填成 0适合流量统计fill(previous)用前一个窗口的值填充适合监控指标补线fill(null)则保留空值。默认的行为是忽略空窗口这在某些场景下图表会变得很难看所以做报表时建议总是显式写明 fill 策略。6.5 查询命令的常用组合与脚本化如果要把查询结果用于脚本处理可以用influx命令的-execute参数一步到位influx -databasemydb -executeselect mean(usage_rate) from cpu where time now() - 1h group by time(1h) -formatcsv-format支持line、csv、json、column。其中csv是我最常用的因为后续导入 Python 或数据处理工具非常方便。还有一个小技巧-formatjson可以和 jq 搭配做复杂的过滤和清洗比如influx -databasemydb -executeshow measurements -formatjson | jq .results[0].series[0].values这个组合我在写巡检脚本时用了很多次基本可以替代一部分 HTTP API 的工作。7. 保留策略、连续查询与数据治理7.1 保留策略为什么你的磁盘一直不见少InfluxDB 默认的保留策略叫autogen数据永久保留。生产环境基本都会按业务需求加上保留策略 show retention policies on mydb create retention policy rp_30d on mydb duration 30d replication 1 default alter retention policy rp_30d on mydb duration 90d shard duration 7d drop retention policy rp_30d on mydbduration决定数据保留多久shard duration决定多长时间的数据放在一个分片组里replication在单机版里填 1 即可。有一个经验值shard duration 最好不要超过 retention duration 的一半因为 InfluxDB 要等一个 shard 完全过期之后才能真正删除它。我见过一个配置retention 设置为 1d但 shard duration 默认是 7d结果过期的数据一直不能被清理白白占着磁盘。排查下来才发现是这个参数在作怪。7.2 删除数据drop series 和 delete如果你需要清理特定条件的数据InfluxDB 提供了两个命令 delete from cpu where time 2024-01-01T00:00:00Z drop series from cpu where hostweb01这里有一个重要的坑delete删除的数据只是标记删除磁盘空间不会立即释放要等 compaction 或 shard 过期。更关键的是delete和drop series在 tag 上的处理不同drop series 会同时删除对应的 series 元数据delete 则只删数据点。如果你发现删完数据后查show series还有记录大概率是用了 delete 而不是 drop series。7.3 连续查询自动降采样的利器监控数据通常不需要永久保留秒级精度可以把历史数据降采样到分钟级或小时级原始数据保留一段时间后自动过期。InfluxDB 的连续查询Continuous Query简称 CQ就是干这件事的 create continuous query cq_1h_cpu on mydb begin select mean(usage_rate) into cpu_1h from cpu group by time(1h) end这个 CQ 会每隔一段时间自动执行一次把原始表 cpu 的数据聚合后写入 cpu_1h 表。查询的时候读明细走原始表看趋势走降采样表性能和成本都能兼顾。停止或删除 CQ 用 drop continuous query cq_1h_cpu on mydb show continuous queries我用 CQ 时遇到最多的问题是为什么 CQ 不执行或执行出来结果比预期少。通常原因有三个一是 CQ 默认只处理最近的数据如果你补录了历史数据它不会自动重新聚合二是 CQ 的 group by time 窗口必须和数据写入的时间范围匹配否则部分窗口可能为空三是在 1.x 中 CQ 的调度周期由resample every for控制如果没配置默认与 group by time 的窗口相同在数据延迟写入时容易出现窗口遗漏。7.4 查看统计与管理命令最后提几条日常运维必备的管理命令 show stats show diagnostics show users show queries kill query idshow stats可以看写入点数、查询耗时、主动合并次数等运行时指标show queries能列出正在执行的查询配合kill query 查询ID可以杀掉慢查询。我在排查系统卡顿的时候第一件事就是show queries看是不是有人跑了一个没加时间范围的聚合查询把整个实例拖垮了。8. 基于上述基础命令的三种完整实战场景光把命令拆开讲你可能会觉得不够直观。我挑三个实际工作中反复出现的场景展示命令怎么串起来用。8.1 场景一监控面板的最近5分钟CPU趋势目标是把测试环境所有主机的 CPU 使用率按 1 分钟粒度展示最近 5 分钟的趋势。完整命令如下 use telegraf select mean(usage_rate) from cpu where time now() - 5m group by time(1m), host fill(null)这里group by time(1m), host会按主机分开输出面板上每条线代表一台机器。fill(null)是为了保留空窗口避免图表时间轴跳变。如果发现某些主机没数据可以用 show tag values from cpu with key host确认实际的 host 标签值而不是凭记忆猜。8.2 场景二每日报表的分钟级数据降采样假设 sensor 表的数据量很大我们需要按天统计每台设备的平均温度同时把原始 1 分钟数据保留 30 天后自动清理降采样数据保留一年。操作如下 create database sensor_db use sensor_db create retention policy rp_raw on sensor_db duration 30d replication 1 default create retention policy rp_1y on sensor_db duration 365d replication 1 create continuous query cq_temp_daily on sensor_db begin select mean(temperature) into sensor_db.rp_1y.temp_daily from sensor_db.rp_raw.sensor group by time(1d), device_id end这段的关键点在于 CQ 的into可以指定写入不同的保留策略这样原始数据在 rp_raw 中保留 30 天而降采样结果在 rp_1y 中保留一年。查询每日均温时走 temp_daily 表速度快很多而且不受原始数据过期影响。8.3 场景三快速定位某个时间点附近的异常值如果业务方问昨晚 23:40 到 23:45 之间某台机器的指标为什么异常我会用这条命令 select * from cpu where hostweb01 and time 2024-06-01T23:40:0008:00 and time 2024-06-01T23:45:0008:00 order by time desc注意这里时区用的是 08:00避免了 8 小时偏差。如果数据量不大可以直接select *把原始点拉出来如果数据量很大先select count(*)看看有多少条再决定是否加 limit 或聚合。9. 常见问题与排查技巧实录9.1 查询结果为空但明明有数据这是最多人踩的坑原因通常是三个一是时间范围没对上。检查你的时间字符串有没有带时区检查now() - 1d和业务上的昨天是不是同一个概念。二是选择错了数据库进库之前先show databases确认当前use的库。三是 tag 条件写错比如 host 值里面有隐藏空格用show tag values检查真实值。9.2 field type conflict 报错这是 InfluxDB 1.x 最经典的报错之一。同一个 field 字段比如temperature第一次写入是浮点数第二次写入却变成了字符串InfluxDB 会拒绝查询或写入。我遇到的情况多是源数据在异常时输出了NaN或unknown这类文本。解决方法是在采集端做类型清洗或者换一个字段名比如temperature和temperature_text分开。9.3 删除数据库后磁盘空间没释放InfluxDB 的删除操作默认是标记删除物理空间要等后台压缩任务或 shard 过期回收。如果你需要立即释放磁盘可以手动触发压缩influx_inspect compact -path /var/lib/influxdb/data不过这个命令要在 InfluxDB 服务停止的状态下跑否则会冲突。正常情况下不建议为了省空间频繁手动压缩等 shard 自然过期就好。9.4 常见问题速查表现象排查思路常用命令查不到数据库名、时间范围、tag 值show databases; show tag values时间差了 8 小时时区问题检查字符串 08:00 后缀查询很慢无时间范围/字段未优化加时间范围、避免 field 过滤字段类型冲突源数据异常show field keys 检查类型磁盘占用只增不减shard 未过期show shards; show retention policiesCQ 不执行窗口或调度配置问题show continuous queries; resample 配置9.5 一个容易被忽略的独家技巧用 influx_inspect 快速验证数据如果你怀疑某条数据没写进去或者想知道某个 shard 到底存了什么可以用influx_inspect工具直接读取底层数据文件做校验influx_inspect report -detailed /var/lib/influxdb/data/mydb/rp_30d这个命令不会经过查询引擎能在服务高负载时帮你快速确认数据是否存在。我做数据迁移核对时经常用它跟select count(*)交叉验证发现过几次查询层统计和底层数据不一致的问题排查效率提升很明显。10. 写在最后的几条个人体会玩了几年 InfluxDB最大的体会是它虽然命令简单但背后每一条都有明确的场景设计。测量值field不带索引、标签tag带索引是为了高效写入和快速过滤时间戳统一纳秒精度是为了跨机器对齐连续查询和保留策略绑定是因为时序数据天生具备热数据价值高、冷数据可降采样的特点。理解了这些设计意图命令记忆负担会小很多因为你不会再背语法而是知道遇到这个场景该用什么。再分享一个小技巧我建议你别只盯着交互式 CLI尽早把常用查询写成脚本文件用influx -execute和-formatcsv封装起来配合系统定时任务就能形成一套自动巡检工具。我后来很多线上问题的发现靠的都是这些脚本在凌晨自动跑出来的异常报表而不是等业务方来反馈。InfluxDB 还有很多东西没展开比如连续查询的 resample 策略、连续查询与INTO多级降采样的组合设计这些有机会单独再写。上面这些基础命令覆盖了我日常 80% 以上的操作如果你能把它们练到不用翻文档就能写顺之后的进阶之路会平坦很多。