企业官网建设流程全解析

TDengine 3.4.0.9 发布说明深度解析：虚拟表备份、订阅令牌、权限修复与 40 项改进全景

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

发布版本：3.4.0.9 ｜ 发布日期：2026-03-02

本文以 TDengine 官方 3.4.0.9 Release Notes（docs/en/17-release-history/03-notes/3.4.0.9.md）为骨架，结合仓库源码逐项展开。3.4.0.9 是 3.4.x 系列的一次重要的稳定性与功能补强版本，共包含 2 项新功能、7 项增强和 40 项修复，覆盖 taosAdapter 订阅令牌、taosdump 虚拟表导入导出、Explorer 大规模 UI 增强、流计算（stream）乱序与触发逻辑、权限（privilege）体系、虚拟表查询性能等核心模块。读完本文，你将能：理解该版本的每一个变更点及其对应的源码依据；掌握虚拟表备份（--content=ext-meta）与 taosAdapter 订阅令牌的配置方式；了解权限、流计算、日志与配置参数等关键修复的底层原理；并据此评估升级路径与回归测试重点。

一、版本概览：一次以“稳定性和正确性”为主的补强

3.4.0.9 发布于 2026-03-02，其变更清单呈现三个明显特征：

• 功能增量克制：仅 2 项新功能（taosAdapter 订阅令牌、taosdump 虚拟表导入导出），聚焦于工具链与接入层，而非核心存储引擎的架构改动，表明该版本定位为 3.4.x 主线的稳定化迭代。
• 增强围绕运维体验：7 项增强中有 5 项（Explorer UI、日志文件数、supportVnodes上限、CREATE XNODE TASK报错信息、表名模板表达式）属于可观测性与易用性范畴。
• 修复覆盖纵深：40 项修复横跨权限体系（4 项）、流计算（4 项）、Explorer/taosX 工具链（10+ 项）、连接协议（native 连接端口占用）、数据类型（decimal stmt 查询崩溃、tinyint(1)/boolean）与安全（fast-xml-parser CVE-2026-25896）等。

对于在生产环境运行 3.4.0.x 的用户，本版本尤其值得关注：权限相关的 4 项修复直接影响安全模型的有效性；流计算的 4 项修复关系到计算结果的正确性与触发及时性；而日志文件数调整、supportVnodes上限调整则影响部署配置的默认行为。

二、新功能详解

2.1 taosAdapter 订阅令牌（Token）支持

Release Notes 原文：feat: taosAdapter add token support for subscription

taosAdapter 是 TDengine 的 RESTful/WebSocket 接入网关。在 3.4.0.9 之前，通过 WebSocket 协议发起数据订阅（tmq）时，taosAdapter 的鉴权走的是传统的用户/密码认证；本次新增对**令牌（token）**的支持，使订阅链路可以像 taosdump 云备份、其他云接入场景一样使用独立令牌完成鉴权，避免在客户端侧暴露明文口令。

从仓库证据看，令牌接入在该版本工具链中是统一的既有机制：例如 taosdump 参数解析 中-X, --dsn=DSN支持https://host?token=<TOKEN>形式，并支持TDENGINE_CLOUD_DSN环境变量。3.4.0.9 将同样的令牌鉴权语义扩展到了 taosAdapter 的订阅场景，使基于 tmq 的订阅消费者可以复用云侧或企业侧的令牌体系。

使用前提与建议：

• 该功能适用于通过 taosAdapter（WebSocket 端口，默认 6041）发起订阅的客户端；
• 令牌的签发与吊销由服务端统一管理，客户端不再直接持有用户名/密码，降低了口令泄露面；
• 升级后建议在测试环境先用一个订阅消费者验证令牌鉴权链路，再切换生产流量。

2.2 taosdump 支持虚拟表导入/导出

Release Notes 原文：feat: taosdump support import/export virtual tables

虚拟表（Virtual Table）是 TDengine 3.4.x 引入的逻辑表能力——它不直接存储数据，而是按定义从一张或多张物理表/既有虚拟表读取列数据、按时间戳对齐后按需生成结果集（详见 虚拟表文档）。在 3.4.0.9 之前，taosdump 只能备份物理表结构与数据，虚拟表这类“扩展元数据（ext-meta）”无法随备份迁移，导致跨集群迁移时虚拟表结构丢失。

