TDengine 3.4.1.13 版本解析：Adapter 高可用、状态窗口增强与 WAL 自愈能力详解

TDengine 3.4.1.13 版本解析Adapter 高可用、状态窗口增强与 WAL 自愈能力详解【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本篇文章以 TDengine 3.4.1.13 的官方 Release Notesdocs/en/17-release-history/03-notes/3.4.1.13.md为骨架结合当前仓库源码逐条展开该版本新增的 6 项特性、22 项增强与 35 项修复重点剖析 Adapter 高可用、状态窗口表达式增强、TSDB CLI 订阅、License Server 授权、WAL 损坏自动清理、强制终止 compact 任务等能力的实现原理与使用方式。读完本文你将掌握该版本的关键新功能、核心配置参数及其底层机制并能据此规划升级与运维策略。版本总览TDengine 3.4.1.13 发布于2026-07-02是该 3.4.1.x 维护序列中的一次功能性版本更新。从 Release Notes 的条目分布来看本次更新呈现三个鲜明特征连接器与生态集成集中发力C#、JDBC、Rust 三类主流连接器同步支持 Adapter 高可用taosX 相关的修复多达十余项窗口计算与流式计算持续增强状态窗口表达式、流式计算 JOIN 效率、事件窗口父子事件关联均有改进稳定性与可运维性并重新增 WAL 损坏自动修复、强制终止 compact、License Server 授权等运维向能力同时修复了 35 个问题。下文按 Features、Enhancements、Fixes 三个板块逐一展开并在每个板块中对重点条目给出源码级佐证。Features六项新能力1. C# / JDBC / Rust 连接器支持 Adapter 高可用三个连接器C#、JDBC、Rust在 3.4.1.13 中统一新增了对taosAdapter 高可用的支持。taosAdapter 是 TDengine 面向 RESTful、WebSocket、MQTT 等协议接入的适配层组件其高可用意味着连接器在配置多个 Adapter 地址后可以在某个 Adapter 实例不可用时自动切换到可用实例从而消除单点故障。该能力对多实例部署、负载均衡的规模化生产环境尤其重要——连接器层面无需依赖外部负载均衡器即可实现 Adapter 层的故障转移。具体配置方式与各连接器的高可用参数说明可参考 docs/en/10-developer-guide/01-connect-to-tdengine/ 下对应连接器章节。2. 状态窗口表达式支持常量、标签列与逻辑运算符状态窗口STATE_WINDOW是 TDengine 流式计算与查询中用于按状态变化切分窗口的窗口类型。3.4.1.13 之前状态窗口的起始/结束条件表达式能力有限本版本起状态窗口表达式支持常量可以在窗口条件中直接使用固定数值标签列可以将标签列作为状态切换的判断依据逻辑运算符支持 AND、OR 等逻辑组合表达更复杂的窗口边界条件。从仓库源码看状态窗口在 source/libs/executor/src/timewindowoperator.c 与 source/libs/planner/src/planPhysiCreater.c 中均有实现本版本的改动扩展了窗口状态表达式的解析与求值能力使得如“当温度大于 100 且湿度小于 30 时开启窗口”这类组合条件成为可能。相关的状态窗口逻辑在 source/libs/executor/test/queryPlanTests.cpp 等测试中持续被覆盖验证。3. TSDB CLI 交互模式支持 subscribe 命令订阅 Topic 数据TSDB 命令行工具taos CLI在交互式模式下新增subscribe命令可直接订阅 Topic 数据并在终端查看。此前订阅数据通常需要编写 TMQ 消费程序或使用专用工具现在运维人员可以直接在 CLI 中快速验证 Topic 内容与订阅链路。4. TSDB 支持通过 License Server 授权本版本为 TSDB 引入了License Server 授权机制使企业版授权可以通过集中式 License Server 发放与校验便于大规模集群的统一授权管理。Enhancements二十二项增强1. 新增 walDeleteOnCorruption 配置WAL 损坏自动修复这是本版本最值得关注的运维能力之一。新增配置参数walDeleteOnCorruption默认开启节点启动时若检测到 WALWrite-Ahead Log目录损坏会自动执行备份并删除损坏的 WAL 目录从而使节点能够正常启动取值 0-11默认表示备份并删除损坏目录0表示不删除节点将因 WAL 损坏而无法正常启动生效方式重启后生效。在源码层面该参数在 source/common/src/tglobal.c 中定义为全局配置项bool tsWalDeleteOnCorruption true; // 默认开启并注册为CFG_SCOPE_SERVER、CFG_DYN_SERVER的布尔类型配置source/common/src/tglobal.c#L475、source/common/src/tglobal.c#L1124。官方配置文档 docs/en/12-operations-and-tooling/03-components/01-taosd.md 中同时给出了数据安全提示单副本场景下启用该参数可能导致部分数据丢失三副本场景下通常不会丢数据因为节点可以从对端副本追赶补齐数据。也就是说该参数利用多副本机制化解了“WAL 损坏导致节点无法启动”的僵局——单副本牺牲少量数据换取可用性多副本则几乎无损。仓库测试用例 test/cases/70-Cluster/test_wal_corruption_single_replica.py 与 test/cases/70-Cluster/test_wal_corruption_three_replica.py 分别覆盖了单副本与三副本场景下的 WAL 损坏恢复验证。2. 新增 kill compact compact_id force 命令新增kill compact compact_id force命令用于强制删除正在运行的 compact数据文件合并任务。当某次 compact 任务卡死、占用资源或引发异常时运维人员可以通过该命令强制终止。在 source/dnode/mnode/impl/src/mndCompact.c 中可以看到完整的实现链路强制终止会创建一个kill-compact-force事务TRN_POLICY_ROLLBACK回滚策略对 compact 涉及的各个 vgroup 下发TDMT_VND_KILL_COMPACT消息mndCompact.c#L524-L531若目标 dnode 离线或 vgroup 不存在会记录告警并跳过重做动作保证事务的幂等性mndCompact.c#L544-L574执行过程会写入审计日志mndCompact.c#L672-L690便于追溯操作记录。测试用例 test/cases/70-Cluster/test_kill_compact_force.py 与 test/cases/02-Databases/01-Create/test_db_compact.py 覆盖了该命令的正常与异常路径。3. 事件窗口子事件通知增加父事件 ID 字段流式计算的事件窗口EVENT_WINDOW在子事件触发通知时新增了父事件 ID字段便于在复杂的嵌套事件流中建立父子事件关联定位事件归属。4. Windows 平台新增共享存储支持共享存储shared storage此前主要在 Linux 平台使用本版本将该能力扩展至 Windows 平台使 Windows 部署同样可以基于共享存储构建多节点集群。5. taosX-agent OPC UA 接入支持存储转发taosX-agent 在 OPC UA 数据采集场景下新增store-and-forward存储转发能力当上游 OPC UA 服务器短暂不可达或网络中断时采集数据先落盘缓存恢复后再转发至目标避免采集窗口内的数据丢失。6. Windows 平台支持 UDF 功能Windows 平台新增对 UDF用户自定义函数的支持此前仅限 Linux 平台同时配套的 Python UDF 运行库 taospyudf 也已随安装包内置见增强 21。7. taosX OPC UA 集成整批失败时的重试与超级表创建策略调整当 taosX 的 OPC UA 批量写入整批失败时本版本调整了重试策略与超级表创建策略避免因批量失败导致的数据丢失。8. Base64 函数支持非字符串类型base64内置函数此前仅接受字符串类型输入本版本起支持数值、时间等非字符串类型使用前会先完成隐式类型转换扩展了编解码函数的适用范围。9. C WebSocket 连接器支持 decimal 数据类型C WebSocket 连接器新增对decimal 精确小数类型的支持补齐了该连接器与原生连接器在数据类型覆盖度上的差距可参见 docs/en/05-tdengine-sql/ 中关于 decimal 类型的说明。10. 提升 ASOF JOIN 查询性能ASOF JOIN非等值时序关联查询的查询性能在本版本得到优化。ASOF JOIN 是时序数据库处理“两张时间错位表按时间就近匹配”场景的核心算子其性能直接影响点查与关联分析场景的体验。11. 流式计算 JOIN 查询效率优化流式计算中 JOIN 查询语句的执行效率得到提升降低多流关联场景下的计算开销相关流式 JOIN 的解析与算子实现在 source/libs/new-stream/ 目录中持续演进。12. ODBC WS 连接器支持传输压缩ODBC WebSocket 连接器新增传输压缩支持降低网络传输数据量对跨公网或低带宽链路下的数据同步有明显收益。13. Windows 平台新建数据库 WAL_LEVEL 默认值为 2Windows 平台上新建数据库的WAL_LEVEL默认值调整为2强制 fsync。这意味着 Windows 默认启用同步落盘策略牺牲部分写入性能换取更强的数据持久性保障与 Windows 文件系统行为特性相匹配。14–15. taos-explorer 错误信息优化taos-explorerWeb 图形化管理界面针对登录失败与连通性检查两类场景优化了错误提示文案使问题定位更直观。16. 列查询结果支持脱敏显示新增敏感数据脱敏显示能力对列查询结果中的敏感字段如账号、手机号等可按规则脱敏输出满足数据安全与合规展示需求。17. 支持动态修改 tmqMaxTopicNum 与 mqRebalanceInterval本版本将两个消息队列相关参数升级为动态可调无需重启即可生效参数默认值取值范围类别说明tmqMaxTopicNum201 - 10000全局CFG_CATEGORY_GLOBAL单客户端可订阅的最大 Topic 数量mqRebalanceInterval21 - 10000全局CFG_CATEGORY_GLOBAL消费组重平衡检测间隔源码中两者的注册位置为 source/common/src/tglobal.c#L1177 与 source/common/src/tglobal.c#L1184均为CFG_DYN_SERVER动态配置项对应运行时变量定义在 source/common/src/tglobal.c#L337tmqMaxTopicNum与 source/common/src/tglobal.c#L493tsMqRebalanceInterval 2。运维人员可通过ALTER DNODE ...或配置文件动态调整适用于消费组规模频繁变化的场景。18. 微秒精度数据库支持 stmt2 查询stmt2二进制协议预编译语句查询在微秒us精度数据库中不再报错补齐了 stmt2 在亚毫秒精度场景下的能力。19. 支持 show create stream 查看流创建语句新增SHOW CREATE STREAM stream_name命令可查看已有流stream的原始创建语句极大方便了流计算任务的运维、审计与迁移复制。从语法层看解析器在 source/libs/parser/inc/sql.y 中新增了该语法规则cmd :: SHOW CREATE STREAM full_stream_name(A). { pCxt-pRootNode createShowCreateStreamStmt(pCxt, A); }同时SHOW CREATE STREAM被映射为PRIV_CM_SHOW_CREATE权限类别sql.y#L584即该命令受show create类权限管控AST 节点在 source/libs/nodes/src/nodesCodeFuncs.c 中完成序列化权限校验逻辑位于 source/common/src/tpriv.c。20. TaosX 新增 backup.auto_create_dir 配置TaosX 新增配置项backup.auto_create_dir在备份任务运行时自动创建目标备份目录省去人工预建目录的步骤降低备份任务配置出错概率。21. Python UDF 运行库 taospyudf 随安装包内置此前使用 Python UDF 需要手动执行pip3 install taospyudf并配置ldconfig本版本起taospyudf 库已随安装包内置开箱即用简化了 Python UDF 的部署流程。结合增强 6Windows 支持 UDFPython UDF 在跨平台场景下的可用性进一步提升。22. Learner 角色 vnode 不再参与选举在 RAFT 分组中learner学习者角色的 vnode 本版本起不再参与 leader 选举。learner 通常用于数据备份、只读同步等场景将其排除在选举之外可避免其对选举结果产生干扰使选举只在具备完整数据同步能力的 follower 之间进行提升集群选举的稳定性与可预期性。Fixes三十五项修复中的重点解读数据一致性与正确性修复F10STMT 高性能插入模式下drop 后重建同名表导致插入错误。修复了预编译插入在表元数据版本变化后未正确重绑定的问题直接影响高频写入链路的正确性。F13查询带 STATE_WINDOW 但无实际聚合函数的虚拟表时报 Invalid Parameter 错误。此前状态窗口必须搭配聚合函数使用本版本修复了仅有窗口无聚合的合法场景误报问题。F25流式计算子查询表达式计算中的值缓存导致查询结果错误。修复了表达式求值阶段缓存值被错误复用导致的脏读问题属于流式计算正确性关键修复。F30超级表标签顺序与自动建表不一致时订阅结果错误。修复了 TMQ 订阅场景下标签顺序错位引发的数据错配问题。F21C WebSocket 连接器 schema-less 写入的微秒精度转换错误。F35Windows 平台 WebSocket 接口时区设置失败F14Windows 平台 Native 库时区格式错误。稳定性与崩溃修复F7流计算中使用 UDF 时函数 ID 越界导致崩溃。F8查询线程内存分配失败时指针过早释放导致崩溃并修复错误路径资源泄漏。F16执行 show users 等操作时频繁修改用户权限导致崩溃。F17STMT2 中使用 concat 函数导致崩溃。F18流计算中使用 %%trows 写入 varchar 数据时崩溃。F24超级表数量庞大时 show stables 卡死。F27taosX 同步 InfluxDB 数据时 measurement 数量过多导致 OOM。F11K8s 部署时无法获取正常容器资源信息。taosX 与生态集成修复taosX 相关修复在本版本中占比最高包括Kafka 规则过滤条件显示异常F1、PI 数据源连接错误F6、UDT 与超级表模板组合时数据采集失败F9、MQTT 数据摄取时过滤条件不生效F12、Kafka 集群异常时的重试机制增强F15、PI Connector 修改超级表名与列名失败F20、PI Vision 使用 CDR 时实时刷新失败F22、同步 InfluxDB 的 OOMF27、MQTT 任务配置 UDT 解析与过滤条件时任务创建失败F32等。升级兼容性与权限修复F28从 3.3 升级到 3.4 后多副本 mnode 场景下部分权限设置失败。F34从 3.3 升级到 3.4 后 ROOT 用户无法创建新用户。两条均为升级路径上的权限兼容问题建议 3.3 → 3.4 升级用户重点关注。F29从 v3.3.8.x 升级到 3.4.1.9 时流状态兼容性问题。F31Windows 平台 taosdlog 日志记录顺序异常。F3balance leader 操作时反引号标识符处理错误F4副本数为 2 时 balance vgroup 出错。F2/F33taosExplorer DataIn 任务同步进度显示异常、datain 任务重命名不生效F23taos-explorer 创建数据摄取任务时保存失败F5英文环境下 Explorer 导出查询结果 CSV 中文乱码。F19多客户端并发 schemaless 写入修改同一超级表时报错。F26LoFLocal Outlier Factor支持多变量异常检测。升级与运维建议综合本版本的 Features、Enhancements 与 Fixes针对不同用户群体给出如下建议连接器使用者C# / JDBC / Rust 连接器升级后可启用 Adapter 高可用配置C WebSocket 连接器用户可解锁 decimal 类型ODBC WS 连接器可开启传输压缩。流式计算用户状态窗口表达式能力大幅增强常量、标签列、逻辑运算符建议评估既有窗口条件是否可用更简洁的表达同时关注 F25子查询值缓存修复对计算结果的影响运维上可使用新增的SHOW CREATE STREAM查看流定义。集群运维人员walDeleteOnCorruption默认开启需知悉其数据安全边界单副本可能丢数据、三副本基本无影响compact 任务异常时可使用kill compact compact_id force强制终止tmqMaxTopicNum与mqRebalanceInterval现已支持动态调整。Windows 用户注意新库WAL_LEVEL默认值为 2强制 fsyncUDF、共享存储等能力已在 Windows 平台就绪。3.3 → 3.4 升级用户重点关注 F28、F34、F29 三项升级兼容修复建议在升级前完成权限与流状态相关验证。更多配置参数细节可查阅 docs/en/12-operations-and-tooling/03-components/01-taosd.md运维命令说明见 docs/en/12-operations-and-tooling/02-operations/04-maintenance.md。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考