在这里插入图片描述

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

📋 目录

一、快速诊断流程图

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

二、安装部署问题

2.1 taosd 无法启动

问题现象
systemctl start taosd
# 没有反应或启动失败
systemctl status taosd
# 显示 failed 或 inactive
排查步骤

1. 查看日志

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

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

2. 常见原因及解决方案

原因 症状 解决方案
端口被占用 日志显示 “bind socket error” 检查端口 6030/6041 是否被占用：netstat -tunlp | grep 6030，关闭占用进程或修改配置文件端口
配置文件错误 启动时解析错误 检查 /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. 测试性启动

# 停止服务
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 不兼容，无法直接升级！

正确升级步骤：

# 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 小版本升级
# 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 部署问题

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

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

解决方案：

# 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)

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

快速诊断清单
# 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：网络层检查

# 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：端口检查

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

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

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

步骤 3：版本匹配检查

# 客户端版本
taos -V

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

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

步骤 4：配置检查

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

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

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

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

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

  1. 安全组规则：确保入站规则开放 6030/6041 端口（TCP + UDP）
  2. 公网 IP vs 内网 IP： 
    # 服务器配置使用内网 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

# 查看当前 hostname
hostname -f

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

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

2. 配置 hosts 文件

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

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

# ⚠️ 不要使用 127.0.0.1 或 localhost！

3. 客户端配置

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

4. 验证

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

3.3 时间不同步 (0x80000013)

问题现象
Client and server's time is not synchronized
原因

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

解决方案

1. 检查时间差

# 服务端查看时间
date

# 客户端查看时间
date

# 查看时区
timedatectl

2. 同步时间

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

# 同步时间
ntpdate pool.ntp.org

# 或使用 timedatectl
timedatectl set-ntp true

3. 设置自动同步

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

# 或使用 chronyd
systemctl enable chronyd
systemctl start chronyd

4. 统一时区

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

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

3.4 REST API 连接问题

3.4.1 连接被拒绝

检查 taosAdapter 状态：

# 检查服务状态
systemctl status taosadapter

# 检查端口
netstat -tunlp | grep 6041

# 启动 taosAdapter
systemctl start taosadapter
systemctl enable taosadapter
3.4.2 401 Unauthorized

原因：用户名或密码错误

# 测试连接
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：

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

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

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

# 重启服务
systemctl restart taosadapter

四、数据写入问题

4.1 写入慢

诊断步骤

1. 检查写入方式

-- ❌ 低效：逐条插入
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 示例
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. 检查网络延迟

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

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

4. 优化配置参数

# 编辑 /etc/taos/taos.cfg

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

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

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

4.2 写入失败

4.2.1 表不存在 (0x80000662)
-- 错误：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)
-- 错误：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)
-- 错误：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 导入
# 导入数据
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 分析查询计划

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

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

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

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

1. 时间过滤优化

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

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

2. 避免全表扫描

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

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

3. 使用时间分区查询

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

4. 合理使用聚合

-- ❌ 慢：多次查询
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 查询超时

调整超时参数
# 客户端配置
# 编辑 /etc/taos/taos.cfg

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

# 重启客户端

-- 或在 SQL 中设置
SET QUERY_TIMEOUT 1200;
优化长时间查询
-- 1. 使用流式计算代替重复查询
CREATE STREAM avg_voltage_stream 
INTO avg_voltage_result 
AS SELECT _wstart, AVG(voltage) 
FROM meters 
INTERVAL(1h);

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

5.3 内存不足

-- 错误：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 节点无法加入集群

问题现象
SHOW DNODES;
-- 新节点状态显示 "offline"
排查步骤

1. 检查网络连通性

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

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

2. 检查 FQDN 配置

# 每个节点上执行
hostname -f

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

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

3. 检查防火墙

# 集群节点之间必须开放端口
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. 清理数据目录重新加入

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

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

6.2 节点离线

检查清单
# 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 数据不均衡

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

-- 查看 vgroup 分布
SHOW VGROUPS;
手动均衡
-- 迁移 vgroup
BALANCE VGROUP;

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

