TDengine 手动部署完全指南：从单机 taosd 到高可用集群与配套服务

最新推荐文章于 2026-09-20 21:58:16 发布
原创 最新推荐文章于 2026-09-20 21:58:16 发布 · 302 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

TDengine 手动部署完全指南：从单机 taosd 到高可用集群与配套服务

【免费下载链接】tdengine TDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps. 【免费下载链接】tdengine 项目地址: https://gitcode.com/taosdata/tdengine

TDengine 支持在物理机或虚拟机上以手动方式完成集群部署，本指南以官方运维手册为主线，逐步讲解 taosd 核心服务的集群搭建、dnodes/mnodes 扩容，以及 taosAdapter、taosKeeper、taosX、taosX-Agent、taos-Explorer 等配套组件的部署方法。读完本文后，你将能够独立完成一套多节点 TDengine 集群从环境检查、配置修改、启动验证到横向扩容、高可用保障的完整实战部署，并理解 firstEp、fqdn、serverPort 等关键参数在底层源码中的真实作用。

部署前必读：taosd 与配套组件概览

在 TDengine 集群中，taosd 是最核心的服务组件，负责数据存储、查询与集群管理。整个集群的拓扑由三类角色组成：

  • dnode：数据节点，是集群的基本组成单元，承载数据的存储与计算；
  • mnode：管理节点，负责集群元数据管理与调度协调，集群创建时第一个 dnode 会自动成为 mnode；
  • vnode：存储单元，由 dnode 内的虚拟节点承担具体的数据分片。

除核心的 taosd 之外，一个生产级集群通常还需要部署若干配套组件：

组件作用参考手册
taosAdapter提供 RESTful 与 WebSocket 访问能力，是各语言连接器与数据采集代理（Telegraf、StatsD、collectd 等）接入 TDengine 的桥梁taosAdapter 参考手册
taosKeeper监控数据采集组件，是启用 TDengine 监控能力的前提taosKeeper 参考手册
taosX / taosX-Agent数据接入服务，用于将外部数据源的数据写入 TDenginetaosX 参考手册
taos-Explorer图形化管理界面，可视化地管理 TDengine 集群taos-Explorer 参考手册

部署 taosd：搭建 TDengine 集群

第一步：清理历史数据

如果用于搭建集群的物理节点上曾经安装过其他版本的 TDengine（例如 1.x / 2.x），或者残留有旧的测试数据，请先卸载旧版本并清理全部数据，避免新旧版本数据格式不一致导致集群初始化失败。这是手动部署最容易忽略、却最容易引发"疑难杂症"的一步。

第二步：检查网络环境

在正式部署前，必须对所有 dnode 所在物理节点以及应用所在物理节点的网络设置做一次彻底检查。官方手册给出了四个标准步骤：

  1. 检查主机名唯一性：在每个物理节点上执行 hostname -f，确认所有节点的主机名互不相同。应用驱动所在节点可以跳过此步骤。
  2. 检测节点间连通性：在每个物理节点上执行 ping host，其中 host 是其他物理节点的主机名。若无法 ping 通，立即排查网络与 DNS 设置——Linux 系统检查 /etc/hosts，Windows 系统检查 C:\Windows\system32\drivers\etc\hosts。网络问题会导致集群无法组建，务必彻底解决。
  3. 检测应用节点连通性：在应用运行所在的物理节点上重复上述网络检测。若网络异常，应用将无法连接 taosd 服务，此时需仔细检查应用所在节点的 DNS 设置或 hosts 文件。
  4. 检查端口：确保集群内所有主机之间能够通过 TCP 在 6030 端口上通信。

完成上述检查后，即可保证所有节点在网络层面通信顺畅，为集群的成功部署打下坚实基础。

第三步：安装 TDengine

为了保证集群内部的一致性与稳定性，所有物理节点必须安装相同版本的 TDengine。版本不一致可能导致节点之间协议不兼容而无法组网。

第四步：修改配置文件

TDengine 的默认配置文件位于 /etc/taos/taos.cfg，仓库中的 示例配置文件 给出了全部参数的完整注释，可作为配置参考。集群中所有节点的配置文件都需要修改。假设第一个启动的 dnode 的 endpoint 为 h1.tdengine.com:6030，集群相关参数配置如下：

# firstEp 是每个 dnode 首次启动后要连接的第一个 dnode
firstEp h1.tdengine.com:6030
# 必须配置为本 dnode 的 FQDN，如果本机只有一个主机名，可以注释或删除下面这行
fqdn h1.tdengine.com
# 配置本 dnode 的端口，默认为 6030
serverPort 6030

