Apache IoTDB C# 客户端双版本发布：V1.3.7 与 V2.0.8 解析及版本选择指南
写在前面
2026 年 4 月 15 日，Apache IoTDB C# 客户端（iotdb-client-csharp）同时发布了两个版本：
⚠️ 重要兼容性提示
两个版本的兼容方向是不对称的：
- v2.0.8 无法连接 1.x 数据库。如果服务端仍在 IoTDB 1.x（例如 V1.3.6 / V1.3.7），必须使用 v1.3.7 客户端。
- v1.3.7 可以连接 2.x 数据库，但只能使用 Tree Model，无法使用 2.x 新增的 Table Model。需要 Table Model 时才升级到 v2.0.8。
换句话说：v1.3.7 是兼容范围更广的”保守选择”，v2.0.8 是面向 2.x 新特性的”激进选择”。
本文梳理以下内容：
- V1.3.7 的核心修复
- V2.0.8 的新特性与改进
- 1.x ↔ 2.x 兼容性边界
- 选型与升级建议
V1.3.7：稳定性修复，兼顾 1.x 与 2.x（Tree Model）
V1.3.7 是 1.x 分支的一次”小步快跑”维护版本，主要聚焦于会话管理和数据读取链路上的若干历史缺陷。
它的连接范围其实是两个大版本：
- 对 IoTDB 1.x 服务端 — 原生支持，推荐升级
- 对 IoTDB 2.x 服务端 — 可用，但只能访问 Tree Model，无法使用 2.x 新增的 Table Model
对于生产环境中仍在使用 1.3.x 服务端、或者已升级到 2.x 但只需要 Tree Model 的用户，这是一次推荐升级。
核心变更
| 变更项 | 说明 | 影响 |
|---|---|---|
| SessionPool 客户端泄漏修复 | 修复重连失败、查询失败时连接未正确归还的资源泄漏 | 长时间运行的服务不再出现句柄/连接耗尽 |
| 服务端错误信息保留 | 将服务端返回的错误消息原样透传给调用方 | 调试更直接，不再被包装层吞掉 |
| SessionDataSet 死锁修复 | 修复数据集操作中的同步死锁 | 高并发查询场景稳定性提升 |
| RowRecord 构造函数升级 | 迁移到 4 参数 RowRecord 构造函数 | 更完整的数据结构表达 |
适用场景
- 服务端是 IoTDB 1.3.x（含 1.3.6 / 1.3.7）
- 服务端已是 2.x，但业务只使用 Tree Model、不需要 Table Model
- 使用 SessionPool 且长时间运行
- 需要在业务侧捕获服务端原始错误信息
- 对数据读取链路的死锁问题敏感
完整 Changelog：v1.3.4…v1.3.7
V2.0.8：面向 2.x 的新特性与协议适配
V2.0.8 是 2.x 分支的一次较大更新，既包含 V1.3.7 的全部稳定性修复，又引入了针对 IoTDB 2.x 服务端的新协议支持和安全能力。
新特性（New Features）
1. 支持 V2 读接口（C# Client support V2 read interface）
这是 V2.0.8 最关键的变更。IoTDB 2.x 服务端在读取路径上引入了 V2 接口（更高效的数据编码、改进的列式传输），V2.0.8 客户端原生支持该接口。
这也是为什么 V2.0.8 无法连接 1.x 服务端 — 1.x 服务端不存在 V2 读接口的实现，协议握手阶段就会失败。
2. 支持 Client TLS
新增客户端侧 TLS 加密能力：
- 面向跨网络/跨云边界的部署场景
- 配合服务端 2.x 的 TLS 配置，可实现端到端的传输加密
- 对金融、能源、政企等合规要求高的行业尤为重要
改进（Improvements）
| 改进项 | 说明 |
|---|---|
| NuGet 包元数据增强 | 改进在 NuGet 上的可发现性与描述信息 |
Array.Reverse 替换 LINQ 反转 | 跨 .NET 运行时（.NET Framework / .NET 6+ / .NET 8+）兼容性更好，性能略优 |
Bug 修复（继承自 V1.3.7 并新增）
- SessionPool 客户端资源泄漏修复
- 服务端错误信息保留
RpcDataSet死锁条件修复- 时区兼容性问题修复（2.x 独有）
- 列索引问题修复（2.x 独有）
- 移除废弃代码
贡献者
本次 V2.0.8 由 4 位开发者贡献，包括首次参与的 thompson-tomo。从 v2.0.2 到 v2.0.8，共合并了 6 个主要 PR。
完整 Changelog：v2.0.2…v2.0.8
1.x 与 2.x 的兼容性边界
这是本次发布中最容易踩坑的一点，单独拎出来讲清楚。兼容方向并不对称。
兼容性矩阵
| 客户端版本 | 服务端 1.x (1.3.x) | 服务端 2.x (Tree Model) | 服务端 2.x (Table Model) |
|---|---|---|---|
| C# Client v1.3.7 | ✅ 支持 | ✅ 支持 | ❌ 不支持 |
| C# Client v2.0.8 | ❌ 不支持 | ✅ 支持 | ✅ 支持 |
一句话概括：
- v1.3.7 是”向上兼容”的：能连 1.x，也能连 2.x（只是用不了 Table Model）
- v2.0.8 是”只向前不向后”的：只能连 2.x，但能用 Table Model
为什么 v2.0.8 连不上 1.x？
IoTDB 从 1.x 到 2.x 的演进不仅是版本号的递进，还带来了：
- RPC 协议层的重构 — 2.x 引入了 V2 读接口，是一套新的 Thrift 定义
- 数据模型的扩展 — 2.x 新增 Table Model（表模型），与 Tree Model 并存
- 会话与元数据交互路径变化 — 例如 Database 概念替代了 Storage Group
V2.0.8 客户端默认走 V2 读接口和新的会话路径，而 1.x 服务端不存在这些实现，握手阶段就会失败：
连接阶段：握手报错 / 协议版本不匹配
查询阶段：响应解析异常 / 字段错位
写入阶段：schema 校验失败为什么 v1.3.7 还能连 2.x？
2.x 服务端保留了对旧版 RPC 接口和 Tree Model 的向后兼容，因此 v1.3.7 客户端发出的 1.x 风格请求仍能被正确处理。代价是：
- Table Model 相关的 API、DDL、查询在 v1.3.7 里不存在 — 客户端根本不会调用这些接口
- 无法享受 V2 读接口带来的性能优化
- 缺少 v2.0.8 独有的 Client TLS 能力
如何确认服务端版本
在 CLI 或通过 SQL 查询：
SHOW VERSION;根据返回结果选择对应的 C# 客户端版本。
选型与升级建议
场景一：服务端在 1.3.x，短期不升级
建议：使用 Apache.IoTDB 的 v1.3.7。
<!-- csproj -->
<PackageReference Include="Apache.IoTDB" Version="1.3.7" />收益：修复了 SessionPool 泄漏与 SessionDataSet 死锁，长时间运行的 .NET 服务会更稳定。
场景二：服务端已升级到 2.x，但业务只用 Tree Model
建议：依然用 v1.3.7 即可，不必强行切到 v2.0.8。
<PackageReference Include="Apache.IoTDB" Version="1.3.7" />理由：
- v1.3.7 能正常连接 2.x 服务端并读写 Tree Model 数据
- 无需为”升级客户端”付出回归测试成本
- 只有以下情况才需要升到 v2.0.8：
- 需要使用 Table Model
- 需要 Client TLS 加密
- 想要 V2 读接口的性能提升
场景三：服务端是 2.x，且需要 Table Model / TLS / V2 读接口
建议：升级到 v2.0.8。
<PackageReference Include="Apache.IoTDB" Version="2.0.8" />切换时关注：TLS 配置、时区设置、V2 读接口带来的性能与行为变化。参考服务端版本解析：IoTDB V2.0.7 与 V1.3.7 解析、V2.0.8 版本解析。
场景四：混合集群（部分 1.x、部分 2.x）
建议：统一使用 v1.3.7 是最简单的做法——一套客户端即可覆盖两种服务端（Tree Model 范围内）。
如果 2.x 集群上必须使用 Table Model，则需按目标集群做隔离：
- 在 DI 容器中按配置切换
ISessionPool的实现版本 - 或以微服务方式将 1.x 与 2.x 的访问拆到不同服务中
更省事的替代方案：如果你的 2.x 集群暂时还不用 Table Model，直接全量使用 v1.3.7 就能同时覆盖 1.x 和 2.x 服务端，省去上述的拆分工作。等到真的需要 Table Model 时再考虑迁移到 v2.0.8。
通用注意事项
- TLS：v2.0.8 引入 Client TLS，服务端也需启用相应证书，否则握手失败。
- 时区：v2.0.8 修复了时区兼容性问题，升级后原本靠客户端”歪打正着”跑通的时区逻辑需要重新核对。
- 列索引：如果此前的业务代码依赖特定列索引顺序，v2.0.8 升级后请用单元测试回归一遍。
- SessionPool：两个版本都修复了资源泄漏，但升级后也要检查业务侧是否有未
Dispose的路径，修复只是让正确用法变得更稳健，并不能掩盖错误用法。
小结
| 维度 | V1.3.7 | V2.0.8 |
|---|---|---|
| 目标服务端 | IoTDB 1.x 和 2.x（Tree Model） | IoTDB 2.x（含 Table Model） |
| 能否连接 1.x 服务端 | ✅ | ❌ |
| 能否连接 2.x 服务端 | ✅（仅 Tree Model） | ✅（Tree + Table Model） |
| 新特性 | 无 | V2 读接口、Client TLS |
| 稳定性修复 | SessionPool / SessionDataSet / 错误透传 | 同 V1.3.7 + 时区 + 列索引 |
| 推荐升级策略 | 适用大多数场景的保守选择 | 需要 Table Model / TLS 时升级 |
一句话总结：v1.3.7 是兼容性最广的选择，能同时覆盖 1.x 和 2.x 服务端（Tree Model）；v2.0.8 是面向 2.x 新特性的选择，需要 Table Model 或 Client TLS 时才升级，但注意它无法连接 1.x 数据库。