本次新增将虚拟表纳入备份/恢复范围。从 taosdump 参数帮助 的源码可以看到内容分层模型的落地：

-M, --content=CONTENT What to backup/restore: basic - super/child/normal tables meta and time-series data(default) ext-meta - streams/virtual tables/topics meta all - basic + ext-meta

对应的类型定义位于 bckTypes.h：BCK_CONTENT_BASIC = 0x1（物理表 + 数据）、BCK_CONTENT_EXTMETA = 0x2（虚拟表 + 流 + 主题）、BCK_CONTENT_ALL = 0x3（两者合并）。备份进度也为此新增了独立的阶段标识PROGRESS_PHASE_EXTMETA = 3（bckProgress.h），说明虚拟表/流/主题的备份发生在物理数据备份之后。

实操要点：

• 备份虚拟表及其依赖结构，使用：taosdump -M all（或-M ext-meta仅导扩展元数据）；
• 恢复时需要注意顺序问题：源码注释明确指出，恢复 ext-meta 时目标数据库必须已存在，因为跨库的流/虚拟表需要在被依赖的库就绪后才能恢复（restoreMeta.h）；
• 虚拟表本身不存数据，因此备份只涉及结构（SHOW CREATE TABLE元数据），backupData.c中也会跳过虚拟超级表的数据备份（skip data backup for virtual STB，backupData.c）；
• 备份/恢复虚拟超级表时，其SHOW CREATE TABLE输出可能内嵌\n换行符，backupMeta.c 已针对该场景做了处理，升级后无需额外转义。

三、增强项详解

3.1 Explorer 大规模 UI 增强

Release Notes 原文：enh: massive ui enhancement for explorer

Explorer 是 TDengine 的图形化管理界面（Web 控制台）。本版本的 UI 增强是“massive（大规模）”级别的，与其配套的修复项（第 20、23、25、28、31、32 项等）共同构成了 Explorer 从交互体验到后端 API 的全面打磨：

• 修复 tmq 连接检查无响应（fix 20）；
• 修复切换 tag 分享主题时的告警语法错误（fix 23）；
• 支持 Grid 自动伸缩（fix 25，Grid auto scalable in Explorer）；
• 修复备份任务创建、批量操作 API、build task 更新 SQL 等一批后端接口问题（fix 28、31、32）。

这些改动整体说明 3.4.0.9 将 Explorer 的稳定性提到了与核心服务同等重要的位置，对于以 Web 控制台为主要运维入口的用户，升级后 UI 操作链路的故障率会有明显下降。

3.2 优化超级表子表订阅场景下的标签修改对写入的影响

Release Notes 原文：enh: optimize the impact of frequent child table tag modifications on data writing when child tables of super table have subscriptions

当超级表（STable）的子表上建有订阅（如基于子表的 tmq 订阅或流计算触发表）时，频繁修改子表标签会与写入路径产生耦合，拖慢写入。本次增强优化了这一交互：从源码结构看，订阅与触发表相关逻辑集中在 source/libs/new-stream 目录（包括streamTriggerMerger.c、streamTriggerTask.c、streamRunner.c等），标签变更触发的元数据广播与数据写入之间不再互相阻塞。对于高频改标签 + 高频写入叠加订阅的 IIoT 场景，此项优化可直接降低写入 P99 延迟。

3.3 表名模板支持表达式

Release Notes 原文：enh: table name template support expression

taosBenchmark（以及部分写入工具）支持通过表名模板批量生成子表。此前模板仅支持固定占位符；3.4.0.9 起模板内可嵌入表达式，使得批量建表时的命名可以携带计算逻辑（例如基于时间、序号或标签值派生的名称），进一步减少手工维护模板的成本。

使用建议：升级后可在 taosBenchmark 的 case JSON 中，将原来的纯占位符模板替换为表达式形式；表达式语法与结果需在测试环境先行验证，确认生成的子表命名符合预期后再用于压测。

3.4 提升含 tbname 列的虚拟表查询性能

Release Notes 原文：enh: improve performance of virtual table queries with the tbname column

虚拟表查询在投影中包含tbname（子表名）列时，此前需要在扫描阶段额外解析元数据，性能存在优化空间。3.4.0.9 优化了该路径。从执行器源码看，虚拟表扫描由virtualtablescanoperator.c负责（source/libs/executor/src/virtualtablescanoperator.c），本次改动直接作用于该算子的列解析与行构造逻辑，减少了tbname投影带来的额外开销。对含大量虚拟子表、且查询经常带tbname分组的聚合场景收益明显。