其中必须修改的参数是 firstEp 和 fqdn：对于每个 dnode，firstEp 配置应保持一致（都指向集群第一个节点），而 fqdn 必须设置为该 dnode 所在主机的主机名。其余参数除非明确知道修改原因，否则不需要改动。

从源码实现看，这几个参数在 tglobal.c 中注册：firstEp 为字符串配置（CFG_SCOPE_BOTH，即客户端与服务端均生效）；fqdn 默认取当前主机 FQDN（获取失败时回退为 localhost）；serverPort 为整型配置，取值范围 1~65056，默认值 6030。启动时 taosd 会根据 fqdn 解析 IP，若解析失败会报错（参见 tglobal.c 中 check global fqdn 相关逻辑），这再次印证了第二步网络检查的必要性。

此外，所有希望加入集群的 dnode，必须保证下表列出的集群相关参数设置完全一致，任何一项不匹配都可能导致 dnode 无法成功加入集群：

参数名含义
statusIntervaldnode 向 mnode 上报状态的间隔
timezone时区
locale系统 locale 信息及编码格式
charset字符集编码
ttlChangeOnWritettl 过期时间是否随表修改而变化

这些参数在源码中均被归类为全局（CFG_CATEGORY_GLOBAL）配置。例如 statusInterval 在 tglobal.c 中注册为取值区间 1~30 秒的整型参数，用于控制 dnode 周期性向 mnode 上报心跳与状态；timezone、locale、charset 在 tglobal.c 中注册，ttlChangeOnWrite 在 tglobal.c 中注册。这类全局参数必须在集群内保持一致，否则节点间对数据的解析与过期策略可能出现分歧。

第五步：启动第一个 dnode 并验证

按照上述步骤在 h1.tdengine.com 上启动第一个 dnode。然后在终端执行 taos 进入 TDengine CLI 程序，在其中执行 show dnodes 查看当前集群中的所有 dnode 信息：

taos> show dnodes;
 id | endpoint | vnodes|support_vnodes|status| create_time | note |
===================================================================================
 1| h1.tdengine.com:6030 | 0| 1024| ready| 2022-07-16 10:50:42.673 | |

可以看到刚启动的 dnode 节点 endpoint 为 h1.tdengine.com:6030，这个地址就是新集群的第一个 Ep（firstEp）。输出中的 support_vnodes 列对应配置项 supportVnodes（源码中注册范围为 0~1024，见 tglobal.c），表示该 dnode 支持创建的 vnode 数量上限。

第六步：添加 dnode 横向扩容

按照前述步骤在每个物理节点上启动 taosd，每个 dnode 都需要在 taos.cfg 中把 firstEp 参数配置为新集群第一个节点的 endpoint，即 h1.tdengine.com:6030。然后在第一个 dnode 所在机器上运行 taos 登录 TDengine 集群，执行如下 SQL 添加新节点：

create dnode "h2.tdengine.com:6030"

注意事项：

  • 新 dnode 的 endpoint 需要以 fqdn:port 形式放在双引号中，否则执行时会报错；
  • 请将示例中的 h2.tdengine.com:6030 替换为实际新 dnode 的 endpoint；
  • 添加完成后执行 show dnodes 查看新节点是否成功加入；
  • 如果希望加入集群的 dnode 当前处于离线状态，请参考本文"常见问题排查"一节。

在日志中，请确认输出的 dnode 的 fqdn 和端口与刚才尝试添加的 endpoint 一致。若不一致，请将其修正为正确的 endpoint。按照上述步骤即可逐一将新 dnode 加入集群，从而扩展集群规模、提升整体性能。

从源码角度看，create dnode 的执行由 mnode 上的事务机制保证一致性，相关处理位于 mndDnode.c，创建请求会记录审计日志（auditRecord(... "createDnode" ...)），便于事后追溯集群变更操作。

关于 firstEp 的三个重要事实（官方手册明确说明）：

  1. 任何已加入集群的 dnode 都可以作为后续新节点的 firstEp。firstEp 参数只在该 dnode 首次加入集群时起作用；加入后 dnode 会保存最新的 mnode endpoint 列表，此后不再依赖该参数。配置文件中的 firstEp 参数主要用于客户端连接——如果 TDengine CLI 未设置任何参数，默认会连接到 firstEp 指定的节点。
  2. 两个未配置 firstEp 参数的 dnode 启动后各自独立运行，此时无法将一个 dnode 加入另一个 dnode 组成集群。
  3. TDengine 不允许将两个独立的集群合并为一个新集群。

