TDengine 常见问题 TOP4

TDengine （老段）2026-09-17 13:55

TDengine 常见问题 TOP4

TOP4 主题：版本升级步骤与升级后异常

典型表现：不知道该怎么升、升完起不来、升完连不上、升完某些功能不工作

为什么它是 TOP4

版本升级是社区里"信息缺口"最大的问题：

  • 《Tdengine 3.3.6.13 → 3.4.x 生产丝滑升级步骤? 》一帖的诉求非常典型："官方文档没有看到升级步骤"。这篇帖子还拿到了点赞，说明是共性问题。
  • 紧跟着的《Tdengine 3.4.1.0 升级到 3.4.2.5 改镜像版本就可以了吗？ 》和《Td 升级后出现订阅失败》，说明"升级步骤"和"升级后遗症"是连续出现的两拨问题。
  • 它有两个特殊难点：
    1. 大版本断层 ：2.x → 3.x 的配置与数据文件完全不兼容，不能直接升，必须导出导入。
    2. 小版本也埋雷 ：3.3.6.0 改了 Docker 默认 FQDN、3.4.0.0 禁止改配置文件调参、3.3.7.0 改了流计算 TRIGGER 语法......版本号只跳一位，行为可能完全不同。
  • 升级一旦出问题，影响面是整集群 + 所有客户端，属于"高风险、低频、难回滚"的操作。

所以这篇的核心是：升级前要做的检查、两种升级路径的具体步骤、升级后必须验证的清单，以及各版本的"暗坑"清单。

一、症状大全（对号入座）

A. 升级前：不知道该怎么做

# 现象 指向
A1 官方文档找不到升级步骤，不知道能不能不停服升级 见本文第四节
A2 不确定 3.3.x → 3.4.x 是否兼容 前三段版本号一致即可兼容
A3 不确定客户端要不要一起升 必须一起升
A4 不确定 2.x 能不能直接升到 3.x 不能，配置与数据文件均不兼容
A5 不知道改镜像版本 + 挂数据卷算不算升级 算，但有前置条件

B. 升级执行失败

# 报错 / 现象 指向
B1 升级后 taosd 起不来 配置不兼容 / 数据目录异常
B2 版本升级失败，fqdn 解析异常 FQDN 变更或 hosts 未更新
B3 Docker 从 3.2.1.0 升级到 3.3.5.8 失败，日志报错 跨版本 + FQDN 变更
B4 Docker 3.3.6.13 升级到 3.3.8.1 失败 root 密码处理机制变更
B5 K8s 环境升级后管理后台一直报错无法登录 组件版本/服务未就绪
B6 升级后提示内存不足 或文件锁获取不到 多个实例抢同一数据目录

C. 升级后功能异常

# 报错 / 现象 指向
C1 升级后出现订阅失败 （ERROR (0x231e): java.util.concurrent...） 客户端驱动版本未同步
C2 升级后 taosExplorer 登录提示 taosAdapter 服务异常 组件未重启 / 版本不一致
C3 升级到 3.3.6.9 后一直报 Unable to establish connection 版本不匹配 / FQDN
C4 升级后 Java 程序开始报 TDengine ERROR (0xb) 客户端与服务端版本不匹配
C5 修改配置项后重启不生效，日志也无报错 3.4.0.0+ 需用 ALTER 改运行时参数
C6 升级后出现 taos.cfg.new、taosadapter.toml.new 等文件，不知道哪个生效 见场景 7
C7 升级后原有流计算不工作 / 建流语句报语法错误 TRIGGER 语法变更
C8 升级后 Grafana / TDinsight 面板没数据 taosKeeper 密码或版本问题
C9 升级后 taosExplorer 反复要求注册 注册状态/授权问题

D. 大版本升级（2.x → 3.x）

# 现象 指向
D1 直接覆盖安装后服务起不来 配置与数据文件不兼容
D2 想保留数据但不知道怎么做 必须导出导入，不能拷贝数据文件
D3 迁移后数据"消失"、集群 ID 变了 dataDir 挂载点变化导致新建集群