3.5 日志文件数缩减为 3 个

Release Notes 原文：enh: reduce log files to 3

tdengine 服务端（taosd）的日志滚动机制将保留的日志文件数由原来的多个缩减为 3 个。从 tglobal.c 的日志初始化入口taosCreateLog(const char *logname, int32_t logFileNum, ...)可见，日志文件数是启动时显式传入的参数。缩减后：

• 收益：磁盘占用更可控，日志目录（默认/var/log/taos）不会无限制膨胀；
• 影响：历史日志保留窗口变短，排障时若需要回溯更长时间，应提前将日志接入外部采集（如 syslog、taoskeeper 监控或日志轮转脚本），或自行调大日志文件数配置。

3.6 配置参数 supportVnodes 最大值由 4096 调整为 1024

Release Notes 原文：enh: adjust the maximum value of configuration parameter supportVnodes from 4096 to 1024

supportVnodes用于声明单个 dnode 支持的最大 vnode 数量。3.4.0.9 将其合法取值范围上限从 4096 收敛为 1024。这一改动在源码配置表中已经落地——tglobal.c 中的注册语句为：

TAOS_CHECK_RETURN(cfgAddInt32(pCfg, "supportVnodes", tsNumOfSupportVnodes, 0, 1024, CFG_SCOPE_SERVER, CFG_DYN_ENT_SERVER, CFG_CATEGORY_LOCAL, CFG_PRIV_SYSTEM));

其中0, 1024即最小值 0、最大值 1024，且该参数是服务端（CFG_SCOPE_SERVER）本地配置、支持企业版动态调整（CFG_DYN_ENT_SERVER）。该值在 dnode 上报状态、vgroup 分配（mndDnode.c、mndVgroup.c）中用于容量规划与 vnode 均衡。

升级注意事项：

• 若现有配置文件中supportVnodes的值超过 1024（如 2048、4096），升级后启动校验将失败或回落，必须先将该参数调整为 ≤1024 再升级；
• 对绝大多数物理机/云主机，单节点 1024 个 vnode 已远高于实际承载量，此调整是合理的资源约束收敛，一般无需关注；
• 该参数属服务端本地配置，各节点独立生效，集群内需保持一致以避免容量认知偏差。

3.7 CREATE XNODE TASK 报错信息细化

Release Notes 原文：enh: CREATE XNODE TASK error message refinement

xnode 是 TDengine 分布式任务（如 taosX 数据接入任务）的执行载体。此前CREATE XNODE TASK在权限不足、状态异常或参数错误时给出的错误信息过于笼统，排障成本高。3.4.0.9 对相关报错信息做了分类细化。配套修复项还包括“创建 xnode 时出现意外错误日志”（fix 18）、“xnoded 角色时间检查错误导致异常退出”（fix 34）、“xnode 任务卡在 created 状态”（fix 24），共同提升了 xnode 任务的创建成功率与可诊断性。

四、关键修复项分类详解（40 项）

4.1 权限体系（fix 2、3、4、5、6、9、10、15、16）

本版本对权限体系做了集中修补，直接关系安全模型的有效性，建议优先阅读：