第七步：添加 mnode 实现高可用

创建 TDengine 集群时，第一个 dnode 会自动成为集群的 mnode，负责管理与协调整个集群。为了实现 mnode 的高可用，后续加入的 dnode 需要手动创建 mnode。请注意：

  • 一个集群最多只能创建 3 个 mnode；
  • 每个 dnode 上只能创建一个 mnode；
  • 当集群中的 dnode 数量达到或超过 3 个时，就可以为现有集群创建 mnode。

在第一个 dnode 上，先通过 taos CLI 登录 TDengine，然后执行以下 SQL：

create mnode on dnode <dnodeId>

请将示例中的 dnodeId 替换为新创建 dnode 的序号（可通过执行 show dnodes 获取）。最后执行 show mnodes 查看新创建的 mnode 是否成功加入集群。

常见问题排查：新节点一直显示 offline

在搭建 TDengine 集群的过程中，如果执行 create dnode 添加新节点后，新节点一直显示为 offline，请按以下步骤排查：

  1. 检查 taosd 服务是否正常启动：通过查看日志文件或使用 ps 命令确认新节点上的 taosd 服务已正常运行。
  2. 检查网络与防火墙：若 taosd 已启动，下一步检查新节点的网络连接是否通畅，并确认防火墙已关闭。网络问题或防火墙设置会阻止节点与集群中其他节点通信。
  3. 用 taos -h fqdn 连接新节点排查：尝试连接新节点后执行 show dnodes，观察其运行状态。如果新节点显示为一个独立的集群（即列表与主节点上看到的不一致），说明新节点可能自行形成了一个单节点集群。解决步骤如下：
    • 停止新节点上的 taosd 服务；
    • 清空新节点 taos.cfg 配置文件中 dataDir 目录（默认 /var/lib/taos）下的所有文件，这会删除该节点相关的全部数据与配置信息；
    • 重新启动新节点上的 taosd 服务，将节点重置回初始状态，即可重新加入主集群。

部署 taosAdapter：RESTful 与 WebSocket 接入层

taosAdapter 为 TDengine 集群提供 RESTful 与 WebSocket 访问能力，是各语言连接器（通过 WebSocket 协议通信）以及 Telegraf、StatsD、collectd、OpenTSDB、InfluxDB 等生态工具接入 TDengine 的关键组件，在集群中扮演非常重要的角色。关于其功能清单与配置参数的完整说明，可参见 taosAdapter 参考手册，其默认监听端口为 6041。

单实例部署

安装 TDengine 后即可使用 taosAdapter（taosAdapter 随 TDengine 服务端一同安装）。如果希望将 taosAdapter 部署到独立服务器上，则这些服务器同样需要安装 TDengine。单实例部署非常简单，具体命令与配置参数请参考 taosAdapter 参考手册。

多实例部署与负载均衡

部署多个 taosAdapter 实例的主要目的有两个：

  • 提升集群吞吐量，避免 taosAdapter 成为系统瓶颈；
  • 增强集群健壮性与高可用性，当某个实例故障时，进入业务系统的请求可自动路由到其他实例。

多实例部署时，需要解决负载均衡问题，避免部分节点过载而其他节点空闲。部署流程为：先分别部署多个单实例（每个实例的部署步骤与单实例部署完全相同），然后配置 Nginx 进行流量分发。以下是经过验证的推荐配置，只需将 endpoint 替换为实际环境中的正确地址即可（各参数含义请参考 Nginx 官方文档）：

user root;
worker_processes auto;
error_log /var/log/nginx_error.log;


events {
        use epoll;
        worker_connections 1024;
}

http {

    access_log off;

    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    server {
        listen 6041;
        location ~* {
            proxy_pass http://dbserver;
            proxy_read_timeout 600s;
            proxy_send_timeout 600s;
            proxy_connect_timeout 600s;
            proxy_next_upstream error http_502 non_idempotent;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $http_connection;
        }
    }
    server {
        listen 6043;
        location ~* {
            proxy_pass http://keeper;
            proxy_read_timeout 60s;
            proxy_next_upstream error  http_502 http_500  non_idempotent;
        }
    }

    server {
        listen 6060;
        location ~* {
            proxy_pass http://explorer;
            proxy_read_timeout 60s;
            proxy_next_upstream error  http_502 http_500  non_idempotent;
        }
    }
    upstream dbserver {
        least_conn;
        server 172.16.214.201:6041 max_fails=0;
        server 172.16.214.202:6041 max_fails=0;
        server 172.16.214.203:6041 max_fails=0;
    }
    upstream keeper {
        ip_hash;
        server 172.16.214.201:6043 ;
        server 172.16.214.202:6043 ;
        server 172.16.214.203:6043 ;
    }
    upstream explorer{
        ip_hash;
        server 172.16.214.201:6060 ;
        server 172.16.214.202:6060 ;
        server 172.16.214.203:6060 ;
    }
}

