简介这是一份 influxdb-nodejs 资源包即用 Node.js 编写的 InfluxDB 客户端源码面向需要读写时序数据、在 Node 或前后端项目中集成 InfluxDB 的 JavaScript 开发者。内含初始化、写入、读取、批量写入、查询等典型调用的实战示例并附带 API 文档、HTML 代码浏览页及 Express、Koa 集成例子适合初学者快速上手对中级工程师二次开发有参考价值。压缩包共 60 个文件以 30 个 JavaScript 源码为主辅以 HTML 文档页、Markdown 说明、npm 配置、样式图片约 262KB按 lib、examples、docs 分目录便于检索。目前已有 579 人浏览学习代码注释完整便于阅读、运行和扩展。1. 先搞清楚这是什么给 Node.js 服务的 InfluxDB 写入与查询客户端做后端服务的人应该都有这种经历服务起来了、接口通了老板说要加监控数据往哪放你调研一圈发现时序数据库里 InfluxDB 是最顺手的然后打开 Node.js 这边一看官方客户端要么太重、要么 API 风格和项目里其它部分对不上。influxdb-nodejs 就是在这个场景下被翻牌子的它是一个纯粹的 JavaScript 实现的 InfluxDB 客户端把最常用的写入、查询、批量提交封装成 Promise 接口你不需要自己去拼 HTTP 请求也不用记 InfluxDB 那一套 line protocol 转义规则。适合谁适合那些服务端语言是 Node.js、又不想为了时序数据引入一套 Java/Go 中间件的团队也适合写脚本做数据校验的人——安装一个 npm 包就能连库读写比用 curl 拼 URL 省心得多。2. 安装与初始化用几行代码建立到 InfluxDB 的连接2.1 安装依赖与基础连接参数先装依赖这个没什么好说的npm install influxdb-nodejs --save安装完以后初始化一个客户端实例。这个库的构造函数接收一个配置对象下面是我在一个埋点上报服务里用到的写法const InfluxDB require(influxdb-nodejs); const client new InfluxDB({ host: 127.0.0.1, port: 8086, protocol: http, database: monitor_db, username: monitor_rw, password: your_password, poolSize: 10 });参数说明host和portInfluxDB 服务端地址。默认端口 8086 是 HTTP API 的端口注意不是 8088那是备份用的 RPC 端口这个我一开始搞混过。protocolhttp或https。如果 InfluxDB 前面挂了 Nginx 做 TLS 终止这里就要改成https。database目标数据库名。这个库不会帮你自动建库数据库不存在时写入会直接报错后面避坑章节我会专门说。username/passwordInfluxDB 1.x 的认证信息。如果是 2.x 版本并且开了兼容端点这里的 password 位置通常放 token。poolSize连接池大小。默认值偏保守如果你的服务写入 QPS 比较高建议手动调大具体多大看你的 InfluxDB 所在机器能扛多少并发。初始化这一步最常见的坑是忘记指定database或者指定了但库里实际不存在。你会在写入时才炸所以我的习惯是初始化后立刻做一次连通性检查而不是等业务写挂了才发现。2.2 先用一条写入和一次查询跑通全链路连接配置好了先别急着封装业务代码写一条最简单的写入和查询确认整条链路是通的。写入长这样// 写入一条数据measurement 为 cpu_usagetag 标识主机field 存实际数值 client.write(cpu_usage) .tag({ host: web-server-01, region: cn-east }) .field({ usage: 63.5, idle: 36.5 }) .then(() console.log(write ok)) .catch((err) console.error(write failed:, err.message));这段代码的逻辑是先指定 measurement 名称然后用tag()方法挂标签用field()方法挂字段值。tag()和field()的区别在 InfluxDB 里很关键——tag 会被索引适合放在查询条件里field 不被索引存真正的数值。把 IP 这类高基数信息放 tag 里是新手最容易犯的错高基数 tag 会拖垮 InfluxDB 的内存索引。查询更简单直接传 InfluxQL 字符串const res await client.query( select * from cpu_usage where time now() - 1h order by time desc limit 10 ); console.log(res);返回的res是 InfluxDB HTTP API 的原始结构——results[0].series[0]里有columns数组和values二维数组columns和values按顺序对应。你大概率会在这里面翻车因为多数人直觉上会以为返回的是对象数组但它其实是列名 值列表。如果你想要对象数组就得自己做个映射const series res.results[0].series[0]; const rows series.values.map((v) Object.fromEntries(series.columns.map((c, i) [c, v[i]])) );这段转换逻辑没有魔法就是把 InfluxDB 的列式返回转成行式对象后面封装数据访问层时能省很多事。2.3 连接配置差异1.x、2.x 兼容端点与 HTTPSInfluxDB 2.x 出来以后API 端点和认证方式都改了很多人以为这个客户端就废了其实不然。2.x 默认提供/api/v2/query和/api/v2/write但同时也保留了 1.x 兼容端点只是默认没开。要在 2.x 上使用 influxdb-nodejs 这类 1.x 风格客户端你需要在 InfluxDB 配置里启用 1.x 兼容 HTTP 端点通常是flux-enabled true和http-enabled true。创建数据库时用 1.x 的create database语句而不是 2.x 的 bucket 概念兼容端点会把database参数映射到 bucket。认证时username 填 2.x 的用户名password 位置填该用户的操作 token。如果你用的是 2.x 且没有开兼容端点最直观的报错是 404因为/query和/write这两个路径根本不存在。这种情况下要么去开兼容端点要么换个原生支持 2.x API 的客户端不要在这个库上死磕。HTTPS 场景下还有一个隐蔽问题如果 InfluxDB 用自签证书Node.js 默认会拒绝连接报self-signed certificate。有些项目图省事会全局关掉证书校验但这是拿整个服务的安全性换一次连库成功不值得。正确做法是把证书路径传给客户端或者在你的服务层单独配置这个客户端的ca参数。3. 数据模型映射measurement、tag、field 与时间戳的转换3.1 line protocol 的本质从对象到一行文本influxdb-nodejs 之所以写起来比直接拼字符串体验好是因为它帮你把 JavaScript 对象转换成了 InfluxDB 的行协议line protocol。行协议是 InfluxDB 写入端的核心概念每一行代表一个数据点结构是measurement,tag_keytag_value field_keyfield_value timestamp注意几个分隔符的差异measurement 和 tag 之间用逗号tag 之间也用逗号tag 和 field 之间用空格多个 field 之间用逗号最后跟时间戳用空格隔开。我来模拟一下这个客户端内部做的事// 模拟客户端内部的行协议组装过程简化版 function toLineProtocol(measurement, tags, fields, timestamp) { const tagStr Object.entries(tags) .map(([k, v]) ${escapeTag(k)}${escapeTag(String(v))}) .join(,); const fieldStr Object.entries(fields) .map(([k, v]) ${escapeKey(k)}${formatValue(v)}) .join(,); return ${measurement},${tagStr} ${fieldStr} ${timestamp}; }代码逻辑不复杂tag 部分要处理 key 和 value 的转义field 部分要看值类型决定怎么写。这里的转义坑在于tag value 里的逗号和空格必须转义成\,和\而 field 的字符串值要用双引号包起来。很多看起来是客户端 bug 的写入失败拆开看其实是转义规则没走对。3.2 时间戳传入方式与精度选择时间戳是 InfluxDB 使用里最容易被忽视的细节。这个客户端支持的常见传法有三种// 方式一不传时间戳让 InfluxDB 使用服务端时间 client.write(cpu_usage) .tag({ host: web-server-01 }) .field({ usage: 63.5 }) .then(() console.log(server timestamp used)); // 方式二传 Date 对象 client.write(cpu_usage) .tag({ host: web-server-01 }) .field({ usage: 63.5 }) .time(new Date()) .then(() console.log(date object used)); // 方式三传毫秒时间戳数字 client.write(cpu_usage) .tag({ host: web-server-01 }) .field({ usage: 63.5 }) .time(Date.now()) .then(() console.log(ms timestamp used));三种方式对应不同的数据写入场景。不传时间戳时以服务器时间为准适合写入频率低、不需要精确回放顺序的场景但代价是大量并发写入时InfluxDB 内部会对同一时间戳的数据做合并或去重。传Date对象时客户端会取出它的毫秒值传数字时毫秒值直接进入行协议。真正要留意的是精度声明。InfluxDB 默认按纳秒解析时间戳如果你给的是毫秒值但没有告知服务端精度它会把毫秒数当成纳秒数时间直接缩水一百万倍查询出来的time字段会变成 1970 年的某一天。这个客户端在.time()之后一般通过链式或构造参数指定precision比如ms、s、u、ns四种。我一般固定用ms因为 JavaScript 的Date.now()天然就是毫秒。3.3 字段类型边界int、float、string、bool 的序列化规则InfluxDB 的 field 类型不是声明出来的是写入时由行协议里的写法推断的。行协议里数字默认是 float整数需要在数字末尾加i后缀布尔值写true/false字符串用双引号包住。这个客户端遵循同样的规则但 JavaScript 本身没有明显的整数/浮点之分所以类型推断就容易出问题// 正确写法与错误写法对照 const points [ { measurement: disk_io, tags: { disk: sda1 }, fields: { read_iops: 1024, write_iops: 256n, readonly: false, model: SSD-512 } } ];先看read_iops: 1024——如果直接提交InfluxDB 会把它存成 float查询出来变成1024.0。有些报表工具对整数字段有要求这时候就得让它识别成整数。这个库在 1.x 时代走的是「数字按 float 提交」的路线你如果需要整数字段常见做法是在字段值上做标记或者在数据写入前自行拼行协议字符串用1024i这种写法。字符串和布尔值相对安全字符串会被加双引号布尔值转小写true/false。但如果你不小心把布尔值传成了字符串trueInfluxDB 会把它存成字符串类型查询时用 true过滤会查不到。这个错 bug 非常恶心因为肉眼完全看不出来只有写查询语句对比字段类型时才能发现。4. 批量写入与性能从单条 insert 到定时刷盘4.1 攒批与定时 flush控制写入粒度逐条写入简单但性能上是最差的方案。每一条数据都是一次 HTTP 请求TCP 握手、请求头、响应解析全走一遍吞吐量上不去还会把 InfluxDB 的写入 WAL 拖出大量小文件。常见做法是维护一个内存队列攒够一定条数或每隔一定时间批量提交一次。下面的代码是我在模拟项目 X 里用过的批量写入模板class BatchWriter { constructor(client, { batchSize 200, flushInterval 5000 } {}) { this.client client; this.batchSize batchSize; this.flushInterval flushInterval; this.queue []; this.timer setInterval(() this.flush(), this.flushInterval); } add(measurement, tags, fields, timestamp) { this.queue.push({ measurement, tags, fields, timestamp }); if (this.queue.length this.batchSize) { this.flush(); } } async flush() { if (this.queue.length 0) return; const batch this.queue.splice(0, this.batchSize); // 组装批量写入请求这里调用客户端的批量接口 try { await this.client.writeBatch(batch); } catch (err) { // 失败时先塞回队列保留现场供重试 this.queue.unshift(...batch); console.error(batch write failed:, err.message); } } }逻辑说明add()先把数据点放进队列长度达到阈值就触发一次flush()setInterval保证即使数据一直攒不够也会定时清空避免低峰期数据长时间滞留内存。batchSize决定单个 HTTP 请求体的大小flushInterval决定数据最大延迟时间。这两个参数要怎么设我的经验是单条 line protocol 约为 200 字节时batchSize取 5002000 之间比较合适太小起不到批量效果太大则一次请求体可能超过 InfluxDB 网关的请求体限制flushInterval按业务容忍的数据延迟定监控类场景选 35 秒日志类场景可能放宽到 10 秒以上。改完参数后要观察内存占用——队列积压说明消费速度跟不上生产速度这时候优先查 InfluxDB 写入耗时而不是继续调大 batch。4.2 重试与丢弃策略丢数据还是延迟批量写入一定会遇到失败网络抖动、InfluxDB 重启、写入超时都可能导致整批数据写不进去。重试策略直接影响两个指标数据完整性上限和写入延迟分布。我的做法是分层处理第一层网络类错误超时、连接重置直接重试因为它们大概率是瞬时故障。第二层HTTP 4xx 错误不重试因为这类错误是请求本身有问题库不存在、字段类型非法、权限不足重试多少次结果都一样只会刷爆日志。第三层5xx 错误做有限重试指数退避间隔从 200ms 开始翻倍到最多 3 次。async function writeWithRetry(writeFn, retries 3) { let delay 200; for (let attempt 1; attempt retries; attempt) { try { return await writeFn(); } catch (err) { if (attempt retries || err.statusCode 400 err.statusCode 500) { throw err; } await new Promise((resolve) setTimeout(resolve, delay)); delay * 2; } } }注意指数退避的陷阱重试时如果队列里积累了多批数据同时重试会造成请求风暴反而把刚恢复的 InfluxDB 又压垮。所以要限制重试队列的并发数常见做法是给重试任务加一个信号量最多同时两个写入请求在飞。还有一种情况值得主动丢数据实时性要求高、数据量又大的场景。比如埋点数据丢了某一秒的几条计数对统计结果影响微乎其微但阻塞写入会让整个服务卡住。这时候「丢」是有意识的选择——我在日志采集服务里会设置队列上限 50000 条超过上限直接丢弃最老的数据并打一条 warn 日志。生产环境里可观测性的核心是系统稳定而不是每一行日志都无损送达。4.3 并发控制与连接池别被慢查询拖垮InfluxDB 客户端的并发模型比很多人想象中要敏感。一个 Node.js 进程往 InfluxDB 写数据如果同时还在跑大范围聚合查询慢查询会占用连接池里的连接写入请求排队最终表现为「数据延迟到达」。我在监控系统里常用的隔离手段是把读写连接分开const writeClient new InfluxDB({ host, port, database, poolSize: 20 }); const queryClient new InfluxDB({ host, port, database, poolSize: 5 });两个连接池独立写流量不会被读流量阻塞。poolSize不是越大越好——它决定的是 HTTP keep-alive 连接数不是 Node.js 异步能力。连接数太多会让 InfluxDB 端的并发 goroutine 数上升内存压力变大太少则在突发流量下排队时间直线上升。一般服务刚开始用默认值压测时观察 InfluxDB 的写入延迟 P99超过 50ms 就调大一点没必要追求极端值。另外一个更隐蔽的问题批量写入时一次请求发了几千条数据如果客户端的批量接口把「拼接行协议」和「发送 HTTP 请求」放在同一个线程里大批量数据会阻塞事件循环。遇到这种情况可以分小批发送一次 500 条发完再发下一批数据量没少延迟反而更低。5. 避坑手册接入 InfluxDB 后最常见的五个翻车点5.1 写入成功但查不到数据时间戳精度不匹配现象写入接口返回 200select查询也执行了但结果集是空的或者查出来的数据时间全部显示成 1970 年。原因客户端发送行协议时带了毫秒时间戳但没有把precision告知服务端InfluxDB 默认按纳秒解析。毫秒数当纳秒用时间被缩水到 1970 年附近按now() - 1h查询当然什么都查不到。解决在初始化客户端或写入时显式指定precision: ms。如果你在系统里见过这类诡异现象先别怀疑查询语句直接用select * from measurement order by time desc limit 1看最老数据的 time 字段一眼就能发现端倪。5.2 数字字段全部变成浮点报表上多了一个.0现象写入的整数值比如计数器的当前值 1024查出来变成1024.0前端展示或 Excel 导出时格式异常。原因InfluxDB 行协议默认把数字解析为 float除非你在数字末尾加i后缀。JavaScript 的数字类型不分整浮客户端无法确认你的意图于是按默认 float 写。解决如果字段必须为整数在写入层自行转换把值拼成1024i的字符串形式或者看客户端是否提供整数标记接口。另一个折中办法是容忍 float 类型在查询侧用客户端函数或者在展示层处理掉.0——这个方法麻烦但省改动。5.3 写入报 404 / database not found现象初始化时没指定 database或者指定了一个不存在的库写入时抛database not found或直接 404。原因InfluxDB 的写入端点要求目标数据库存在客户端不会在写入前自动建库。我在第一次接入时也被这个坑过想当然以为连接成功就等于库存在。解决初始化完成后先执行一次建库动作用 InfluxQL 的CREATE DATABASE IF NOT EXISTS your_db或者提前通过管理端创建好数据库。如果用了 2.x 兼容端点要确认 database 参数能正确映射到 bucket。5.4 批量重试导致数据重复现象网络抖动触发重试重试成功后查询发现同一条数据出现了多次或者计数类字段被累加了两遍。原因写入请求超时但服务端实际已经写入成功客户端重试时把同一批数据又发了一次。InfluxDB 的写入端不做幂等相同的时间戳加相同 tag 的多个点会并存。解决两条路——一是让时间戳尽量唯一这本来也是时序数据的常态二是接受 at-least-once 语义在查询侧做去重。我的经验是写入重试时标注重试日志如果发现大量重复优先排查超时阈值和 InfluxDB 负载而不是机械地加重试次数。5.5 查询字符串注入别直接用用户输入拼 InfluxQL现象查询接口传入的 measurement 名或 tag 值里含有特殊字符查询报语法错误或者查询范围被篡改。原因InfluxQL 只要拼接用户输入就可能被分号或引号破坏结构。Nginx 层可能拦掉明显注入但内部服务之间的调用没人帮你兜底。解决尽量把用户输入限制在可信枚举里必须拼接时对字符串做引号转义。如果要开放任意查询能力换个思路让用户传查询参数而不是查询文本把可选范围限制在 measurement 和时间窗口内再拼 InfluxQL 模板。这样可以少很多心智负担。6. 收尾技巧写一个五分钟自检脚本验证整个读写链路很多接入问题不在代码逻辑而在环境InfluxDB 地址变了、认证 token 过期、服务端精度默认值被改动。与其等业务数据出问题不如在项目里放一个自检脚本每次客户端配置改动后跑一遍快速确认链路通、数据能写能查。脚本核心逻辑是三步写入一条标记数据、查出来校验、清理现场。// scripts/check-influx.js const InfluxDB require(influxdb-nodejs); async function selfCheck() { const client new InfluxDB({ host: process.env.INFLUX_HOST || 127.0.0.1, port: Number(process.env.INFLUX_PORT || 8086), database: process.env.INFLUX_DB || monitor_db, username: process.env.INFLUX_USER, password: process.env.INFLUX_PASSWORD }); const measureName connectivity_check; const uniqueTag probe_${Date.now()}; try { // 写入探针数据 await client.write(measureName) .tag({ probe: uniqueTag }) .field({ value: 1 }) .time(Date.now()); // 按唯一 tag 查出来 const res await client.query( select * from ${measureName} where probe ${uniqueTag} limit 1 ); const series res.results[0].series res.results[0].series[0]; if (!series) { console.error(FAIL: probe write ok but query empty); process.exit(1); } // 清理探针数据只清理本次写入的探针不误删业务数据 await client.query(delete from ${measureName} where probe ${uniqueTag}); console.log(PASS: write - query - delete all ok); } catch (err) { console.error(FAIL:, err.message); process.exit(1); } } selfCheck();脚本说明先用唯一 tag 标记探针数据防止清理时误删业务数据写入成功后按 tag 查询确认能查到最后执行 delete 清理现场。跑一次只要几秒但它能覆盖最常见的三类故障——网络不通、认证失败、写入链路坏了。从那以后我每次改 InfluxDB 相关配置都会强制走一遍这个自检脚本再放业务数据进去。别小看这几秒的检查它能省掉你后面一个小时的排查时间。希望帮到你。本文还有配套的精品资源点击获取