1. GRANT ALL 对指定流不生效（fix 2）：向特定 stream 授予ALL权限后实际不生效。从 mndStream.c 的权限校验逻辑（如PRIV_CM_SHOW、PRIV_CM_STOP、PRIV_CM_START、PRIV_CM_DROP、PRIV_CM_RECALC针对PRIV_OBJ_STREAM的检查）可以推断，此前ALL在对象级权限展开时未覆盖 stream 对象类型的全部操作码，本版本补齐了映射。
2. START/STOP STREAM 授权后不生效（fix 3）：单独授予流的启停权限后，校验路径未正确命中（对应源码中PRIV_CM_START/PRIV_CM_STOP+PRIV_OBJ_STREAM的组合检查），已修复。
3. 有 DROP STREAM 权限却无法删除流（fix 4）：删除操作未正确匹配对象级 DROP 权限（PRIV_CM_DROP+PRIV_OBJ_STREAM），导致权限判定失败，已修复。
4. 无权限查询视图导致 taosd 崩溃（fix 5）：查询无权限的视图时触发空指针/未定义路径，属于安全边界上的健壮性问题，升级后不再崩溃而是返回明确的权限错误。
5. ALTER VIEW 权限授权后不生效（fix 6）：视图的 ALTER 权限校验路径与执行路径不一致，已对齐（源码中视图权限校验见 parAuthenticator.c 的checkViewAuth）。
6. auditor 无法查看完整用户信息（fix 7）：审计角色（auditor）查看用户列表时信息被截断，已修复。
7. DROP ROLE ... IF EXISTS 失败（fix 9）：使用IF EXISTS语法删除不存在的角色时未按语义返回成功，已修复（角色删除权限校验见 parAuthenticator.c）。
8. 权限缺失时报错信息不清晰（fix 10）：统一了缺少权限时的错误提示文案，便于快速定位是"无权限"还是"对象不存在"。
9. 普通用户建普通表后无显式授权缺写权限（fix 15）：普通用户创建普通表后，本应自动获得对该表的写权限，但 3.4.0.9 之前实际校验失败，导致“自己建的表自己不能写”。本次修复了建表后的隐式授权逻辑，属于数据写入链路上的重要正确性修复。
10. 新增加密函数名改关键字后数据写入串内容（fix 16）：新增加密函数被命名为关键字后，写入时关键字被当作实际内容误写库中，已通过调整命名/转义规则解决。

升级建议：若线上存在基于 stream/视图/角色授权或普通用户自助建表的场景，建议升级后编写覆盖"授权→执行→回收"全链路的冒烟用例，重点验证 fix 2/3/4/6/15 对应的操作。

4.2 流计算（fix 8、12、13、35、37、38）

流计算是本版本修复密度最高的模块之一，6 项修复覆盖正确性与触发机制：

1. varchar 复合主键表的流读取崩溃（fix 8）：当触发表/源表使用 varchar 类型的复合主键（如timestamp + varchar组合主键，见 超级表文档 中COMPOSITE KEY语法）时，流读取其时间戳字段触发崩溃，已修复。
2. 流子查询中 JOIN 对时间占位符误报缺主键（fix 12）：流子查询结果第一列为_twstart等时间占位符且包含 JOIN 时，引擎误报“缺少时间戳主键”，已修复。
3. 流子查询含 interval 窗口时结果时间戳错置（fix 13）：interval 开窗后结果集的时间戳列被错误设置，影响窗口聚合结果的时间对齐，已修复。
4. 带主键触发表乱序数据的 merge 逻辑错误（fix 35）：流处理乱序数据时，触发表带主键场景下 merge 逻辑处理错误，可能导致数据错位或丢失，已修复——该逻辑位于 streamTriggerMerger.c。
5. sliding < interval 时扫描间隔误判（fix 37）：滑动触发场景中sliding < interval时扫描间隔判定错误，会导致窗口计算遗漏，已修复。
6. max_delay 触发重置等待时间导致长时间不触发（fix 38）：触发阶段若积压大量待算请求，max_delay触发会不断重置等待计时，导致计算迟迟不被触发。这是典型的“触发饥饿”问题，本次修复后max_delay语义恢复正确（相关调度逻辑见 streamTriggerTask.c）。

升级建议：使用流计算且配置了sliding < interval、max_delay、复合主键或 JOIN 子查询的用户，应重点回归以上场景；尤其建议构造乱序数据测试 fix 35 的 merge 正确性。

4.3 连接与客户端协议（fix 11、36、40）

1. macOS 上 native 连接 taos_query 端口占用持续增长（fix 11）：在 macOS 上反复调用 native 连接的taos_query方法时，端口（fd）持续泄漏增长，属于客户端资源释放问题，本次已修复。
2. stmt 查询 decimal 类型客户端崩溃（fix 36）：使用 stmt（参数化/绑定）接口查询decimal类型数据时客户端崩溃，涉及 decimal 数据在绑定结果集时的内存布局处理（decimal 类型实现见 source/libs/decimal），已修复。
3. 非法用户登录导致 adapter 内存增长（fix 40）：非法用户反复尝试登录时，taosAdapter 侧内存持续增长（资源未释放），已修复，降低了暴力破解尝试对内存的冲击。

4.4 虚拟表相关（fix 39）与数据写入（fix 21、27）