二、原因分析

2.1 版本兼容的三个层次

#mermaid-svg-J4gevRNSFlYFciYN{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-J4gevRNSFlYFciYN .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-J4gevRNSFlYFciYN .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-J4gevRNSFlYFciYN .error-icon{fill:#552222;}#mermaid-svg-J4gevRNSFlYFciYN .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-J4gevRNSFlYFciYN .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-J4gevRNSFlYFciYN .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-J4gevRNSFlYFciYN .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-J4gevRNSFlYFciYN .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-J4gevRNSFlYFciYN .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-J4gevRNSFlYFciYN .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-J4gevRNSFlYFciYN .marker{fill:#333333;stroke:#333333;}#mermaid-svg-J4gevRNSFlYFciYN .marker.cross{stroke:#333333;}#mermaid-svg-J4gevRNSFlYFciYN svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-J4gevRNSFlYFciYN p{margin:0;}#mermaid-svg-J4gevRNSFlYFciYN .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-J4gevRNSFlYFciYN .cluster-label text{fill:#333;}#mermaid-svg-J4gevRNSFlYFciYN .cluster-label span{color:#333;}#mermaid-svg-J4gevRNSFlYFciYN .cluster-label span p{background-color:transparent;}#mermaid-svg-J4gevRNSFlYFciYN .label text,#mermaid-svg-J4gevRNSFlYFciYN span{fill:#333;color:#333;}#mermaid-svg-J4gevRNSFlYFciYN .node rect,#mermaid-svg-J4gevRNSFlYFciYN .node circle,#mermaid-svg-J4gevRNSFlYFciYN .node ellipse,#mermaid-svg-J4gevRNSFlYFciYN .node polygon,#mermaid-svg-J4gevRNSFlYFciYN .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-J4gevRNSFlYFciYN .rough-node .label text,#mermaid-svg-J4gevRNSFlYFciYN .node .label text,#mermaid-svg-J4gevRNSFlYFciYN .image-shape .label,#mermaid-svg-J4gevRNSFlYFciYN .icon-shape .label{text-anchor:middle;}#mermaid-svg-J4gevRNSFlYFciYN .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-J4gevRNSFlYFciYN .rough-node .label,#mermaid-svg-J4gevRNSFlYFciYN .node .label,#mermaid-svg-J4gevRNSFlYFciYN .image-shape .label,#mermaid-svg-J4gevRNSFlYFciYN .icon-shape .label{text-align:center;}#mermaid-svg-J4gevRNSFlYFciYN .node.clickable{cursor:pointer;}#mermaid-svg-J4gevRNSFlYFciYN .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-J4gevRNSFlYFciYN .arrowheadPath{fill:#333333;}#mermaid-svg-J4gevRNSFlYFciYN .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-J4gevRNSFlYFciYN .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-J4gevRNSFlYFciYN .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-J4gevRNSFlYFciYN .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-J4gevRNSFlYFciYN .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-J4gevRNSFlYFciYN .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-J4gevRNSFlYFciYN .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-J4gevRNSFlYFciYN .cluster text{fill:#333;}#mermaid-svg-J4gevRNSFlYFciYN .cluster span{color:#333;}#mermaid-svg-J4gevRNSFlYFciYN div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-J4gevRNSFlYFciYN .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-J4gevRNSFlYFciYN rect.text{fill:none;stroke-width:0;}#mermaid-svg-J4gevRNSFlYFciYN .icon-shape,#mermaid-svg-J4gevRNSFlYFciYN .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-J4gevRNSFlYFciYN .icon-shape p,#mermaid-svg-J4gevRNSFlYFciYN .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-J4gevRNSFlYFciYN .icon-shape .label rect,#mermaid-svg-J4gevRNSFlYFciYN .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-J4gevRNSFlYFciYN .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-J4gevRNSFlYFciYN .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-J4gevRNSFlYFciYN :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 版本兼容性
① 客户端 ↔ 服务端

