ZH Release Notes 2.1.2

Home · GitHub

English | 简体中文

TsGate 2.1.2

状态：最终源码本地及 main／tag GitHub CI 完整验证通过，仅通过 GitHub 分发；Maven Central 仍为 2.1.0。 GitHub 发行包与报告。2.1.0 与 2.1.1 发布说明页保持原样，作为历史记录。

修改内容

1. HTTP 重定向： 统一 HTTP 适配器请求不再自动跟随 3xx，同源重定向也不例外。应配置最终入口；保留后端既有错误／提交分类，不向重定向目标重放提交不明的写入。
2. InfluxDB 3 响应完整性： 缺失、空或仅含空白的 JSON 响应产生 QUERY_ERROR。真实 JSON [] 仍表示空成功，非法／超限响应保留已有校验。
3. 聚合输出名： 分组 tag、聚合 alias 与实际生成的 window_start 共享预检命名空间。在直接 query/count 及模板 list/offset 总数路径中，冲突均在 I/O 前返回 ARGUMENT_ERROR。Influx 保留大小写，IoTDB 使用小写身份；没有生成窗口时 window_start 可以作 alias。InfluxDB 1.x／OpenGemini 还保留聚合响应的隐式 time，大小写不同的 Time 仍可使用，两个 SQL 适配器不继承此保留名。已有不支持能力的错误优先级及原生 SQL 保持。
4. HTTP 批次合计字节预算： tsdb.influxdb.max-batch-bytes、tsdb.influxdb1.max-batch-bytes、tsdb.opengemini.max-batch-bytes 默认 67108864 字节（64 MiB）。正数限制进入构造快照，约束整个应用批次预生成 UTF-8 payload 的合计字节，包含 payload 分隔符。超预算写入在请求前返回 ARGUMENT_ERROR、NOT_COMMITTED 及零确认提交；物理请求／记录数限制分别保持，IoTDB 无新增此属性。
5. POJO 读计划： 默认读取按类生命周期复用构造器／字段／类型／候选名元数据，与写注解分离。查找优先级、继承字段、显式 null、数值／时间转换、普通 DTO 与缺失列语义保持。不缓存结果行或业务实例，实测性能范围及限制见下方。

升级与分发

已验证源码及带注解的 v2.1.2 标签已推送 GitHub，两组完整 CI 均已验证通过，发行包与报告见 GitHub 入口。

公开 API、Java 17 基线、既有 SDK、支持的引擎范围及 TGTemplate → TSDBAdapter → 后端架构保持。使用最终 HTTP URL、唯一聚合输出名，并使应用批次处于配置的字节预算内。详见配置、查询及映射。

先从 v2.1.2 源码构建安装到本地，再声明统一为 2.1.2 的 io.github.alandevise 模块／BOM。本次不签名、不上传或发布 Central 制品，已发布 Central 2.1.0 保持。见本地安装。

结果映射微基准

全新基准在 Java 17.0.14／aarch64 上，以同一份未修改 harness 比较准确的已发布 2.1.1 baseline core JAR 与当前 2.1.2 JAR，交替执行每种实现三个全新 JVM fork。每个 fork 预热四轮、测量七轮、两次 pass，完整覆盖 1,000／10,000 行和单／四线程八个场景，每个场景六个 fork 的新旧 checksum 均一致。

整个当前测量 JAR 与暂存的正式审计 core JAR 一致，SHA-256 为 b81f1f045ebed6cf5d35dfe9bf6473a121d325a093566dc4aed5cb6cfa27c6c2，最终 benchmark/summary.json 已核对身份。下表为三个 fork 中位数的中位数，B→C 表示 baseline 2.1.1 → 当前 2.1.2。

DTO 场景	行/线程	线程数	ns/row B→C	分配 bytes/row B→C
少字段，无注解继承 DTO	1,000	1	3928.959 → 4110.209	3432.032 → 1936.032
少字段，无注解继承 DTO	1,000	4	235.734 → 161.094	3208.032 → 1520.032
少字段，无注解继承 DTO	10,000	1	749.252 → 417.742	3208.000 → 1520.000
少字段，无注解继承 DTO	10,000	4	203.924 → 118.673	3208.000 → 1520.000
多字段，带注解继承 DTO	1,000	1	3205.458 → 2518.729	10942.872 → 6771.984
多字段，带注解继承 DTO	1,000	4	906.245 → 503.427	10931.952 → 6771.952
多字段，带注解继承 DTO	10,000	1	2947.825 → 2011.006	10942.803 → 6782.803
多字段，带注解继承 DTO	10,000	4	900.102 → 527.461	10942.803 → 6782.803