七、资源使用问题

7.1 内存占用高

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

# 查看详细内存分布
cat /proc/$(pgrep taosd)/status | grep -i mem
优化配置
# 编辑 /etc/taos/taos.cfg

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

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

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

# 4. 限制查询内存
queryMemory 10240

# 重启服务
systemctl restart taosd
应用层优化
# 使用流式查询，不一次性加载所有数据
cursor = conn.cursor()
cursor.execute("SELECT * FROM big_table")

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

7.2 磁盘占用高

检查磁盘使用
# 查看数据目录大小
du -sh /var/lib/taos/*

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

1. 设置数据保留期

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

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

2. 删除过期数据

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

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

3. 压缩数据

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

4. 数据分层存储

# 企业版功能：冷热数据分离
# 配置 /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 使用率高

诊断
# 查看 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）：

# 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）：

REM 复制 taos.dll 到系统目录
copy C:\TDengine\driver\taos.dll C:\Windows\System32\
8.1.2 版本不匹配
// 确保 JDBC 版本与服务端版本匹配
<dependency>
    <groupId>com.taosdata.jdbc</groupId>
    <artifactId>taos-jdbcdriver</artifactId>
    <version>3.3.0</version>  <!-- 与服务端版本一致 -->
</dependency>

8.2 Python 连接器问题

8.2.1 安装问题
# 问题：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 导入错误
# 错误：ImportError: cannot import name 'connect'

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

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

# 2. 验证安装
python -c "import taos; print(taos.__version__)"
8.2.3 连接示例
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 问题
# 错误：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 连接示例
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 连接器问题

// 使用 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 创建订阅失败

-- 错误：Topic already exists

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

9.2 消费延迟

原因分析
  1. 消费速度慢：处理逻辑复杂
  2. 网络延迟：消费者与服务器距离远
  3. 分区不足：并发消费能力不够
优化方案
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 消息丢失

# 确保手动提交偏移量
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 节
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 内存不足 增加内存或优化查询

10.2 错误码查询方法

1. 在线查询

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

2. 命令行查询

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

3. 日志查询

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

十一、调试与诊断工具

11.1 日志分析

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

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

# 客户端日志
/var/log/taos/taoslog.0
调整日志级别
# 临时调整（立即生效，重启后失效）
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 性能监控

系统监控指标
-- 查看服务器信息
SHOW DNODES;

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

-- 查看表统计
SHOW TABLES;

-- 查看当前连接
SHOW CONNECTIONS;

-- 查看查询
SHOW QUERIES;

-- 查看流
SHOW STREAMS;

-- 查看订阅
SHOW TOPICS;
SHOW CONSUMERS;
使用 TDinsight 监控
# 安装 TDinsight
# 1. 安装 Grafana
# 2. 导入 TDinsight dashboard
# 3. 配置数据源指向 TDengine

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

11.3 网络诊断

TDengine 内置网络测试
# 服务器端启动测试（监听模式）
taosd -k

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

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

11.4 性能测试

使用 taosBenchmark
# 写入性能测试
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 常用命令速查

# 服务管理
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 提供实时分析、可视化、事件管理与报警等功能。

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

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

更多推荐

JupyterLab实现医疗推理数据集Llama4Scout的4-bit量化、LoRA低秩适配、SFT有监督微调|轻量化适配

大模型显存不足问题：采用4-bit量化技术对模型进行降显存处理，同时结合多GPU分布式加载，将17B规模的大模型成功加载到3张H200 GPU上，彻底解决显存瓶颈；第三方库兼容问题：发现Transformers库最新版本的嵌入不匹配bug后，选择固定4.51.0版本进行安装，从根源上解决模型加载的兼容性问题，保证项目顺利开展；大模型微调算力成本过高问题：选用云GPU平台按需搭建训练环境，避免了专业

avatar 2048 AI社区
cover

店透视AI解析：智能图文视频处理

avatar 2048 AI社区
cover

深度实测“快降重”：寻找保留原意与降低AI率的完美平衡点

avatar 2048 AI社区