一、部署阶段常见问题及解决方案
1. docker entrypoint.sh 相关 bug
问题描述 ：在特定 docker-compose.yaml 文件下无法自动建立集群，原因是 Docker 镜像 entrypoint 文件 /usr/bin/entrypoint.sh 执行代码无法抓取出 FIRST_EP 信息（TDengine 3.3.6.3 版本）。
解决方案 ：需检查 taosd -C 执行结果是否正常获取 FIRST_EP，并确保 taos.cfg 中 firstEp 配置项正确指向集群首个节点的 fqdn:port，必要时手动调整脚本逻辑以正确解析 FIRST_EP。
2. 本地执行 taos 报错
问题描述 ：本地执行 taos 客户端时报错，预估是 epSet 中的 EP 的 fqdn 在本地无法解析。
解决方案 ：
- 确保所有节点（包括客户端）的
/etc/hosts文件或 DNS 服务已正确配置集群所有节点的fqdn与 IP 映射； - 避免使用
localhost或 IP 地址作为fqdn（开发环境除外），建议使用统一网段内可解析的完整域名； - 若为 Docker 环境，可通过
docker exec -it <容器名> bash进入容器执行taos命令，确保网络互通。
3. 奇怪的 SQL 报错（时间戳列无序）
问题描述 ：执行含 JOIN 条件的 SQL 时报错，原因为 TDengine 要求 JOIN 条件的时间戳列必须有序。
解决方案 ：在 SQL 语句中添加 ORDER BY ts 确保时间戳列有序。
4. 单机部署内存不足
问题描述 ：单机部署集群时，查询因内存不足报错。原因是每个节点默认预留 20% 内存（3 节点集群需预留 60%），导致单机资源紧张。
解决方案 ：通过修改 taos.cfg 中的 minAvailableMem 和 maxSessions 参数调整内存预留策略，降低单机资源占用。
5. 安装后连接报错（Unable to resolve FQDN）
问题描述 ：客户端连接 TDengine 时提示无法解析 FQDN。
解决方案 ：
- 服务端：每个节点执行
hostname -f获取完整域名，配置到taos.cfg的fqdn参数； - 客户端 / 其他节点：通过
hosts文件或 DNS 服务配置所有集群节点（含仲裁节点）的fqdn与 IP 映射； - 避免使用
localhost或 IP 地址作为fqdn（仅开发环境允许）。
6. taosd 启动异常（宕机恢复、Vnode 失败、crash）
问题描述 ：节点宕机恢复后内存占用过高、Vnode 恢复失败或启动时因磁盘满导致 crash。
解决方案 ：
- 检查磁盘空间（
df -h），清理/var/lib/taos或dataDir目录冗余文件； - 若 Vnode 恢复失败，查看
taosd日志（默认路径/var/log/taos/taosd.log）定位具体错误； - 内存过高时，调整
taos.cfg中maxSessions或cacheBlockSize限制会话和缓存大小。
7. 集群连接验证失败（show cluster alive 失败）
问题描述 ：执行 show cluster alive 提示连接失败或集群组建失败。
解决方案 ：检查以下配置：
- 端口：确保所有节点开放
6030-6042（TCP/UDP）； - 网络：各节点间
ping fqdn需通； - 时钟：节点间时间差不超过 1 秒（通过
ntp同步）； - 配置：
taos.cfg中statusInterval（状态上报间隔）、timezone（时区）等参数需一致
二、扩容阶段常见问题及解决方案
1. 新节点加入后状态为 Offline
问题描述 ：执行 CREATE DNODE '<fqdn:port>' 后，新节点在 SHOW DNODES 中显示 Offline。
解决方案 ：
- 检查节点状态 ：确认新节点
taosd已启动（systemctl status taosd）、防火墙关闭（ufw disable或firewall-cmd --add-port=6030-6042/tcp --permanent）； - 清理数据目录 ：若节点曾部署过 TDengine，需清空
/var/lib/taos目录（rm -rf /var/lib/taos/*）； - 验证域名解析 ：所有节点（含新节点）的
/etc/hosts或 DNS 需包含所有集群节点（含仲裁节点）的fqdn与 IP 映射； - 检查配置参数 ：新节点
taos.cfg中firstEp需指向集群已有节点的fqdn:port，fqdn需为自身完整域名。
三、缩容阶段常见问题及解决方案
1. 缩容操作不生效或数据丢失
问题描述 ：直接停止 taosd 进程无法完成缩容，或缩容后数据未迁移导致丢失。
解决方案 ：
- 规范缩容步骤 ：
- 执行
SHOW DNODES确认待删除节点状态为Ready； - 执行
DROP DNODE '<fqdn:port>'或DROP DNODE <dnode_id>； - 等待集群自动迁移该节点数据（时间取决于数据量及网络 / 磁盘性能）；
- 数据迁移完成后，执行
SHOW DNODES确认节点已移除； - 停止该节点
taosd服务（systemctl stop taosd）。
- 执行
- 注意事项 ：
- 缩容前确保剩余节点数 ≥ 副本数（如三副本集群至少保留 2 节点）；
- 缩容后节点若需重新加入集群，需清空
/var/lib/taos目录、重新配置taos.cfg，并执行CREATE DNODE重新加入。
四、总结
TDengine 集群部署、扩容、缩容的核心在于 网络配置（FQDN 解析、端口互通） 、 参数一致性（firstEp、fqdn、时区等） 及 操作规范性（数据迁移、节点状态检查） 。遇到问题时，优先通过日志（/var/log/taos）和 SHOW DNODES 等命令定位。