首个 1,000 行／单线程普通 DTO 场景耗时约增加 4.6%，但分配量下降；该表不能支持所有工作负载均变快的结论。较早测量保留于 history/pre-readiness/benchmark/ 和 history/readiness-v1/benchmark/，不混入这些最终 JAR 数据。

这是本地非 JMH、热缓存 DTO 映射微基准，不含数据库／网络、SQL、结果解析、写映射或端到端吞吐，也不测首次计划构建、常驻／峰值内存。分配量来自可用工作线程计数，多线程 ns/row 为墙钟时间除以合计行数；较短预热和固定场景顺序仍受 JIT／GC／调度影响。选定字段 checksum 一致属于负载合理性检查，功能语义另由回归验证。

使用已提交的 ResultMappingBenchmark 源码及分别准备的 baseline／current core JAR 复现：

javac --release 17 -cp /path/to/baseline-core.jar -d /tmp/tsgate-benchmark-classes \
  tsgate-core/src/test/java/com/alandevise/tsgate/benchmark/ResultMappingBenchmark.java
java -Xms256m -Xmx512m -cp /tmp/tsgate-benchmark-classes:/path/to/baseline-core.jar \
  com.alandevise.tsgate.benchmark.ResultMappingBenchmark --label baseline \
  --warmup 4 --iterations 7 --passes 2 --rows 1000,10000 --threads 1,4
java -Xms256m -Xmx512m -cp /tmp/tsgate-benchmark-classes:/path/to/current-core.jar \
  com.alandevise.tsgate.benchmark.ResultMappingBenchmark --label current \
  --warmup 4 --iterations 7 --passes 2 --rows 1000,10000 --threads 1,4

保持已编译 harness 不变，两条 Java 命令交替执行，每种实现各运行三个全新 fork。非 Unix 平台使用该平台的 classpath 分隔符。

验证证据

最终验证源码为 2ba077ac0f960555ccb00eee33373b7cd3ace324。此提交已重新在列明的 Temurin／Spring Boot 组合（17.0.14／2.7.18、21.0.11／3.5.14、25.0.2／4.1.0）下各通过 1,233 项单测，失败／错误／跳过均为零，源码／Git 身份均保持一致。27 JAR／11 POM 无签名发行审计、71 项 Python 运行器／夹具回归（34 + 37）及 actionlint 均通过；全新代表性 Docker 也通过 120 项集成测试，失败／错误／跳过均为零，三个自有容器全部移除；最终 JAR 八场景微基准完成，checksum 一致、完整 JAR 身份已核对。OpenGemini 完整矩阵四种部署各通过 46 项、共 184 项，失败／错误／跳过均为零，自有容器和网络全部清理；加上代表性后端，本轮最终源码 Docker 合计 304 次测试执行。main／tag 两组 GitHub CI 也已完整通过，下载的原始报告已核对相同源码和资源清理证据；不计入已替代构建的结果。

验证范围	最终源码本地结果
Java 17／Spring Boot 2.7.18 单测	1,233 通过，失败／错误／跳过均为零
Java 21／Spring Boot 3.5.14 单测	1,233 通过，失败／错误／跳过均为零
Java 25／Spring Boot 4.1.0 单测	1,233 通过，失败／错误／跳过均为零
代表性 IoTDB／InfluxDB 1.x／InfluxDB 3 Docker	120 通过，失败／错误／跳过均为零，三个自有容器全部移除
OpenGemini 1.4.1 单节点	46 通过，失败／错误／跳过均为零，自有资源已清理
OpenGemini 1.4.1 三节点／三副本	46 通过，失败／错误／跳过均为零，自有资源已清理
OpenGemini 1.5.2 单节点	46 通过，失败／错误／跳过均为零，自有资源已清理
OpenGemini 1.5.2 三节点／三副本	46 通过，失败／错误／跳过均为零，自有资源已清理
无签名制品审计	27 JAR、11 POM 通过
Python 运行器／夹具回归及 actionlint	71 项 Python 通过，工作流 lint 通过
正式审计 JAR 的映射微基准	八场景完成，checksum 全部一致，完整发行 JAR 身份已核对
GitHub CI	main 运行及 v2.1.2 标签运行各 9/9 作业通过，原始报告及清理已核对
GitHub 分发	v2.1.2 发行包与报告；Maven Central 仍为 2.1.0

