在这里插入图片描述

TOP1 主题：无法连接 / 连接超时
核心报错：Unable to establish connection（错误码 0x8000000B）

为什么它是 TOP1

在 TDengine 技术社区，这个主题的出现频率远高于其他任何一类问题：

  • 以 Unable to establish connection 为关键词检索社区，命中的独立主题数量是所有报错中最多的，且跨越 2.6 / 3.0 / 3.2 / 3.3 / 3.4 全部版本。
  • 近 6 周（2026-08 ~ 2026-09）社区热度最高的两个帖子，都是连接类问题：
    • 《TDengine 总是连接超时》
    • 《6041 端口突然不可用了》
  • 它的"变体"极多——同一个根因，在不同连接方式（原生 / WebSocket / REST）、不同语言（Java / Python / Go / C#）、不同组件（JDBC / Flink / Kafka-connect / taosdump / taosBenchmark / Grafana）下，会报出几十种看起来完全不同的错误信息，导致用户很难判断"我遇到的到底是哪一类"。

所以这篇文章的结构是：先把症状列全，让你对号入座；再讲原因；最后给可以照着敲的操作步骤。

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

以下均为社区用户贴出的报错原文（节选），按场景分组。找到最像你的那一条，记住它的编号，后面第二节有对应的原因分析。

A. taos 命令行（taos shell）

#报错原文出现时机
A1failed to connect to server, reason: Unable to establish connection [0x8000000B]直接执行 taos
A2failed to connect to server, reason: Unable to establish connection（版本 3.3.0.3）集群部署后首次连接
A3DB error: Unable to establish connection (48.059006s) 或 (0.028392s)执行 SQL 时；注意括号里是耗时
A4show databases; 正常、show stables; 正常，但 show tables; / select 就报 DB error: Unable to establish connection集群部分节点不通
A5修改端口后，终端执行 taos 会特别慢，并且无法执行指令，会报 DB error：Unable to establish connection 0x8000000B改过 serverPort
A6failed to connect to server, reason: Unable to establish connection（改了 taos.cfg / taosadapter.toml / explorer.toml 端口后）改端口后重启

B. Java / JDBC

#报错原文出现时机
B1java.sql.SQLException: TDengine ERROR (0xb): sql: use yk, desc: Unable to establish connection重启 TDengine 后，Java 程序开始报
B2TDengine ERROR (0x8000000b): Unable to establish connection at com.taosdata.jdbc.TSDBError.createSQLException原生连接（jdbc:TAOS://...:6030）
B3Caused by: com.zaxxer.hikari.pool.HikariPool$PoolInitializationException: Failed to initialize pool: TDengine ERROR (0xb): sql: use yk, desc: Unable to establish connection应用启动、连接池初始化
B4java.sql.SQLException: ERROR (0x231d): can't create connection with server within: 60000 milliseconds at com.taosdata.jdbc.ws.Transport.checkConnectionJDBC WebSocket 连接超时
B5java.sql.SQLException: JNI ERROR (0x2354): Unable to establish connection原生 JNI 连接
B6java.lang.UnsatisfiedLinkError: no taos in java.library.path找不到本地库
B7failed to load libtaosws.so since No such file or directory [0x80FF0002]找不到 WebSocket 动态库
B8TDengine ERROR (0xb): sql: select server_status(), desc: Unable to establish connection（Spring Boot 的 validation-query）数据源健康检查
B9Failed to check Server Edition, Reason:0x8000000b:Fail to get table info, error: Unable to establish connection远程登录，停顿几秒后能进去但操作异常
B10Caused by: java.lang.ClassNotFoundException: com.taosdata.jdbc.rs.RestfulDriver依赖 / 驱动缺失（表象相似，见场景 6）

C. 其他语言 / 生态组件

