ZH Getting Started

Home · GitHub

English | 简体中文

TsGate 2.1.0： 本页使用 com.alandevise.tsgate.*。从 2.0.0 升级时须更新 import、反射类名和包扫描配置，并重新编译。Central 2.0.0 保留 com.alandevise.tsdb.*。详见迁移步骤与发布状态。

Maven 引入

下面的依赖集合使用 2.1.0，与 com.alandevise.tsgate.* 示例一致。按所需后端选择 starter，也可直接使用 adapter。从 2.0.0 升级时须迁移 import 并重新编译；Central 2.0.0 使用旧包名，且没有 OpenGemini 模块。解析新版本前请核对发布状态。

IoTDB starter：

<dependency>
  <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-iotdb-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

InfluxDB 3 Core starter（可与上面的依赖同时加入同一个 POM）：

<dependency>
  <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-influxdb3-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

InfluxDB OSS 1.x starter：

<dependency>
    <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-influxdb1-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

OpenGemini starter

TsGate 2.1.0 新增 tsgate-opengemini 与 tsgate-opengemini-spring-boot-starter，构建包含四个后端、九个 JAR 模块，2.1.0 BOM 管理这两个新模块。Central 2.0.0 不包含它们。准确的默认引擎版本与拓扑验证范围见 OpenGemini 接入指南。

OpenGemini starter 依赖：

<dependency>
    <groupId>io.github.alandevise</groupId>
    <artifactId>tsgate-opengemini-spring-boot-starter</artifactId>
    <version>2.1.0</version>
</dependency>

通过 tsdb.opengemini.enable=true 启用，并在 tsdb.opengemini 下配置 url 与 database。实现对 InfluxDB1 的依赖不会启用后者；四个后端开关最多一个为 true。借用的原生客户端为兼容的 org.influxdb.InfluxDB，完整配置见专页。

业务 API 为 com.alandevise.tsgate.core 下的 TGTemplate、TGQueryBuilder<T>，以及 com.alandevise.tsgate.annotation 下的 TGMeasurement、TGTime、TGTag、TGField。启用的 starter 默认模板 Bean 名为 tgTemplate。完整 POJO 与注入示例见写入说明，模板配置见TG API 与模板配置。

OpenGemini 适配中，写入成功表示服务端已确认请求；新 measurement 或新 tag series 的索引合并后，数据才可能对查询可见。按写入/读取示例使用时，业务若需要读到刚写入的数据，应在读侧显式轮询具体 timestamp、tags 与 field 值，并设置截止时间。每次 adapter 查询只发送一次请求，TsGate 不做透明的可见性重试。详见 OpenGemini 接入指南。

最低要求与兼容范围

层级	最低支持版本 / 固定客户端	说明
Java	JDK 17	编译目标 --release 17，不使用预览特性；可运行于更新 JDK，实际验证组合见兼容性与验证
Spring Boot starter	2.7.18	使用 2.7 起支持的自动配置 imports 机制；3.x / 4.x 需按下面的依赖配置对齐客户端
构建工具	Maven 3.9+	2.1.0 包含九个 JAR 模块，另有父 POM 和独立 BOM
IoTDB server	2.0.2 表模型，须关闭 RPC 压缩	默认 iotdb-session:2.0.11；2.0.2 须显式设置 tsdb.iotdb.table.rpc-compression-enabled=false。准确 SDK/服务端/配置组合见验证矩阵；不支持树模型
InfluxDB 3 server	Core 3.0.0，须使用 union-all	固定 influxdb3-java:1.10.0；Core 3.0.0 / 3.0.3 的严格游标须显式设置 tsdb.influxdb.strict-cursor-sql=union-all。Core 3.10.0 / 3.11.5 支持默认 or，准确组合见验证矩阵
InfluxDB 1 server	1.13.1 OSS	固定 org.influxdb:influxdb-java:2.25；基于 1.x HTTP / InfluxQL，未声明旧补丁版兼容
openGemini 默认引擎	1.4.1 / 1.5.2，单节点与三节点三副本集群	使用兼容的 org.influxdb:influxdb-java:2.25；准确拓扑/配置结果见 OpenGemini 接入指南

