diff --git a/src/.vuepress/public/img/thingsboard-table-attributes.png b/src/.vuepress/public/img/thingsboard-table-attributes.png new file mode 100644 index 000000000..f9e8eef6a Binary files /dev/null and b/src/.vuepress/public/img/thingsboard-table-attributes.png differ diff --git a/src/.vuepress/public/img/thingsboard-table-telemetry.png b/src/.vuepress/public/img/thingsboard-table-telemetry.png new file mode 100644 index 000000000..ea3067ae2 Binary files /dev/null and b/src/.vuepress/public/img/thingsboard-table-telemetry.png differ diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts b/src/.vuepress/sidebar/V2.0.x/en-Table.ts index 73eee9bcd..13e763dd1 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts @@ -220,6 +220,13 @@ export const enSidebar = { { text: 'MyBatisPlus Generator', link: 'MyBatisPlus-Generator' }, ], }, + { + text: 'IoT Platform', + collapsible: true, + children: [ + { text: 'ThingsBoard', link: 'Thingsboard' }, + ], + }, ], }, { diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index a1f69708b..c8a643a89 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -220,6 +220,13 @@ export const zhSidebar = { { text: 'MyBatisPlus Generator', link: 'MyBatisPlus-Generator' }, ], }, + { + text: '物联网对接', + collapsible: true, + children: [ + { text: 'ThingsBoard', link: 'Thingsboard' }, + ], + }, ], }, { diff --git a/src/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md b/src/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md index 96d73ffc1..87d8850eb 100644 --- a/src/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md +++ b/src/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md @@ -41,4 +41,6 @@ The following documentation will help you quickly and comprehensively understand - Programming Framework - Spring Boot Starter [Spring Boot Starter](./Spring-Boot-Starter.md) - Mybatis Generator [Mybatis Generator](./Mybatis-Generator.md) - - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) \ No newline at end of file + - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) +- IoT Platform + - ThingsBoard [ThingsBoard](./Thingsboard.md) \ No newline at end of file diff --git a/src/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md b/src/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md new file mode 100644 index 000000000..47c73f907 --- /dev/null +++ b/src/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md @@ -0,0 +1,196 @@ + + +# ThingsBoard + +The `iotdb-thingsboard-table` module lets a stock ThingsBoard deployment store +historical telemetry, latest telemetry, and entity attributes in the IoTDB Table +Model. This page follows the operator workflow: download, install, configure, +run, and verify. + +This integration is independent of the earlier +[ThingsBoard Tree Model integration](../../Tree/Ecosystem-Integration/Thingsboard.md), +which requires an IoTDB-adapted ThingsBoard build. + +## 1. Download + +The tested combination is: + +| Component | Version | +| --- | --- | +| IoTDB | 2.0.8, Table Model | +| ThingsBoard | 4.3.1.2 | +| JDK | 17 or later | + +This module is not yet included in an ASF release. Build it from the official +`apache/iotdb-extras` source at commit `275043ed` or later: + +```bash +git clone https://github.com/apache/iotdb-extras.git +cd iotdb-extras +git checkout 275043ed +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am clean package +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am \ + dependency:copy-dependencies -DincludeScope=runtime \ + -DoutputDirectory="$PWD/runtime-deps" +``` + +The second command intentionally produces an unfiltered dependency directory. +Section 2 lists the exact runtime jars to deploy; do not copy the directory as +a whole. + +## 2. Install + +ThingsBoard must be installed before the IoTDB selectors are enabled. Its +installer resolves a `TsDatabaseSchemaService` supplied by the built-in +backends, so enabling this module during installation makes the installation +fail. + +1. Install and start IoTDB. See [IoTDB QuickStart](../QuickStart/QuickStart.md). + + When IoTDB 2.0.8 and ThingsBoard run in separate containers, put them on the + same Docker network and make IoTDB advertise a reachable service name. The + `2.0.8-standalone` image otherwise binds these endpoints to `127.0.0.1`. + For an IoTDB service named `iotdb`, set: + + ```yaml + cn_seed_config_node: iotdb:10710 + dn_seed_config_node: iotdb:10710 + cn_internal_address: iotdb + dn_internal_address: iotdb + dn_rpc_address: iotdb + ``` + +2. Install ThingsBoard normally without any of the properties from section 3. +3. Create a deployment `lib/` directory containing the module's binary jar from + `iotdb-thingsboard-table/target/` and the ten runtime jars listed below from + `runtime-deps/`. Place all eleven jars on the ThingsBoard classpath. + +For the ThingsBoard Docker image, mount or copy the jars to +`/usr/share/thingsboard/extensions`; its `PropertiesLauncher` already includes +that directory through `LOADER_PATH`. Other installation formats may use a +different classpath extension mechanism. + +The deployment directory contains exactly eleven jars: the module, `iotdb-session`, +`isession`, `service-rpc`, `iotdb-thrift`, `iotdb-thrift-commons`, `libthrift`, +`pipe-api`, `tsfile`, `common`, and `xz`. Do not add the unfiltered Maven runtime +directory: it contains older copies of libraries already supplied by +ThingsBoard. In particular, `antlr4-runtime` 4.9.3 shadows ThingsBoard's 4.13.0 +copy and prevents Spring Data JPA from starting. + +## 3. Configure + +Add the properties for the storage paths you want to move to IoTDB. The +following example enables all three paths for a single-node deployment: + +```properties +# IoTDB connection +# Docker service name; use 127.0.0.1 only when both processes share a host +iotdb.host=iotdb +iotdb.port=6667 +iotdb.username=root +iotdb.password=root +iotdb.database=thingsboard +iotdb.session-pool-size=8 +iotdb.schema.bootstrap=true + +# Historical telemetry +database.ts.type=iotdb-table +iotdb.ts.experimental-raw-only=true + +# Latest telemetry +database.ts_latest.type=iotdb-table +iotdb.ts_latest.cluster_mode=disabled + +# Entity attributes +database.attributes.type=iotdb-table +iotdb.attributes.cluster_mode=disabled +``` + +The historical and latest selectors are separate. Omitting +`database.ts_latest.type` leaves latest values on the original ThingsBoard +backend even when historical telemetry is stored in IoTDB. + +The example writes the connection defaults explicitly. Outside Docker, +`iotdb.host` defaults to `127.0.0.1`; the other defaults are port `6667`, +username/password `root`/`root`, database `thingsboard`, session-pool size `8`, +and schema bootstrap enabled. + +Attributes require a build containing +[apache/iotdb-extras#125](https://github.com/apache/iotdb-extras/pull/125), +merged as commit `275043ed`. Earlier builds cannot enable the attributes +selector on stock ThingsBoard. + +When latest telemetry or attributes are enabled, their `cluster_mode` must be +set explicitly: + +- `sticky-routing`: route writes for one identity to one node. +- `disabled`: single-node deployment, or explicitly accept best-effort + convergence. + +Any other value, including an empty value, stops startup with an explanatory +error. + +## 4. Run and verify + +1. Restart ThingsBoard after the bundle and configuration are in place. +2. Check the log for `IoTDB Table Mode session pool initialized`. With schema + bootstrap enabled, also check for `IoTDB Table Mode schema bootstrap + complete`. +3. Send test telemetry and attributes to a ThingsBoard device, then confirm + them on the device's **Latest telemetry** and **Attributes** pages. + + ![ThingsBoard latest telemetry stored through the IoTDB Table Model backend](/img/thingsboard-table-telemetry.png) + + ![ThingsBoard client attributes stored through the IoTDB Table Model backend](/img/thingsboard-table-attributes.png) + +4. Confirm the same values in IoTDB: + +```sql +USE thingsboard; + +SELECT * +FROM telemetry +ORDER BY time DESC +LIMIT 10; + +SELECT * +FROM entity_attributes +ORDER BY time DESC +LIMIT 10; +``` + +## 5. Known limitations + +- IoTDB 2.0.8 and ThingsBoard 4.3.1.2 are the tested versions. Other 2.x or + ThingsBoard versions require separate verification. +- Attribute and latest-overlay writes converge within one JVM. A multi-writer + deployment must use sticky routing or explicitly accept best-effort + convergence. +- The latest-value path is derived from the telemetry table, with a small + overlay for latest-only writes and deletes. +- Retention uses IoTDB table-level TTL. See the module's + [user guide](https://github.com/apache/iotdb-extras/blob/master/iotdb-thingsboard-table/docs/user-guide.md) + for its mapping to ThingsBoard retention settings. + +Design, source-build, migration, and compile-surface verification details remain +in the +[`iotdb-thingsboard-table` module](https://github.com/apache/iotdb-extras/tree/master/iotdb-thingsboard-table). diff --git a/src/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md b/src/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md index 96d73ffc1..87d8850eb 100644 --- a/src/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md +++ b/src/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md @@ -41,4 +41,6 @@ The following documentation will help you quickly and comprehensively understand - Programming Framework - Spring Boot Starter [Spring Boot Starter](./Spring-Boot-Starter.md) - Mybatis Generator [Mybatis Generator](./Mybatis-Generator.md) - - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) \ No newline at end of file + - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) +- IoT Platform + - ThingsBoard [ThingsBoard](./Thingsboard.md) \ No newline at end of file diff --git a/src/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md b/src/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md new file mode 100644 index 000000000..53f8cbaf2 --- /dev/null +++ b/src/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md @@ -0,0 +1,196 @@ + + +# ThingsBoard + +The `iotdb-thingsboard-table` module lets a stock ThingsBoard deployment store +historical telemetry, latest telemetry, and entity attributes in the IoTDB Table +Model. This page follows the operator workflow: download, install, configure, +run, and verify. + +This integration is independent of the earlier +[ThingsBoard Tree Model integration](../../latest/Ecosystem-Integration/Thingsboard.md), +which requires an IoTDB-adapted ThingsBoard build. + +## 1. Download + +The tested combination is: + +| Component | Version | +| --- | --- | +| IoTDB | 2.0.8, Table Model | +| ThingsBoard | 4.3.1.2 | +| JDK | 17 or later | + +This module is not yet included in an ASF release. Build it from the official +`apache/iotdb-extras` source at commit `275043ed` or later: + +```bash +git clone https://github.com/apache/iotdb-extras.git +cd iotdb-extras +git checkout 275043ed +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am clean package +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am \ + dependency:copy-dependencies -DincludeScope=runtime \ + -DoutputDirectory="$PWD/runtime-deps" +``` + +The second command intentionally produces an unfiltered dependency directory. +Section 2 lists the exact runtime jars to deploy; do not copy the directory as +a whole. + +## 2. Install + +ThingsBoard must be installed before the IoTDB selectors are enabled. Its +installer resolves a `TsDatabaseSchemaService` supplied by the built-in +backends, so enabling this module during installation makes the installation +fail. + +1. Install and start IoTDB. See [IoTDB QuickStart](../QuickStart/QuickStart.md). + + When IoTDB 2.0.8 and ThingsBoard run in separate containers, put them on the + same Docker network and make IoTDB advertise a reachable service name. The + `2.0.8-standalone` image otherwise binds these endpoints to `127.0.0.1`. + For an IoTDB service named `iotdb`, set: + + ```yaml + cn_seed_config_node: iotdb:10710 + dn_seed_config_node: iotdb:10710 + cn_internal_address: iotdb + dn_internal_address: iotdb + dn_rpc_address: iotdb + ``` + +2. Install ThingsBoard normally without any of the properties from section 3. +3. Create a deployment `lib/` directory containing the module's binary jar from + `iotdb-thingsboard-table/target/` and the ten runtime jars listed below from + `runtime-deps/`. Place all eleven jars on the ThingsBoard classpath. + +For the ThingsBoard Docker image, mount or copy the jars to +`/usr/share/thingsboard/extensions`; its `PropertiesLauncher` already includes +that directory through `LOADER_PATH`. Other installation formats may use a +different classpath extension mechanism. + +The deployment directory contains exactly eleven jars: the module, `iotdb-session`, +`isession`, `service-rpc`, `iotdb-thrift`, `iotdb-thrift-commons`, `libthrift`, +`pipe-api`, `tsfile`, `common`, and `xz`. Do not add the unfiltered Maven runtime +directory: it contains older copies of libraries already supplied by +ThingsBoard. In particular, `antlr4-runtime` 4.9.3 shadows ThingsBoard's 4.13.0 +copy and prevents Spring Data JPA from starting. + +## 3. Configure + +Add the properties for the storage paths you want to move to IoTDB. The +following example enables all three paths for a single-node deployment: + +```properties +# IoTDB connection +# Docker service name; use 127.0.0.1 only when both processes share a host +iotdb.host=iotdb +iotdb.port=6667 +iotdb.username=root +iotdb.password=root +iotdb.database=thingsboard +iotdb.session-pool-size=8 +iotdb.schema.bootstrap=true + +# Historical telemetry +database.ts.type=iotdb-table +iotdb.ts.experimental-raw-only=true + +# Latest telemetry +database.ts_latest.type=iotdb-table +iotdb.ts_latest.cluster_mode=disabled + +# Entity attributes +database.attributes.type=iotdb-table +iotdb.attributes.cluster_mode=disabled +``` + +The historical and latest selectors are separate. Omitting +`database.ts_latest.type` leaves latest values on the original ThingsBoard +backend even when historical telemetry is stored in IoTDB. + +The example writes the connection defaults explicitly. Outside Docker, +`iotdb.host` defaults to `127.0.0.1`; the other defaults are port `6667`, +username/password `root`/`root`, database `thingsboard`, session-pool size `8`, +and schema bootstrap enabled. + +Attributes require a build containing +[apache/iotdb-extras#125](https://github.com/apache/iotdb-extras/pull/125), +merged as commit `275043ed`. Earlier builds cannot enable the attributes +selector on stock ThingsBoard. + +When latest telemetry or attributes are enabled, their `cluster_mode` must be +set explicitly: + +- `sticky-routing`: route writes for one identity to one node. +- `disabled`: single-node deployment, or explicitly accept best-effort + convergence. + +Any other value, including an empty value, stops startup with an explanatory +error. + +## 4. Run and verify + +1. Restart ThingsBoard after the bundle and configuration are in place. +2. Check the log for `IoTDB Table Mode session pool initialized`. With schema + bootstrap enabled, also check for `IoTDB Table Mode schema bootstrap + complete`. +3. Send test telemetry and attributes to a ThingsBoard device, then confirm + them on the device's **Latest telemetry** and **Attributes** pages. + + ![ThingsBoard latest telemetry stored through the IoTDB Table Model backend](/img/thingsboard-table-telemetry.png) + + ![ThingsBoard client attributes stored through the IoTDB Table Model backend](/img/thingsboard-table-attributes.png) + +4. Confirm the same values in IoTDB: + +```sql +USE thingsboard; + +SELECT * +FROM telemetry +ORDER BY time DESC +LIMIT 10; + +SELECT * +FROM entity_attributes +ORDER BY time DESC +LIMIT 10; +``` + +## 5. Known limitations + +- IoTDB 2.0.8 and ThingsBoard 4.3.1.2 are the tested versions. Other 2.x or + ThingsBoard versions require separate verification. +- Attribute and latest-overlay writes converge within one JVM. A multi-writer + deployment must use sticky routing or explicitly accept best-effort + convergence. +- The latest-value path is derived from the telemetry table, with a small + overlay for latest-only writes and deletes. +- Retention uses IoTDB table-level TTL. See the module's + [user guide](https://github.com/apache/iotdb-extras/blob/master/iotdb-thingsboard-table/docs/user-guide.md) + for its mapping to ThingsBoard retention settings. + +Design, source-build, migration, and compile-surface verification details remain +in the +[`iotdb-thingsboard-table` module](https://github.com/apache/iotdb-extras/tree/master/iotdb-thingsboard-table). diff --git a/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md index a27cd20bd..7dd061f5a 100644 --- a/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md +++ b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Ecosystem-Overview_apache.md @@ -35,4 +35,6 @@ IoTDB 生态集成打通时序数据全链路：通过数据采集实现设备 - 编程框架 - Spring Boot Starter [Spring Boot Starter](./Spring-Boot-Starter.md) - Mybatis Generator [Mybatis Generator](./Mybatis-Generator.md) - - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) \ No newline at end of file + - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) +- 物联网对接 + - ThingsBoard [ThingsBoard](./Thingsboard.md) \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md new file mode 100644 index 000000000..2b4c23e7e --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/Thingsboard.md @@ -0,0 +1,177 @@ + + +# ThingsBoard + +`iotdb-thingsboard-table` 模块让原版 ThingsBoard 可以把历史时序、最新值时序和实体属性 +存入 IoTDB 表模型。本页按操作者真正使用它的顺序说明：下载、安装、配置、运行与验证。 + +这套集成独立于较早的 +[ThingsBoard 树模型集成](../../Tree/Ecosystem-Integration/Thingsboard.md)，后者需要使用 +IoTDB 适配版 ThingsBoard。 + +## 1. 下载 + +已经验证的版本组合如下： + +| 组件 | 版本 | +| --- | --- | +| IoTDB | 2.0.8，表模型 | +| ThingsBoard | 4.3.1.2 | +| JDK | 17 或更高版本 | + +本模块尚未进入 ASF Release。请从 `apache/iotdb-extras` 官方源码的 commit `275043ed` +或更新版本构建： + +```bash +git clone https://github.com/apache/iotdb-extras.git +cd iotdb-extras +git checkout 275043ed +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am clean package +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am \ + dependency:copy-dependencies -DincludeScope=runtime \ + -DoutputDirectory="$PWD/runtime-deps" +``` + +第二条命令会有意生成未经筛选的依赖目录。第 2 节列出了实际需要部署的运行期 jar；不要 +直接复制整个目录。 + +## 2. 安装 + +必须先安装 ThingsBoard，再启用 IoTDB 选择器。ThingsBoard 安装器会解析由内置后端提供的 +`TsDatabaseSchemaService`；若安装阶段已经启用本模块，安装会失败。 + +1. 安装并启动 IoTDB，参见 [IoTDB 快速上手](../QuickStart/QuickStart.md)。 + + 若 IoTDB 2.0.8 与 ThingsBoard 分别运行在容器中，请把两者放入同一 Docker 网络，并让 + IoTDB 公布网络内可达的服务名。`2.0.8-standalone` 镜像默认把这些地址绑定到 + `127.0.0.1`。假设 IoTDB 服务名为 `iotdb`，请设置： + + ```yaml + cn_seed_config_node: iotdb:10710 + dn_seed_config_node: iotdb:10710 + cn_internal_address: iotdb + dn_internal_address: iotdb + dn_rpc_address: iotdb + ``` + +2. 按常规方式安装 ThingsBoard，此时不要设置第 3 节的任何属性。 +3. 创建部署用的 `lib/` 目录，从 `iotdb-thingsboard-table/target/` 复制模块的二进制 jar， + 再从 `runtime-deps/` 复制下方列出的 10 个运行期 jar。将这 11 个 jar 全部放到 + ThingsBoard classpath 上。 + +对于 ThingsBoard Docker 镜像，可将这些 jar 挂载或复制到 +`/usr/share/thingsboard/extensions`。镜像使用的 `PropertiesLauncher` 已通过 +`LOADER_PATH` 包含该目录。其他安装方式可能采用不同的 classpath 扩展机制。 + +部署目录必须正好包含 11 个 jar：模块本身，以及 `iotdb-session`、`isession`、 +`service-rpc`、`iotdb-thrift`、`iotdb-thrift-commons`、`libthrift`、`pipe-api`、 +`tsfile`、`common` 和 `xz`。不要直接放入 Maven 复制出的全部运行期依赖；其中包含 +ThingsBoard 已自带的旧版本冲突项。特别是 `antlr4-runtime` 4.9.3 会盖住 ThingsBoard 的 +4.13.0，导致 Spring Data JPA 无法启动。 + +## 3. 配置 + +按需要启用要迁移到 IoTDB 的存储路径。下面的单节点示例同时启用三条路径： + +```properties +# IoTDB 连接 +# Docker 服务名；仅当两个进程共享同一主机时使用 127.0.0.1 +iotdb.host=iotdb +iotdb.port=6667 +iotdb.username=root +iotdb.password=root +iotdb.database=thingsboard +iotdb.session-pool-size=8 +iotdb.schema.bootstrap=true + +# 历史时序 +database.ts.type=iotdb-table +iotdb.ts.experimental-raw-only=true + +# 最新值时序 +database.ts_latest.type=iotdb-table +iotdb.ts_latest.cluster_mode=disabled + +# 实体属性 +database.attributes.type=iotdb-table +iotdb.attributes.cluster_mode=disabled +``` + +历史时序和最新值时序使用两个独立选择器。若遗漏 `database.ts_latest.type`，即使历史数据 +已经存入 IoTDB，最新值仍会留在 ThingsBoard 原来的后端中。 + +示例显式写出了连接配置的默认值。在非 Docker 环境中，`iotdb.host` 默认为 +`127.0.0.1`；其他默认值为端口 `6667`、用户名/密码 `root`/`root`、数据库 +`thingsboard`、会话池大小 `8`，并默认启用表结构引导。 + +属性路径要求构建中包含 +[apache/iotdb-extras#125](https://github.com/apache/iotdb-extras/pull/125)，即上游 +commit `275043ed` 或更新版本。更早的构建无法在原版 ThingsBoard 上启用属性选择器。 + +启用最新值或属性时，必须显式设置对应的 `cluster_mode`： + +- `sticky-routing`：把同一 identity 的写入固定路由到一个节点。 +- `disabled`：单节点部署，或明确接受尽力而为的收敛。 + +其他取值（包括空值）都会让启动停止并给出明确错误。 + +## 4. 运行与验证 + +1. 部署 jar 并完成配置后，重启 ThingsBoard。 +2. 在日志中确认出现 `IoTDB Table Mode session pool initialized`。若启用了表结构引导， + 还应出现 `IoTDB Table Mode schema bootstrap complete`。 +3. 向一台 ThingsBoard 测试设备发送时序和属性数据，然后在设备的“最新遥测”和“属性”页面 + 确认这些值。 + + ![通过 IoTDB 表模型后端存储的 ThingsBoard 最新遥测](/img/thingsboard-table-telemetry.png) + + ![通过 IoTDB 表模型后端存储的 ThingsBoard 客户端属性](/img/thingsboard-table-attributes.png) + +4. 在 IoTDB 中查询同一批数据： + +```sql +USE thingsboard; + +SELECT * +FROM telemetry +ORDER BY time DESC +LIMIT 10; + +SELECT * +FROM entity_attributes +ORDER BY time DESC +LIMIT 10; +``` + +## 5. 已知限制 + +- 已验证版本为 IoTDB 2.0.8 和 ThingsBoard 4.3.1.2。其他 IoTDB 2.x 或 ThingsBoard + 版本需要单独验证。 +- 属性写入和最新值覆盖层只在单个 JVM 内收敛。多写入者部署必须使用固定路由，或明确接受 + 尽力而为的收敛。 +- 最新值路径从时序表派生，并使用一个小型覆盖层承接仅写最新值和仅删最新值的路径。 +- 保留策略使用 IoTDB 表级 TTL；其与 ThingsBoard 保留设置的对应关系参见模块的 + [用户指南](https://github.com/apache/iotdb-extras/blob/master/iotdb-thingsboard-table/docs/user-guide.md)。 + +设计、源码构建、迁移和编译接口验证细节保留在 +[`iotdb-thingsboard-table` 模块](https://github.com/apache/iotdb-extras/tree/master/iotdb-thingsboard-table) +中。 diff --git a/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md index a27cd20bd..7dd061f5a 100644 --- a/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md +++ b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Ecosystem-Overview_apache.md @@ -35,4 +35,6 @@ IoTDB 生态集成打通时序数据全链路：通过数据采集实现设备 - 编程框架 - Spring Boot Starter [Spring Boot Starter](./Spring-Boot-Starter.md) - Mybatis Generator [Mybatis Generator](./Mybatis-Generator.md) - - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) \ No newline at end of file + - MyBatisPlus Generator [MyBatisPlus Generator](./MyBatisPlus-Generator.md) +- 物联网对接 + - ThingsBoard [ThingsBoard](./Thingsboard.md) \ No newline at end of file diff --git a/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md new file mode 100644 index 000000000..ef51e6af0 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/Thingsboard.md @@ -0,0 +1,177 @@ + + +# ThingsBoard + +`iotdb-thingsboard-table` 模块让原版 ThingsBoard 可以把历史时序、最新值时序和实体属性 +存入 IoTDB 表模型。本页按操作者真正使用它的顺序说明：下载、安装、配置、运行与验证。 + +这套集成独立于较早的 +[ThingsBoard 树模型集成](../../latest/Ecosystem-Integration/Thingsboard.md)，后者需要使用 +IoTDB 适配版 ThingsBoard。 + +## 1. 下载 + +已经验证的版本组合如下： + +| 组件 | 版本 | +| --- | --- | +| IoTDB | 2.0.8，表模型 | +| ThingsBoard | 4.3.1.2 | +| JDK | 17 或更高版本 | + +本模块尚未进入 ASF Release。请从 `apache/iotdb-extras` 官方源码的 commit `275043ed` +或更新版本构建： + +```bash +git clone https://github.com/apache/iotdb-extras.git +cd iotdb-extras +git checkout 275043ed +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am clean package +mvn -P with-thingsboard -pl iotdb-thingsboard-table -am \ + dependency:copy-dependencies -DincludeScope=runtime \ + -DoutputDirectory="$PWD/runtime-deps" +``` + +第二条命令会有意生成未经筛选的依赖目录。第 2 节列出了实际需要部署的运行期 jar；不要 +直接复制整个目录。 + +## 2. 安装 + +必须先安装 ThingsBoard，再启用 IoTDB 选择器。ThingsBoard 安装器会解析由内置后端提供的 +`TsDatabaseSchemaService`；若安装阶段已经启用本模块，安装会失败。 + +1. 安装并启动 IoTDB，参见 [IoTDB 快速上手](../QuickStart/QuickStart.md)。 + + 若 IoTDB 2.0.8 与 ThingsBoard 分别运行在容器中，请把两者放入同一 Docker 网络，并让 + IoTDB 公布网络内可达的服务名。`2.0.8-standalone` 镜像默认把这些地址绑定到 + `127.0.0.1`。假设 IoTDB 服务名为 `iotdb`，请设置： + + ```yaml + cn_seed_config_node: iotdb:10710 + dn_seed_config_node: iotdb:10710 + cn_internal_address: iotdb + dn_internal_address: iotdb + dn_rpc_address: iotdb + ``` + +2. 按常规方式安装 ThingsBoard，此时不要设置第 3 节的任何属性。 +3. 创建部署用的 `lib/` 目录，从 `iotdb-thingsboard-table/target/` 复制模块的二进制 jar， + 再从 `runtime-deps/` 复制下方列出的 10 个运行期 jar。将这 11 个 jar 全部放到 + ThingsBoard classpath 上。 + +对于 ThingsBoard Docker 镜像，可将这些 jar 挂载或复制到 +`/usr/share/thingsboard/extensions`。镜像使用的 `PropertiesLauncher` 已通过 +`LOADER_PATH` 包含该目录。其他安装方式可能采用不同的 classpath 扩展机制。 + +部署目录必须正好包含 11 个 jar：模块本身，以及 `iotdb-session`、`isession`、 +`service-rpc`、`iotdb-thrift`、`iotdb-thrift-commons`、`libthrift`、`pipe-api`、 +`tsfile`、`common` 和 `xz`。不要直接放入 Maven 复制出的全部运行期依赖；其中包含 +ThingsBoard 已自带的旧版本冲突项。特别是 `antlr4-runtime` 4.9.3 会盖住 ThingsBoard 的 +4.13.0，导致 Spring Data JPA 无法启动。 + +## 3. 配置 + +按需要启用要迁移到 IoTDB 的存储路径。下面的单节点示例同时启用三条路径： + +```properties +# IoTDB 连接 +# Docker 服务名；仅当两个进程共享同一主机时使用 127.0.0.1 +iotdb.host=iotdb +iotdb.port=6667 +iotdb.username=root +iotdb.password=root +iotdb.database=thingsboard +iotdb.session-pool-size=8 +iotdb.schema.bootstrap=true + +# 历史时序 +database.ts.type=iotdb-table +iotdb.ts.experimental-raw-only=true + +# 最新值时序 +database.ts_latest.type=iotdb-table +iotdb.ts_latest.cluster_mode=disabled + +# 实体属性 +database.attributes.type=iotdb-table +iotdb.attributes.cluster_mode=disabled +``` + +历史时序和最新值时序使用两个独立选择器。若遗漏 `database.ts_latest.type`，即使历史数据 +已经存入 IoTDB，最新值仍会留在 ThingsBoard 原来的后端中。 + +示例显式写出了连接配置的默认值。在非 Docker 环境中，`iotdb.host` 默认为 +`127.0.0.1`；其他默认值为端口 `6667`、用户名/密码 `root`/`root`、数据库 +`thingsboard`、会话池大小 `8`，并默认启用表结构引导。 + +属性路径要求构建中包含 +[apache/iotdb-extras#125](https://github.com/apache/iotdb-extras/pull/125)，即上游 +commit `275043ed` 或更新版本。更早的构建无法在原版 ThingsBoard 上启用属性选择器。 + +启用最新值或属性时，必须显式设置对应的 `cluster_mode`： + +- `sticky-routing`：把同一 identity 的写入固定路由到一个节点。 +- `disabled`：单节点部署，或明确接受尽力而为的收敛。 + +其他取值（包括空值）都会让启动停止并给出明确错误。 + +## 4. 运行与验证 + +1. 部署 jar 并完成配置后，重启 ThingsBoard。 +2. 在日志中确认出现 `IoTDB Table Mode session pool initialized`。若启用了表结构引导， + 还应出现 `IoTDB Table Mode schema bootstrap complete`。 +3. 向一台 ThingsBoard 测试设备发送时序和属性数据，然后在设备的“最新遥测”和“属性”页面 + 确认这些值。 + + ![通过 IoTDB 表模型后端存储的 ThingsBoard 最新遥测](/img/thingsboard-table-telemetry.png) + + ![通过 IoTDB 表模型后端存储的 ThingsBoard 客户端属性](/img/thingsboard-table-attributes.png) + +4. 在 IoTDB 中查询同一批数据： + +```sql +USE thingsboard; + +SELECT * +FROM telemetry +ORDER BY time DESC +LIMIT 10; + +SELECT * +FROM entity_attributes +ORDER BY time DESC +LIMIT 10; +``` + +## 5. 已知限制 + +- 已验证版本为 IoTDB 2.0.8 和 ThingsBoard 4.3.1.2。其他 IoTDB 2.x 或 ThingsBoard + 版本需要单独验证。 +- 属性写入和最新值覆盖层只在单个 JVM 内收敛。多写入者部署必须使用固定路由，或明确接受 + 尽力而为的收敛。 +- 最新值路径从时序表派生，并使用一个小型覆盖层承接仅写最新值和仅删最新值的路径。 +- 保留策略使用 IoTDB 表级 TTL；其与 ThingsBoard 保留设置的对应关系参见模块的 + [用户指南](https://github.com/apache/iotdb-extras/blob/master/iotdb-thingsboard-table/docs/user-guide.md)。 + +设计、源码构建、迁移和编译接口验证细节保留在 +[`iotdb-thingsboard-table` 模块](https://github.com/apache/iotdb-extras/tree/master/iotdb-thingsboard-table) +中。