@timecho/node-red-node-iotdb 0.0.1

Node-RED SQL and native subscription nodes for Apache IoTDB and TimechoDB

npm install @timecho/node-red-node-iotdb

@timecho/node-red-node-iotdb

Node-RED nodes for Apache IoTDB and TimechoDB:统一的树/表模型 SQL 和原生订阅接口。

当前包版本为 0.0.1。生产验收尚未通过:TimechoDB 2.0.12.1 树、表模型的未确认与停机期间记录在重开后均未恢复,详细结果见 验证报告 和 生产验收清单。不得将此包用于要求断连或重启期间不丢数据的生产订阅场景。

当前订阅节点已增加停止保护:连接丢失时报告 RECOVERY_REQUIRED;首次连接前将标记同步写入 Node-RED 用户目录,重启或重新部署遇到同一 Topic/组时也会停止。该标记不保存消息或消费位点,不能用来恢复数据。详见恢复说明。

rc.2 增加 SDK 连接可用性检查:SDK 可能把网络失败转为空批次,桥接层现在会检查可用连接,并在暂停或等待 ACK 时继续检查。受控断网回归通过;这仍不替代持久恢复。接口核验和待明确的恢复条件见调查材料。

三种节点

类型 作用
iotdb-server 共享配置:地址、模型、数据库、Node-RED credentials、超时和队列限制
iotdb-operator SQL 查询、写入和管理;支持固定 SQL 或 msg.topic
iotdb-consumer 原生 Topic 消费;输入端接收 ACK / pause / resume

配置节点不占用画布。树、表各使用一个独立配置节点。数据写入和 Topic 管理由 operator 执行 SQL,首版不另外注册 write 或 ack 节点。

安装

要求 Node.js 22.9+、Node-RED 4.1+。在 Node-RED 用户目录安装指定版本,然后重启 Node-RED:

cd ~/.node-red
npm install @timecho/[email protected]

生产使用前应固定经验证的包版本,设置 Node-RED credentialSecret,并按 部署说明 配置身份验证与网络边界。

SQL 使用固定版本 @iotdb/[email protected]。SDK 的默认行迭代器会转换树模型时间戳、返回物理列顺序;本包用隔离且锁定版本的适配层保留原始整数与逻辑列映射。升级 SDK 前必须重跑兼容测试。客户端运行在受限 Worker 中;超时会终止该连接,写入不会自动重试,调用方需判断未知执行结果。

SQL 消息

输入:

msg.topic = "SELECT temperature FROM root.factory.device01 LIMIT 100";
return msg;

查询输出 msg.payload 为对象数组;非查询成功为 {success:true}。原消息的其他字段保留,msg.iotdb 提供 operation、model、columns、rowCount、timestampPrecision。

  • INT64、时间戳始终输出十进制字符串;NULL 保持 null;BLOB 使用 0x 十六进制;非有限浮点数使用字符串。
  • 重复列名生成 #2、#3 后缀,原始列名及输出 key 均保留在 columns。
  • 默认最多 10,000 行 / 8 MiB。超过边界时整个请求报错,不输出悄悄截断的结果。SQL 中应设置时间条件和 LIMIT。
  • 模式 auto / query / execute。自动分类不明的 SQL 应手动指定模式。
  • SQL 按原文执行;不提供占位符替换。不要直接拼接不可信输入。
  • 共用连接不允许 USE 或 SET SQL_DIALECT 改变其他 operator 的模型/库;请编辑 server 配置。
  • Catch 接收错误,Complete 在实际操作完成后触发。msg.iotdb.error 包含稳定错误分类。

原生订阅

服务端必须启用相应版本/模型的原生订阅。当前桥接需要 Java 17+ 和与服务端相匹配的官方 Java SDK 及其依赖;SDK 不随 npm 包分发。

export IOTDB_SUBSCRIPTION_CLASSPATH='/path/to/approved-sdk/lib/*'
npm run build:bridge

编译需要 JDK 17+;已有编译产物的部署只需 Java 17+ 运行时。没有编译产物时会使用 Java 源文件启动,需要 JDK。桥接以私有标准输入/输出通信,凭据通过管道传递,未放入 Java 参数或原始日志。

在 consumer 中选择已有 Topic,填写稳定 groupId 和 consumerId。表模型 Topic 支持版本与模式见兼容矩阵;incremental 依赖 IoTConsensus,且仅消费首次成功订阅后进入共识链路的写入。

// consumer 输出示意
{
  topic: "temperature_topic",
  payload: [{source: "root.factory.device01", timestamp: "1794133480573", values: {temperature: 25.5}}],
  iotdb: {model: "tree", consumerGroupId: "alarms", consumerId: "worker1", ackToken: "opaque-token"}
}

默认手动 ACK:下游全部必要处理成功后,保留 msg.iotdb.ackToken 回送同一 consumer,可显式设置 msg.iotdb.action = "ack"。ACK 输入成功后不再发出数据消息,避免循环。多分支处理应在汇合成功后 ACK。

树模型 source 为完整设备路径;表模型为 database.table,可以区分跨库同名表。如果 Topic 的列筛选排除了时间,timestamp 为 null。原生消息可能包含同一时间的部分列或重复记录;保留服务端原始记录,业务应按实际字段执行幂等处理。

delivery 模式在 node.send() 后提交,表示已交付流程,不能代表下游业务成功。未确认消息可能重投,业务需要幂等处理;没有端到端 exactly-once 保证。

pause 停止后续拉取,保留连接和心跳;已在执行的一次 poll 仍可能返回。resume 只恢复同一存活会话内的拉取,不能解除恢复保护。达到待确认批次上限后自动停止新 poll。服务端会在 SDK close 时隐式取消订阅。断线后不自动重订阅,旧 token 失效;当前保护限制同一 Topic/组同时使用一个 consumer。

首版支持记录格式 Topic;TsFile 和不支持的数据类型会报错且不确认。超大批次失败后需调整 Topic 范围/批次限制;不会丢弃后继续。订阅桥接暂不支持原生 TLS,请使用受保护网络或加密隧道;SQL TLS 始终验证证书。

开发验证

npm ci
npm test
npm run check
# 环境中提供 IOTDB_TEST_PASSWORD、IOTDB_TEST_HOST、IOTDB_TEST_PORT
# 原生订阅测试还需 IOTDB_SUBSCRIPTION_CLASSPATH
npm run test:integration
# 生产恢复验收:当前 TimechoDB 2.0.12.1 有两个已知失败,不能跳过并发布
npm run test:acceptance
npm pack --dry-run

集成测试会创建随机 nr_test_ 命名空间、Topic 和消费组,并清理自己的资源。仅对获授权的测试数据库运行。未提供密码时数据库测试会跳过,跳过不等于通过。

Node Info

Version: 0.0.1
Updated 1 day ago
License: Apache-2.0
Rating: not yet rated

Categories

Actions

Rate:

Downloads

0 in the last week

Nodes

  • iotdb-server
  • iotdb-operator
  • iotdb-consumer

Keywords

  • node-red
  • iotdb
  • timechodb
  • timeseries
  • subscription

Maintainers