TDengine 集群部署及启动、扩容、缩容常见问题与解决方案

一、部署阶段常见问题及解决方案

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 进程无法完成缩容，或缩容后数据未迁移导致丢失。
解决方案 ：

• 规范缩容步骤 ：
  1. 执行 SHOW DNODES 确认待删除节点状态为 Ready；
  2. 执行 DROP DNODE '<fqdn:port>' 或 DROP DNODE <dnode_id>；
  3. 等待集群自动迁移该节点数据（时间取决于数据量及网络 / 磁盘性能）；
  4. 数据迁移完成后，执行 SHOW DNODES 确认节点已移除；
  5. 停止该节点 taosd 服务（systemctl stop taosd）。
• 注意事项 ：
  • 缩容前确保剩余节点数 ≥ 副本数（如三副本集群至少保留 2 节点）；
  • 缩容后节点若需重新加入集群，需清空 /var/lib/taos 目录、重新配置 taos.cfg，并执行 CREATE DNODE 重新加入。

---

四、总结

TDengine 集群部署、扩容、缩容的核心在于 网络配置（FQDN 解析、端口互通） 、 参数一致性（firstEp、fqdn、时区等） 及 操作规范性（数据迁移、节点状态检查） 。遇到问题时，优先通过日志（/var/log/taos）和 SHOW DNODES 等命令定位。