#报错原文组件
C1Kafka-connect-tdengine 报错 JNI ERROR (0x2354): Unable to establish connectionKafka Connect
C2{‘code’: 11, ‘desc’: ‘Unable to establish connection’, ‘timing’: 10013435798}REST API 返回 JSON，code: 11 即 0xB
C3connection 0x...: code: 0x8000000b, reason: Unable to establish connection，随后 is dumping out schema:41%taosdump 备份中途失败
C4Unable to establish connection + failed to create databasetaosBenchmark 在宿主机跑，容器内跑正常
C5Grafana / TDinsight 无数据、无法添加数据源6041 不通

D. 服务端日志（taosdlog）

#报错原文含义
D1C TSC ERROR failed to connect to server, reason: Unable to establish connection客户端侧
D2C RPC ERROR TSC conn:0x..., failed to connect to gkmn:6030 since connection refused目标端口没有监听
D3UTL ERROR failed to connect socket, ip:0x..., port:6030(target host cannot be reached)网络不可达
D4user:root, auth msg received from mnodes, error:Unable to establish connection与 mnode 通信异常
D5failed to connect to server, reason: Authentication failure密码错误（易混淆）
D6DND ERROR failed to create dnode since Resource temporarily unavailable迁移 data/log 目录后
D7DND ERROR Version not compatible, client: 3000700, server: 3020300版本不兼容

E. 特定场景现象

#现象场景
E1集群 3 节点，只要一个节点有问题，客户端切换地址连接其他节点也连不上，或连上了执行 SQL 又报 0xb客户端 FQDN 未配全
E2双网卡冗余部署（/etc/hosts 里同一域名配两个 IP），A 网断掉后无法走 B 网双网 + FQDN 机制
E3Docker 容器状态正常、能 docker exec 进去，但里面 taos 报连不上，ps aux | grep taos 看不到 taosd 进程容器内 taosd 挂掉
E4查询偶尔报错，大约半小时一次网络抖动 / 节点切换
E5升级到新版本后一直报 Unable to establish connection升级后版本/FQDN 变化
E6服务端启用 TLS 后，客户端连不上；或非 TLS 客户端连 TLS 集群TLS 模式不匹配

二、原因分析

Unable to establish connection 只是一个统一的表层错误，底层对应错误码 TSDB_CODE_RPC_NETWORK_UNAVAIL (0x000B)。它真正的含义是：

客户端请求没能成功送达并可用的服务端节点。

所以问题一定落在下面这条链路的某一环：

客户端进程
   │  ① 本地库是否加载成功？
   ▼
连接器 / 驱动（libtaos.so、JDBC jar）
   │  ② 版本是否匹配？传输方式（原生/WS）是否一致？
   ▼
DNS / hosts 解析 FQDN
   │  ③ 域名能否解析成正确 IP？
   ▼
网络（安全组、防火墙、路由、双网卡）
   │  ④ 端口是否放行、是否可达？
   ▼
taosd / taosadapter 进程
   │  ⑤ 进程是否在跑？端口是否 LISTEN？
   ▼
集群拓扑（mnode leader / vnode）
   │  ⑥ 是否配全所有节点 FQDN？leader 是否可达？
   ▼
鉴权 / TLS
      ⑦ 密码、Token、TLS 证书是否匹配？

根本原因归类（对应上表编号）

类别说明对应症状
① 服务端未运行taosd / taosadapter 没启动，或启动了又崩了A1 A2 D2 E3
② FQDN 解析问题客户端 hosts/DNS 缺配置、配错、或配了不可达的 IPB9 E1 E2
③ 网络与端口安全组/防火墙未放行 6030/6041；跨网段路由不通A3 D3 C4
④ 版本 / 传输方式不匹配客户端与服务端版本前三段不一致；TLS 与非 TLS 混用；原生连 6041D7 E5 E6
⑤ 端口被改但未同步改了 serverPort，客户端仍连 6030；集群 EP 未统一A5 A6
⑥ 集群拓扑不完整客户端只配了部分节点 FQDN；mnode leader 不可达A4 E1
⑦ 本地库 / 依赖问题libtaos.so 路径不对、jar 冲突、驱动类缺失B5 B6 B7 B10
⑧ 连接被复用/关闭连接关闭后继续使用，报 JNI NULLB5 C1