要求前三段版本号一致
② 服务端 ↔ 组件

taosAdapter / taosKeeper / taosX / taosExplorer

必须同版本
③ 跨大版本

2.x ↔ 3.x

配置与数据文件均不兼容

三条判断规则：

规则 说明
前三段一致即可兼容 例如 3.3.6.13 与 3.3.6.9 兼容；3.3.6.x 与 3.4.2.x 不兼容
开源版与企业版不能混用 客户端、服务端都不行
2.x 与 3.x 完全隔离 必须导出 → 安装新版 → 导入

另外还有一条规则：企业版不能升级至社区版。

2.2 根因归类

类别 说明 对应症状
① 大版本不兼容 配置/数据文件结构变更 D1 D2
② 组件版本不一致 只升了 taosd，没升 adapter/keeper/客户端 C1 C2 C4 C8
③ FQDN / hostname 变更 Docker 默认 FQDN 变更、主机名改动 B2 B3 C3
④ root 密码机制变更 Docker 各版本对自定义密码的处理不同 B4 C2
⑤ 配置方式变更 3.4.0.0+ 配置文件不再能改运行时参数 C5
⑥ 语法 / 行为变更 流计算 TRIGGER、配置项新增/废除 C7
⑦ 升级顺序错误 未按 mnode leader 顺序升级 B5 集群异常
⑧ 目录 / 挂载问题 数据目录未挂载或抢占 B6 D3

三、先搞懂升级：三种升级场景与两条路径

3.1 三种升级场景（先对号入座）

场景 判断依据 升级方式
① 同大版本小版本升级 前三段一致，如 3.3.6.13 → 3.3.6.15 常规升级，风险低
② 跨中版本升级 第一二段一致，如 3.3.x → 3.4.x 本文重点，需评估变更点
③ 跨大版本升级 2.x → 3.x 必须导出导入，不能直接升

3.2 两条升级路径

路径 命令 / 方式 适用
停服升级 停所有节点 → 依次升级重启 推荐，风险可控
滚动升级 taosinstall upgrade --rolling-upgrade 官方明确提示"目前仅推荐测试环境使用"

停服升级顺序 ：按 firstEp → secondEp → dnode3 → ...... 依次升级并重启。

滚动升级顺序：非 mnode 节点 → mnode follower 节点 → mnode leader 节点。

⚠️ 官方对滚动升级的原话是："由于客户现场环境复杂，在启停服务过程可能遇到不可预期的问题，目前升级功能仅推荐在测试环境使用。若在业务环境使用需要提前评估其风险。"生产环境请优先选择停服升级 + 业务窗口。

3.3 升级涉及的全部组件

一次完整升级，下面这些全部要对齐版本 （taosinstall 的升级流程就是按这个顺序启停的）：

顺序 组件 说明
1 taosd 数据库服务端（先升这个）
2 taosadapter REST/WS 接入；随 taosd 一起升，不能单独升
3 taoskeeper 监控上报
4 taosx 数据接入/同步
5 taos-explorer 可视化管理界面
6 客户端 / 驱动 JDBC、Python、Go、C# 等全部对齐前三段

四、标准排查流程（照着做）

第 1 步：升级前 ------ 备份

bash 复制代码 
# ① 备份数据（taosdump 走 6030，不要用 6041）
taosdump -h <host> -P 6030 -u root -p -D <db_name> -o /backup/taos

# ② 备份配置
tar czf /backup/taos-config-$(date +%F).tar.gz /etc/taos

# ③ 记录当前版本信息（回滚时对比用）
taos -V > /backup/version-before.txt
taos -s "select server_version();" >> /backup/version-before.txt
taos -s "show dnodes;" >> /backup/version-before.txt
taos -s "show mnodes;" >> /backup/version-before.txt
taos -s "show vgroups;" >> /backup/version-before.txt

企业版也可使用官方备份工具或 taosx 做备份任务。没有备份就不要升级。

第 2 步：升级前 ------ 核对兼容性与变更点

