diff --git a/src/.vuepress/public/img/ThingsBoard-Table-01.png b/src/.vuepress/public/img/ThingsBoard-Table-01.png new file mode 100644 index 000000000..99c502d96 Binary files /dev/null and b/src/.vuepress/public/img/ThingsBoard-Table-01.png differ diff --git a/src/.vuepress/public/img/ThingsBoard-Table-02.png b/src/.vuepress/public/img/ThingsBoard-Table-02.png new file mode 100644 index 000000000..dbc5e7172 Binary files /dev/null and b/src/.vuepress/public/img/ThingsBoard-Table-02.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 fdbfc2969..d8cf67dc7 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts @@ -221,6 +221,11 @@ export const enSidebar = { { text: 'MyBatisPlus Generator', link: 'MyBatisPlus-Generator' }, ], }, + { + text: 'IoT Platform', + collapsible: true, + children: [{ text: 'ThingsBoard', link: 'ThingsBoard-Table_apache' }], + }, ], }, { diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index ce2dc8f4f..2a64e28e4 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -221,6 +221,11 @@ export const zhSidebar = { { text: 'MyBatisPlus Generator', link: 'MyBatisPlus-Generator' }, ], }, + { + text: '物联网平台', + collapsible: true, + children: [{ text: 'ThingsBoard', link: 'ThingsBoard-Table_apache' }], + }, ], }, { 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..e6881a93c 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-Table_apache.md) diff --git a/src/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md b/src/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md new file mode 100644 index 000000000..df4dd33e9 --- /dev/null +++ b/src/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md @@ -0,0 +1,276 @@ + + +# ThingsBoard + +## 1. Product Overview + +### 1.1 Introduction to ThingsBoard + +ThingsBoard is an open-source IoT platform for device management, data collection, and visualization. It helps users rapidly develop, manage, and scale IoT applications. For details, see the [ThingsBoard documentation](https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/). + +![ThingsBoard.png](/img/ThingsBoard-en1.png) + +### 1.2 ThingsBoard Integration with the IoTDB Table Model + +The `iotdb-thingsboard-table` extension stores ThingsBoard historical telemetry, latest telemetry values, and entity attributes in the IoTDB table model. ThingsBoard can continue to read and display these data. You can choose which data types to store in IoTDB and use ThingsBoard for device management and visualization. + +## 2. Setup + +### 2.1 Requirements + +This guide uses IoTDB 2.0.11, ThingsBoard 4.3.1.2, and `iotdb-thingsboard-table` 2.0.11. For later versions, check the corresponding compatibility information and adjust dependencies, configuration, and startup procedures as needed. + +| Software | Example version or configuration | Purpose | +|---|---|---| +| IoTDB | 2.0.11, table model | Stores telemetry and/or attributes | +| ThingsBoard | 4.3.1.2 | Device connectivity and data management | +| JDK | 17 | Runs IoTDB and ThingsBoard | + +IoTDB and ThingsBoard can run on separate hosts or containers. The ThingsBoard runtime must be able to reach the IoTDB RPC address (port `6667` by default). For initial deployment, use a dedicated test instance and test device. + +### 2.2 Install the Prerequisites + +Follow the official installation guides for ThingsBoard and IoTDB and verify that both start independently. Complete ThingsBoard installation and database initialization before connecting it to the IoTDB table model. + +- For IoTDB deployment, see [Standalone Deployment](../Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md). +- Download ThingsBoard from the [4.3.1.2 release page](https://github.com/thingsboard/thingsboard/releases/tag/v4.3.1.2), then follow its official guide to install it, configure its database, and initialize it. + +If IoTDB and ThingsBoard run in separate containers, connect them to the same Docker network and use an IoTDB service name resolvable by ThingsBoard. For `apache/iotdb:2.0.11-standalone`, if the IoTDB service is named `iotdb`, set these values in its `environment`: + +```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.3 Obtain and Deploy the Extension + +1. **Get the extension.** Download `iotdb-thingsboard-table-2.0.11.jar` from the [Apache IoTDB Extras 2.0.11 release](https://github.com/apache/iotdb-extras/releases/tag/v2.0.11). + +2. **Download the dependencies.** The extension JAR does not bundle IoTDB client libraries. Download all nine dependency JARs from Maven Central and save them with the extension JAR in a local `lib` directory. + + | Maven dependency | Version | JAR download | + |---|---|---| + | `org.apache.iotdb:iotdb-session` | `2.0.11` | [iotdb-session-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar) | + | `org.apache.iotdb:isession` | `2.0.11` | [isession-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar) | + | `org.apache.iotdb:service-rpc` | `2.0.11` | [service-rpc-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar) | + | `org.apache.iotdb:iotdb-thrift` | `2.0.11` | [iotdb-thrift-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar) | + | `org.apache.iotdb:iotdb-thrift-commons` | `2.0.11` | [iotdb-thrift-commons-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar) | + | `org.apache.thrift:libthrift` | `0.23.0` | [libthrift-0.23.0.jar](https://repo1.maven.org/maven2/org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar) | + | `org.apache.tsfile:tsfile` | `2.4.0` | [tsfile-2.4.0.jar](https://repo1.maven.org/maven2/org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar) | + | `org.apache.tsfile:common` | `2.4.0` | [common-2.4.0.jar](https://repo1.maven.org/maven2/org/apache/tsfile/common/2.4.0/common-2.4.0.jar) | + | `org.tukaani:xz` | `1.10` | [xz-1.10.jar](https://repo1.maven.org/maven2/org/tukaani/xz/1.10/xz-1.10.jar) | + + The `lib` directory must contain 10 JARs: the extension and nine dependencies. ThingsBoard 4.3.1.2 already includes LZ4, Zstd, Snappy, and ANTLR runtime libraries. Do not add duplicate versions of these libraries. + +3. **Deploy the extension.** Put the extension JAR and all nine dependency JARs in the ThingsBoard extensions directory: + - **Linux (`.deb`):** `/usr/share/thingsboard/extensions` (create it if needed). + - **Windows:** `\extensions`. + - **Docker:** Mount `lib` at `/usr/share/thingsboard/extensions` in the container. + + For a Linux `.deb` installation, run this from the directory containing `lib`: + + ```Bash + sudo install -d /usr/share/thingsboard/extensions + sudo install -m 0644 lib/*.jar /usr/share/thingsboard/extensions/ + ``` + + If you changed the installation path or startup configuration, use the extension loading path actually used by the ThingsBoard process. Creating the directory and copying JARs does not add it to the loading path automatically. + +### 2.4 Configure the Extension + +Pass configuration through the ThingsBoard process `SPRING_APPLICATION_JSON` environment variable. The examples below are for a single ThingsBoard node and enable historical telemetry, latest telemetry, and entity attribute storage. + +Change the IoTDB host, port, credentials, and database name to match your environment. If `SPRING_APPLICATION_JSON` already exists, merge these properties into its JSON object and preserve the other settings. Keep property names exactly as shown. Defaults are `127.0.0.1:6667`, username/password `root`/`root`, database `thingsboard`, and session pool size `8`. With `iotdb.schema.bootstrap=true`, the first startup creates the database and required tables. In a container, specify an IoTDB host reachable from that container; the default address does not change automatically. + +#### 2.4.1 Docker Compose + +Merge this snippet into the ThingsBoard service in your existing Compose file. The example uses service names `thingsboard` and `iotdb`; update them as needed and preserve existing ports, networks, volumes, and environment variables. The `lib` directory from Section 2.3 should be next to the Compose file. + +```YAML +services: + thingsboard: + image: thingsboard/tb-node:4.3.1.2 + volumes: + - ./lib:/usr/share/thingsboard/extensions:ro + environment: + SPRING_APPLICATION_JSON: >- + { + "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" + } +``` + +This snippet is for an already installed ThingsBoard service, not a complete Compose file. If the extensions directory is already mounted, place all 10 JARs in that mount source and do not mount the same container path twice. + +#### 2.4.2 Linux (`.deb`) + +Add this to `/etc/thingsboard/conf/thingsboard.conf`, preserving existing settings. The ThingsBoard service reads this shell file at startup, so keep `export` and the single quotes around the JSON. Exporting a variable only in an interactive terminal does not change system service configuration. This example assumes IoTDB is on the same host; change `iotdb.host` otherwise. + +```Bash +export SPRING_APPLICATION_JSON='{ + "iotdb.host": "127.0.0.1", + "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" +}' +``` + +#### 2.4.3 Windows + +Set the JSON object from Section 2.4.2 as a system or service environment variable accessible to the ThingsBoard process. The variable is named `SPRING_APPLICATION_JSON`; its value is the JSON content from `{` to `}`, without Bash `export` or the surrounding single quotes. + +Setting `$env:SPRING_APPLICATION_JSON` in the current PowerShell window does not change an already registered service's environment. The official Windows installer uses `install.bat` to configure the extension loading path. After changing the installation location or startup method, confirm that the actual loading path includes the extensions directory. + +### 2.5 Start and Check ThingsBoard + +Start or restart ThingsBoard using the procedure for your deployment: + +- **Docker Compose:** Run in the directory containing the Compose file. Replace `thingsboard` if your service has a different name. + + ```Bash + docker compose up -d thingsboard + ``` + + This command recreates the container when configuration changes. Restarting an existing container alone does not apply changed environment variables or mounts. + +- **Linux (`.deb`):** Restart the system service with `sudo systemctl restart thingsboard`. +- **Windows:** Restart the ThingsBoard service in Windows Service Manager. + +Check the logs for extension connection-pool initialization. When schema bootstrap is enabled, the logs should also show schema creation completion: + +```Plain Text +IoTDB Table Mode session pool initialized +IoTDB Table Mode schema bootstrap complete +``` + +When entity attribute storage is enabled, a WARN about the extension replacing `jpaAttributeDao` is expected. If you see `NoClassDefFoundError: org/apache/iotdb/isession/pool/ITableSessionPool`, verify that the extension directory contains the module JAR and all nine dependencies and that it is in the ThingsBoard loading path. + +Linux `.deb` service logs are usually under `/var/log/thingsboard/`. Log locations for Windows services and containers depend on how they are installed or run. A foreground process usually writes logs to the console or configured log directory. + +### 2.6 Verify the Data + +Create a device in ThingsBoard and get its access token. Send telemetry to the device: + +```HTTP +POST http://:8080/api/v1//telemetry +Content-Type: application/json + +{"temperature":23.75,"status":"ok"} +``` + +Send client attributes to the device: + +```HTTP +POST http://:8080/api/v1//attributes +Content-Type: application/json + +{"site":"local"} +``` + +Use any HTTP client to send these requests. In Windows PowerShell, use `curl.exe` or `Invoke-RestMethod`. + +After writing data, open the device details in ThingsBoard: + +- On the **Latest telemetry** page, confirm the telemetry keys and values. + +![ThingsBoard-Table-01.png](/img/ThingsBoard-Table-01.png) + +- On the **Attributes** page, select **Client attributes** and confirm the attribute keys and values. + +![ThingsBoard-Table-02.png](/img/ThingsBoard-Table-02.png) + +The screenshots are examples; their keys and values differ from the requests above. Check the data you sent. + +After telemetry has been written in batches, query it with the IoTDB table-model CLI or a JDBC client. Replace `` with the device ID from ThingsBoard: + +```SQL +USE thingsboard; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry_latest +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, attribute_scope, key, bool_v, long_v, double_v, str_v, json_v +FROM entity_attributes +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; +``` + +Compare the entity ID, key, and value. In the telemetry example, `ts` and `value` are stored in `json_v`; the table's `time` is the IoTDB row time and may differ from the sample timestamp in the request. Check attributes by scope and value type; for example, a string attribute in `CLIENT_SCOPE` is stored in `str_v`. Latest telemetry and attributes can also be read from the ThingsBoard device page. + +## 3. Select Storage Paths + +Keep the relevant selectors and properties in `SPRING_APPLICATION_JSON`: + +| Storage path | Configuration | Description | +|---|---|---| +| Historical telemetry | `database.ts.type=iotdb-table`, `iotdb.ts.experimental-raw-only=true` | Supports writes, raw queries, deletion, and time-window aggregation. This compatibility-named property must be set with the historical telemetry selector. | +| Latest telemetry | `database.ts_latest.type=iotdb-table`, `iotdb.ts_latest.cluster_mode` | Depends on historical telemetry storage. Without this selector, ThingsBoard continues to use its original backend for latest telemetry. | +| Entity attributes | `database.attributes.type=iotdb-table`, `iotdb.attributes.cluster_mode` | Independent of telemetry storage. When enabled, the extension provides the attribute DAO. | + +When enabling latest telemetry or entity attribute storage, set a valid corresponding `cluster_mode`: + +- For one ThingsBoard node, use `disabled`. +- For multiple ThingsBoard nodes, use `sticky-routing` only if writes, updates, and deletes for latest values and attributes of the same device or entity are consistently routed to the same node. This setting does not configure ThingsBoard traffic routing. +- In a multi-node deployment without sticky routing, `disabled` can produce inconsistent results when different nodes concurrently update the same latest-value key or attribute. The extension does not coordinate cross-node writes. + +Here, “node” means a ThingsBoard node, not an IoTDB node. `disabled` does not turn off storage. If the corresponding backend is enabled and `cluster_mode` is missing, empty, or set to another value, ThingsBoard fails to start. + +## 4. Data Migration and Limitations + +- **Existing data:** The extension does not migrate data automatically. Backfill and verify an existing instance before switching. After enabling attribute storage, old attributes that were not migrated may no longer be readable through ThingsBoard. +- **Data retention:** IoTDB applies TTL at the table level and does not apply ThingsBoard per-record TTL. `telemetry_latest` does not expire automatically by default and is not affected by the historical telemetry table TTL; plan its retention separately. +- **Data types:** Keep the type consistent for the same entity, key, and timestamp. Changing the type across batches can make that data point unreadable. +- **Version notifications:** Latest telemetry and attribute operations return a `null` `version`; notifications requiring a non-null version will not work. +- **Configuration rollback:** Restoring the original storage configuration does not move data back from IoTDB. Plan a backfill or synchronization separately if you need to preserve data written during the integration. + +## 5. References + +For configuration parameters, table schemas, and migration mappings, see the [IoTDB ThingsBoard Table extension documentation](https://github.com/apache/iotdb-extras/tree/v2.0.11/iotdb-thingsboard-table). The module `README.md` provides an overview; `docs/user-guide.md` and `docs/migration-guide.md` provide detailed usage and migration guidance. 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..e6881a93c 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-Table_apache.md) diff --git a/src/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md b/src/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md new file mode 100644 index 000000000..df4dd33e9 --- /dev/null +++ b/src/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md @@ -0,0 +1,276 @@ + + +# ThingsBoard + +## 1. Product Overview + +### 1.1 Introduction to ThingsBoard + +ThingsBoard is an open-source IoT platform for device management, data collection, and visualization. It helps users rapidly develop, manage, and scale IoT applications. For details, see the [ThingsBoard documentation](https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/). + +![ThingsBoard.png](/img/ThingsBoard-en1.png) + +### 1.2 ThingsBoard Integration with the IoTDB Table Model + +The `iotdb-thingsboard-table` extension stores ThingsBoard historical telemetry, latest telemetry values, and entity attributes in the IoTDB table model. ThingsBoard can continue to read and display these data. You can choose which data types to store in IoTDB and use ThingsBoard for device management and visualization. + +## 2. Setup + +### 2.1 Requirements + +This guide uses IoTDB 2.0.11, ThingsBoard 4.3.1.2, and `iotdb-thingsboard-table` 2.0.11. For later versions, check the corresponding compatibility information and adjust dependencies, configuration, and startup procedures as needed. + +| Software | Example version or configuration | Purpose | +|---|---|---| +| IoTDB | 2.0.11, table model | Stores telemetry and/or attributes | +| ThingsBoard | 4.3.1.2 | Device connectivity and data management | +| JDK | 17 | Runs IoTDB and ThingsBoard | + +IoTDB and ThingsBoard can run on separate hosts or containers. The ThingsBoard runtime must be able to reach the IoTDB RPC address (port `6667` by default). For initial deployment, use a dedicated test instance and test device. + +### 2.2 Install the Prerequisites + +Follow the official installation guides for ThingsBoard and IoTDB and verify that both start independently. Complete ThingsBoard installation and database initialization before connecting it to the IoTDB table model. + +- For IoTDB deployment, see [Standalone Deployment](../Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md). +- Download ThingsBoard from the [4.3.1.2 release page](https://github.com/thingsboard/thingsboard/releases/tag/v4.3.1.2), then follow its official guide to install it, configure its database, and initialize it. + +If IoTDB and ThingsBoard run in separate containers, connect them to the same Docker network and use an IoTDB service name resolvable by ThingsBoard. For `apache/iotdb:2.0.11-standalone`, if the IoTDB service is named `iotdb`, set these values in its `environment`: + +```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.3 Obtain and Deploy the Extension + +1. **Get the extension.** Download `iotdb-thingsboard-table-2.0.11.jar` from the [Apache IoTDB Extras 2.0.11 release](https://github.com/apache/iotdb-extras/releases/tag/v2.0.11). + +2. **Download the dependencies.** The extension JAR does not bundle IoTDB client libraries. Download all nine dependency JARs from Maven Central and save them with the extension JAR in a local `lib` directory. + + | Maven dependency | Version | JAR download | + |---|---|---| + | `org.apache.iotdb:iotdb-session` | `2.0.11` | [iotdb-session-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar) | + | `org.apache.iotdb:isession` | `2.0.11` | [isession-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar) | + | `org.apache.iotdb:service-rpc` | `2.0.11` | [service-rpc-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar) | + | `org.apache.iotdb:iotdb-thrift` | `2.0.11` | [iotdb-thrift-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar) | + | `org.apache.iotdb:iotdb-thrift-commons` | `2.0.11` | [iotdb-thrift-commons-2.0.11.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar) | + | `org.apache.thrift:libthrift` | `0.23.0` | [libthrift-0.23.0.jar](https://repo1.maven.org/maven2/org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar) | + | `org.apache.tsfile:tsfile` | `2.4.0` | [tsfile-2.4.0.jar](https://repo1.maven.org/maven2/org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar) | + | `org.apache.tsfile:common` | `2.4.0` | [common-2.4.0.jar](https://repo1.maven.org/maven2/org/apache/tsfile/common/2.4.0/common-2.4.0.jar) | + | `org.tukaani:xz` | `1.10` | [xz-1.10.jar](https://repo1.maven.org/maven2/org/tukaani/xz/1.10/xz-1.10.jar) | + + The `lib` directory must contain 10 JARs: the extension and nine dependencies. ThingsBoard 4.3.1.2 already includes LZ4, Zstd, Snappy, and ANTLR runtime libraries. Do not add duplicate versions of these libraries. + +3. **Deploy the extension.** Put the extension JAR and all nine dependency JARs in the ThingsBoard extensions directory: + - **Linux (`.deb`):** `/usr/share/thingsboard/extensions` (create it if needed). + - **Windows:** `\extensions`. + - **Docker:** Mount `lib` at `/usr/share/thingsboard/extensions` in the container. + + For a Linux `.deb` installation, run this from the directory containing `lib`: + + ```Bash + sudo install -d /usr/share/thingsboard/extensions + sudo install -m 0644 lib/*.jar /usr/share/thingsboard/extensions/ + ``` + + If you changed the installation path or startup configuration, use the extension loading path actually used by the ThingsBoard process. Creating the directory and copying JARs does not add it to the loading path automatically. + +### 2.4 Configure the Extension + +Pass configuration through the ThingsBoard process `SPRING_APPLICATION_JSON` environment variable. The examples below are for a single ThingsBoard node and enable historical telemetry, latest telemetry, and entity attribute storage. + +Change the IoTDB host, port, credentials, and database name to match your environment. If `SPRING_APPLICATION_JSON` already exists, merge these properties into its JSON object and preserve the other settings. Keep property names exactly as shown. Defaults are `127.0.0.1:6667`, username/password `root`/`root`, database `thingsboard`, and session pool size `8`. With `iotdb.schema.bootstrap=true`, the first startup creates the database and required tables. In a container, specify an IoTDB host reachable from that container; the default address does not change automatically. + +#### 2.4.1 Docker Compose + +Merge this snippet into the ThingsBoard service in your existing Compose file. The example uses service names `thingsboard` and `iotdb`; update them as needed and preserve existing ports, networks, volumes, and environment variables. The `lib` directory from Section 2.3 should be next to the Compose file. + +```YAML +services: + thingsboard: + image: thingsboard/tb-node:4.3.1.2 + volumes: + - ./lib:/usr/share/thingsboard/extensions:ro + environment: + SPRING_APPLICATION_JSON: >- + { + "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" + } +``` + +This snippet is for an already installed ThingsBoard service, not a complete Compose file. If the extensions directory is already mounted, place all 10 JARs in that mount source and do not mount the same container path twice. + +#### 2.4.2 Linux (`.deb`) + +Add this to `/etc/thingsboard/conf/thingsboard.conf`, preserving existing settings. The ThingsBoard service reads this shell file at startup, so keep `export` and the single quotes around the JSON. Exporting a variable only in an interactive terminal does not change system service configuration. This example assumes IoTDB is on the same host; change `iotdb.host` otherwise. + +```Bash +export SPRING_APPLICATION_JSON='{ + "iotdb.host": "127.0.0.1", + "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" +}' +``` + +#### 2.4.3 Windows + +Set the JSON object from Section 2.4.2 as a system or service environment variable accessible to the ThingsBoard process. The variable is named `SPRING_APPLICATION_JSON`; its value is the JSON content from `{` to `}`, without Bash `export` or the surrounding single quotes. + +Setting `$env:SPRING_APPLICATION_JSON` in the current PowerShell window does not change an already registered service's environment. The official Windows installer uses `install.bat` to configure the extension loading path. After changing the installation location or startup method, confirm that the actual loading path includes the extensions directory. + +### 2.5 Start and Check ThingsBoard + +Start or restart ThingsBoard using the procedure for your deployment: + +- **Docker Compose:** Run in the directory containing the Compose file. Replace `thingsboard` if your service has a different name. + + ```Bash + docker compose up -d thingsboard + ``` + + This command recreates the container when configuration changes. Restarting an existing container alone does not apply changed environment variables or mounts. + +- **Linux (`.deb`):** Restart the system service with `sudo systemctl restart thingsboard`. +- **Windows:** Restart the ThingsBoard service in Windows Service Manager. + +Check the logs for extension connection-pool initialization. When schema bootstrap is enabled, the logs should also show schema creation completion: + +```Plain Text +IoTDB Table Mode session pool initialized +IoTDB Table Mode schema bootstrap complete +``` + +When entity attribute storage is enabled, a WARN about the extension replacing `jpaAttributeDao` is expected. If you see `NoClassDefFoundError: org/apache/iotdb/isession/pool/ITableSessionPool`, verify that the extension directory contains the module JAR and all nine dependencies and that it is in the ThingsBoard loading path. + +Linux `.deb` service logs are usually under `/var/log/thingsboard/`. Log locations for Windows services and containers depend on how they are installed or run. A foreground process usually writes logs to the console or configured log directory. + +### 2.6 Verify the Data + +Create a device in ThingsBoard and get its access token. Send telemetry to the device: + +```HTTP +POST http://:8080/api/v1//telemetry +Content-Type: application/json + +{"temperature":23.75,"status":"ok"} +``` + +Send client attributes to the device: + +```HTTP +POST http://:8080/api/v1//attributes +Content-Type: application/json + +{"site":"local"} +``` + +Use any HTTP client to send these requests. In Windows PowerShell, use `curl.exe` or `Invoke-RestMethod`. + +After writing data, open the device details in ThingsBoard: + +- On the **Latest telemetry** page, confirm the telemetry keys and values. + +![ThingsBoard-Table-01.png](/img/ThingsBoard-Table-01.png) + +- On the **Attributes** page, select **Client attributes** and confirm the attribute keys and values. + +![ThingsBoard-Table-02.png](/img/ThingsBoard-Table-02.png) + +The screenshots are examples; their keys and values differ from the requests above. Check the data you sent. + +After telemetry has been written in batches, query it with the IoTDB table-model CLI or a JDBC client. Replace `` with the device ID from ThingsBoard: + +```SQL +USE thingsboard; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry_latest +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, attribute_scope, key, bool_v, long_v, double_v, str_v, json_v +FROM entity_attributes +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; +``` + +Compare the entity ID, key, and value. In the telemetry example, `ts` and `value` are stored in `json_v`; the table's `time` is the IoTDB row time and may differ from the sample timestamp in the request. Check attributes by scope and value type; for example, a string attribute in `CLIENT_SCOPE` is stored in `str_v`. Latest telemetry and attributes can also be read from the ThingsBoard device page. + +## 3. Select Storage Paths + +Keep the relevant selectors and properties in `SPRING_APPLICATION_JSON`: + +| Storage path | Configuration | Description | +|---|---|---| +| Historical telemetry | `database.ts.type=iotdb-table`, `iotdb.ts.experimental-raw-only=true` | Supports writes, raw queries, deletion, and time-window aggregation. This compatibility-named property must be set with the historical telemetry selector. | +| Latest telemetry | `database.ts_latest.type=iotdb-table`, `iotdb.ts_latest.cluster_mode` | Depends on historical telemetry storage. Without this selector, ThingsBoard continues to use its original backend for latest telemetry. | +| Entity attributes | `database.attributes.type=iotdb-table`, `iotdb.attributes.cluster_mode` | Independent of telemetry storage. When enabled, the extension provides the attribute DAO. | + +When enabling latest telemetry or entity attribute storage, set a valid corresponding `cluster_mode`: + +- For one ThingsBoard node, use `disabled`. +- For multiple ThingsBoard nodes, use `sticky-routing` only if writes, updates, and deletes for latest values and attributes of the same device or entity are consistently routed to the same node. This setting does not configure ThingsBoard traffic routing. +- In a multi-node deployment without sticky routing, `disabled` can produce inconsistent results when different nodes concurrently update the same latest-value key or attribute. The extension does not coordinate cross-node writes. + +Here, “node” means a ThingsBoard node, not an IoTDB node. `disabled` does not turn off storage. If the corresponding backend is enabled and `cluster_mode` is missing, empty, or set to another value, ThingsBoard fails to start. + +## 4. Data Migration and Limitations + +- **Existing data:** The extension does not migrate data automatically. Backfill and verify an existing instance before switching. After enabling attribute storage, old attributes that were not migrated may no longer be readable through ThingsBoard. +- **Data retention:** IoTDB applies TTL at the table level and does not apply ThingsBoard per-record TTL. `telemetry_latest` does not expire automatically by default and is not affected by the historical telemetry table TTL; plan its retention separately. +- **Data types:** Keep the type consistent for the same entity, key, and timestamp. Changing the type across batches can make that data point unreadable. +- **Version notifications:** Latest telemetry and attribute operations return a `null` `version`; notifications requiring a non-null version will not work. +- **Configuration rollback:** Restoring the original storage configuration does not move data back from IoTDB. Plan a backfill or synchronization separately if you need to preserve data written during the integration. + +## 5. References + +For configuration parameters, table schemas, and migration mappings, see the [IoTDB ThingsBoard Table extension documentation](https://github.com/apache/iotdb-extras/tree/v2.0.11/iotdb-thingsboard-table). The module `README.md` provides an overview; `docs/user-guide.md` and `docs/migration-guide.md` provide detailed usage and migration guidance. 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..c8ea96bf4 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-Table_apache.md) diff --git a/src/zh/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md new file mode 100644 index 000000000..d0d9cf541 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/Ecosystem-Integration/ThingsBoard-Table_apache.md @@ -0,0 +1,306 @@ +# ThingsBoard + +## 1\. 产品概述 + +### 1\.1 ThingsBoard 简介 + +ThingsBoard 是一个开源物联网平台,提供设备管理、数据采集和可视化等功能,帮助用户快速开发、管理和扩展物联网应用。更多介绍请参考 [ThingsBoard 官网](https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/)。 + +![ThingsBoard.png](/img/ThingsBoard-1.png) + +### 1\.2 ThingsBoard 与 IoTDB 表模型集成 + +IoTDB 提供的 `iotdb-thingsboard-table` 扩展,可将 ThingsBoard 的历史遥测、最新遥测值和实体属性存储到 IoTDB 表模型,并支持在 ThingsBoard 中读取和展示这些数据。用户可按需选择使用 IoTDB 存储的数据类型,通过 ThingsBoard 进行设备数据管理与可视化。 + +## 2\. 使用步骤 + +### 2\.1 环境要求 + +本文以 IoTDB 2\.0\.11、ThingsBoard 4\.3\.1\.2 和 `iotdb-thingsboard-table` 2\.0\.11 为例介绍集成步骤。使用更高版本时,请结合对应版本文档确认扩展兼容性,并调整依赖、配置及启动方式。 + +|软件|示例版本或配置|用途| +|---|---|---| +|IoTDB|2\.0\.11,表模型|存储遥测和/或属性| +|ThingsBoard|4\.3\.1\.2|设备接入与数据管理| +|JDK|17|运行 IoTDB 和 ThingsBoard| + +IoTDB 与 ThingsBoard 可以部署在不同主机或容器中。ThingsBoard 运行环境必须能够访问 IoTDB RPC 地址(默认端口 `6667`)。首次部署建议使用独立测试实例和测试设备。 + +### 2\.2 安装基础环境 + +按官方安装指南完成 ThingsBoard 和 IoTDB 的安装,并确认它们可以独立启动。先完成 ThingsBoard 自身的安装和数据库初始化,再按后续步骤接入 IoTDB 表模型。 + +- IoTDB 的安装部署请参考[单机部署](../Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md)章节。 + +- 从 [ThingsBoard 4\.3\.1\.2 发布页](https://github.com/thingsboard/thingsboard/releases/tag/v4.3.1.2)获取安装包,并按 ThingsBoard 官方安装指南完成安装、数据库配置和初始化。 + +如果 IoTDB 与 ThingsBoard 分别运行在容器中,应将两者接入同一 Docker 网络,并让 IoTDB 使用 ThingsBoard 可访问的服务名。对于 `apache/iotdb:2.0.11-standalone` 镜像,假设 IoTDB 服务名为 `iotdb`,在该服务的 `environment` 中设置: + +```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\.3 获取并部署扩展 + +1. **获取扩展。** 从 [Apache IoTDB Extras 2\.0\.11 发布目录](https://github.com/apache/iotdb-extras/releases/tag/v2.0.11)获取 `iotdb-thingsboard-table-2.0.11.jar`。 + +2. **下载依赖。** 扩展 JAR 不包含 IoTDB 客户端库。通过下表中的 Maven Central 链接下载全部 9 个依赖 JAR,与扩展 JAR 一起保存到本地 `lib` 目录。 + + | Maven 依赖| 版本| JAR 下载| + |---|---|---| + | `org.apache.iotdb:iotdb-session`| `2.0.11`| [iotdb\-session\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar)| + | `org.apache.iotdb:isession`| `2.0.11`| [isession\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar)| + | `org.apache.iotdb:service-rpc`| `2.0.11`| [service\-rpc\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar)| + | `org.apache.iotdb:iotdb-thrift`| `2.0.11`| [iotdb\-thrift\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar)| + | `org.apache.iotdb:iotdb-thrift-commons`| `2.0.11`| [iotdb\-thrift\-commons\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar)| + | `org.apache.thrift:libthrift`| `0.23.0`| [libthrift\-0\.23\.0\.jar](https://repo1.maven.org/maven2/org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar)| + | `org.apache.tsfile:tsfile`| `2.4.0`| [tsfile\-2\.4\.0\.jar](https://repo1.maven.org/maven2/org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar)| + | `org.apache.tsfile:common`| `2.4.0`| [common\-2\.4\.0\.jar](https://repo1.maven.org/maven2/org/apache/tsfile/common/2.4.0/common-2.4.0.jar)| + | `org.tukaani:xz`| `1.10`| [xz\-1\.10\.jar](https://repo1.maven.org/maven2/org/tukaani/xz/1.10/xz-1.10.jar)| + + 也可在 Bash 中执行以下命令,一次下载扩展和全部依赖到当前目录下的 `lib` 文件夹(适用于 Linux、macOS 或 Windows Git Bash): + + ```Bash + mkdir -p lib + R=https://github.com/apache/iotdb-extras/releases/download/v2.0.11 + curl -fL -o lib/iotdb-thingsboard-table-2.0.11.jar "$R/iotdb-thingsboard-table-2.0.11.jar" + + M=https://repo1.maven.org/maven2 + for path in \ + org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar \ + org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar \ + org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar \ + org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar \ + org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar \ + org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar \ + org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar \ + org/apache/tsfile/common/2.4.0/common-2.4.0.jar \ + org/tukaani/xz/1.10/xz-1.10.jar; do + curl -fL -o "lib/${path##*/}" "$M/$path" + done + ``` + + 下载完成后,`lib` 目录中应有 10 个 JAR(1 个扩展 JAR 和 9 个依赖 JAR)。 + + ThingsBoard 4\.3\.1\.2 已包含 LZ4、Zstd、Snappy 和 ANTLR 运行库,不要在扩展目录中放入这些库的重复版本。 + +3. **部署扩展。** 将扩展 JAR 和全部 9 个依赖 JAR 放入 ThingsBoard 扩展目录: + + - **Linux(****`.deb`**** 安装包):** `/usr/share/thingsboard/extensions`(适用于 ThingsBoard 4\.3\.1\.2 官方 `.deb` 包的常规安装,目录不存在时需手动创建)。 + + - **Windows:** `\extensions`。 + + - **Docker:** 将 `lib` 目录挂载到容器内的 `/usr/share/thingsboard/extensions`,配置示例见第 2\.4\.1 节。 + + 使用 Linux `.deb` 安装包时,在包含 `lib` 文件夹的目录中执行以下命令,创建扩展目录并复制全部 JAR: + + ```Bash + sudo install -d /usr/share/thingsboard/extensions + sudo install -m 0644 lib/*.jar /usr/share/thingsboard/extensions/ + ``` + + 若修改了安装位置或启动配置,请以 ThingsBoard 进程的实际扩展加载路径为准。仅创建目录并复制 JAR,不会自动将该目录加入加载路径。 + +> 可选:如需验证扩展包的来源与完整性,可导入 Apache IoTDB [KEYS 文件](https://dist.apache.org/repos/dist/release/iotdb/KEYS)中的发布签名公钥,使用同一次发布中与扩展 JAR 对应的 `.asc` 文件校验签名。签名文件不需要部署到扩展目录。 +> +> + +### 2\.4 配置扩展 + +通过 ThingsBoard 进程的 `SPRING_APPLICATION_JSON` 环境变量传入配置。以下示例均适用于单个 ThingsBoard 节点,并同时启用历史遥测、最新遥测和实体属性存储。 + +根据实际部署修改 IoTDB 主机、端口、账号和数据库名。若已设置 `SPRING_APPLICATION_JSON`,将这些属性合并到现有 JSON 对象中,保留其他配置。属性名称中的连字符和下划线须按示例书写。 + +模块默认连接地址为 `127.0.0.1:6667`、账号密码为 `root`/`root`、数据库名为 `thingsboard`、会话池大小为 `8`。`iotdb.schema.bootstrap=true` 时首次启动会自动创建数据库和扩展所需的表。容器中应显式填写可访问的 IoTDB 主机名,默认地址不会因容器部署而自动改变。 + +#### 2\.4\.1 Docker Compose + +将以下片段合并到现有 Compose 文件的 ThingsBoard 服务中。示例使用服务名 `thingsboard`,IoTDB 服务名为 `iotdb`;请按实际服务名称修改,并保留原有端口、网络、数据卷及其他环境变量。第 2\.3 节下载的 `lib` 目录应与 Compose 文件位于同一目录。 + +```YAML +services: + thingsboard: + image: thingsboard/tb-node:4.3.1.2 + volumes: + - ./lib:/usr/share/thingsboard/extensions:ro + environment: + SPRING_APPLICATION_JSON: >- + { + "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" + } +``` + +该片段用于已经完成基础安装的 ThingsBoard 运行服务,不是独立的完整 Compose 文件。若已挂载扩展目录,将全部 10 个 JAR 放入原挂载目录,不要对同一容器路径重复挂载。 + +#### 2\.4\.2 Linux(`.deb` 安装包) + +将以下配置加入 `/etc/thingsboard/conf/thingsboard.conf`,保留文件中的现有设置。ThingsBoard 服务启动时会读取该 shell 文件,因此须保留 `export` 和 JSON 外侧的单引号。只在终端中导出环境变量不会修改系统服务配置。 + +示例假设 IoTDB 与 ThingsBoard 部署在同一主机;若使用其他地址,请修改 `iotdb.host`。 + +```Bash +export SPRING_APPLICATION_JSON='{ + "iotdb.host": "127.0.0.1", + "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" +}' +``` + +#### 2\.4\.3 Windows + +将第 2\.4\.2 节中 `SPRING_APPLICATION_JSON` 的 JSON 对象内容设置为 ThingsBoard 服务进程可读取的系统或服务环境变量。变量名为 `SPRING_APPLICATION_JSON`;变量值仅填写从 `{` 到 `}` 的 JSON 内容,不包含 Bash 的 `export` 和外侧单引号。 + +只在当前 PowerShell 窗口设置 `$env:SPRING_APPLICATION_JSON` 不会更改已注册服务的环境。Windows 官方安装包通过 `install.bat` 配置扩展加载路径;修改安装位置或启动方式后,应确认实际加载路径包含扩展目录。 + +### 2\.5 启动并检查 + +按部署方式启动或重启 ThingsBoard: + +- **Docker Compose:** 在 Compose 文件所在目录执行;若服务名不同,替换 `thingsboard`。 + + ```Bash + docker compose up -d thingsboard + ``` + + 配置发生变化时,该命令会重建容器。仅重启已有容器不会应用修改后的环境变量或挂载配置。 + +- **Linux(****`.deb`**** 安装包):** 重启系统服务。 + + ```Bash + sudo systemctl restart thingsboard + ``` + +- **Windows:** 通过 Windows 服务管理器重启 ThingsBoard 服务。 + +确认日志包含扩展连接池初始化信息;启用表结构初始化时,还应出现 schema 创建完成信息: + +```Plain Text +IoTDB Table Mode session pool initialized +IoTDB Table Mode schema bootstrap complete +``` + +启用实体属性存储时,日志中出现扩展替换 `jpaAttributeDao` 的 WARN 属于预期信息。若出现 `NoClassDefFoundError: org/apache/iotdb/isession/pool/ITableSessionPool`,请确认扩展目录包含模块 JAR 和全部 9 个依赖 JAR,并且该目录已加入 ThingsBoard 加载路径。 + +Linux `.deb` 服务日志通常位于 `/var/log/thingsboard/`;Windows 服务和容器的日志位置由其安装或运行方式决定。以前台进程运行时,日志通常输出到控制台或该进程配置的日志目录。 + +### 2\.6 验证数据 + +在 ThingsBoard 中创建设备并取得设备访问令牌。向设备遥测接口写入数据: + +```HTTP +POST http://:8080/api/v1/<设备访问令牌>/telemetry +Content-Type: application/json + +{"temperature":23.75,"status":"ok"} +``` + +向客户端属性接口写入数据: + +```HTTP +POST http://:8080/api/v1/<设备访问令牌>/attributes +Content-Type: application/json + +{"site":"local"} +``` + +可使用任意支持 HTTP 请求的客户端发送上述请求。Windows PowerShell 中请使用 `curl.exe`,或使用 `Invoke-RestMethod`;两者只是命令行调用方式不同。 + +写入后,在设备详情中查看数据: + +- 在 **Latest telemetry(最新遥测)** 页面确认遥测键和值。 + +![ThingsBoard-Table-01.png](/img/ThingsBoard-Table-01.png) + +- 在 **Attributes(属性)** 页面选择 **Client attributes(客户端属性)**,确认属性键和值。 + +![ThingsBoard-Table-02.png](/img/ThingsBoard-Table-02.png) + +以上为页面示例,图中键值与本文写入样本不同,请以实际发送的数据为准。 + +等待遥测批量写入后,在 IoTDB 表模型 CLI 或 JDBC 客户端中查询。将 `` 替换为 ThingsBoard 中该设备的 ID: + +```SQL +USE thingsboard; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry_latest +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, attribute_scope, key, bool_v, long_v, double_v, str_v, json_v +FROM entity_attributes +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; +``` + +对照实体 ID、键和值。遥测样本的 `ts` 和 `value` 存储在 `json_v` 中;表的 `time` 表示 IoTDB 行时间,不一定与请求中的样本时间戳相同。属性可按 scope 和对应类型列核对,例如 `CLIENT_SCOPE` 的字符串属性位于 `str_v`。ThingsBoard 设备页面中的最新遥测和属性也可用于回读检查。 + +## 3\. 存储路径配置 + +按需在 `SPRING_APPLICATION_JSON` 中保留相应存储选择器及参数: + +|存储路径|配置|说明| +|---|---|---| +|历史遥测|`database.ts.type=iotdb-table`、`iotdb.ts.experimental-raw-only=true`|支持写入、原始查询、删除和时间窗口聚合。`experimental-raw-only` 是兼容性配置名,必须与历史遥测选择器同时设置。| +|最新遥测|`database.ts_latest.type=iotdb-table`、`iotdb.ts_latest.cluster_mode`|依赖历史遥测存储。未启用该选择器时,最新遥测仍由 ThingsBoard 原存储后端处理。| +|实体属性|`database.attributes.type=iotdb-table`、`iotdb.attributes.cluster_mode`|独立于遥测存储。启用后使用扩展提供的属性 DAO。| + +启用最新遥测或实体属性存储时,必须为对应的 `cluster_mode` 设置有效值: + +- 单个 ThingsBoard 节点使用 `disabled`。 + +- 多个 ThingsBoard 节点只有在同一设备或实体的最新遥测值和属性写入、更新及删除都能稳定路由至同一节点时,才使用 `sticky-routing`。该配置值不会自动配置 ThingsBoard 流量路由。 + +- 未配置粘性路由的多节点部署使用 `disabled` 时,不同节点并发更新同一最新值键或属性可能导致结果不一致。扩展不协调跨节点写入。 + +这里的“节点”指 ThingsBoard 节点,而不是 IoTDB 节点。`disabled` 不会关闭存储功能。启用了相应后端但未设置、留空或使用其他 `cluster_mode` 值时,ThingsBoard 会启动失败。 + +## 4\. 数据迁移与限制 + +- **已有数据:** 扩展不会自动迁移数据。已有实例切换前需完成回填并核对;启用属性存储后,未迁移的旧属性可能无法通过 ThingsBoard 读取。 + +- **数据保留:** IoTDB 按表设置 TTL,不会应用 ThingsBoard 的单条数据 TTL。`telemetry_latest` 默认不自动过期,也不受历史遥测表 TTL 影响,需单独规划保留策略。 + +- **数据类型:** 同一实体、键和时间戳的数据应保持类型一致,跨批次变更类型可能导致该数据点读取失败。 + +- **版本通知:** 最新遥测和属性操作返回的 `version` 为 `null`,依赖非空版本号的通知不会生效。 + +- **配置回退:** 恢复原存储配置不会自动迁回 IoTDB 中的数据;如需保留接入期间新增的数据,应另行安排回填或同步。 + +## 5\. 参考资料 + +完整配置参数、表结构和数据迁移映射等资料,请参见 [IoTDB ThingsBoard Table 扩展文档](https://github.com/apache/iotdb-extras/tree/v2.0.11/iotdb-thingsboard-table)。该目录的 `README.md` 提供模块概览,`docs/user-guide.md` 和 `docs/migration-guide.md` 分别提供详细使用说明与迁移说明。 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..c8ea96bf4 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-Table_apache.md) diff --git a/src/zh/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md new file mode 100644 index 000000000..d0d9cf541 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/Ecosystem-Integration/ThingsBoard-Table_apache.md @@ -0,0 +1,306 @@ +# ThingsBoard + +## 1\. 产品概述 + +### 1\.1 ThingsBoard 简介 + +ThingsBoard 是一个开源物联网平台,提供设备管理、数据采集和可视化等功能,帮助用户快速开发、管理和扩展物联网应用。更多介绍请参考 [ThingsBoard 官网](https://thingsboard.io/docs/getting-started-guides/what-is-thingsboard/)。 + +![ThingsBoard.png](/img/ThingsBoard-1.png) + +### 1\.2 ThingsBoard 与 IoTDB 表模型集成 + +IoTDB 提供的 `iotdb-thingsboard-table` 扩展,可将 ThingsBoard 的历史遥测、最新遥测值和实体属性存储到 IoTDB 表模型,并支持在 ThingsBoard 中读取和展示这些数据。用户可按需选择使用 IoTDB 存储的数据类型,通过 ThingsBoard 进行设备数据管理与可视化。 + +## 2\. 使用步骤 + +### 2\.1 环境要求 + +本文以 IoTDB 2\.0\.11、ThingsBoard 4\.3\.1\.2 和 `iotdb-thingsboard-table` 2\.0\.11 为例介绍集成步骤。使用更高版本时,请结合对应版本文档确认扩展兼容性,并调整依赖、配置及启动方式。 + +|软件|示例版本或配置|用途| +|---|---|---| +|IoTDB|2\.0\.11,表模型|存储遥测和/或属性| +|ThingsBoard|4\.3\.1\.2|设备接入与数据管理| +|JDK|17|运行 IoTDB 和 ThingsBoard| + +IoTDB 与 ThingsBoard 可以部署在不同主机或容器中。ThingsBoard 运行环境必须能够访问 IoTDB RPC 地址(默认端口 `6667`)。首次部署建议使用独立测试实例和测试设备。 + +### 2\.2 安装基础环境 + +按官方安装指南完成 ThingsBoard 和 IoTDB 的安装,并确认它们可以独立启动。先完成 ThingsBoard 自身的安装和数据库初始化,再按后续步骤接入 IoTDB 表模型。 + +- IoTDB 的安装部署请参考[单机部署](../Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md)章节。 + +- 从 [ThingsBoard 4\.3\.1\.2 发布页](https://github.com/thingsboard/thingsboard/releases/tag/v4.3.1.2)获取安装包,并按 ThingsBoard 官方安装指南完成安装、数据库配置和初始化。 + +如果 IoTDB 与 ThingsBoard 分别运行在容器中,应将两者接入同一 Docker 网络,并让 IoTDB 使用 ThingsBoard 可访问的服务名。对于 `apache/iotdb:2.0.11-standalone` 镜像,假设 IoTDB 服务名为 `iotdb`,在该服务的 `environment` 中设置: + +```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\.3 获取并部署扩展 + +1. **获取扩展。** 从 [Apache IoTDB Extras 2\.0\.11 发布目录](https://github.com/apache/iotdb-extras/releases/tag/v2.0.11)获取 `iotdb-thingsboard-table-2.0.11.jar`。 + +2. **下载依赖。** 扩展 JAR 不包含 IoTDB 客户端库。通过下表中的 Maven Central 链接下载全部 9 个依赖 JAR,与扩展 JAR 一起保存到本地 `lib` 目录。 + + | Maven 依赖| 版本| JAR 下载| + |---|---|---| + | `org.apache.iotdb:iotdb-session`| `2.0.11`| [iotdb\-session\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar)| + | `org.apache.iotdb:isession`| `2.0.11`| [isession\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar)| + | `org.apache.iotdb:service-rpc`| `2.0.11`| [service\-rpc\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar)| + | `org.apache.iotdb:iotdb-thrift`| `2.0.11`| [iotdb\-thrift\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar)| + | `org.apache.iotdb:iotdb-thrift-commons`| `2.0.11`| [iotdb\-thrift\-commons\-2\.0\.11\.jar](https://repo1.maven.org/maven2/org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar)| + | `org.apache.thrift:libthrift`| `0.23.0`| [libthrift\-0\.23\.0\.jar](https://repo1.maven.org/maven2/org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar)| + | `org.apache.tsfile:tsfile`| `2.4.0`| [tsfile\-2\.4\.0\.jar](https://repo1.maven.org/maven2/org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar)| + | `org.apache.tsfile:common`| `2.4.0`| [common\-2\.4\.0\.jar](https://repo1.maven.org/maven2/org/apache/tsfile/common/2.4.0/common-2.4.0.jar)| + | `org.tukaani:xz`| `1.10`| [xz\-1\.10\.jar](https://repo1.maven.org/maven2/org/tukaani/xz/1.10/xz-1.10.jar)| + + 也可在 Bash 中执行以下命令,一次下载扩展和全部依赖到当前目录下的 `lib` 文件夹(适用于 Linux、macOS 或 Windows Git Bash): + + ```Bash + mkdir -p lib + R=https://github.com/apache/iotdb-extras/releases/download/v2.0.11 + curl -fL -o lib/iotdb-thingsboard-table-2.0.11.jar "$R/iotdb-thingsboard-table-2.0.11.jar" + + M=https://repo1.maven.org/maven2 + for path in \ + org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar \ + org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar \ + org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar \ + org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar \ + org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar \ + org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar \ + org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar \ + org/apache/tsfile/common/2.4.0/common-2.4.0.jar \ + org/tukaani/xz/1.10/xz-1.10.jar; do + curl -fL -o "lib/${path##*/}" "$M/$path" + done + ``` + + 下载完成后,`lib` 目录中应有 10 个 JAR(1 个扩展 JAR 和 9 个依赖 JAR)。 + + ThingsBoard 4\.3\.1\.2 已包含 LZ4、Zstd、Snappy 和 ANTLR 运行库,不要在扩展目录中放入这些库的重复版本。 + +3. **部署扩展。** 将扩展 JAR 和全部 9 个依赖 JAR 放入 ThingsBoard 扩展目录: + + - **Linux(****`.deb`**** 安装包):** `/usr/share/thingsboard/extensions`(适用于 ThingsBoard 4\.3\.1\.2 官方 `.deb` 包的常规安装,目录不存在时需手动创建)。 + + - **Windows:** `\extensions`。 + + - **Docker:** 将 `lib` 目录挂载到容器内的 `/usr/share/thingsboard/extensions`,配置示例见第 2\.4\.1 节。 + + 使用 Linux `.deb` 安装包时,在包含 `lib` 文件夹的目录中执行以下命令,创建扩展目录并复制全部 JAR: + + ```Bash + sudo install -d /usr/share/thingsboard/extensions + sudo install -m 0644 lib/*.jar /usr/share/thingsboard/extensions/ + ``` + + 若修改了安装位置或启动配置,请以 ThingsBoard 进程的实际扩展加载路径为准。仅创建目录并复制 JAR,不会自动将该目录加入加载路径。 + +> 可选:如需验证扩展包的来源与完整性,可导入 Apache IoTDB [KEYS 文件](https://dist.apache.org/repos/dist/release/iotdb/KEYS)中的发布签名公钥,使用同一次发布中与扩展 JAR 对应的 `.asc` 文件校验签名。签名文件不需要部署到扩展目录。 +> +> + +### 2\.4 配置扩展 + +通过 ThingsBoard 进程的 `SPRING_APPLICATION_JSON` 环境变量传入配置。以下示例均适用于单个 ThingsBoard 节点,并同时启用历史遥测、最新遥测和实体属性存储。 + +根据实际部署修改 IoTDB 主机、端口、账号和数据库名。若已设置 `SPRING_APPLICATION_JSON`,将这些属性合并到现有 JSON 对象中,保留其他配置。属性名称中的连字符和下划线须按示例书写。 + +模块默认连接地址为 `127.0.0.1:6667`、账号密码为 `root`/`root`、数据库名为 `thingsboard`、会话池大小为 `8`。`iotdb.schema.bootstrap=true` 时首次启动会自动创建数据库和扩展所需的表。容器中应显式填写可访问的 IoTDB 主机名,默认地址不会因容器部署而自动改变。 + +#### 2\.4\.1 Docker Compose + +将以下片段合并到现有 Compose 文件的 ThingsBoard 服务中。示例使用服务名 `thingsboard`,IoTDB 服务名为 `iotdb`;请按实际服务名称修改,并保留原有端口、网络、数据卷及其他环境变量。第 2\.3 节下载的 `lib` 目录应与 Compose 文件位于同一目录。 + +```YAML +services: + thingsboard: + image: thingsboard/tb-node:4.3.1.2 + volumes: + - ./lib:/usr/share/thingsboard/extensions:ro + environment: + SPRING_APPLICATION_JSON: >- + { + "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" + } +``` + +该片段用于已经完成基础安装的 ThingsBoard 运行服务,不是独立的完整 Compose 文件。若已挂载扩展目录,将全部 10 个 JAR 放入原挂载目录,不要对同一容器路径重复挂载。 + +#### 2\.4\.2 Linux(`.deb` 安装包) + +将以下配置加入 `/etc/thingsboard/conf/thingsboard.conf`,保留文件中的现有设置。ThingsBoard 服务启动时会读取该 shell 文件,因此须保留 `export` 和 JSON 外侧的单引号。只在终端中导出环境变量不会修改系统服务配置。 + +示例假设 IoTDB 与 ThingsBoard 部署在同一主机;若使用其他地址,请修改 `iotdb.host`。 + +```Bash +export SPRING_APPLICATION_JSON='{ + "iotdb.host": "127.0.0.1", + "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" +}' +``` + +#### 2\.4\.3 Windows + +将第 2\.4\.2 节中 `SPRING_APPLICATION_JSON` 的 JSON 对象内容设置为 ThingsBoard 服务进程可读取的系统或服务环境变量。变量名为 `SPRING_APPLICATION_JSON`;变量值仅填写从 `{` 到 `}` 的 JSON 内容,不包含 Bash 的 `export` 和外侧单引号。 + +只在当前 PowerShell 窗口设置 `$env:SPRING_APPLICATION_JSON` 不会更改已注册服务的环境。Windows 官方安装包通过 `install.bat` 配置扩展加载路径;修改安装位置或启动方式后,应确认实际加载路径包含扩展目录。 + +### 2\.5 启动并检查 + +按部署方式启动或重启 ThingsBoard: + +- **Docker Compose:** 在 Compose 文件所在目录执行;若服务名不同,替换 `thingsboard`。 + + ```Bash + docker compose up -d thingsboard + ``` + + 配置发生变化时,该命令会重建容器。仅重启已有容器不会应用修改后的环境变量或挂载配置。 + +- **Linux(****`.deb`**** 安装包):** 重启系统服务。 + + ```Bash + sudo systemctl restart thingsboard + ``` + +- **Windows:** 通过 Windows 服务管理器重启 ThingsBoard 服务。 + +确认日志包含扩展连接池初始化信息;启用表结构初始化时,还应出现 schema 创建完成信息: + +```Plain Text +IoTDB Table Mode session pool initialized +IoTDB Table Mode schema bootstrap complete +``` + +启用实体属性存储时,日志中出现扩展替换 `jpaAttributeDao` 的 WARN 属于预期信息。若出现 `NoClassDefFoundError: org/apache/iotdb/isession/pool/ITableSessionPool`,请确认扩展目录包含模块 JAR 和全部 9 个依赖 JAR,并且该目录已加入 ThingsBoard 加载路径。 + +Linux `.deb` 服务日志通常位于 `/var/log/thingsboard/`;Windows 服务和容器的日志位置由其安装或运行方式决定。以前台进程运行时,日志通常输出到控制台或该进程配置的日志目录。 + +### 2\.6 验证数据 + +在 ThingsBoard 中创建设备并取得设备访问令牌。向设备遥测接口写入数据: + +```HTTP +POST http://:8080/api/v1/<设备访问令牌>/telemetry +Content-Type: application/json + +{"temperature":23.75,"status":"ok"} +``` + +向客户端属性接口写入数据: + +```HTTP +POST http://:8080/api/v1/<设备访问令牌>/attributes +Content-Type: application/json + +{"site":"local"} +``` + +可使用任意支持 HTTP 请求的客户端发送上述请求。Windows PowerShell 中请使用 `curl.exe`,或使用 `Invoke-RestMethod`;两者只是命令行调用方式不同。 + +写入后,在设备详情中查看数据: + +- 在 **Latest telemetry(最新遥测)** 页面确认遥测键和值。 + +![ThingsBoard-Table-01.png](/img/ThingsBoard-Table-01.png) + +- 在 **Attributes(属性)** 页面选择 **Client attributes(客户端属性)**,确认属性键和值。 + +![ThingsBoard-Table-02.png](/img/ThingsBoard-Table-02.png) + +以上为页面示例,图中键值与本文写入样本不同,请以实际发送的数据为准。 + +等待遥测批量写入后,在 IoTDB 表模型 CLI 或 JDBC 客户端中查询。将 `` 替换为 ThingsBoard 中该设备的 ID: + +```SQL +USE thingsboard; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v +FROM telemetry_latest +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; + +SELECT time, entity_id, attribute_scope, key, bool_v, long_v, double_v, str_v, json_v +FROM entity_attributes +WHERE entity_id = '' +ORDER BY time DESC +LIMIT 10; +``` + +对照实体 ID、键和值。遥测样本的 `ts` 和 `value` 存储在 `json_v` 中;表的 `time` 表示 IoTDB 行时间,不一定与请求中的样本时间戳相同。属性可按 scope 和对应类型列核对,例如 `CLIENT_SCOPE` 的字符串属性位于 `str_v`。ThingsBoard 设备页面中的最新遥测和属性也可用于回读检查。 + +## 3\. 存储路径配置 + +按需在 `SPRING_APPLICATION_JSON` 中保留相应存储选择器及参数: + +|存储路径|配置|说明| +|---|---|---| +|历史遥测|`database.ts.type=iotdb-table`、`iotdb.ts.experimental-raw-only=true`|支持写入、原始查询、删除和时间窗口聚合。`experimental-raw-only` 是兼容性配置名,必须与历史遥测选择器同时设置。| +|最新遥测|`database.ts_latest.type=iotdb-table`、`iotdb.ts_latest.cluster_mode`|依赖历史遥测存储。未启用该选择器时,最新遥测仍由 ThingsBoard 原存储后端处理。| +|实体属性|`database.attributes.type=iotdb-table`、`iotdb.attributes.cluster_mode`|独立于遥测存储。启用后使用扩展提供的属性 DAO。| + +启用最新遥测或实体属性存储时,必须为对应的 `cluster_mode` 设置有效值: + +- 单个 ThingsBoard 节点使用 `disabled`。 + +- 多个 ThingsBoard 节点只有在同一设备或实体的最新遥测值和属性写入、更新及删除都能稳定路由至同一节点时,才使用 `sticky-routing`。该配置值不会自动配置 ThingsBoard 流量路由。 + +- 未配置粘性路由的多节点部署使用 `disabled` 时,不同节点并发更新同一最新值键或属性可能导致结果不一致。扩展不协调跨节点写入。 + +这里的“节点”指 ThingsBoard 节点,而不是 IoTDB 节点。`disabled` 不会关闭存储功能。启用了相应后端但未设置、留空或使用其他 `cluster_mode` 值时,ThingsBoard 会启动失败。 + +## 4\. 数据迁移与限制 + +- **已有数据:** 扩展不会自动迁移数据。已有实例切换前需完成回填并核对;启用属性存储后,未迁移的旧属性可能无法通过 ThingsBoard 读取。 + +- **数据保留:** IoTDB 按表设置 TTL,不会应用 ThingsBoard 的单条数据 TTL。`telemetry_latest` 默认不自动过期,也不受历史遥测表 TTL 影响,需单独规划保留策略。 + +- **数据类型:** 同一实体、键和时间戳的数据应保持类型一致,跨批次变更类型可能导致该数据点读取失败。 + +- **版本通知:** 最新遥测和属性操作返回的 `version` 为 `null`,依赖非空版本号的通知不会生效。 + +- **配置回退:** 恢复原存储配置不会自动迁回 IoTDB 中的数据;如需保留接入期间新增的数据,应另行安排回填或同步。 + +## 5\. 参考资料 + +完整配置参数、表结构和数据迁移映射等资料,请参见 [IoTDB ThingsBoard Table 扩展文档](https://github.com/apache/iotdb-extras/tree/v2.0.11/iotdb-thingsboard-table)。该目录的 `README.md` 提供模块概览,`docs/user-guide.md` 和 `docs/migration-guide.md` 分别提供详细使用说明与迁移说明。