三、先搞懂 FQDN：它是什么，怎么配

上一节的第 ② ⑥ 类根因都指向 FQDN。这一节把 FQDN 讲透——看懂这一节，连接类的坑基本就排掉一半了。

3.1 什么是 FQDN

FQDN = Fully Qualified Domain Name，全限定域名。 通俗讲，就是「一台机器在网络上的完整名字」。

名称例子说明
hostname（短名）td1机器自己的短名字，hostname 命令可查看
FQDN（全限定域名）td1.taosdata.com带完整域名的名字，hostname -f 可查看
IP 地址192.168.1.10网络地址，会随环境变化

为什么 TDengine 不用 IP，而是用 FQDN 来标识机器？

  1. 机器换 IP、换网段时，只需改 hosts / DNS，不用动 TDengine 配置，也不用动数据。
  2. TDengine 以 hostname 唯一标识一台机器，数据文件与集群元信息里记录的都是 FQDN，而不是 IP。
  3. 集群需要节点之间互相寻址，FQDN 比 IP 稳定。

TDengine 的寻址机制（理解这一点，就能理解绝大部分连接问题）

节点3 节点2 节点1 (mnode leader) 客户端 节点3 节点2 节点1 (mnode leader) 客户端 ① 用 firstEp / -h 指定的地址连接 ② 返回集群完整拓扑（各节点的 FQDN:6030） ③ 按 FQDN 直连节点2 ④ 按 FQDN 直连节点3

三个关键结论：

  1. 你第一次连接用 IP 还是 FQDN 都能连上。
  2. 但连上之后，客户端会按服务端返回的 FQDN 去连其他节点，而不是继续用你传入的 IP。
  3. 因此客户端必须能解析并访问所有节点的 FQDN，只配一个节点是不够的。

这就是「客户端能连上，但一执行 SQL 就报 Unable to establish connection」的根本原因——第一个节点连上了，后续按 FQDN 找其他节点时失败了。

3.2 TDengine 里和 FQDN 有关的 4 个配置

参数配在哪作用默认值
fqdn服务端 taos.cfg我是谁：本节点对外通告的服务地址本机第一个 hostname
serverPort服务端 taos.cfg我在哪个端口：本节点监听端口6030
firstEp服务端 taos.cfg去哪找组织：首次启动时连接的集群首个节点 endpointlocalhost:6030
secondEp服务端 taos.cfgfirstEp 连不上时的备用节点（可选）无

节点的 endpoint = fqdn:serverPort，例如 node1.taosdata.com:6030。执行 SHOW DNODES 时看到的 endpoint 列，就是它。

补充：firstEp 只在节点首次加入集群时起作用。加入成功后，节点会保存最新的 mnode endpoint 列表，后续不再依赖该参数；但客户端（taos shell、应用）仍会用它作为默认连接地址。

3.3 怎么配（以 3 节点集群为例）

第一步：为每台机器设置 hostname
# 在每台机器上分别执行；注意：hostname 必须唯一
sudo hostnamectl set-hostname node1.taosdata.com    # node2 / node3 同理

# 确认结果
hostname -f
第二步：所有机器（包括客户端）都配 hosts

Linux / macOS 的 /etc/hosts：

192.168.1.10  node1.taosdata.com  node1
192.168.1.11  node2.taosdata.com  node2
192.168.1.12  node3.taosdata.com  node3

Windows 客户端的 C:\Windows\System32\drivers\etc\hosts：

192.168.1.10  node1.taosdata.com
192.168.1.11  node2.taosdata.com
192.168.1.12  node3.taosdata.com

内网有 DNS 就优先用 DNS，没有 DNS 才用 hosts。每个服务端节点、每个客户端机器，都要能解析全部节点的 FQDN。

第三步：配置每个节点的 taos.cfg
# ---------- node1.taosdata.com ----------
fqdn        node1.taosdata.com       # 我是 node1
firstEp     node1.taosdata.com:6030  # 集群入口（所有节点保持一致）
serverPort  6030