逐项确认：

bash 复制代码 
# 当前版本
taos -V
taos -s "select server_version();"

# 目标版本的前三段是否与当前一致？
# 若 3.3.x → 3.4.x，属于跨中版本，必须逐条阅读目标版本的变更说明

必查清单：

  • 目标版本是否改过 FQDN 默认值 （3.3.6.0 是分界线）；
  • 目标版本是否限制配置文件改运行时参数 （3.4.0.0 是分界线）；
  • 目标版本是否改了 SQL 语法 （如流计算 TRIGGER，3.3.7.0 是分界线）；
  • 目标版本是否改了 Docker root 密码处理方式 （3.3.6.6 / 3.3.8.8 / 3.4.1.0 是分界线）；
  • 是否有废除的配置项 需要从 taos.cfg 中删除。

第 3 步：升级前 ------ 在测试环境演练

这一步不能省。 用与生产相同的数据量级、相同的部署方式（容器 / 非容器）跑一遍完整升级，验证：

  1. 服务能起来；
  2. 数据能查到；
  3. 所有客户端能连上；
  4. 流计算 / 订阅 / 备份等关键功能正常。

第 4 步：执行升级

方式 A：官方安装工具（支持多节点 SSH 批量）

bash 复制代码 
# 查看用法
taosinstall upgrade --help

# 停服升级
taosinstall upgrade -m ssh -f /path/to/config.ini

# 滚动升级（仅测试环境）
taosinstall upgrade -m ssh -f /path/to/config.ini --rolling-upgrade

配置文件示例（config.ini）：

ini 复制代码 
[test_env]
firstep=192.168.0.1||fqdn=tdengine1||username=root||password=123456||port=22
secondep=192.168.0.2||fqdn=tdengine2||username=root||password=123456||port=22
dnode3=192.168.0.3||fqdn=tdengine3||username=root||password=123456||port=22

[local_pack]
package=/path_to_file/tdengine-tsdb-enterprise-3.3.x.x-Linux-x64.tar.gz
md5=317f88bf13aa21706ae8c2d4f919d30f

[database]
username=root
password=taosdata

提示：节点间配置免密登录时，运行安装工具的当前节点也要配免密。

方式 B：手动逐节点升级

bash 复制代码 
# ① 停止所有服务（顺序：先业务组件，再数据库）
sudo systemctl stop taosd taosadapter taoskeeper taosx taos-explorer

# ② 安装新版本包（覆盖安装）
sudo rpm -Uvh tdengine-tsdb-*.rpm        # 或 dpkg -i / tar 解包

# ③ 按顺序启动
sudo systemctl start taosd
sudo systemctl start taosadapter
sudo systemctl start taoskeeper
sudo systemctl start taosx
sudo systemctl start taos-explorer

方式 C：Docker 升级

bash 复制代码 
# ① 停止容器（保留数据卷）
docker stop tdengine

# ② 备份数据目录
tar czf /backup/taos-data-$(date +%F).tar.gz /data/taos

# ③ 用新镜像启动，沿用旧 hostname 与 FQDN（关键！）
docker run -d --name tdengine \
  -h <old_hostname> -e TAOS_FQDN=<old_fqdn> \
  -e TAOS_ROOT_PASSWORD='<当前实际密码>' \
  -p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6060:6060 \
  -v /data/taos/data:/var/lib/taos \
  -v /data/taos/log:/var/log/taos \
  -v /data/taos/cfg:/etc/taos \
  tdengine/tsdb:<new_version>

第 5 步：升级后 ------ 验证服务与版本

bash 复制代码 
# 服务状态
systemctl status taosd taosadapter taoskeeper taosx taos-explorer

# 版本是否已更新，且组件间是否一致
taos -V
taos -s "select server_version();"
taosadapter -V
taoskeeper -V

版本必须全员对齐前三段。 只升 taosd 不升客户端，就会报 C1 / C4 这类错误。

第 6 步：升级后 ------ 验证数据与集群