两组 CI 的源码均为 2ba077ac0f960555ccb00eee33373b7cd3ace324。每组均通过三个 JDK 各 1,233 项单测及 120 项代表性 Docker（后端三组为 43／52／25）；main CI 另通过 OpenGemini 两个单节点共 92 项，tag CI 通过完整四部署共 184 项。下载的全部原始报告均零失败／错误／跳过，自有资源清理已核对；下载制品验证清单 SHA-256 为 ba2ed138cd8020466933075906d940211f08c196a442fe9f5ad7b73e530d8ef0。上方本地 304 次 Docker 执行与这些远程范围分别记录。

全新代表性 Docker 使用 IoTDB 2.0.10（RPC 压缩启用）、InfluxDB OSS 1.13.1、InfluxDB 3 Core 3.11.5（默认 OR 策略），三个后端状态均通过。已完成的运行时、代表性 Docker 及 OpenGemini 完整矩阵均保留一致的源码／Git 身份和自有资源清理通过证据；OpenGemini 父级 opengemini-matrix/summary.json 已确认最终源码的四种选定环境共 184 项通过。全新报告写入 .local-test/release-2.1.2-20261007/，已替代运行保留于下方历史目录。本次不执行 Central 发布，Maven Central 仍为 2.1.0。

首次集群故障与测试就绪修正

首次源码构建的两个集群部署共出现 3 项错误：OpenGemini 1.4.1 执行 44 项 adapter 测试、1 项错误；1.5.2 执行 44 项 adapter 测试、2 项错误。两个失败部署均未执行到 starter 测试；运行器正确排除了旧 starter XML。1.4.1 聚合用例的 seed 写入返回 HTTP 500（select timeout in 10s seconds），1.5.2 还记录了提交不明的写入 I/O 故障。适配层保持 UNKNOWN 提交契约，没有重放这些写入。

服务端日志及默认配置下 direct HTTP、已发布 2.1.1、当前 2.1.2 的独立对照指向：CREATE DATABASE 后每数据库的数据 Raft 尚未就绪，即使全局元数据和成员状态已正常。仅测试侧在每次首次写入前，只读等待初始数据 Raft 生命周期证据，最多 45 秒。1.5.2 保留精确 database／partition 完成记录；1.4.1 官方二进制的完成日志缺少这两个字段，因此使用版本绑定的完整日志 transfer 账本及稳定观察。这只是受控串行夹具的初始就绪观察，不能理解为原子或持续健康保证。详见就绪机制及限制。

首次源码的全部报告和制品逐字保留在 history/pre-readiness/，其中包含 opengemini-matrix/1.4.1-cluster/ 和 opengemini-matrix/1.5.2-cluster/ 两个失败目录；诊断对照保留在 cluster-control/results*.json。此前单节点通过不计为最终源码证据，最终零错误总数仅指最终源码运行，首次故障始终保留在发行记录中。

独立的 1.4.1 三节点诊断在三个串行新建数据库中验证了修正门禁：6 次业务写入均只尝试一次、全部返回 HTTP 204，三个 SQL 入口均读回全部预期点，自有资源清理完成；门禁观察约需 6–7 秒。结果及历史日志解析校验保留在 cluster-readiness-v2-control/results.json、history-validation.json。这些对照只验证受控设置中的夹具观察，不能代替独立记录的正式四部署集成结果，也不保证集群持续健康。

首版就绪门禁缺陷与中断

首版门禁（b9ab030）错误假设 1.4.1 二进制的 transfer 完成记录含 database、partition，导致只读门禁达到 45 秒期限。该集群运行被主动中断，finally 资源清理通过；完整汇总／日志和该版本其他报告／制品均保留在 history/readiness-v1/。最终源码修正这一版本专用测试假设，不改变生产适配器／POM 行为；完整验证及发行 JAR 基准均已重跑，没有沿用上一版本通过数。这项测试门禁缺陷与首次服务端就绪故障分别记录，提交不明写入始终不自动重放。