# ---------- node2.taosdata.com ----------
fqdn        node2.taosdata.com       # 我是 node2
firstEp     node1.taosdata.com:6030  # 同上，保持一致
serverPort  6030

# ---------- node3.taosdata.com ----------
fqdn        node3.taosdata.com       # 我是 node3
firstEp     node1.taosdata.com:6030  # 同上，保持一致
serverPort  6030

记忆口诀：firstEp 全场一样，fqdn 各不相同。

  • fqdn 必须等于本机 hostname -f 的输出。
  • 若本机只有一个 hostname 且它就是要用的 FQDN，fqdn 这行可以省略（默认取第一个 hostname），但显式写出来更不容易出错。
  • 客户端如果没在命令行指定 -h，会默认连本机 taos.cfg 里 firstEp 指定的节点。
第四步：启动并加入集群
# 每个节点启动 taosd
sudo systemctl start taosd

# 在 node1 上查看（此时只有 1 个节点）
taos -h node1.taosdata.com -s "show dnodes;"

# 把 node2 / node3 加入集群（注意 endpoint 两侧的英文双引号不能省）
taos -h node1.taosdata.com -s 'create dnode "node2.taosdata.com:6030"'
taos -h node1.taosdata.com -s 'create dnode "node3.taosdata.com:6030"'

# 确认
# 要求：endpoint 列必须是 FQDN:6030，如果显示的是 IP 或短名，说明 fqdn 没配对
taos -h node1.taosdata.com -s "show dnodes;"
单机部署也要配 FQDN

单机场景同样建议配好，否则以后扩成集群要返工：

# /etc/hosts
127.0.0.1     localhost
192.168.1.10  tdengine.taosdata.com  tdengine

# /etc/taos/taos.cfg
fqdn        tdengine.taosdata.com
firstEp     tdengine.taosdata.com:6030
serverPort  6030

⚠️ 即使单机，也不建议把 fqdn 配成 localhost：容器、CI、多网卡环境下 localhost 的解析结果不可控，且远程客户端无法使用。

3.4 怎么验证 FQDN 配好了

按顺序执行，全部通过才算 OK：

# ① 本机 FQDN 是否正确
hostname -f

# ② 能否解析（重点看返回的 IP 对不对）
getent hosts node1.taosdata.com
ping -c 2 node1.taosdata.com

# ③ 端口是否可达（每台机器上都要对每个节点测一遍）
nc -vz node1.taosdata.com 6030
nc -vz node2.taosdata.com 6030
nc -vz node3.taosdata.com 6030

# ④ 用 FQDN 连接并检查集群拓扑（每个节点都连一次）
taos -h node1.taosdata.com -s "show dnodes;"
taos -h node2.taosdata.com -s "show dnodes;"

3.5 FQDN 相关的 6 个经典坑

#坑现象正确做法
1用 localhost / 127.0.0.1 当 FQDN本机能用、远程用不了；容器里行为诡异用真实 FQDN
2只配了部分节点的 FQDN能连上，一执行 SQL 就报 0xb；单节点故障后整体不可用全节点 FQDN 都配到每个客户端
3改了 hostname 但没处理数据目录起不来，或「库消失了」、集群 ID 变了变更 hostname 后清理 dataDir（/var/lib/taos）重建
4hosts 里同一域名配两个 IP（双网冗余）主网断掉后无法自动切到备网用 DNS 或多 FQDN，不要在 hosts 里重复同名记录
5图省事直接用 IP 连接首次能连，后续按 FQDN 找节点就失败首次连接也用 FQDN
6Docker 容器 hostname 随机重启后 FQDN 变化，节点互相找不到固定 -h <fqdn>，并设置 TAOS_FQDN

报错 → FQDN 问题 对照表