sql 复制代码 
-- 集群拓扑是否完整
SHOW DNODES;
SHOW MNODES;
SHOW VGROUPS;

-- 数据是否可查（用业务表名）
SHOW DATABASES;
SELECT COUNT(*) FROM <db>.<stable>;

-- 流任务是否正常
SELECT * FROM information_schema.ins_streams;

-- 订阅 topic
SHOW TOPICS;

第 7 步：升级后 ------ 验证全部接入方式

bash 复制代码 
# 原生
taos -h <host> -P 6030 -s "show dnodes;"
# WebSocket
taos -Z 1 -h <host> -P 6041 -s "show dnodes;"
# REST
curl -u root:<password> -d "show databases" http://<host>:6041/rest/sql
# taosExplorer
curl -I http://<host>:6060

再跑一次业务的读写回归，以及关键功能（流计算、订阅、备份）。

第 8 步：升级后 ------ 处理配置与语法变更

sql 复制代码 
-- 3.4.0.0+：运行时参数改成用 ALTER，不要再改 taos.cfg
ALTER DNODE <dnode_id> '<param>' '<value>';
ALTER ALL DNODES '<param>' '<value>';     -- 全局参数只能这样改
ALTER LOCAL '<param>' '<value>';          -- 仅影响当前客户端进程的新连接
  • 自 v3.3.4.0 起，通过 ALTER 修改的动态参数会自动持久化，重启后仍生效。
  • 流计算建流语句按新语法改造（见 TOP3）。
  • 检查 /etc/taos/*.new 文件，比对并合并自定义配置（见场景 7）。

五、典型场景实操

场景 1：3.3.x → 3.4.x 生产升级完整步骤

bash 复制代码 
# ============ 阶段一：准备（提前 1~2 周）============
# 1. 在测试环境完整演练一次
# 2. 阅读目标版本的全部变更说明，标注影响项
# 3. 全量备份 + 配置备份 + 版本信息留存

# ============ 阶段二：升级窗口内执行 ============
# 4. 通知业务方，停止写入
# 5. 停止服务
sudo systemctl stop taosd taosadapter taoskeeper taosx taos-explorer

# 6. 备份数据目录（最后一道保险）
sudo tar czf /backup/taos-data-$(date +%F).tar.gz /var/lib/taos

# 7. 逐节点升级（顺序：firstEp → secondEp → dnode3 ...）
#    Docker 场景务必保留 -h / TAOS_FQDN / 密码环境变量
sudo rpm -Uvh tdengine-tsdb-*.rpm

# 8. 按顺序启动
sudo systemctl start taosd
sudo systemctl start taosadapter
sudo systemctl start taoskeeper
sudo systemctl start taosx
sudo systemctl start taos-explorer

# ============ 阶段三：验证（升级后 24 小时内重点关注）============
# 9. 版本对齐 + 集群状态 + 数据抽查 + 全部接入方式
taos -V && taos -s "show dnodes;" && taos -Z 1 -h <host> -P 6041 -s "show dnodes;"

# 10. 解密客户端与业务回归
# 11. 观察 taosKeeper 监控指标是否正常上报

场景 2：2.x → 3.x（不能直接升）

原因 ：v3.0 相对此前版本做了全面重构，配置文件与数据文件均不兼容。

正确步骤：

bash 复制代码 
# ===== 在 2.x 环境 =====
# 1. 用 2.x 版本的 taosdump 导出全部数据
taosdump -h <old_host> -P 6030 -u root -p -o /backup/from2x

# ===== 在新环境 =====
# 2. 安装 3.x，并彻底清理旧残留
sudo rm -rf /etc/taos/taos.cfg
sudo rm -rf /var/log/taos/
# 确认数据不再需要后再执行
sudo rm -rf /var/lib/taos/

# 3. 安装并启动 3.x
sudo systemctl start taosd

# 4. 用 3.x 版本的 taosdump 导入
taosdump -h <new_host> -P 6030 -u root -p -i /backup/from2x

注意 ：导入时必须使用与目标版本匹配的 taosdump，2.x 的 taosdump 不能用于 3.x。

场景 3：Docker 升级后起不来

排查顺序：

bash 复制代码 
# ① 容器是否在运行、退出码是多少
docker ps -a
docker inspect <container> --format '{{.State.Status}} {{.State.ExitCode}}'

# ② 看日志
docker logs --tail 200 <container>
docker exec -it <container> bash -c "tail -200 /var/log/taos/taosdlog*"

三个高频原因：

原因 处理
FQDN 变了 （3.3.6.0 起默认从 buildkitsandbox 变为 localhost） 启动时显式指定 -e TAOS_FQDN=<old_value> -h <old_value>
root 密码机制变更 3.3.6.6--3.3.8.4：在数据目录 touch .docker-entrypoint-root-password-changed；3.3.8.8+：用 TAOS_ROOT_PASSWORD / TAOS_ROOT_PASSWORD_FILE 提供当前实际密码
数据目录未挂载 / 权限不对 检查 docker inspect --format '{``{json .Mounts}}'，确认三个目录都在宿主机上

场景 4：升级后客户端连不上

排查：

bash 复制代码 
# 服务端版本
taos -s "select server_version();"
# 客户端版本
taos -V
# 驱动版本（Java 示例）
mvn dependency:tree | grep taos

判断规则：

  • 版本前三段不一致 → 升级客户端/驱动。
  • 版本一致但仍连不上 → 检查 FQDN / 端口（参考 TOP1）。
  • 只有 WebSocket 连不上 → 检查 taosAdapter（参考 TOP2）。

典型误判 ：升级了服务端到 3.4.x，客户端还是 3.3.x 的驱动 → 报 TDengine ERROR (0xb) 或订阅失败。升级必须"服务端 + 客户端 + 组件"一起做。

场景 5：修改配置不生效（3.4.0.0+）

原因 ：自 v3.4.0.0 起，为提升安全性、防止配置文件被篡改，不再允许通过修改 taos.cfg 变更运行时配置参数。

正确做法：

sql 复制代码 
-- 修改单个节点
ALTER DNODE 1 'debugFlag' '135';

-- 修改所有节点（全局参数只能用这个）
ALTER ALL DNODES 'EnableStrongPassword' '0';

-- 仅当前客户端进程
ALTER LOCAL 'timezone' 'Asia/Shanghai';
bash 复制代码 
# 修改后确认
taos -s "show variables like '<param>';"
# 或
taos -C          # 打印 -c 指定目录下 taos.cfg 的配置参数

在低于 3.4.0.0 的版本上，改配置文件仍是有效手段；但推荐统一改用 ALTER，避免将来升级再踩坑。

场景 6：升级后订阅（TMQ）失败

现象 ：ERROR (0x231e): java.util.concurrent...，或消费端拿不到数据。

原因 ：0x231e 是请求处理超时 ，在升级场景中通常源于驱动与服务端版本不匹配。

操作：

bash 复制代码 
# ① 对齐版本
taos -s "select server_version();"      # 服务端
mvn dependency:tree | grep taos          # 客户端驱动版本
sql 复制代码 
-- ② 检查 topic 是否存在、状态如何
SHOW TOPICS;
SHOW CONSUMERS;
java 复制代码 
// ③ 必要时调大超时参数
properties.setProperty(TMQConstants.MSG_WAIT_TIMEOUT, "5000");
sql 复制代码 
// ④ 若 WAL 保留策略不足导致消费落后太多
// 检查库的 WAL_RETENTION_PERIOD / WAL_RETENTION_SIZE
SHOW CREATE DATABASE <db_name>;

场景 7：升级后出现 .new 配置文件，哪个生效？

现象 ：/etc/taos/ 下同时存在 taosadapter.toml 和 taosadapter.toml.new、taos.cfg 和 taos.cfg.new。

原因 ：升级时安装脚本会把新版本自带的默认配置写成 <name>.new，避免直接覆盖你已有的配置。

处理：

bash 复制代码 
cd /etc/taos

# ① 先确认实际生效的文件（不带 .new 的那个）
ls -l taos.cfg taosadapter.toml

# ② 比对差异，把新版本新增/变更的项合并到生效文件
diff -u taosadapter.toml taosadapter.toml.new

# ③ 只合并你需要的项，然后重启
sudo systemctl restart taosadapter

结论：实际生效的是不带 .new 的文件 。.new 只是"新版本默认配置模板"，用于对比参考；确认合并完成后可以删除，避免下次升级混淆。

场景 8：升级后流计算不工作

原因 ：流计算语法在 3.3.7.0 前后发生变更，TRIGGER 关键字仅适用于 v3.0.0.0--v3.3.7.0。

sql 复制代码 
-- 查看现有流的创建语句
SHOW CREATE STREAM <stream_name>;

-- 按新语法重建
DROP STREAM <stream_name>;
CREATE STREAM <stream_name> INTERVAL(1h) SLIDING(1h)
  FROM <stb> PARTITION BY tbname
  INTO <out> AS SELECT ...;

详见 TOP3。

场景 9：升级后数据"消失"、集群 ID 变了

原因 ：dataDir 指向的挂载点没有自动挂载。服务器重启后该目录变成普通本地目录，taosd 启动时在里面新建了 mnode/dnode/vnode，于是形成了一个新集群。

处理：

bash 复制代码 
# ① 确认数据盘是否真的挂载了
df -h | grep taos
mount | grep <dataDir>

# ② 把数据盘写入 fstab，确保持久化自动挂载
# ③ 重新挂载后重启 taosd，原来的库会回来

预防 ：所有数据目录必须写进 /etc/fstab，并在监控里对"挂载点丢失"告警。

场景 10：需要回滚

bash 复制代码 
# ① 停止服务
sudo systemctl stop taosd taosadapter taoskeeper taosx taos-explorer

# ② 卸载新版本，装回旧版本包
sudo rpm -Uvh --oldpackage tdengine-tsdb-<old_version>.rpm

# ③ 恢复配置
tar xzf /backup/taos-config-<date>.tar.gz -C /

# ④ 启动并按第 5~7 步重新验证

⚠️ 回滚前务必确认 ：新版本是否已经写过数据文件。如果数据文件已被新版本升级过格式，直接回滚旧版本可能无法读取。这也是"升级前必须备份数据"的原因。

六、版本暗坑清单（重点）

版本分界线 变更内容 升级时要做的事
v3.0.0.0 配置与数据文件与 2.x 完全不兼容 删除 /etc/taos/taos.cfg、/var/log/taos/、/var/lib/taos/ 后重装
v3.0.0.0 ~ v3.3.7.0 流计算使用 TRIGGER 关键字 升级到更高版本需改造建流 SQL
v3.3.4.0 ALTER 修改的动态参数自动持久化 可用 ALTER 替代改配置
v3.3.5.0 新增 queryUseMemoryPool / minReservedMemorySize / singleQueryMaxMemorySize 关注内存行为变化
v3.3.5.1 taosd.service 的 StartLimitInterval 由 60s 调整为 900s 900 秒内重启 3 次会触发 start-limit-hit，需 systemctl reset-failed
v3.3.6.0 Docker 默认 fqdn 从 buildkitsandbox 变为 localhost 升级启动时指定 -e TAOS_FQDN=<old> -h <old>
v3.3.6.6 Docker 支持 TAOS_ROOT_PASSWORD 自定义密码的容器升级需提供该变量
v3.3.6.13 taosAdapter 支持 IPv6 注意 localhost 解析歧义
v3.3.7.0 流计算语法切换；新增 IGNORE_NODATA_TRIGGER 改造建流 SQL
v3.3.8.8 Docker 支持 TAOS_ROOT_PASSWORD_FILE，镜像可直接升级 密码必须在部署配置中同步
v3.4.0.0 禁止通过配置文件修改运行时参数 改用 ALTER DNODE / ALTER ALL DNODES
v3.4.1.0 支持 taos-check startup / taos-check service K8s 探针需同步调整

上表仅列出社区高频踩坑点，完整变更请以目标版本的官方变更说明为准。

七、预防清单

  • 升级前必须全量备份（数据 + 配置 + 版本信息）。
  • 先在测试环境演练，用相同数据量级与部署方式。
  • 逐条阅读目标版本的变更说明，对照第六节暗坑清单。
  • 服务端、taosAdapter、taosKeeper、taosX、taosExplorer、客户端驱动全部对齐版本。
  • 生产环境优先停服升级，滚动升级仅在测试环境使用。
  • Docker 升级时显式指定 -h / TAOS_FQDN / root 密码环境变量。
  • K8s 环境同步更新探针配置（taos-check）。
  • 升级后逐项验证：集群拓扑、数据、三种接入方式、流计算、订阅、备份。
  • 数据目录写进 /etc/fstab 并监控挂载点。
  • 保留旧版本安装包与配置，明确回滚路径。
  • 升级后 24 小时内重点观察 CPU、内存、连接数、流任务重算。

八、求助模板（贴在社区里，回复会快很多）

text 复制代码 
【TDengine 使用环境】生产 / 预生产 / 测试 / PoC
【升级前版本】___
【目标版本】___
【操作系统及版本】___
【部署方式】容器（镜像名/版本） / 非容器（rpm/deb/tar）
【集群节点数】___    【副本数】___
【升级方式】停服升级 / 滚动升级 / 改镜像 tag / 覆盖安装
【升级阶段】升级前咨询 / 升级中失败 / 升级后异常
【报错完整文本】（不要只截图）
【已排查】
  - taos -V 与 select server_version()：___
  - taosadapter -V：___
  - 客户端/驱动版本：___
  - systemctl status taosd：___
  - show dnodes / show vgroups：___
  - /etc/taos 目录下有哪些文件（含 .new）：___
【日志】/var/log/taos 下的 taosdlog / taosadapterlog 关键片段

九、相关链接

本文整理自 TDengine 技术社区真实提问，覆盖 2.x 至 3.4 各版本的升级场景。如果你遇到的情况不在上述症状列表中，欢迎到社区发帖并附上本文第八节的求助模板。

相关推荐
小蒜学长1 小时前
基于RFID技术的仓储管理系统设计（代码+数据库+LW）
java·数据库·spring boot·后端·rfid技术·仓储管理
梦影_1 小时前
Langchain简单快速上手教程（五）——聊天模型之流式传输
java·数据库·人工智能·python·langchain
数据狐(Datafox)1 小时前
1688商品列表API接口解析（附 JSON 样例）
java·开发语言·数据库·爬虫·json
华普微HOPERF2 小时前
远距离、低功耗、大容量，RFM6601如何打造可靠的LoRaWAN网络
物联网·lora·智慧水表·智慧电表
adinnet20262 小时前
客服与工单：响应时长与满意度问数
数据库·人工智能
Quanqiucard2 小时前
摄像头网络不稳定怎么办？商用监控物联网卡怎么选才靠谱
物联网·机器人
文人sec2 小时前
MYSQL：insert...select：为什么锁源表的所有行和间隙？怎么最快地复制一张表？
数据库·python·mysql
iNeuOS工业互联网3 小时前
大模型（DeepSeek）辅助 3D 实时建模 + 拖拽配置：业务可视化应用快速构建实践（标注、巡检与视角控制等）
人工智能·物联网·3d·语言模型·工业互联网
oradh3 小时前
Oracle联机日志文件损坏故障总结
数据库·oracle·oracle联机日志文件损坏
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02数学公理体系大全:第六章 选择公理的等价形式及证明03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点05微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07人工智能（AI）发展史：详细里程碑082026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？09ZCode 周末送额度活动开启：3 亿 Token 免费领取10【一等奖版】2026 国赛 A题 药材的烘干问题