该配置中的负载均衡策略很有讲究：

  • dbserver（端口 6041，taosAdapter 服务）：使用 least_conn（最少连接）算法，配合 max_fails=0 与 proxy_next_upstream 故障转移，让请求均匀分布到各实例，任一实例故障时自动切换到健康实例，同时通过 proxy_http_version 1.1 与 Upgrade/Connection 头透传支持 WebSocket 长连接；
  • keeper（端口 6043，taosKeeper 监控服务）：使用 ip_hash，将同一客户端的请求固定路由到同一实例，保证监控上报数据的连续性与稳定性；
  • explorer（端口 6060，taos-Explorer 图形界面服务）：同样使用 ip_hash，确保浏览器会话在多个实例之间保持一致性。

部署完成后，可通过 http://<fqdn>:6041/-/ping 健康检查接口验证各实例状态（正常返回 code 200）。taosAdapter 还支持命令行参数、环境变量、配置文件三种配置方式，优先级为：命令行参数 > 环境变量 > 配置文件，默认配置文件为 /etc/taos/taosadapter.toml，例如 taosadapter -p=30000 --debug=true。

部署 taosKeeper：监控能力底座

要使用 TDengine 的监控能力，taosKeeper 是必不可少的组件。taosKeeper 负责采集集群各节点的运行指标并写入监控库，是后续可视化监控方案 TDinsight 的数据来源。其部署细节请参考 taosKeeper 参考手册，监控面板的搭建与使用请参考 TDinsight 文档。若采用多实例部署，可按上一节 Nginx 配置中的 keeper upstream 方式（端口 6043、ip_hash）进行负载均衡。

部署 taosX 与 taosX-Agent：数据接入

  • taosX：要使用 TDengine 的数据接入能力，需要部署 taosX 服务，它负责将各种外部数据源（数据库、消息队列等）的数据持续写入 TDengine。详细说明与部署方法请参考 TSDB-Enterprise 参考手册及 taosX 参考手册。
  • taosX-Agent：对于 Pi、OPC 等部分数据源，由于网络条件和数据源访问限制，taosX 无法直接访问数据源，此时需要在其附近部署一个代理服务 taosX-Agent，由它就近采集数据再转发给 taosX。详细说明与部署方法请参考 TSDB-Enterprise 参考手册及 taosX-Agent 文档。

部署 taos-Explorer：图形化管理

TDengine 提供可视化地管理 TDengine 集群的能力，要使用图形化界面，需要部署 taos-Explorer 服务。它默认监听 6060 端口，多实例场景下可按上一节 Nginx 配置中的 explorer upstream 方式进行负载均衡。详细说明与部署方法请参考 taos-Explorer 参考手册。

部署检查清单与要点总结

完成上述全部部署后，建议按以下清单做最终核对：

  1. 所有节点 hostname -f 唯一，ping 互通，6030 端口 TCP 可达；
  2. 所有节点安装相同版本 TDengine，firstEp 指向同一首个节点，各节点 fqdn 为本机主机名；
  3. statusInterval、timezone、locale、charset、ttlChangeOnWrite 等全局参数在集群内完全一致；
  4. show dnodes 显示所有 dnode 均为 ready，show mnodes 显示 mnode 数量达到预期（最多 3 个）；
  5. taosAdapter、taosKeeper、taos-Explorer 等配套组件健康检查通过（如 /-/ping 返回 200）。

手动部署是理解 TDengine 集群架构的最佳路径：通过 firstEp 的引导机制完成节点加入，通过全局参数一致性保障集群协同，再通过 mnode 多副本与 taosAdapter 多实例实现高可用。无论是用于生产环境还是学习验证，掌握本文的部署流程都能帮助你快速搭建一套稳定、可扩展的 TDengine 集群。

【免费下载链接】tdengine TDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps. 【免费下载链接】tdengine 项目地址: https://gitcode.com/taosdata/tdengine

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值