报错指向的 FQDN 问题
Unable to resolve FQDN客户端解析不了 FQDN（hosts / DNS 缺配置）
some vnode/qnode/mnode(s) out of service只配了部分节点 FQDN
Sync leader is unreachable集群其他节点端口未开放，或 hosts 未配全
连上后执行 SQL 报 0xb同上
本机 taos 正常、远程客户端报 Unable to establish connection远程客户端的 FQDN 解析问题

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

第 0 步：先看"有多快失败"

这能帮你省下大量时间：

报错耗时含义优先怀疑
< 1 秒（如 0.028s）一步都没走通端口没监听 / 网络不可达 / FQDN 解析失败
几秒 ~ 几十秒（如 48s）连接上了但在等某个节点集群拓扑不全 / mnode leader 不可达 / 节点离线
整 60 秒（0x231d）WebSocket 握手超时taosAdapter 不通 / Nginx 配置

第 1 步：服务端进程与端口

# 服务是否在运行
systemctl status taosd
systemctl status taosadapter

# 端口是否在 LISTEN（关键！）
netstat -lntp | grep -E '6030|6041|6043|6060'
# 或
ss -lntp | grep -E '6030|6041'

# 容器内排查（E3 场景）
docker exec -it <container> bash -c "ps aux | grep taos; netstat -lntp"

如果 6041 没有 LISTEN → taosadapter 没起来：systemctl start taosadapter（容器场景见第五节场景 4）。
如果 6030 没有 LISTEN → taosd 没起来，先看 /var/log/taos/taosdlog*。

第 2 步：FQDN 解析

如果还不清楚 FQDN 是什么、该怎么配，请先看本文第三节。

# 服务端：拿到自己的 FQDN
hostname -f

# 客户端：必须能解析并 ping 通
ping <fqdn>
getent hosts <fqdn>     # 看解析到了哪个 IP
cat /etc/hosts
cat /etc/hostname

⚠️ 最重要的一条经验：TDengine 用 hostname 唯一标识节点，服务端返回给客户端的节点地址是 FQDN + 端口，而不是你连接时用的 IP。
所以即使你用 -h 192.168.1.10 连上了，客户端随后仍会用服务端自报的 FQDN 去连其他节点——FQDN 解析不通，就会出现"能连上但一执行 SQL 就报 0xb"（症状 A4 / B9 / E1）。

第 3 步：网络连通性

# 基础端口探测
nc -vz <host> 6030
nc -vz <host> 6041
telnet <host> 6030

# Windows
Test-NetConnection -ComputerName <fqdn> -Port 6030

# 防火墙
firewall-cmd --list-port          # CentOS
ufw status                        # Ubuntu

# 云服务器记得检查「安全组」

推荐一次性开放端口段 6030–6070（TCP），即可覆盖 TSDB / IDMP / TDgpt 全部默认端口：

组件默认端口
taosd（原生接口）6030
taosAdapter（REST / WebSocket）6041
taosKeeper（监控）6043
taosX（REST / gRPC）6050 / 6055
taosExplorer6060

第 4 步：用 TDengine 自带的网络检测功能（强烈推荐）

taos shell 内置了网络连通性压测，比 ping / telnet 更贴近真实链路：

# 服务端起一个 nettest 服务端（在被测的服务器上执行，会一直挂着）
taos -n server

# 客户端发起 10 个 2000 字节的包
taos -h <host> -n client -l 2000 -N 10

成功时会输出类似：

response is received, size:2000
total succ:   10/10   cost:   12.34 ms   speed:  15.87 MB/s

如果 10/10 拿不到，说明 TCP/UDP 链路本身有问题，先解决网络，再谈 TDengine 配置。

另外还有一个快速状态检测参数：

# 0=unavailable 1=network ok 2=service ok 3=service degraded 4=exiting
taos -h <host> -k

-k 1 表示网络通但服务不通；-k 2 表示服务完全可用。这是区分"网络问题"还是"服务问题"最快的方法。

第 5 步：用最简方式验证服务端本身

# 服务端本机
taos -h 127.0.0.1 -s "show dnodes;"

