TDengine TSDB 产品常见问题解决指南

TDengine TSDB 产品常见问题解决指南

📋 目录

一、快速诊断流程图
二、安装部署问题
三、连接问题
四、数据写入问题
五、查询性能问题
六、集群部署问题
七、资源使用问题
八、客户端连接器问题
九、数据订阅问题
十、错误码速查

一、快速诊断流程图

复制代码

遇到问题
    │
    ├─ 无法启动 taosd？
    │   └─> 参考 [二、安装部署问题](#二安装部署问题)
    │
    ├─ 无法连接数据库？
    │   └─> 参考 [三、连接问题](#三连接问题)
    │
    ├─ 写入失败或慢？
    │   └─> 参考 [四、数据写入问题](#四数据写入问题)
    │
    ├─ 查询慢或超时？
    │   └─> 参考 [五、查询性能问题](#五查询性能问题)
    │
    ├─ 集群节点异常？
    │   └─> 参考 [六、集群部署问题](#六集群部署问题)
    │
    ├─ 内存或磁盘占用高？
    │   └─> 参考 [七、资源使用问题](#七资源使用问题)
    │
    ├─ 客户端连接器报错？
    │   └─> 参考 [八、客户端连接器问题](#八客户端连接器问题)
    │
    └─ 查看详细错误码？
        └─> 参考 [十、错误码速查](#十错误码速查)

二、安装部署问题

2.1 taosd 无法启动

问题现象

bash 复制代码

systemctl start taosd
# 没有反应或启动失败
systemctl status taosd
# 显示 failed 或 inactive

排查步骤

1. 查看日志

bash 复制代码

# 查看 systemd 日志
journalctl -u taosd -n 50

# 查看 TDengine 日志
tail -f /var/log/taos/taosdlog.0

2. 常见原因及解决方案

原因	症状	解决方案
端口被占用	日志显示 "bind socket error"	检查端口 6030/6041 是否被占用：`netstat -tunlp
配置文件错误	启动时解析错误	检查 `/etc/taos/taos.cfg` 语法，尝试删除自定义配置测试
数据目录权限	"permission denied"	确保 taos 用户对 `/var/lib/taos` 有写权限：`chown -R taos:taos /var/lib/taos`
数据文件损坏	"Invalid file format"	备份后删除数据目录：`mv /var/lib/taos /var/lib/taos.bak`，重新启动
端口冲突	无法绑定监听端口	修改 `serverPort` 配置或关闭占用端口的进程

3. 测试性启动

bash 复制代码

# 停止服务
systemctl stop taosd

# 前台启动查看详细输出
/usr/bin/taosd -c /etc/taos

# 如果成功启动，按 Ctrl+C 停止，然后使用 systemctl 启动
systemctl start taosd

2.2 版本升级问题

2.2.1 从 2.x 升级到 3.x

⚠️ 重要提示 ：TDengine 3.x 与 2.x 不兼容，无法直接升级！

正确升级步骤：

bash 复制代码

# 1. 在 2.x 环境中导出数据
taosdump -o /tmp/taos_backup -A

# 2. 停止并卸载 2.x
systemctl stop taosd
apt remove tdengine  # 或 rpm -e tdengine

# 3. 备份旧数据（可选，但强烈建议）
mv /var/lib/taos /var/lib/taos.2x.bak
mv /etc/taos /etc/taos.2x.bak
mv /var/log/taos /var/log/taos.2x.bak

# 4. 安装 3.x
# 下载安装包并安装...

# 5. 导入数据到 3.x
taosdump -i /tmp/taos_backup

2.2.2 3.x 小版本升级

bash 复制代码

# 1. 备份数据（可选但推荐）
taosdump -o /tmp/backup_$(date +%Y%m%d)

# 2. 停止服务
systemctl stop taosd
systemctl stop taosadapter

# 3. 升级安装包
apt install ./TDengine-server-3.x.x-Linux-x64.deb
# 或
rpm -Uvh TDengine-server-3.x.x-Linux-x64.rpm

# 4. 启动服务
systemctl start taosd
systemctl start taosadapter

# 5. 验证版本
taos -V

2.3 Docker 部署问题

问题：容器启动后立即退出

原因：数据目录权限问题或配置错误

解决方案：

bash 复制代码

# 1. 检查容器日志
docker logs tdengine

# 2. 确保数据目录有正确权限
mkdir -p /data/taos/{data,log}
chmod -R 777 /data/taos

# 3. 正确启动容器
docker run -d \
  --name tdengine \
  -p 6030:6030 \
  -p 6041:6041 \
  -v /data/taos/data:/var/lib/taos \
  -v /data/taos/log:/var/log/taos \
  -e TZ=Asia/Shanghai \
  tdengine/tdengine:3.3.0.0

# 4. 进入容器检查
docker exec -it tdengine taos

三、连接问题

3.1 Unable to establish connection (0x8000000B)

最常见的连接问题，可能原因多样，需逐步排查。

快速诊断清单

bash 复制代码

# 1. 检查 taosd 是否运行
systemctl status taosd

# 2. 检查端口是否监听
netstat -tunlp | grep 6030

# 3. 测试网络连通性
ping <server_fqdn>
nc -vz <server_fqdn> 6030

# 4. 检查防火墙
# CentOS/RHEL
firewall-cmd --list-ports
firewall-cmd --add-port=6030/tcp --permanent
firewall-cmd --add-port=6030/udp --permanent
firewall-cmd --reload

# Ubuntu/Debian
ufw status
ufw allow 6030/tcp
ufw allow 6030/udp

详细排查步骤

步骤 1：网络层检查

bash 复制代码

# 1.1 检查服务器 FQDN
hostname -f
# 应该返回完整的域名，如 tdengine.example.com

# 1.2 检查客户端能否解析 FQDN
ping $(hostname -f)
nslookup $(hostname -f)

# 1.3 如果无法解析，添加到 hosts
echo "192.168.1.100 tdengine.example.com tdengine" >> /etc/hosts

步骤 2：端口检查

bash 复制代码

# 2.1 确认端口开放
ss -tunlp | grep -E '6030|6041'

# 2.2 测试 TCP 连接
telnet <server_ip> 6030

# 2.3 测试 UDP 连接
nc -vuz <server_ip> 6030

步骤 3：版本匹配检查

bash 复制代码

# 客户端版本
taos -V

# 服务端版本
taosd -V
# 或在 taos shell 中
SELECT server_version();

# ⚠️ 客户端和服务端版本必须完全一致！

步骤 4：配置检查

bash 复制代码

# 检查服务端 FQDN 配置
grep fqdn /etc/taos/taos.cfg

# 检查服务端端口配置
grep serverPort /etc/taos/taos.cfg

# 客户端连接时必须使用正确的 FQDN
taos -h tdengine.example.com

步骤 5：云服务器特殊检查

如果是云服务器（阿里云、腾讯云、AWS 等）：

安全组规则：确保入站规则开放 6030/6041 端口（TCP + UDP）

公网 IP vs 内网 IP ：

bash 复制代码

# 服务器配置使用内网 IP
grep firstEp /etc/taos/taos.cfg
# 应该是：firstEp your_internal_ip:6030

# 客户端连接使用公网 IP 或域名
taos -h your_public_ip

3.2 Unable to resolve FQDN (0x80000014)

问题现象

复制代码

Unable to resolve FQDN: xxx.xxx.xxx

原因

服务器 hostname 配置不正确
DNS 解析失败
/etc/hosts 配置缺失

解决方案

1. 设置正确的 FQDN

bash 复制代码

# 查看当前 hostname
hostname -f

# 如果不是 FQDN，需要修改
hostnamectl set-hostname tdengine.example.com

# 验证
hostname -f
# 应输出：tdengine.example.com

2. 配置 hosts 文件

bash 复制代码

# 编辑 /etc/hosts
vim /etc/hosts

# 添加（注意顺序很重要）
192.168.1.100 tdengine.example.com tdengine

# ⚠️ 不要使用 127.0.0.1 或 localhost！

3. 客户端配置

bash 复制代码

# 客户端机器也需要能解析服务器 FQDN
echo "192.168.1.100 tdengine.example.com" >> /etc/hosts

4. 验证

bash 复制代码

# 在各个节点上测试
ping tdengine.example.com
nslookup tdengine.example.com

3.3 时间不同步 (0x80000013)

问题现象

复制代码

Client and server's time is not synchronized

原因

客户端和服务端时间相差超过 900 秒（15 分钟）

解决方案

1. 检查时间差

bash 复制代码

# 服务端查看时间
date

# 客户端查看时间
date

# 查看时区
timedatectl

2. 同步时间

bash 复制代码

# 安装 NTP
yum install -y ntp ntpdate  # CentOS
apt install -y ntp ntpdate  # Ubuntu

# 同步时间
ntpdate pool.ntp.org

# 或使用 timedatectl
timedatectl set-ntp true

3. 设置自动同步

bash 复制代码

# 启用 NTP 服务
systemctl enable ntpd
systemctl start ntpd

# 或使用 chronyd
systemctl enable chronyd
systemctl start chronyd

4. 统一时区

bash 复制代码

# 设置为中国时区
timedatectl set-timezone Asia/Shanghai

# 或
ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

3.4 REST API 连接问题

3.4.1 连接被拒绝

检查 taosAdapter 状态：

bash 复制代码

# 检查服务状态
systemctl status taosadapter

# 检查端口
netstat -tunlp | grep 6041

# 启动 taosAdapter
systemctl start taosadapter
systemctl enable taosadapter

3.4.2 401 Unauthorized

原因：用户名或密码错误

bash 复制代码

# 测试连接
curl -u root:taosdata http://localhost:6041/rest/sql \
  -d "SELECT server_version()"

# 如果密码已修改，使用新密码
curl -u root:your_password http://localhost:6041/rest/sql \
  -d "SELECT server_version()"

3.4.3 跨域问题 (CORS)

配置 taosAdapter：

bash 复制代码

# 编辑配置文件
vim /etc/taos/taosadapter.toml

# 添加 CORS 配置
[cors]
allowAllOrigins = true

# 或指定特定域名
[cors]
allowOrigins = ["http://example.com", "https://example.com"]

# 重启服务
systemctl restart taosadapter

四、数据写入问题

4.1 写入慢

诊断步骤

1. 检查写入方式

sql 复制代码

-- ❌ 低效：逐条插入
INSERT INTO d1001 VALUES (now, 23.5, 60.2);
INSERT INTO d1002 VALUES (now, 24.1, 58.3);

-- ✅ 高效：批量写入
INSERT INTO 
  d1001 VALUES (now, 23.5, 60.2)
  d1002 VALUES (now, 24.1, 58.3)
  d1003 VALUES (now, 22.8, 61.5);

2. 使用参数绑定

python 复制代码

# Python 示例
import taos

conn = taos.connect()
stmt = conn.statement()

# 准备语句
stmt.prepare("INSERT INTO ? USING meters TAGS(?) VALUES(?, ?, ?)")

# 绑定表名和标签
stmt.set_tbname("d1001")
stmt.set_tags([("location", "California")])

# 批量绑定数据
stmt.bind_param([
    [timestamp1, timestamp2, ...],
    [current1, current2, ...],
    [voltage1, voltage2, ...]
])

stmt.execute()

3. 检查网络延迟

bash 复制代码

# 测试网络延迟
ping -c 100 <server_ip>

# 如果延迟高，考虑：
# - 使用批量写入减少网络往返
# - 部署在同一局域网或地域

4. 优化配置参数

bash 复制代码

# 编辑 /etc/taos/taos.cfg

# 增大写缓存（默认 96MB）
cache 256

# 增大并行写入线程数（默认 4）
asynclog 1

# 提交时机（默认 3000ms）
fsync 3000

4.2 写入失败

4.2.1 表不存在 (0x80000662)

sql 复制代码

-- 错误：Table does not exist

-- 解决方案 1：先创建表
CREATE TABLE IF NOT EXISTS d1001 USING meters TAGS('California', 3);

-- 解决方案 2：使用自动建表
INSERT INTO d1001 USING meters TAGS('California', 3) 
VALUES (now, 23.5, 60.2);

4.2.2 时间戳重复 (0x80000622)

sql 复制代码

-- 错误：Duplicate timestamp

-- 原因：同一张表不能有重复时间戳

-- 解决方案 1：更新而不是插入（TDengine 不支持 UPDATE）
-- 需要先删除再插入
DELETE FROM d1001 WHERE ts = '2024-01-01 10:00:00';
INSERT INTO d1001 VALUES ('2024-01-01 10:00:00', 23.5, 60.2);

-- 解决方案 2：使用毫秒或微秒精度避免冲突
INSERT INTO d1001 VALUES (now + 1s, 23.5, 60.2);

4.2.3 数据类型不匹配 (0x80000216)

sql 复制代码

-- 错误：Syntax error in SQL

-- 检查数据类型
DESC meters;

-- 确保数据类型匹配
-- 正确：
INSERT INTO d1001 VALUES (now, 23.5, 60);
-- 错误（voltage 是 INT 类型，不能插入字符串）：
INSERT INTO d1001 VALUES (now, 23.5, 'abc');

4.3 批量导入问题

使用 taosdump 导入

bash 复制代码

# 导入数据
taosdump -i /path/to/backup

# 常见问题：
# 1. 导入慢 -> 增加并发
taosdump -i /path/to/backup -T 16

# 2. 内存不足 -> 减少批量大小
taosdump -i /path/to/backup -B 1000

# 3. 跳过已存在的表
taosdump -i /path/to/backup -n

# 4. 只导入部分数据库
taosdump -i /path/to/backup -D db1,db2

五、查询性能问题

5.1 查询慢

诊断工具

1. 使用 EXPLAIN 分析查询计划

sql 复制代码

-- 查看查询执行计划
EXPLAIN SELECT * FROM meters WHERE ts > now - 1h;

-- 查看详细执行统计
EXPLAIN ANALYZE SELECT AVG(voltage) FROM meters 
WHERE ts > now - 1d GROUP BY TBNAME;

2. 检查查询是否使用索引

sql 复制代码

-- 时间索引自动使用
-- 标签索引：
EXPLAIN SELECT * FROM meters WHERE location = 'California';
-- 应该显示 "tag filter"

优化建议

1. 时间过滤优化

sql 复制代码

-- ❌ 慢：没有时间过滤
SELECT * FROM meters WHERE voltage > 200;

-- ✅ 快：添加时间范围
SELECT * FROM meters 
WHERE ts > now - 1h AND voltage > 200;

2. 避免全表扫描

sql 复制代码

-- ❌ 慢：SELECT *
SELECT * FROM meters WHERE ts > now - 1d;

-- ✅ 快：只选择需要的列
SELECT ts, voltage, current FROM meters 
WHERE ts > now - 1d;

3. 使用时间分区查询

sql 复制代码

-- 利用 TDengine 的时间分区特性
SELECT AVG(voltage) FROM meters 
WHERE ts >= '2024-01-01' AND ts < '2024-01-02'
GROUP BY TBNAME;

4. 合理使用聚合

sql 复制代码

-- ❌ 慢：多次查询
SELECT AVG(voltage) FROM d1001 WHERE ts > now - 1h;
SELECT MAX(voltage) FROM d1001 WHERE ts > now - 1h;

-- ✅ 快：一次查询多个聚合
SELECT AVG(voltage), MAX(voltage), MIN(voltage) 
FROM d1001 WHERE ts > now - 1h;

5.2 查询超时

调整超时参数

bash 复制代码

# 客户端配置
# 编辑 /etc/taos/taos.cfg

# 查询超时时间（默认 600 秒）
queryTimeout 1200

# 重启客户端

sql 复制代码

-- 或在 SQL 中设置
SET QUERY_TIMEOUT 1200;

优化长时间查询

sql 复制代码

-- 1. 使用流式计算代替重复查询
CREATE STREAM avg_voltage_stream 
INTO avg_voltage_result 
AS SELECT _wstart, AVG(voltage) 
FROM meters 
INTERVAL(1h);

-- 2. 使用连续查询
-- 3. 分段查询大数据量

5.3 内存不足

sql 复制代码

-- 错误：Out of memory

-- 原因：查询结果集过大

-- 解决方案 1：限制返回行数
SELECT * FROM meters WHERE ts > now - 1h LIMIT 10000;

-- 解决方案 2：使用聚合减少数据量
SELECT _wstart, AVG(voltage) 
FROM meters 
WHERE ts > now - 1d 
INTERVAL(1h);

-- 解决方案 3：分页查询
SELECT * FROM meters 
WHERE ts > now - 1h 
LIMIT 1000 OFFSET 0;

六、集群部署问题

6.1 节点无法加入集群

问题现象

sql 复制代码

SHOW DNODES;
-- 新节点状态显示 "offline"

排查步骤

1. 检查网络连通性

bash 复制代码

# 在各节点之间互相测试
ping node1.example.com
ping node2.example.com
ping node3.example.com

# 测试端口
nc -vz node1.example.com 6030

2. 检查 FQDN 配置

bash 复制代码

# 每个节点上执行
hostname -f

# 检查 firstEp 配置
grep firstEp /etc/taos/taos.cfg
# 应该指向第一个节点的 FQDN

# 检查 fqdn 配置
grep fqdn /etc/taos/taos.cfg
# 每个节点应该是自己的 FQDN

3. 检查防火墙

bash 复制代码

# 集群节点之间必须开放端口
firewall-cmd --add-port=6030/tcp --permanent
firewall-cmd --add-port=6030/udp --permanent
firewall-cmd --add-port=6041/tcp --permanent
firewall-cmd --reload

4. 清理数据目录重新加入

bash 复制代码

# 如果节点曾经单独组成集群
systemctl stop taosd
rm -rf /var/lib/taos/*
systemctl start taosd

# 在第一个节点上重新添加
CREATE DNODE "node2.example.com:6030";

6.2 节点离线

检查清单

bash 复制代码

# 1. taosd 进程是否运行
systemctl status taosd

# 2. 查看日志
tail -f /var/log/taos/taosdlog.0

# 3. 网络是否通畅
ping <other_nodes>

# 4. 查看集群状态
taos -h node1
SHOW DNODES;
SHOW MNODES;

常见原因

原因	解决方案
taosd 崩溃	查看日志，修复问题后重启
网络故障	修复网络，节点会自动重新加入
磁盘满	清理空间，扩容磁盘
时间不同步	同步各节点时间

6.3 数据不均衡

检查数据分布

sql 复制代码

-- 查看各节点数据量
SHOW DNODES;
-- 查看 data_size 列

-- 查看 vgroup 分布
SHOW VGROUPS;

手动均衡

sql 复制代码

-- 迁移 vgroup
BALANCE VGROUP;

-- 指定 vgroup 迁移到特定节点
-- （企业版功能）

七、资源使用问题

7.1 内存占用高

诊断

bash 复制代码

# 查看进程内存
ps aux | grep taosd
top -p $(pgrep taosd)

# 查看详细内存分布
cat /proc/$(pgrep taosd)/status | grep -i mem

优化配置

bash 复制代码

# 编辑 /etc/taos/taos.cfg

# 1. 减少缓存大小（默认 96MB）
cache 64

# 2. 减少缓存块数量（默认 3）
cacheBlockSize 3

# 3. 减少元数据缓存
pages 128

# 4. 限制查询内存
queryMemory 10240

# 重启服务
systemctl restart taosd

应用层优化

python 复制代码

# 使用流式查询，不一次性加载所有数据
cursor = conn.cursor()
cursor.execute("SELECT * FROM big_table")

# 分批处理
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break
    process_rows(rows)

7.2 磁盘占用高

检查磁盘使用

bash 复制代码

# 查看数据目录大小
du -sh /var/lib/taos/*

# 查看各数据库大小
ls -lh /var/lib/taos/vnode/

清理策略

1. 设置数据保留期

sql 复制代码

-- 创建数据库时设置
CREATE DATABASE sensor 
KEEP 365  -- 保留 365 天
UPDATE 1;  -- 可更新

-- 修改已存在的数据库
ALTER DATABASE sensor KEEP 180;

2. 删除过期数据

sql 复制代码

-- TDengine 会自动删除超过 KEEP 的数据

-- 手动删除特定时间段数据
DELETE FROM table_name WHERE ts < '2023-01-01';

3. 压缩数据

bash 复制代码

# 企业版功能：数据压缩
# 配置 /etc/taos/taos.cfg
comp 2  # 压缩等级 0-2，2 最高

4. 数据分层存储

bash 复制代码

# 企业版功能：冷热数据分离
# 配置 /etc/taos/taos.cfg

# S3 存储配置
s3Endpoint http://s3.amazonaws.com
s3AccessKey YOUR_ACCESS_KEY
s3SecretKey YOUR_SECRET_KEY
s3BucketName tdengine-data

# 超过 30 天的数据迁移到 S3
# ALTER DATABASE sensor S3_STORAGE 30;

7.3 CPU 使用率高

诊断

bash 复制代码

# 查看 CPU 使用
top -p $(pgrep taosd)

# 查看线程 CPU 使用
top -H -p $(pgrep taosd)

常见原因

原因	解决方案
大量写入	正常现象，考虑扩容或优化写入批次
复杂查询	优化 SQL，添加时间过滤，使用流式计算
元数据操作	减少频繁的建表删表操作
流式计算	优化流式计算 SQL，增加触发间隔

八、客户端连接器问题

8.1 Java JDBC 问题

8.1.1 找不到动态库

复制代码

failed to load libtaos.so (or taos.dll)

解决方案（Linux）：

bash 复制代码

# 1. 检查文件是否存在
ls -l /usr/local/taos/driver/libtaos.so*

# 2. 添加到 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/taos/driver
echo 'export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/taos/driver' >> ~/.bashrc

# 3. 或创建软链接
ln -s /usr/local/taos/driver/libtaos.so /usr/lib/libtaos.so

解决方案（Windows）：

cmd 复制代码

REM 复制 taos.dll 到系统目录
copy C:\TDengine\driver\taos.dll C:\Windows\System32\

8.1.2 版本不匹配

java 复制代码

// 确保 JDBC 版本与服务端版本匹配
<dependency>
    <groupId>com.taosdata.jdbc</groupId>
    <artifactId>taos-jdbcdriver</artifactId>
    <version>3.3.0</version>  <!-- 与服务端版本一致 -->
</dependency>

8.2 Python 连接器问题

8.2.1 安装问题

bash 复制代码

# 问题：pip install taospy 失败

# 解决方案 1：升级 pip
pip install --upgrade pip

# 解决方案 2：使用国内镜像
pip install taospy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 解决方案 3：指定版本
pip install taospy==2.7.15

8.2.2 导入错误

python 复制代码

# 错误：ImportError: cannot import name 'connect'

# 原因：包名冲突或安装不完整

# 解决方案：
# 1. 卸载重装
pip uninstall taospy
pip install taospy

# 2. 验证安装
python -c "import taos; print(taos.__version__)"

8.2.3 连接示例

python 复制代码

import taos

try:
    # 原生连接
    conn = taos.connect(
        host='localhost',
        user='root',
        password='taosdata',
        database='test'
    )
    
    cursor = conn.cursor()
    cursor.execute("SELECT server_version()")
    print(cursor.fetchall())
    
except Exception as e:
    print(f"连接失败: {e}")
finally:
    conn.close()

8.3 Go 连接器问题

8.3.1 CGO 问题

bash 复制代码

# 错误：CGO_ENABLED required

# 解决方案：启用 CGO
export CGO_ENABLED=1
export CGO_CFLAGS="-I/usr/local/taos/include"
export CGO_LDFLAGS="-L/usr/local/taos/driver -ltaos"

go build

8.3.2 连接示例

go 复制代码

package main

import (
    "database/sql"
    "fmt"
    _ "github.com/taosdata/driver-go/v3/taosRestful"
)

func main() {
    // REST 连接（推荐，无需安装客户端）
    db, err := sql.Open("taosRestful", 
        "root:taosdata@http(localhost:6041)/test")
    if err != nil {
        panic(err)
    }
    defer db.Close()
    
    rows, err := db.Query("SELECT server_version()")
    if err != nil {
        panic(err)
    }
    defer rows.Close()
    
    for rows.Next() {
        var version string
        rows.Scan(&version)
        fmt.Println("版本:", version)
    }
}

8.4 Node.js 连接器问题

javascript 复制代码

// 使用 REST 连接器（推荐）
const { options, connect } = require('@tdengine/rest');

const dsn = 'http://localhost:6041';
options.setLogLevel('debug');

async function test() {
  try {
    const conn = await connect(dsn, 'root', 'taosdata');
    const cursor = conn.cursor();
    
    await cursor.execute('SELECT server_version()');
    const data = await cursor.fetchall();
    console.log(data);
    
    await conn.close();
  } catch (err) {
    console.error('错误:', err);
  }
}

test();

九、数据订阅问题

9.1 创建订阅失败

sql 复制代码

-- 错误：Topic already exists

-- 解决方案：先删除再创建
DROP TOPIC IF EXISTS topic_meters;
CREATE TOPIC topic_meters AS SELECT * FROM meters;

9.2 消费延迟

原因分析

消费速度慢：处理逻辑复杂
网络延迟：消费者与服务器距离远
分区不足：并发消费能力不够

优化方案

python 复制代码

import taos
from taos.tmq import Consumer

# 1. 增加消费者数量（并行消费）
conf = {
    "group.id": "group1",
    "td.connect.ip": "127.0.0.1",
    "td.connect.port": "6030",
    "client.id": "client1",
    "enable.auto.commit": "true",
    "auto.commit.interval.ms": "1000"
}

consumer = Consumer(conf)
consumer.subscribe(["topic_meters"])

# 2. 批量消费
while True:
    res = consumer.poll(timeout=1.0)
    if res:
        # 批量处理
        process_batch(res)

9.3 消息丢失

python 复制代码

# 确保手动提交偏移量
conf = {
    "group.id": "group1",
    "enable.auto.commit": "false"  # 禁用自动提交
}

consumer = Consumer(conf)

while True:
    res = consumer.poll(timeout=1.0)
    if res:
        try:
            process(res)
            consumer.commit()  # 处理成功后提交
        except Exception as e:
            print(f"处理失败: {e}")
            # 不提交，下次会重新消费

十、错误码速查

10.1 高频错误码

错误码	错误信息	常见原因	解决方案
0x8000000B	Unable to establish connection	网络不通、端口未开放、版本不匹配	参考 [3.1 节](#错误码错误信息常见原因解决方案 0x8000000B Unable to establish connection 网络不通、端口未开放、版本不匹配参考 3.1 节 0x80000013 Time not synchronized 时间相差超过 15 分钟同步时间，参考 3.3 节 0x80000014 Unable to resolve FQDN FQDN 配置错误参考 3.2 节 0x80000216 Syntax error in SQL SQL 语法错误检查 SQL 语法 0x80000662 Table does not exist 表不存在先创建表或使用自动建表 0x80000622 Duplicate timestamp 时间戳重复使用更高精度或检查时间戳 0x80000213 Database not specified 未指定数据库执行 USE database_name; 0x80000600 Database already exists 数据库已存在使用 CREATE DATABASE IF NOT EXISTS 0x80FF0002 No such file or directory 文件不存在检查动态库路径 0x8000063A Out of memory 内存不足增加内存或优化查询)
0x80000013	Time not synchronized	时间相差超过 15 分钟	同步时间，参考 [3.3 节](#错误码错误信息常见原因解决方案 0x8000000B Unable to establish connection 网络不通、端口未开放、版本不匹配参考 3.1 节 0x80000013 Time not synchronized 时间相差超过 15 分钟同步时间，参考 3.3 节 0x80000014 Unable to resolve FQDN FQDN 配置错误参考 3.2 节 0x80000216 Syntax error in SQL SQL 语法错误检查 SQL 语法 0x80000662 Table does not exist 表不存在先创建表或使用自动建表 0x80000622 Duplicate timestamp 时间戳重复使用更高精度或检查时间戳 0x80000213 Database not specified 未指定数据库执行 USE database_name; 0x80000600 Database already exists 数据库已存在使用 CREATE DATABASE IF NOT EXISTS 0x80FF0002 No such file or directory 文件不存在检查动态库路径 0x8000063A Out of memory 内存不足增加内存或优化查询)
0x80000014	Unable to resolve FQDN	FQDN 配置错误	参考 [3.2 节](#错误码错误信息常见原因解决方案 0x8000000B Unable to establish connection 网络不通、端口未开放、版本不匹配参考 3.1 节 0x80000013 Time not synchronized 时间相差超过 15 分钟同步时间，参考 3.3 节 0x80000014 Unable to resolve FQDN FQDN 配置错误参考 3.2 节 0x80000216 Syntax error in SQL SQL 语法错误检查 SQL 语法 0x80000662 Table does not exist 表不存在先创建表或使用自动建表 0x80000622 Duplicate timestamp 时间戳重复使用更高精度或检查时间戳 0x80000213 Database not specified 未指定数据库执行 USE database_name; 0x80000600 Database already exists 数据库已存在使用 CREATE DATABASE IF NOT EXISTS 0x80FF0002 No such file or directory 文件不存在检查动态库路径 0x8000063A Out of memory 内存不足增加内存或优化查询)
0x80000216	Syntax error in SQL	SQL 语法错误	检查 SQL 语法
0x80000662	Table does not exist	表不存在	先创建表或使用自动建表
0x80000622	Duplicate timestamp	时间戳重复	使用更高精度或检查时间戳
0x80000213	Database not specified	未指定数据库	执行 `USE database_name;`
0x80000600	Database already exists	数据库已存在	使用 `CREATE DATABASE IF NOT EXISTS`
0x80FF0002	No such file or directory	文件不存在	检查动态库路径
0x8000063A	Out of memory	内存不足	增加内存或优化查询

10.2 错误码查询方法

1. 在线查询

访问文档：https://docs.taosdata.com/reference/error-code/

2. 命令行查询

bash 复制代码

# 查看完整错误码列表
taos
> SHOW ERRORS;

3. 日志查询

bash 复制代码

# 查看详细错误日志
tail -f /var/log/taos/taosdlog.0 | grep -i error

十一、调试与诊断工具

11.1 日志分析

日志位置

bash 复制代码

# 服务端日志
/var/log/taos/taosdlog.0       # 最新日志
/var/log/taos/taosdlog.1       # 历史日志

# taosAdapter 日志
/var/log/taos/taosadapter.log

# 客户端日志
/var/log/taos/taoslog.0

调整日志级别

bash 复制代码

# 临时调整（立即生效，重启后失效）
taos
> ALTER DNODE 1 'debugFlag' '135';  # 135=debug级别

# 永久调整
vim /etc/taos/taos.cfg
debugFlag 135  # 131=info, 135=debug, 143=trace

# 重启生效
systemctl restart taosd

# ⚠️ debug 级别会产生大量日志，生产环境使用 131

11.2 性能监控

系统监控指标

sql 复制代码

-- 查看服务器信息
SHOW DNODES;

-- 查看数据库统计
SHOW DATABASES;

-- 查看表统计
SHOW TABLES;

-- 查看当前连接
SHOW CONNECTIONS;

-- 查看查询
SHOW QUERIES;

-- 查看流
SHOW STREAMS;

-- 查看订阅
SHOW TOPICS;
SHOW CONSUMERS;

使用 TDinsight 监控

bash 复制代码

# 安装 TDinsight
# 1. 安装 Grafana
# 2. 导入 TDinsight dashboard
# 3. 配置数据源指向 TDengine

# 监控指标包括：
# - CPU、内存、磁盘使用率
# - 写入/查询 QPS
# - 慢查询分析
# - 集群节点状态

11.3 网络诊断

TDengine 内置网络测试

bash 复制代码

# 服务器端启动测试（监听模式）
taosd -k

# 客户端测试（指定服务器）
taos -n server_fqdn:6030

# 测试结果会显示网络延迟、丢包率等

11.4 性能测试

使用 taosBenchmark

bash 复制代码

# 写入性能测试
taosbenchmark -f write_test.json

# write_test.json 示例
{
  "filetype": "insert",
  "cfgdir": "/etc/taos",
  "host": "127.0.0.1",
  "port": 6030,
  "user": "root",
  "password": "taosdata",
  "databases": [{
    "dbinfo": {
      "name": "test",
      "drop": "yes"
    },
    "super_tables": [{
      "name": "meters",
      "child_table_count": 1000,
      "child_table_prefix": "d",
      "insert_rows": 10000,
      "timestamp_step": 1000,
      "start_timestamp": "2020-01-01 00:00:00.000",
      "sample_format": "csv",
      "sample_file": "./sample.csv",
      "tags_file": "",
      "columns": [
        {"type": "FLOAT", "name": "current"},
        {"type": "INT", "name": "voltage"}
      ],
      "tags": [
        {"type": "INT", "name": "groupid"},
        {"type": "BINARY", "len": 16, "name": "location"}
      ]
    }]
  }]
}

# 查看测试报告
# 会输出写入速度、延迟分布等指标

十二、最佳实践清单

12.1 安装部署

✅ 使用 FQDN 而不是 IP 地址
✅ 配置 NTP 时间同步
✅ 开放必要的防火墙端口（6030, 6041）
✅ 设置数据目录在独立磁盘
✅ 定期备份数据和配置

12.2 数据建模

✅ 一个数据采集点一张子表
✅ 合理设计超级表和标签
✅ 使用合适的数据类型
✅ 设置合理的数据保留期（KEEP）
✅ 避免过多列（建议 < 100 列）

12.3 数据写入

✅ 使用批量写入
✅ 使用参数绑定提高性能
✅ 并发写入不同的表
✅ 避免频繁建表删表
✅ 时间戳按顺序写入

12.4 数据查询

✅ 始终添加时间范围过滤
✅ 使用标签过滤减少扫描范围
✅ 只查询需要的列
✅ 合理使用聚合函数
✅ 使用 EXPLAIN 分析查询计划

12.5 运维管理

✅ 监控集群健康状态
✅ 定期检查日志
✅ 设置磁盘空间告警
✅ 定期备份数据
✅ 保持客户端与服务端版本一致

十三、获取帮助

13.1 官方资源

📘 官方文档: https://docs.taosdata.com
💬 GitHub Discussions: https://github.com/taosdata/TDengine/discussions
🐛 Issue 提交: https://github.com/taosdata/TDengine/issues
📺 视频教程: https://www.taosdata.com/blog/category/video

13.2 社区支持

💬 微信群: 扫描官网二维码加入技术交流群
📧 邮件: support@taosdata.com
🌐 技术论坛: https://github.com/taosdata/TDengine/discussions

13.3 商业支持

📞 技术支持热线: 400-890-0591
📧 企业客户: enterprise@taosdata.com
🌐 在线咨询: https://www.taosdata.com/contact

十四、附录

14.1 常用命令速查

bash 复制代码

# 服务管理
systemctl start taosd
systemctl stop taosd
systemctl restart taosd
systemctl status taosd

# 查看版本
taosd -V
taos -V

# 连接数据库
taos
taos -h hostname
taos -h hostname -P port -u user -p

# 导入导出
taosdump -o /backup -A              # 导出所有数据
taosdump -i /backup                 # 导入数据

# 性能测试
taosbenchmark -f config.json        # 自定义测试

14.2 配置参数速查

参数	默认值	说明	调优建议
cache	96	单个 vnode 写缓存大小（MB）	高并发写入增大到 256-512
blocks	3	每个 vnode 的内存块数	查询多增大到 6-8
pages	256	元数据缓存页数	表多时增大到 512-1024
maxVgroupsPerDb	0	数据库最大 vgroup 数	0=自动，手动设置建议 CPU 核数 * 2
fsync	3000	数据同步周期（ms）	要求高可靠性减小到 1000
comp	2	压缩等级（0-2）	2=最高压缩率
keep	3650	数据保留天数	根据需求设置

📞 问题反馈

如果本指南没有覆盖您遇到的问题，或者有任何建议，请通过以下方式反馈：

📧 文档反馈: docs@taosdata.com
🐛 提交 Issue: https://github.com/taosdata/TDengine/issues
💬 技术讨论: https://github.com/taosdata/TDengine/discussions

关于 TDengine

TDengine 专为物联网IoT平台、工业大数据平台设计。其中，TDengine TSDB 是一款高性能、分布式的时序数据库（Time Series Database），同时它还带有内建的缓存、流式计算、数据订阅等系统功能；TDengine IDMP 是一款AI原生工业数据管理平台，它通过树状层次结构建立数据目录，对数据进行标准化、情景化，并通过 AI 提供实时分析、可视化、事件管理与报警等功能。