IoTDB RPC 开关默认 true，通常无需填写 YAML；它控制 Tablet 载荷编码，与 Thrift 传输、磁盘压缩不同。2.0.2 应显式设为 false，并验证一个实际 Tablet 至少 10 行的写入。业务侧覆盖默认 SDK 应使用实际依赖坐标的 dependencyManagement 示例；仅在应用 POM 定义 iotdb.version 属性，不会覆盖 starter 的传递 SDK。

record 在 Java 16 正式引入，但本项目与 InfluxDB Java 客户端的最低基线为 Java 17，不能运行于 Java 8 / 11。 公共模型使用 record，源码遵循 Java 17 的语法与 API 基线。 这里的“最低支持”是经过回归的支持承诺，不是推测数据库理论上最早能运行的版本；更新数据库版本仍须执行升级验证。 InfluxDB 3 的支持范围与配置绑定：Core 3.0.0 / 3.0.3 在显式 union-all 下已通过更新后的 Docker 回归，默认 OR 严格游标仍不兼容；这不代表其中所有 3.x 版本均得到支持。 Spring Boot 2.7.18 是兼容目标，并不代表它仍处于上游开源维护期。模块不强制业务应用继承本项目的父 POM。

服务端版本验证状态

当前不承诺兼容 IoTDB 表模型、InfluxDB 3.x、InfluxDB 1.x 或 openGemini 的所有版本，也没有逐个版本进行实际测试。

产品	完整回归已通过	已发现不兼容	未验证范围
Apache IoTDB 表模型	SDK 2.0.11 搭配服务端 2.0.2（须 false）、2.0.10、2.0.11（两种设置均通过）；精确运行时组合见兼容指南	2.0.2 在压缩 true、单个 Tablet 至少 10 行时拒绝本次所测新版编码	其他 SDK/服务端/配置组合；树模型不在适配目标内
InfluxDB 3 Core	3.0.0 / 3.0.3 显式 union-all；3.10.0 / 3.11.5 两种策略均通过，默认 or；准确运行时/策略组合见兼容指南	3.0.0 / 3.0.3 原有 or 严格游标形态仍返回 HTTP 500，对外为 CONNECTION_ERROR；原生 SQL 不改写	其他 3.x 版本，以及 Enterprise / Cloud 产品
InfluxDB OSS 1.x	1.13.1	本次已测版本未发现阻断问题	其他 1.x 版本，以及 Enterprise 产品
openGemini 默认引擎	1.4.1 / 1.5.2，单节点与三节点三副本集群	HTTP 整数路径须精度前检；新 series 查询可见性为异步	其他版本/引擎、COLUMNSTORE/Arrow、TLS/认证及节点/入口故障切换

“未验证”不等于已知不兼容，也不构成兼容承诺；相同主版本或更高补丁号不能替代回归测试。 上述兼容结论仅针对本 Wiki 列出的适配层能力，不代表覆盖数据库的全部功能。 单元测试验证 Java 逻辑与模拟场景；服务端兼容性由真实 Docker 数据库集成测试验证。 实际测试矩阵只覆盖明确列出的 JDK / Spring Boot / 数据库组合，既不是全部版本遍历，也不是这些版本的全排列。

截至 2026-09-25，InfluxDB 1.x 最新稳定版本按官方 Docker 镜像与源码标签核验为 1.13.1；IoTDB 2.0.11 对应官方发行包。

使用 TsGate BOM 对齐客户端依赖

只需导入一次 io.github.alandevise:tsgate-bom:2.1.0，不必复制五组运行时 BOM。2.1.0 BOM 管理九个 TsGate JAR 模块，包括两个新增 openGemini 模块。它对齐选定的 IoTDB / InfluxDB 3 SDK，以及已验证的 OkHttp / Netty / gRPC / Arrow / Jackson 版本。该 BOM 无项目 parent，也不导入 Spring Boot、JUnit 或 Mockito。版本管理不会将未使用的时序库客户端加入业务 classpath。

以下示例适用于未继承 Spring Boot parent 的业务项目，将 TsGate BOM 放在 Boot BOM 前，并显式选择业务 Boot 版本；Java 17 基线保持不变。