# 验证 taosAdapter（REST）
curl -u root:taosdata -d "show databases" http://<host>:6041/rest/sql

# 用 WebSocket 方式连接（验证 Adapter 的 WS 通道）
taos -Z 1 -h <host> -P 6041
  • 本机通、远程不通 → 网络 / 端口 / FQDN 问题。
  • REST 通、原生不通 → 6030 被拦。
  • 原生通、REST 不通 → taosadapter 问题。

第 6 步：版本与本地库

taos -V                          # 客户端版本
# 服务端版本
taos -h <host> -s "select server_version();"

# 本地库路径
echo $LD_LIBRARY_PATH
ls -l /usr/local/taos/driver/    # libtaos.so
ldd /usr/local/taos/driver/libtaos.so | grep "not found"

铁律：客户端与服务端版本号前三段必须一致（如 3.3.6.x 与 3.3.6.y），且开源版与企业版不能混用。

五、六大典型场景实操

场景 1：客户端在另一台机器连不上（最常见）

现象：服务端本机 taos 正常，客户端机器报 0x8000000B；telnet localhost 6030 能通，但 telnet 服务器公网 IP 不通。

原因：安全组 / 防火墙没放行，或客户端 hosts 没配。

操作：

# ① 服务端开放端口（CentOS 示例）
sudo firewall-cmd --permanent --add-port=6030/tcp
sudo firewall-cmd --permanent --add-port=6041/tcp
sudo firewall-cmd --reload

# ② 云服务器：控制台安全组放行 6030-6070/TCP

# ③ 客户端配置 hosts（用服务端 hostname -f 的输出）
sudo tee -a /etc/hosts <<'EOF'
192.168.1.10  tdengine-server-01
EOF

# ④ 客户端验证
ping tdengine-server-01
taos -h tdengine-server-01 -P 6030 -s "show dnodes;"

场景 2：集群一个节点故障，客户端就整体不可用

现象：3 节点集群，任一节点出问题后，客户端即使切换到其他健康节点的地址也无法连接，或连上了执行 SQL 报 TDengine ERROR (0xb)。

原因：客户端只配置了部分节点的 FQDN 解析。TDengine 客户端要先连 mnode，再由 mnode 返回完整拓扑，客户端随后必须能直接访问所有节点的 FQDN。少配一个，就会在"拿到拓扑后"失败。

操作：

# 客户端 /etc/hosts 必须配全集群所有节点
192.168.1.10  node1.taosdata.com
192.168.1.11  node2.taosdata.com
192.168.1.12  node3.taosdata.com

# 逐台验证
for h in node1 node2 node3; do
  echo -n "$h: "; nc -vz $h.taosdata.com 6030
done

如果用 JDBC 连接串做高可用，把多个节点都写进去：

// 原生连接
jdbc:TAOS://node1:6030,node2:6030,node3:6030/db?user=root&password=taosdata

// WebSocket 连接
jdbc:TAOS-WS://node1:6041,node2:6041,node3:6041/db?user=root&password=taosdata

⚠️ 不要把 FQDN 指向 VIP/Nginx 虚拟地址让所有节点"共用一个域名"。TDengine 需要按真实节点寻址；接入层 VIP 只能用于第一次连接，节点故障后仍会因找不到真实 FQDN 而失败。

场景 3：改了端口就连不上

现象：按需修改了 taos.cfg 的 serverPort（如 11030）、taosadapter.toml 的 port（如 11041）、explorer.toml 的 port（如 11060），重启后 taos 报连不上。

原因：taos 客户端默认连 6030，你改了服务端端口，但客户端没跟着改；或集群各节点端口不一致。

操作：

# ① taos 客户端显式指定新端口
taos -h <host> -P 11030

# ② 让客户端默认走新端口：客户端 taos.cfg 里也要同步
serverPort 11030

# ③ 集群场景：所有节点的 serverPort 必须一致，
#    且 SHOW DNODES 里的 endpoint 端口要与实际监听端口一致
taos -P 11030 -s "show dnodes;"

排查顺序：先确认服务端监听了新端口（ss -lntp | grep 11030），再确认客户端连的是新端口，最后确认集群内各节点端口一致。

场景 4：Docker 容器正常，但容器内 taosd 消失

现象：容器状态 Up，能 docker exec 进去，但 taos 报连不上，ps aux | grep taos 看不到 taosd，日志停在某个时间点。

原因：容器内 taosd 进程崩溃或被杀（常见于内存不足被 OOM Killer 干掉，或配置/数据目录权限问题）。

操作：

# ① 确认进程与退出原因
docker exec -it <container> bash -c "ps aux | grep taos"
docker inspect <container> --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
dmesg -T | grep -i "killed process"

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

# ③ 检查挂载（数据/日志/配置三个目录都要挂）
docker inspect <container> --format '{{json .Mounts}}'

推荐的挂载方式（三类目录一个都不能少）：

docker run -d --name tdengine \
  -h tdengine \
  -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-ee

内存不足的预防：为容器设置足够内存，并检查主机 vm.min_free_kbytes 与 SWAP 配置。

场景 5：升级后连不上

现象：升级 TDengine 后一直报 Unable to establish connection；或升级后 Java 程序报 TDengine ERROR (0xb): sql: use xxx, desc: Unable to establish connection。

原因（按概率排序）

  1. 版本不匹配：客户端 / 驱动 / taosd / taosAdapter 版本不统一。
  2. Docker 场景 FQDN 变化：v3.3.6.0 起容器内默认 fqdn 从 buildkitsandbox 变为 localhost，升级启动时若未指定旧值，节点可能起不来或互相寻址失败。
  3. 配置不再允许直接改文件：v3.4.0.0 起运行时参数只能通过 ALTER 修改。

操作：

# ① 统一版本：server / client / driver / adapter 全部对齐前三段
taos -V
taos -h <host> -s "select server_version();"

# ② Docker 升级时保留旧 fqdn
docker run -e TAOS_FQDN=<old_value> -h <old_value> ...

# ③ 3.4.0.0+ 用 ALTER 而不是改 taos.cfg
taos -s "ALTER DNODE 1 'debugFlag' '135';"

# ④ taosAdapter 不单独升级，随 TDengine Server 一起升级

升级前务必：在测试环境演练一遍、全量备份、确认客户端与服务端版本策略。

场景 6：Java 应用启动就报连接失败

现象 A：HikariPool$PoolInitializationException: Failed to initialize pool: TDengine ERROR (0xb): ...

// 连接池配置建议（连接建立阶段不要做额外探测）
config.setMinimumIdle(10);
config.setMaximumPoolSize(10);
config.setConnectionTimeout(30000);
config.setMaxLifetime(0);   // 无限制
config.setIdleTimeout(0);   // 无限制
// 无需配置 validationQuery（JDBC 3.7.5+ 对 isValid 已做缓存优化）

现象 B：配了 validation-query: SELECT SERVER_STATUS() 就报错，去掉就正常。

说明健康检查 SQL 走的路径与业务 SQL 不同，暴露了网络/版本问题；建议先修根因，而不是简单去掉检查（去掉后问题会在业务高峰暴露）。

现象 C：no taos in java.library.path / failed to load libtaosws.so

# Linux
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/taos/driver
# 启动参数
-Djava.library.path=/usr/local/taos/driver

# 确认库文件与依赖完整
ls -l /usr/local/taos/driver/
ldd /usr/local/taos/driver/libtaos.so | grep "not found"
readelf -h /usr/local/taos/driver/libtaos.so

现象 D：通过 Nginx 转发 6041 时 WebSocket 握手失败