1. taosX 兼容 3.4.x information_schema 查询结果变化（fix 39）：taosX 对information_schema的查询结果解析与 3.4.x 的系统表结构变更不同步，已做兼容适配。
2. str len 计算错误导致非法 raw data len 的 create 子句报错（fix 21）：字符串长度计算错误会引发建表语句（create clause）报“非法原始数据长度”，已修复底层长度计算。
3. STMT 写入时自动建表请求未释放导致内存泄漏（fix 27）：STMT 数据写入过程中产生的自动建表请求对象未释放，形成内存泄漏，已修复——该场景常见于 schemaless/自动建表写入路径。

4.5 Explorer / taosX 工具链（fix 14、17、19、20、22-26、28-34）

• 审计建库操作在未设置数据加密密钥时无返回（fix 14）：audit database creation在未配置加密密钥时挂起无响应，已修复。
• timetruncate 偶发无结果（fix 17）：timetruncate函数偶尔返回空结果，属边界条件处理缺陷，已修复。
• taosX 解析器长度扩至 48k（fix 19）：expand parser length to 48k in taosX，提升了超长 SQL/表达式的解析上限。
• Explorer tmq 连接检查无响应（fix 20）：见 3.1 节。
• 通过 agent 创建任务失败（fix 22）：create task via agent error，修复 agent 通道创建任务的失败问题。
• Explorer 切换 tag 共享主题告警语法错误（fix 23）：见 3.1 节。
• xnode 任务卡在 created 状态（fix 24）：任务状态机在 created 阶段推进失败，已修复。
• Explorer Grid 自动伸缩（fix 25）：见 3.1 节。
• mysql tinyint(1)/boolean 读取（fix 26）：数据接入 mysql 时对tinyint(1)/boolean类型的读取处理修正。
• Explorer 备份任务创建错误（fix 28）、任务 API 创建成功后数据为空（fix 30）、批量操作 API 错误（fix 31）、build task 更新 SQL 错误（fix 32）：一批 Explorer 后端接口问题集中修复。
• opcplc 特殊 point id 导致数据点列表错误（fix 29）：OPC PLC 数据源中特殊 point id 导致的数据点列表解析错误，已修复。
• fast-xml-parser CVE-2026-25896（fix 33）：taosX 依赖的fast-xml-parser存在 CVE-2026-25896 安全漏洞，本版本升级依赖完成修复。安全建议：涉及 XML 解析的接入场景应尽快升级。
• xnoded 角色时间检查错误导致异常退出（fix 34）：见 3.7 节。

五、升级路径与回归测试建议

结合以上变更点，给出可落地的升级与验证清单：

1. 升级前检查：确认所有节点配置文件中supportVnodes均 ≤ 1024，否则先行调整；梳理并记录当前日志保留策略（日志文件数已缩减为 3）。
2. 权限回归：构造覆盖以下操作的测试脚本——对 stream 授予ALL/START/STOP/DROP权限后执行对应操作；DROP ROLE IF EXISTS；普通用户建表后自写；无权限查询视图应返回权限错误而非崩溃；auditor 查看用户完整信息。
3. 流计算回归：重点验证sliding < interval、max_delay触发及时性、varchar 复合主键源表、含 JOIN 与_twstart占位符的子查询、带主键触发表的乱序数据 merge。
4. 虚拟表备份回归：使用taosdump -M all备份包含虚拟表/流/主题的库，在目标集群先恢复 basic 再恢复 ext-meta，验证虚拟表结构与跨库依赖完整还原。
5. 连接与内存回归：macOS 端长时间循环调用 nativetaos_query观察端口占用；STMT 自动建表写入后观察内存是否平稳；非法登录重试后观察 adapter 内存曲线。
6. 安全项：确认 taosX 依赖已随版本升级脱离 fast-xml-parser CVE-2026-25896 影响范围。

六、小结

TDengine 3.4.0.9 是一份典型的“稳定化 + 工具链补强”版本：功能面上，订阅令牌与虚拟表备份补全了接入与迁移能力；增强面上，虚拟表tbname查询性能、日志文件数、supportVnodes上限与 Explorer 体验得到系统性改进；修复面上，权限体系、流计算正确性、连接资源释放与一批工具链接口问题被集中收敛。对于从 3.4.0.x 升级的用户，本文第五节的回归清单可直接作为验收依据。

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine