TDengine 常见问题 TOP2

TDengine （老段）2026-09-13 16:03

TDengine 常见问题 TOP2

TOP2 主题：taosAdapter 不可用 / 6041 端口不通

影响范围：RESTful、WebSocket、JDBC-WS、taosExplorer、taosKeeper、Grafana、Telegraf 等全部 HTTP 接入链路

为什么它是 TOP2

紧跟 TOP1（原生连接）之后，社区第二高频的问题就是「6041 不通」：

  • 社区检索 6041 命中的独立主题数量仅次于连接类问题，检索 taosadapter 同样居高不下。
  • 近 6 周社区热度第二的帖子就是《6041 端口突然不可用了》。
  • 它的杀伤面极大：6041 一旦不通，所有 HTTP 系接入全部瘫痪------REST API、WebSocket 写入、taosExplorer 管理界面、taosKeeper 监控上报、Grafana / TDinsight 面板、Telegraf / collectd / Prometheus 数据采集，一个都活不了。
  • 更麻烦的是它的"表现"极其发散：同样是 6041 出问题，Java 报 0x231d、C# 报 61445、curl 直接无响应、Grafana 说加不了数据源、taosExplorer 提示"服务异常"、日志里刷 stmt2 execute callback error, code:-2147481324......看起来完全不是同一个问题，其实是同一条链路。

所以这篇的组织方式与 TOP1 一致：先列全症状对号入座 → 讲清底层链路 → 给出可照抄的操作步骤。

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

以下均为社区用户贴出的报错原文（节选），按场景分组。记住编号，第二节有对应的原因分析。

A. WebSocket / JDBC 客户端

# 报错原文 出现时机
A1 java.sql.SQLException: ERROR (0x231d): can't create connection with server within: 60000 milliseconds JDBC-WS 握手超时
A2 Failed to create database power or stable meters, ErrCode: 61445, ErrMessage: connect to ws://127.0.0.1:6041/ws fail C# 连接器；服务启动半小时后开始出现
A3 ERROR (0x231e): failed to complete the task within the specified time WS 请求处理超时
A4 WebSocket handshake error, code: 400 Bad Request 经 Nginx 反代访问 6041
A5 disconnect uri: 192.168.1.253:6041, code: 1000, reason: unknown, remote: true（日志里反复刷） WS 反复断开重连
A6 disconnect uri: ws://192.168.3.141:6041/ws, code : -1 , reason: , remote: true 同上
A7 通过 Nginx 连接，"一段时间后连接会自动断开" Nginx 超时设置过短
A8 java系统使用 jdbc:TAOS-WS://10.129.220.2:6041,10.129.220.3:6041,10.129.220.4:6041/iot 连接集群失败，连单个节点可以 多地址 WS 连接
A9 No suitable driver found for jdbc:TAOS-RS://172.16.0.1:6041/pulse1 驱动类没选对
A10 No suitable driver found for jdbc:TAOS://172.16.0.1:6041/pulse1 协议与端口混用（原生协议配 6041）

B. REST / HTTP 接口

# 报错原文 出现时机
B1 curl -uroot:taosdata ip:6041/rest/sql -d 'show dnodes' 没有返回，也没有报错，重启 taosAdapter 后恢复 服务假死
B2 REST 返回 {"code":11,"desc":"Unable to establish connection"} 上游 taosd 异常
B3 Read timed out（/influxdb/v1/write 写入一段时间后） 需重启 taosAdapter 才恢复
B4 read tcp 127.0.0.1:43500->127.0.0.1:6041: read: connection reset by peer 连接被重置
B5 dial tcp 127.0.0.1:6043: connect: connection refused 见 C2（注意是 6043）
B6 6041 端口突然不通了，数据库突然不可用 突发故障，见 D3
B7 Grafana / TDinsight 无法添加数据源、面板无数据 6041 不通
B8 taosExplorer 登录提示 "您的 taosadapter 服务处于异常，请尝试重启 taosadapter 服务并保证服务可用"（但进程看起来正常） 6041 异常
B9 http://xxxxxx:6041/debug/pprof/ 被安全扫描判定为中危漏洞 调试端口暴露

C. 服务端日志（taosadapterlog）

# 报错原文 真实含义
C1 WSC ERROR SID:0x1, QID:0x6fa13f0265830987 stmt2 execute callback error, code:-2147481324, err:success, action:stmt2_exec -2147481324 = 0x80000914 = Sync leader is restoring（切主后日志重演中）
C2 result is nil, result_id:2, action:fetch_raw_block 同一故障的伴随现象
C3 MON ERROR upload_id:0x2000000000c87f00, upload to keeper error, err:Post "http://127.0.0.1:6043/adapter_report": dial tcp 127.0.0.1:6043: connect: connection refused taosKeeper（6043）没起来，不影响读写，只丢监控
C4 err:Post "http://localhost:6041/rest/sql/log?req_id=...": dial tcp [::1]:6041: connect: connection refused 注意 [::1] ------ 走了 IPv6 回环，见场景 8
C5 insert into km_xxx using keeper_monitor ... err:Post "...": read: connection reset by peer taosAdapter 被打爆/重启
C6 TaosAdapter 崩溃，无法通过 ws/restful 读写数据 进程崩溃

D. 资源与稳定性

# 现象 场景
D1 taosAdapter 内存不断增长（3G / 6G / 30G），几个小时都不释放，关掉客户端也不降 大量写入或高并发查询后
D2 taosAdapter 进程 CPU 100%，容器资源占用持续升高，写入耗时从 2 秒涨到 100 多秒 长时间持续写入；或 WS + 无模式写入场景
D3 taosAdapter 与 taosd 之间建立了上千个连接 ，连接数远超 CPU × 2，长期不释放 连接池参数理解偏差
D4 taosadapter 不定时崩溃 / 自动停止运行，崩溃前日志有 keeper error 稳定性问题
D5 taosadapter 挂掉后 Query memory exhausted，并提示重启 taosadapter 内存耗尽连带效应

E. 部署与配置

# 现象 场景
E1 Docker 装了 3.3.6.13，为什么不自带 taosadapter；运行一段时间后 6041 不通 容器未启动 adapter
E2 改了 taosadapter.toml 的 port（如 11041），之后连不上 客户端/其他组件没同步改
E3 taosadapter 和 taosd 部署在不同服务器，找不到配置 taosd 地址的地方 分离部署
E4 Nginx + taosAdapter 多实例，taosd 负载严重不均衡（大量负载只在其中一个节点） 负载均衡未按预期工作
E5 taosdump -h 127.0.0.1 -P 6041 ... 进程卡死、备份失败、dbs.sql 是空的 参数用错（taosdump 走 6030）
E6 ODBC 用 6030 能连，改用 6041 连不上 协议与端口混用
E7 K8s 部署后 6030 6041 6043 6044 这些端口自己被强制停掉，重启报内存不足或文件锁获取不到 多实例抢同一数据目录
E8 Docker 修改 taosadapter.toml / taoskeeper.toml 后重启容器，配置不生效 挂载/覆盖问题

二、原因分析

2.1 先认清这条链路

6041 和 6030 是两个完全不同的服务、两条完全不同的链路：
#mermaid-svg-7SBD3ywVBmAKAKaH{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-7SBD3ywVBmAKAKaH .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-7SBD3ywVBmAKAKaH .error-icon{fill:#552222;}#mermaid-svg-7SBD3ywVBmAKAKaH .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-7SBD3ywVBmAKAKaH .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-7SBD3ywVBmAKAKaH .marker{fill:#333333;stroke:#333333;}#mermaid-svg-7SBD3ywVBmAKAKaH .marker.cross{stroke:#333333;}#mermaid-svg-7SBD3ywVBmAKAKaH svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-7SBD3ywVBmAKAKaH p{margin:0;}#mermaid-svg-7SBD3ywVBmAKAKaH .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster-label text{fill:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster-label span{color:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster-label span p{background-color:transparent;}#mermaid-svg-7SBD3ywVBmAKAKaH .label text,#mermaid-svg-7SBD3ywVBmAKAKaH span{fill:#333;color:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH .node rect,#mermaid-svg-7SBD3ywVBmAKAKaH .node circle,#mermaid-svg-7SBD3ywVBmAKAKaH .node ellipse,#mermaid-svg-7SBD3ywVBmAKAKaH .node polygon,#mermaid-svg-7SBD3ywVBmAKAKaH .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-7SBD3ywVBmAKAKaH .rough-node .label text,#mermaid-svg-7SBD3ywVBmAKAKaH .node .label text,#mermaid-svg-7SBD3ywVBmAKAKaH .image-shape .label,#mermaid-svg-7SBD3ywVBmAKAKaH .icon-shape .label{text-anchor:middle;}#mermaid-svg-7SBD3ywVBmAKAKaH .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-7SBD3ywVBmAKAKaH .rough-node .label,#mermaid-svg-7SBD3ywVBmAKAKaH .node .label,#mermaid-svg-7SBD3ywVBmAKAKaH .image-shape .label,#mermaid-svg-7SBD3ywVBmAKAKaH .icon-shape .label{text-align:center;}#mermaid-svg-7SBD3ywVBmAKAKaH .node.clickable{cursor:pointer;}#mermaid-svg-7SBD3ywVBmAKAKaH .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-7SBD3ywVBmAKAKaH .arrowheadPath{fill:#333333;}#mermaid-svg-7SBD3ywVBmAKAKaH .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-7SBD3ywVBmAKAKaH .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-7SBD3ywVBmAKAKaH .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-7SBD3ywVBmAKAKaH .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-7SBD3ywVBmAKAKaH .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-7SBD3ywVBmAKAKaH .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster text{fill:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH .cluster span{color:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH 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-7SBD3ywVBmAKAKaH .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-7SBD3ywVBmAKAKaH rect.text{fill:none;stroke-width:0;}#mermaid-svg-7SBD3ywVBmAKAKaH .icon-shape,#mermaid-svg-7SBD3ywVBmAKAKaH .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-7SBD3ywVBmAKAKaH .icon-shape p,#mermaid-svg-7SBD3ywVBmAKAKaH .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-7SBD3ywVBmAKAKaH .icon-shape .label rect,#mermaid-svg-7SBD3ywVBmAKAKaH .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-7SBD3ywVBmAKAKaH .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-7SBD3ywVBmAKAKaH .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-7SBD3ywVBmAKAKaH :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 6041 HTTP/WS
6030 私有协议
6030 原生协议
6041 上报
6041
6041
客户端

JDBC-WS / REST / C# / Python
taosAdapter
客户端

taos shell / JDBC 原生
taosd
taosKeeper
taosExplorer
Grafana / Telegraf / collectd / Prometheus

关键结论：

  1. 6041 通不了 ≠ taosd 挂了。 6041 属于 taosAdapter，6030 属于 taosd。判断故障先看端口。
  2. taosAdapter 只是"翻译层" ，它自己不存数据。上游 taosd 出问题，6041 一样会报错（典型就是 C1 的 Sync leader is restoring）。
  3. 日志也要分开看 ：6030 的问题看 taosdlog，6041 的问题看 taosadapterlog，都在 /var/log/taos。
text 复制代码 
客户端 6041 请求
   │  ① taosAdapter 进程在跑吗？端口 LISTEN 吗？
   ▼
taosAdapter
   │  ② 配置对吗？（port / taosConfigDir / root 密码 / TLS）
   │  ③ 资源够吗？（内存 / CPU / 连接池）
   ▼
taosd（通过 6030）
   │  ④ taosd 进程在跑吗？集群健康吗？（Sync leader restoring？）
   ▼
taosKeeper（通过 6043）
      ⑤ 只影响监控上报，不影响读写

2.2 根因归类

类别 说明 对应症状
① taosAdapter 未启动 / 崩溃 容器没带 adapter、进程被 OOM 杀掉、不定时崩溃 A1 A2 B1 B6 D4 E1
② 端口问题 未映射、被占用、防火墙未放行、改端口未同步 A2 E1 E2 E6
③ 配置不一致 taosadapter.toml 的 port / taosConfigDir 指向的 taos.cfg / root 密码 B5 E2 E3 E8
④ 上游 taosd 异常 Sync leader is restoring、mnode 切换、taosd 挂掉 B2 C1 C2
⑤ 依赖组件异常 taosKeeper（6043）未启动 C3 C4 C5
⑥ 网络中间层 Nginx WS 升级头缺失、超时过短、多地址/负载均衡配置错误 A4 A7 A8 E4
⑦ 客户端用法错误 6041 当 6030 用、驱动类选错、多地址格式错 A9 A10 E5 E6
⑧ 资源耗尽 内存暴涨、CPU 100%、连接数失控 D1 D2 D3 D5
⑨ 版本不匹配 taosAdapter 必须与 TDengine Server 同版本 各类兼容性异常

三、先搞懂 taosAdapter：它是什么、端口怎么分、日志在哪

上一节反复提到 taosAdapter。这一节把它讲清楚------社区里 6041 相关的困惑，一半源于不清楚 taosAdapter 是个独立进程。

3.1 taosAdapter 是什么

  • 它是 TDengine 服务端软件的一部分 ，随 TDengine Server 一起安装，不需要额外安装步骤。
  • 它对外提供 RESTful 与 WebSocket 两种 HTTP 系接入能力，是 6041 端口的"主人"。
  • 它是一个独立的进程 （taosadapter），有独立的配置文件 （/etc/taos/taosadapter.toml）和独立的日志 （/var/log/taos/taosadapterlog*）。
  • 它支持分离部署：可以装在与 taosd 不同的服务器上。
  • 它通过本机的 taos.cfg 找到要连接的 taosd（配置项 taosConfigDir，默认 /etc/taos）。

3.2 端口清单（别只记 6041）

端口 协议 归属 用途
6030 TCP taosd 原生接口（taosc）
6041 TCP taosAdapter RESTful + WebSocket
6043 TCP taosKeeper 监控上报接收
6044 TCP/UDP taosAdapter StatsD 写入
6045 TCP/UDP taosAdapter collectd 写入
6046 TCP taosAdapter OpenTSDB TELNET 写入
6047 TCP taosAdapter collectd 走 OpenTSDB TELNET
6048 TCP taosAdapter icinga2 走 OpenTSDB TELNET
6049 TCP taosAdapter tcollector 走 OpenTSDB TELNET
6060 TCP taosExplorer Web 管理界面

所以排查 6041 时，6030、6043、6044--6049 也要一起看 ------它们都可能因为同一个 taosAdapter 进程而一起失效。推荐防火墙一次性放行 6030--6070/TCP（StatsD/collectd 另需 UDP）。

3.3 三个关键配置项

配置项 默认值 作用
port 6041 taosAdapter 对外提供 HTTP/WS 服务的端口
taosConfigDir /etc/taos 从哪个目录加载 taos.cfg（决定它连哪个 taosd）
debug true 是否开启 pprof 调试（/debug/pprof），生产建议设 false

补充（稳定性相关）：

  • pool.maxConnect：连接池最大连接数，默认 2 × CPU 核心数 ，建议保持默认。
  • pool.maxIdle：最大空闲连接数，默认与 maxConnect 相同。
  • logLevel：panic / fatal / error / warn / info / debug / trace，默认 info。

配置文件优先级：命令行参数 > 环境变量 > 配置文件 。用法形如 taosadapter -p=30000 --debug=true。

3.4 查看日志与状态

bash 复制代码 
# 服务状态
systemctl status taosadapter

# 进程与端口（最常用的两条）
ps -ef | grep taosadapter
netstat -anlp | grep 6041        # 或 ss -lntp | grep 6041

# 日志（默认目录）
ls -l /var/log/taos/taosadapterlog*
tail -200 /var/log/taos/taosadapterlog

# 容器内部
docker exec -it <container> bash -c "ps -ef | grep taosadapter; netstat -anlp | grep 6041"

3.5 动态调整日志级别（排障利器）

从 3.3.5.0 起，可以不改配置文件、不重启服务就调日志级别：

bash 复制代码 
curl --location --request PUT 'http://127.0.0.1:6041/config' \
  -u root:taosdata \
  --data '{"log.level": "debug"}'

排查完成后记得调回 info，否则日志量会很大。

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

第 1 步：先确认"我走的是哪条路"

你用的方式 端口 出问题看哪个日志
taos shell、jdbc:TAOS://、ODBC/Python/Go 原生 6030 taosdlog
jdbc:TAOS-WS://、jdbc:TAOS-RS://、curl REST、Grafana、taosExplorer 6041 taosadapterlog
taosdump / taosBenchmark 6030 taosdlog

⚠️ 这一步能挡掉大量误判。例如 taosdump -P 6041 卡死、jdbc:TAOS://...:6041 报 No suitable driver，本质都是端口与协议用错，不是 taosAdapter 的锅。

第 2 步：进程与端口

bash 复制代码 
systemctl status taosadapter
ps -ef | grep taosadapter
ss -lntp | grep -E '6041|6043|6044'
  • 进程不存在 → 启动：sudo systemctl start taosadapter
  • 进程在但 6041 没有 LISTEN → 配置的 port 不是 6041，或被占用
  • 检查端口占用：ss -lntp | grep <port> / lsof -i:<port>

第 3 步：本机自测（区分"服务问题"还是"网络问题"）

bash 复制代码 
# ① REST 是否可用
curl -u root:taosdata -d "show databases" http://127.0.0.1:6041/rest/sql

# ② WebSocket 是否可用（taos 内置 WS 客户端）
taos -Z 1 -h 127.0.0.1 -P 6041 -s "show dnodes;"

# ③ 健康检查端点（容器 / K8s 探针常用，视版本支持）
curl -i http://127.0.0.1:6041/-/ping
  • 本机通、远程不通 → 网络 / 防火墙 / 端口映射问题
  • 本机也不通 → taosAdapter 或上游 taosd 问题

第 4 步：顺链路上溯到 taosd

bash 复制代码 
# taosd 是否正常运行
systemctl status taosd
taos -h 127.0.0.1 -s "show dnodes;"

# 集群健康（排查 Sync leader restoring 的关键）
taos -h 127.0.0.1 -s "show vgroups;"

注意 ：如果在 taosadapterlog 里看到：

text 复制代码 
stmt2 execute callback error, code:-2147481324, err:success, action:stmt2_exec

把 -2147481324 换成十六进制就是 0x80000914 = Sync leader is restoring ------ 这是切主后新 leader 正在重演日志 ，根因在 taosd / 集群，不在 taosAdapter。处理方式是等恢复 + 检查集群状态，而不是反复重启 adapter。

第 5 步：检查依赖组件 taosKeeper（6043）

bash 复制代码 
systemctl status taoskeeper
ss -lntp | grep 6043

日志里的这类报错：

text 复制代码 
upload to keeper error, err:Post "http://127.0.0.1:6043/adapter_report": dial tcp 127.0.0.1:6043: connect: connection refused

只代表 taosKeeper 没启动，不影响数据读写 ，只会丢监控数据。启动 taoskeeper 即可。

第 6 步：检查配置与版本

bash 复制代码 
# taosAdapter 版本
taosadapter -V
# taosd 版本
taos -h 127.0.0.1 -s "select server_version();"
# 配置
cat /etc/taos/taosadapter.toml

铁律：taosAdapter 必须与 TDengine Server 同版本 ，且升级 taosAdapter 的正确方式是升级它所在的 TDengine Server，不能单独升级。

第 7 步：检查客户端链路（远程才失败时）

bash 复制代码 
# 端口连通性
nc -vz <host> 6041
# Windows
Test-NetConnection -ComputerName <host> -Port 6041

若中间有 Nginx，重点检查 WebSocket 升级头与超时（见场景 6）。

第 8 步：检查资源与稳定性

bash 复制代码 
# 内存 / CPU 占用
top -Hp $(pgrep taosadapter)
ps -o pid,rss,vsz,pcpu,pmem,cmd -p $(pgrep taosadapter)

# taosAdapter 与 taosd 的连接数（正常应接近 CPU*2，不该上千）
ss -tnp | grep 6030 | wc -l

第 9 步：提高日志级别再复现

bash 复制代码 
curl --location --request PUT 'http://127.0.0.1:6041/config' \
  -u root:taosdata --data '{"log.level": "debug"}'
# 复现问题后
tail -300 /var/log/taos/taosadapterlog
# 记得调回
curl --location --request PUT 'http://127.0.0.1:6041/config' \
  -u root:taosdata --data '{"log.level": "info"}'

五、典型场景实操

场景 1：6041 突然不通，日志刷 code:-2147481324

现象 ：数据库突然不可用，taosAdapter 日志刷 stmt2 execute callback error, code:-2147481324 与 result is nil, action:fetch_raw_block。

原因 ：-2147481324 = 0x80000914 = Sync leader is restoring 。发生了 mnode/vnode 切主，新 leader 正在重演日志，此时请求会被拒绝。根因在 taosd，不在 taosAdapter。

操作：

bash 复制代码 
# ① 不要急着重启 taosAdapter，先看集群状态
taos -h 127.0.0.1 -s "show vgroups;"
taos -h 127.0.0.1 -s "show dnodes;"

# ② 看 taosd 日志，确认切主/重演进度
tail -300 /var/log/taos/taosdlog

# ③ 等 leader 重演完成（通常几十秒到几分钟），服务自动恢复
# ④ 如果长时间不恢复，检查节点是否宕机、网络是否分区

要点 ：这类错误是瞬时可自愈的。客户端应开启自动重连与重试，而不是把 taosAdapter 重启当解决方案。

场景 2：taosAdapter 没起来（含容器场景）

现象：6041 完全无响应；Docker 部署时"为什么不自带 taosadapter"。

操作：

bash 复制代码 
# 非容器
sudo systemctl start taosadapter
sudo systemctl status taosadapter

# 容器：进入容器检查
docker exec -it <container> bash
ps -ef | grep taosadapter
# 容器内手动启动
taosadapter &

容器注意事项：

  • 官方镜像通过环境变量控制组件启停，TAOS_DISABLE_ADAPTER（默认 0，即启动）。
  • 端口必须映射，否则宿主机访问不到：
bash 复制代码 
docker run -d --name tdengine -h tdengine \
  -p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6060:6060 \
  -p 6044-6049:6044-6049 -p 6044-6045:6044-6045/udp \
  -v /data/taos/data:/var/lib/taos \
  -v /data/taos/log:/var/log/taos \
  -v /data/taos/cfg:/etc/taos \
  tdengine/tsdb:3.4.1.6
  • 修改容器内配置文件不生效时，用挂载 而不是 docker exec 改文件：
bash 复制代码 
-v /data/taos/cfg/taosadapter.toml:/etc/taos/taosadapter.toml:ro

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

现象 ：把 taosadapter.toml 的 port 改成 11041，结果所有 HTTP 接入都不通。

原因 ：taosAdapter 的端口被改，但下游依赖方没同步------taosKeeper 上报、taosExplorer、客户端连接串、防火墙规则都还指向 6041。

操作（改端口必须同步这 5 处）：

bash 复制代码 
# ① taosadapter.toml
port = 11041

# ② taoskeeper.toml（keeper 上报指向 adapter 的端口，注意区分监听/上报）
# ③ explorer.toml
# ④ 客户端连接串
jdbc:TAOS-WS://host:11041/db
# ⑤ 防火墙
sudo firewall-cmd --permanent --add-port=11041/tcp && sudo firewall-cmd --reload

# ⑥ 重启全部相关服务
sudo systemctl restart taosd taosadapter taoskeeper taos-explorer

建议：生产环境尽量沿用默认端口，确需变更时一次性改全所有组件。

场景 4：taosAdapter 内存 / CPU 持续增长

现象 ：内存涨到 3G / 6G / 30G 不释放；CPU 100%；写入耗时从 2 秒涨到 100 多秒；taosAdapter 与 taosd 之间连接数上千（远超 CPU × 2）。

原因（按概率）

  1. 连接未被有效复用，连接池/线程数失控（D3）。
  2. 大量无模式（Schemaless）/ WS 写入，adapter 侧解析开销大（D2）。
  3. 高并发大查询（如多线程 union all 拼 500 个子句），内存飙升后崩溃（D5）。

操作：

bash 复制代码 
# ① 确认连接数
ss -tnp | grep 6030 | wc -l
# ② 确认资源占用
top -Hp $(pgrep taosadapter)
toml 复制代码 
# taosadapter.toml ------ 连接池保持默认即可
[pool]
maxConnect = 0   # 0 表示默认 2*CPU，建议不要手改大
maxIdle = 0

# 关闭 pprof 暴露
debug = false

客户端侧优化：

  • 复用连接 / Statement 对象，不要频繁创建（参考 TOP1 场景 6）。
  • 应用侧配置连接池上限，避免请求量放大。
  • 避免单条 SQL 拼过大的 union all / 超大 IN 列表，拆批执行。
  • 无模式写入量大时，评估改用 SQL/Stmt 批量写入。

服务端侧：

  • 若为已知缺陷导致的内存不释放，升级到最新版本。
  • 内存紧张时配置 SWAP，并对 taosAdapter RSS 做监控告警。

场景 5：taosAdapter 与 taosd 分离部署

现象：taosadapter 和 taosd 在不同服务器上，找不到配置 taosd 地址的地方，连接不到远端。

原因 ：taosAdapter 没有独立的"taosd 地址"配置项 ，它是通过加载 taos.cfg（firstEp 等）来确定要连哪个 taosd 的。

操作：

bash 复制代码 
# 在 taosAdapter 所在服务器上，准备好 taos.cfg
sudo mkdir -p /etc/taos
sudo tee /etc/taos/taos.cfg <<'EOF'
firstEp   <taosd所在节点的FQDN>:6030
serverPort 6030
EOF
toml 复制代码 
# taosadapter.toml
taosConfigDir = "/etc/taos"     # 指向上面这个目录

要点：

  • 该服务器上的 /etc/hosts 必须能解析 taosd 集群全部节点的 FQDN（参见 TOP1 第三节）。
  • taosAdapter 所在服务器也必须安装完整的 TDengine（不能只拷一个二进制）。
  • 多副本集群可部署多个 taosAdapter 实例做水平扩展与容灾。

场景 6：Nginx 反向代理 6041

现象 ：WebSocket handshake error, code: 400 Bad Request，或连接一段时间后自动断开。

操作（正确的 Nginx 配置）：

nginx 复制代码 
http {
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    server {
        listen 6041;

        location ~* {
            proxy_pass http://dbserver;      # 后端 taosAdapter 集群
            proxy_http_version 1.1;          # 必须
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;

            # 长连接必须调大超时，否则会被 Nginx 提前掐断
            proxy_read_timeout 3600s;
            proxy_send_timeout 3600s;
            proxy_connect_timeout 60s;
            proxy_next_upstream error http_502 non_idempotent;
        }
    }
}

要点：

  • proxy_http_version 1.1 + Upgrade / Connection 头是 WebSocket 的必要条件，缺一个就会 400。
  • 超时必须调大，否则 WS 长连接会被周期性断开（症状 A5 / A7）。
  • 多实例后端用 upstream 做负载均衡（见场景 7）。

场景 7：多实例 + JDBC 多地址

现象：Nginx + taosAdapter 多实例，但 taosd 负载严重不均衡；或 JDBC 多地址连不上、单节点可以。

关键点：
#mermaid-svg-bCZAcfGxuUkPvr6n{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-bCZAcfGxuUkPvr6n .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bCZAcfGxuUkPvr6n .error-icon{fill:#552222;}#mermaid-svg-bCZAcfGxuUkPvr6n .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bCZAcfGxuUkPvr6n .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bCZAcfGxuUkPvr6n .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bCZAcfGxuUkPvr6n .marker.cross{stroke:#333333;}#mermaid-svg-bCZAcfGxuUkPvr6n svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bCZAcfGxuUkPvr6n p{margin:0;}#mermaid-svg-bCZAcfGxuUkPvr6n .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster-label text{fill:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster-label span{color:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster-label span p{background-color:transparent;}#mermaid-svg-bCZAcfGxuUkPvr6n .label text,#mermaid-svg-bCZAcfGxuUkPvr6n span{fill:#333;color:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n .node rect,#mermaid-svg-bCZAcfGxuUkPvr6n .node circle,#mermaid-svg-bCZAcfGxuUkPvr6n .node ellipse,#mermaid-svg-bCZAcfGxuUkPvr6n .node polygon,#mermaid-svg-bCZAcfGxuUkPvr6n .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bCZAcfGxuUkPvr6n .rough-node .label text,#mermaid-svg-bCZAcfGxuUkPvr6n .node .label text,#mermaid-svg-bCZAcfGxuUkPvr6n .image-shape .label,#mermaid-svg-bCZAcfGxuUkPvr6n .icon-shape .label{text-anchor:middle;}#mermaid-svg-bCZAcfGxuUkPvr6n .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bCZAcfGxuUkPvr6n .rough-node .label,#mermaid-svg-bCZAcfGxuUkPvr6n .node .label,#mermaid-svg-bCZAcfGxuUkPvr6n .image-shape .label,#mermaid-svg-bCZAcfGxuUkPvr6n .icon-shape .label{text-align:center;}#mermaid-svg-bCZAcfGxuUkPvr6n .node.clickable{cursor:pointer;}#mermaid-svg-bCZAcfGxuUkPvr6n .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bCZAcfGxuUkPvr6n .arrowheadPath{fill:#333333;}#mermaid-svg-bCZAcfGxuUkPvr6n .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bCZAcfGxuUkPvr6n .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bCZAcfGxuUkPvr6n .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bCZAcfGxuUkPvr6n .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bCZAcfGxuUkPvr6n .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bCZAcfGxuUkPvr6n .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster text{fill:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n .cluster span{color:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n 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-bCZAcfGxuUkPvr6n .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bCZAcfGxuUkPvr6n rect.text{fill:none;stroke-width:0;}#mermaid-svg-bCZAcfGxuUkPvr6n .icon-shape,#mermaid-svg-bCZAcfGxuUkPvr6n .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bCZAcfGxuUkPvr6n .icon-shape p,#mermaid-svg-bCZAcfGxuUkPvr6n .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bCZAcfGxuUkPvr6n .icon-shape .label rect,#mermaid-svg-bCZAcfGxuUkPvr6n .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bCZAcfGxuUkPvr6n .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bCZAcfGxuUkPvr6n .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bCZAcfGxuUkPvr6n :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 客户端
Nginx / 负载均衡

listen 6041
taosAdapter A

:6041
taosAdapter B

:6041
taosAdapter C

:6041
TDengine 集群

:6030

  • WebSocket 是长连接 ，一旦建立就固定在某个 adapter 上，因此多 worker / 多实例下容易负载不均 。需要在 Nginx 侧确认 upstream 的均衡策略与 worker 配置。
  • JDBC WebSocket 支持在 URL 中写多个端点 （注意：仅 WebSocket 支持多地址，端口是 6041，不是 6030）：
java 复制代码 
jdbc:TAOS-WS://host1:6041,host2:6041,host3:6041/db?user=root&password=taosdata
  • 原生连接（jdbc:TAOS://）多地址格式不同，端口用 6030，不要与 WS 混用。
  • 建议在 JDBC URL 中显式开启自动重连：
java 复制代码 
jdbc:TAOS-WS://host1:6041,host2:6041/db?user=root&password=xxx&enableAutoReconnect=true

注意：密码中若含 @ 等特殊字符，在 URL 中需要 URL 编码 （如 @ → %40）。

场景 8：日志刷 6043 connection refused 或 [::1]:6041 connection refused

现象 A ：upload to keeper error ... dial tcp 127.0.0.1:6043: connect: connection refused

→ taosKeeper 没启动。虽不影响读写，但监控数据会丢。

bash 复制代码 
sudo systemctl start taoskeeper
ss -lntp | grep 6043

现象 B ：Post "http://localhost:6041/rest/sql/log?req_id=...": dial tcp [::1]:6041: connect: connection refused

→ 注意 [::1]！这是 IPv6 回环地址 。localhost 被解析到了 IPv6，而 taosAdapter 只监听 IPv4（或反之），导致"看起来在连本机却连不上"。

处理：

bash 复制代码 
# ① 确认 adapter 实际监听情况
ss -lntp | grep 6041

# ② 统一把 localhost 换成 127.0.0.1
#    修改 taoskeeper.toml / 其他组件配置中的 host 配置

# ③ 检查 /etc/hosts，避免 localhost 同时映射到 IPv4 与 IPv6 造成的歧义

taosAdapter 自 3.3.6.13 起支持 IPv6，会同时监听 IPv4 与 IPv6。若你使用更早版本且环境启用了 IPv6，就很容易踩到这个坑（社区有大量此类案例，容器内尤其常见）。

场景 9：安全加固（6041 暴露面）

现象 ：安全扫描报告 http://xxxxxx:6041/debug/pprof/ 为中危漏洞。

操作：

toml 复制代码 
# taosadapter.toml
debug = false       # 关闭 pprof 调试端口
bash 复制代码 
sudo systemctl restart taosadapter
# 验证
curl -i http://127.0.0.1:6041/debug/pprof/   # 期望 404

其他加固建议：

  • 修改 root 默认密码；taosAdapter 配置中的密码要同步更新（3.3.6.6+ 支持 TAOS_ROOT_PASSWORD，3.3.8.8+ 支持 TAOS_ROOT_PASSWORD_FILE）。
  • 生产环境启用 HTTPS/WSS（企业版支持，配置 [ssl] 段）。
  • 6041 不要直接暴露公网，前面加 Nginx 或网关做访问控制。

六、错误码 / 日志关键字速查

错误码 / 关键字 报错文本 真实含义 处理方向
0x231D can't create connection with server within 与 taosAdapter 连接超时 检查 6041 / Nginx / 网络
0x231E failed to complete the task within the specified time WS 请求处理超时 调大 messageWaitTimeout，或检查 taosAdapter
0xF005（61445） WebSocket Connection Failed 所有候选地址都建不起 WS 连接 检查 taosAdapter 是否退出
0x80000914（-2147481324） Sync leader is restoring 切主后日志重演中 检查集群状态，等待恢复
0x2354 JNI connection is NULL 连接已关闭 检查连接生命周期
code: 11（0xB） REST 返回 Unable to establish connection 上游 taosd 不可用 见 TOP1
0x73a Query memory exhausted 查询内存耗尽 收敛查询范围 / 调内存参数
connection refused（6043） upload to keeper error taosKeeper 未启动 启动 taoskeeper（不影响读写）
[::1]:6041 connection refused dial tcp [::1]:6041 IPv6/IPv4 监听不一致 把 localhost 换成 127.0.0.1
read: connection reset by peer 无 adapter 被打爆或重启 检查资源与稳定性
read timed out 无 adapter 假死 重启 adapter + 排查根因

日志文件对照

日志 路径 对应端口
taosadapterlog* /var/log/taos/ 6041 / 6044--6049
taosdlog* /var/log/taos/ 6030
taoskeeperlog* /var/log/taos/ 6043
taoslog*（客户端） /var/log/taos/ 客户端侧

七、预防清单

部署与运维阶段做好这些，可以避免大部分 6041 问题：

  • 区分端口职责：6030 = taosd，6041 = taosAdapter，6043 = taosKeeper，排障别串线。
  • 防火墙一次性放行 6030--6070/TCP（StatsD/collectd 另需 UDP），避免逐个端口踩坑。
  • 容器部署端口全部映射 ，且配置文件用挂载 而不是 docker exec 改。
  • taosAdapter 与 TDengine Server 版本保持一致，通过升级 Server 来升级 adapter。
  • 生产环境 debug = false，关闭 pprof 暴露面。
  • pool.maxConnect / maxIdle 保持默认（2 × CPU），不要盲目调大。
  • 客户端复用连接与 Statement，并配置连接池上限与自动重连。
  • Nginx 反代必须配 proxy_http_version 1.1 + Upgrade 头 + 大超时。
  • 分离部署时，adapter 所在服务器的 /etc/taos/taos.cfg 与 /etc/hosts 都要配好。
  • 监控 taosAdapter 的 RSS / CPU / 连接数，设置阈值告警。
  • 修改任何端口，同步 5 处 ：taosadapter.toml、taoskeeper.toml、explorer.toml、客户端连接串、防火墙。
  • 统一使用 127.0.0.1 而非 localhost，规避 IPv4/IPv6 解析歧义。

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

text 复制代码 
【TDengine 使用环境】生产 / 预生产 / 测试 / PoC
【TDengine 版本】服务端：x.x.x.x   taosAdapter：x.x.x.x   客户端/驱动：x.x.x.x
【操作系统及版本】CentOS 7.9 / Ubuntu 22.04 / Windows 11 ...
【部署方式】容器 / 非容器；taosAdapter 与 taosd 是否同机
【集群节点数】___    【集群副本数】___
【接入方式】REST 6041 / WebSocket 6041 / JDBC-WS / JDBC-RS / Grafana / taosExplorer
【报错完整文本】（不要只截图，把文字贴出来）
【复现步骤】做过哪些操作
【已排查】
  - systemctl status taosadapter：___
  - ps -ef | grep taosadapter：___
  - ss -lntp | grep 6041：___
  - curl -uroot:taosdata 127.0.0.1:6041/rest/sql -d "show dnodes"：___
  - systemctl status taosd：___
  - taos -h 127.0.0.1 -s "show dnodes;"：___
  - taosadapter -V 与 select server_version()：___
【日志】
  - /var/log/taos/taosadapterlog（关键片段）
  - /var/log/taos/taosdlog（关键片段）
  - /etc/taos/taosadapter.toml

临时提高日志级别：

bash 复制代码 
curl --location --request PUT 'http://127.0.0.1:6041/config' \
  -u root:taosdata --data '{"log.level": "debug"}'
# 复现后记得调回 info

九、相关链接

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

相关推荐
飘羽7152 小时前
多方联动筑防线 金融宣讲护民生 ——中邮保险吉林分公司“金融教育宣传周”走进文苑社区
大数据
笃行3502 小时前
数据迁移工具 KDMS 帮我把一本糊涂账算清了
数据库
llilian_162 小时前
标准时间间隔发生器应用解决方案 脉冲发生器 时间测量仪
大数据·网络·人工智能·功能测试·单片机·嵌入式硬件·51单片机
世岩清上3 小时前
展厅数字内容同质化严重，怎样打造专属叙事风格？
大数据·前端·javascript·人工智能·html·音视频·展厅改造
涤生大数据3 小时前
有了 Java UDF，Doris 为什么还要 Python UDF
大数据
笃行3503 小时前
SQLServer数据库迁移实录：十年老系统搬上 KingbaseES，T-SQL 基本没重写
数据库
跨境卫士—小依3 小时前
2026跨境电商数据分析入门：用指标判断选品与投放是否有效
大数据·人工智能·数据分析·跨境电商·营销策略
2601_962218474 小时前
万象生鲜系统多账套隔离技术适配集团生鲜企业集团化数字化管控
大数据·运维·微服务·云原生·架构
落魄大学生之流水线上谋生计4 小时前
Java并发核心机制详解：线程池、CAS、AQS、锁升级
java·开发语言·数据库
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05【一等奖版】2026 国赛 A题 药材的烘干问题06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08人工智能（AI）发展史：详细里程碑09如何新建文件夹？ 电脑新建文件夹的4种方法10ZCode 周末送额度活动开启：3 亿 Token 免费领取