<properties>
    <spring-boot.version>2.7.18</spring-boot.version>
    <maven.compiler.release>17</maven.compiler.release>
</properties>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.alandevise</groupId>
            <artifactId>tsgate-bom</artifactId>
            <version>2.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

导入后，所选 starter 的 dependency 可以省略 version。starter 的传递 POM 不能自动覆盖业务 dependencyManagement，因此需要对齐时仍须业务显式导入一次。业务直接管理的版本仍优先，部署前请检查 mvn dependency:tree。继承 Spring Boot starter parent 时，只需在业务 dependencyManagement 导入 TsGate BOM，省略上例中的 Boot BOM；Boot parent 2.7.18 方式已通过依赖树、写读和原生 Arrow Flight 验证，其他业务依赖组合仍须单独验证。

仅用 IoTDB 时，可继续使用 starter 默认依赖图而不导入该 BOM。InfluxDB 1.x 与 openGemini 兼容适配器需要 OkHttp / Jackson 对齐，但不需要 Arrow JVM 参数。合并 BOM 也会管理应用其他组件所引入的 Netty / gRPC / Arrow 版本；如果业务还使用 WebFlux 或其他 gRPC 组件，仍需验证整个业务应用的依赖共存。

业务选择 IoTDB SDK 时，在自身 dependencyManagement 中直接指定 org.apache.iotdb:iotdb-session，见升级指南。仅在应用设置 tsgate.iotdb.version 属性不会重写已导入的 BOM。所选官方 SDK 的 POM 会带入配套 RPC / TSFile / Thrift，须检查冲突，不要把 SDK 版本号套到所有制品上。

不要把 TsGate 根构建 POM 当作消费者 BOM，它还管理构建和测试依赖。运行时 BOM 不设置 Java 启动参数。规则依据见 Maven 依赖管理。

可选的本地源码安装

本地开发或验证源码修改时，可安装版本统一为 2.1.0 的模块与 BOM。本地安装不代表 Central 已发布；不要以 2.0.0 坐标构建迁包后的源码，也不要替换已发布的 Central 制品。

本地开发或测试源码修改时，可在 TsGate 源码仓库根目录执行以下命令，将模块安装到本地 Maven 仓库：

mvn clean install -DskipTests

Windows PowerShell：

mvn clean install "-DskipTests"

运行要求

InfluxDB 3 官方客户端使用 Apache Arrow，运行应用时需要 JVM 参数：

--add-opens=java.base/java.nio=ALL-UNNAMED

仅使用 IoTDB、InfluxDB 1.x 或 openGemini 兼容适配器不需要此 Arrow 参数。Java 25 使用官方 Arrow 客户端时，可按上游说明额外设置 --sun-misc-unsafe-memory-access=allow。JVM 参数应传给实际运行业务应用的 Java 进程。

配置 Arrow JVM 参数

这是 JVM 模块访问选项，不是 YAML 配置，也不能由普通依赖库在 JVM 启动后通过设置系统属性补上。TsGate 不采用自挂载 agent 或反射强开模块的办法。对于已验证的 classpath / Spring Boot 可执行 JAR 方式：

java --add-opens=java.base/java.nio=ALL-UNNAMED -jar application.jar

IDE 中填入 VM options，不是程序参数。容器中将参数追加到业务 Java 启动命令或现有 JDK_JAVA_OPTIONS，保留其他已有选项。Maven 运行消费者测试时，配置该业务项目 Surefire/Failsafe 的 argLine；TsGate 自身的测试参数不会通过 starter 传递给业务。

这不代表已认证 JPMS/module-path 方式；命名模块可能还需额外 opens/reads，见 Arrow 安装指南。替换原生 Arrow 客户端或将其改为可选功能属于单独的 API/设计变更，不在 BOM 收敛中自动实施。

---

← 项目概览 · 配置与数据库选择 →

2.1.0 中的 OpenGemini

TsGate 2.1.0 包含独立的 OpenGemini adapter 与 starter。配置、默认引擎边界及准确版本测试见 OpenGemini 接入指南，迁移要求见 2.1.0 发布说明。