location /ws {
    proxy_pass http://<taosadapter>:6041;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

现象 E：mvn dependency:tree 排查 JSON 库冲突（jackson / fastjson），这类冲突也会伪装成连接失败。

六、错误码速查

错误码报错文本真实含义处理方向
0x8000000B（0xB）Unable to establish connection网络不通 / 多次重试仍无法执行请求本文全部流程
0x000B同上（部分组件显示为 [0x000B] Internal error）同上同上
code: 11REST 返回 {"code":11,"desc":"Unable to establish connection"}11 == 0x0B同上
0x800003D5Unable to establish connection While execute transaction...事务执行中网络错误，会后台重试检查网络
0x231Dcan't create connection with server within与 taosAdapter 连接失败检查 6041 / Nginx
0x2354JNI connection is NULL连接已关闭 / JNI 层为空检查连接生命周期与驱动
0x80FF0002failed to load libtaosws.so找不到动态库检查 LD_LIBRARY_PATH
0x80002605Invalid value type常量值非法（SQL 问题，非连接）修正 SQL

七、预防清单

部署阶段就做好这几件事，可以避免 90% 的连接问题：

  • 用真实 FQDN，不要用 localhost / IP 硬编码；hostname -f 的输出要能在所有节点和客户端解析。
  • 集群所有节点的 FQDN 都写进每个客户端和每个服务端的 hosts（或 DNS）。
  • 一次性放行 6030–6070/TCP（StatsD/collectd 另需 UDP）。
  • 客户端、服务端、驱动、Adapter 版本统一，前三段一致，开源版不与企业版混用。
  • Docker 部署三个目录全部持久化：/var/lib/taos、/var/log/taos、/etc/taos；固定 -h/TAOS_FQDN。
  • 不要把 FQDN 指向 VIP；VIP 只用于接入层。
  • 数据盘写进 fstab 自动挂载，避免机器重启后目录"变空"。
  • 保留数据盘 20%~30% 空闲，并对 OOM、磁盘、连接数做监控。
  • 改配置前先备份 taos.cfg；v3.4.0.0+ 用 ALTER 改运行时参数。

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

【TDengine 使用环境】生产 / 预生产 / 测试 / PoC
【TDengine 版本】服务端：x.x.x.x   客户端/驱动：x.x.x.x
【操作系统及版本】CentOS 7.9 / Ubuntu 22.04 / Windows 11 ...
【部署方式】容器 / 非容器
【集群节点数】___    【集群副本数】___
【连接方式】原生 6030 / REST 6041 / WebSocket 6041
【报错完整文本】（不要只截图，把文字贴出来）
【报错耗时】（例如 0.03s / 48s / 60s，这个信息很关键）
【复现步骤】做过哪些操作
【已排查】
  - systemctl status taosd：___
  - netstat 6030/6041：___
  - 客户端 ping FQDN：___
  - hostname -f：___
  - taos -h 127.0.0.1：___
  - taos -V 与 select server_version()：___
【日志】/var/log/taos 与 /etc/taos 打包上传

临时提高日志级别以获取更多信息：

ALTER DNODE <dnode_id> 'debugFlag' '135';
-- 131=错误+警告  135=+调试  143=+跟踪
-- 问题解决后记得调回 131，否则日志量大且影响性能

九、相关链接

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

# tdengine # linq # 大数据 # 时序数据库 # 数据库 # 物联网 # iotdb
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

CTF、SRC、渗透测试到底学什么？网络安全新手最容易走错的路线

avatar 2048 AI社区
cover

码道 | 三国人物数据库：当 HTML5 遇上 AI 大模型——纯前端智能问答项目实战全记录

avatar 2048 AI社区

AI产品经理：如何将AI技术跟产品无缝结合？

将AI技术跟产品无缝结合，不是某一项单点技能能够完成的任务，而是多种能力的综合运用。一个优秀的AI产品经理需要具备：对用户场景的敏锐洞察力、对AI技术边界的清醒认知、对产品体验的精细打磨能力、对数据闭环的系统设计能力，以及对跨团队协作的统筹能力。最重要的是，AI产品经理要避免两个极端：一是过度迷信技术，认为AI能解决一切问题；二是过度保守，只把AI当作锦上添花的噱头。真正的价值创造，源自对“AI能

avatar 2048 AI社区