TDengine 双活(Active-Standby)高可用方案:架构、客户端 Failover 与 taosx replica 运维实战

原创2026-09-21 19:28:591,878 阅读
文章标签:数据库时序数据库大数据实时分析物联网云原生机器学习

TDengine 双活(Active-Standby)高可用方案:架构、客户端 Failover 与 taosx replica 运维实战

双活(Active-Standby)是 TDengine TSDB Enterprise 在 3.3.0.0 版本中首次发布的高可用特性,它让业务侧只看到两台服务器上的一套完整服务,并通过客户端 Failover 与 taosX 数据复制实现主备切换与数据同步。本文以官方双活方案文档为核心,结合仓库中 Java 连接器文档与 taosX 组件说明,完整讲解双活的架构原理、集群与客户端配置、约束条件、taosx replica 全量运维命令以及异常容错处理,帮助你在一台机器只有两台服务器的受限环境(或两套集群灾备场景)中快速落地一套可运维的双活系统。

双活方案概述

双活系统的定义是:业务系统中有且仅有两台服务器,其上分别部署一套 TDengine 服务,在业务层看来,这两台机器和两套服务是一个完整的系统,对其中的细节业务层不需要感知。双活中的两个节点通常被称为 Master-Slave,意为“主从”或“主备”,文档与命令输出中两者可能混用。

双活方案适用于两类典型场景:

  • 资源受限环境:因部署环境特殊性只能部署两台服务器,但又希望获得一定的服务高可用和数据高可靠;
  • 灾备场景:在两套 TDengine 集群(不限资源)之间建立主备灾备,备集群随时准备接管业务。

需要特别留意版本边界:双活是 TDengine TSDB Enterprise 特有功能,在 3.3.0.0 版本中第一次发布,建议使用最新版本;目前 3.4.x 版本暂不支持双活功能。

双活系统架构与三大关键技术

TDengine 双活系统的部署架构如下图所示。图中以一个单机版 TDengine 作为示例,但在实际部署中,图中的一个 Host 也可以被任意节点数量的 TDengine 集群代替——即双活既可以是两台单机互为备份,也可以是两个集群互为备份。

TDengine 双活系统部署架构:客户端通过 Failover 在两台 Host 之间切换,taosX 负责从主节点向从节点复制数据,数据订阅读写接口配合避免重复复制

整个双活系统涉及三个关键点,缺一不可:

  1. 客户端 Failover(主从切换):由 Client Driver 实现对双系统的 Failover,即主节点宕机时自动进行主从切换,业务无感知;
  2. 数据复制(同步通道):由 taosX 从(当前的)主节点到从节点实现数据复制,保证两端数据一致;
  3. 防循环复制(Anti-Loop):由数据订阅的写接口在写入复制过来的数据时在 WAL 中加入特殊标记,由数据订阅的读接口在读取数据时自动过滤掉带有该特殊标记的数据,避免复制回来的数据被再次当作新数据复制回去,形成 infinite loop(无限循环)。

其中 taosX 是 TDengine 官方提供的数据同步工具,负责把主节点的数据通过订阅方式拉取并写入从节点,具体组件介绍可参见 taosX 组件说明。防循环机制则借助 TDengine 数据订阅(taosX 底层即消费 WAL 的订阅机制)在写入侧打标、读取侧过滤,从协议层面保证同步链路是单向的。

集群配置

双活对 TDengine 集群本身的配置没有任何要求,即不需要为双活修改集群的副本数、仲裁或心跳等参数;但对要在双活系统之间同步的数据库的 WAL 保留时长 有一定要求:

  • WAL 保留时长越大,双活系统的容错率越高;
  • 如果备节点宕机时长超过主节点上的 WAL 保留时长,必定会导致备节点上有数据缺失;
  • 如果备节点宕机时长虽未超过主节点上的 WAL 保留时长,也有一定概率丢失数据,取决于宕机时长接近保留时长的程度以及数据同步的速度。

因此在实际部署中,应结合业务可容忍的最大宕机时间与网络/同步速度,合理设置待同步数据库的 WAL 保留时长(数据库 wal_retention_period 相关参数),把双活的容错窗口拉长。

客户端配置(Java 连接器 WebSocket 模式)

目前只有 Java 连接器在 WebSocket 连接模式下支持双活。其配置示例如下:

url = "jdbc:TAOS-WS://" + host + ":6041/?user=root&password=taosdata&varcharAsString=true";
Properties properties = new Properties();
properties.setProperty(TSDBDriver.PROPERTY_KEY_SLAVE_CLUSTER_HOST, "192.168.1.11");
properties.setProperty(TSDBDriver.PROPERTY_KEY_SLAVE_CLUSTER_PORT, "6041");
properties.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true");
properties.setProperty(TSDBDriver.PROPERTY_KEY_RECONNECT_INTERVAL_MS, "2000");
properties.setProperty(TSDBDriver.PROPERTY_KEY_RECONNECT_RETRY_COUNT, "3");
connection = DriverManager.getConnection(url, properties);

其中各配置属性及含义如下表:

属性名 含义
PROPERTY_KEY_SLAVE_CLUSTER_HOST 第二节点的主机名或者 IP,默认空
PROPERTY_KEY_SLAVE_CLUSTER_PORT 第二节点的端口号,默认空
PROPERTY_KEY_ENABLE_AUTO_RECONNECT 是否启用自动重连。仅在使用 WebSocket 连接时生效。true:启用,false:不启用。默认为 false。双活场景下请设置为 true
PROPERTY_KEY_RECONNECT_INTERVAL_MS 重连的时间间隔,单位毫秒:默认 2000 毫秒(即 2 秒);最小值为 0,表示立即重试;最大值不做限制
PROPERTY_KEY_RECONNECT_RETRY_COUNT 每节点最多重试次数:默认值为 3;最小值为 0,表示不进行重试;最大值不做限制

可以看到,双活的客户端 Failover 本质上是 WebSocket 连接层之上的“双端点 + 自动重连”机制:主连接走 jdbc:TAOS-WS://host:6041,辅节点通过 SLAVE_CLUSTER_HOST/PORT 指定;当主节点不可达时,连接器按 RECONNECT_INTERVAL_MS 的间隔、以 RECONNECT_RETRY_COUNT 为每节点重试上限自动切换到备用节点。Java 连接器对这几个重连参数的通用说明可参考 Java 连接器参考文档,其中明确这些重连参数同样只在 WebSocket 连接下生效,reconnectIntervalMs 默认 2000、reconnectRetryCount 默认 3。

约束条件

在双活场景下,应用开发和使用需要注意以下约束:

  1. 应用程序不能使用订阅接口,如果配置了双活参数会导致创建消费者失败;
  2. 不建议应用程序使用**参数绑定(PreparedStatement/参数化写入与查询)**的方式,如果使用,应用需要自己解决连接切换后的相关对象失效问题;
  3. 在双活场景下,不建议用户应用程序显式调用 use database,应该在连接参数中指定 database;
  4. 双活的两端集群必须同构,即数据库的命名和所有配置参数以及用户名密码和权限设置等完全相同;
  5. 只支持 WebSocket 连接模式。

这些约束本质上都围绕“连接切换”与“两端一致性”展开:订阅接口会与双活内部的数据同步通道冲突;参数绑定对象绑定的是具体连接,切换后句柄失效需要应用自行处理;显式 use database 会带来连接级状态,切换后难以保持一致;两端同构则保证 Failover 后业务读写的库表、权限语义完全一致。

运维命令:taosx replica 全量操作

TDengine 双活系统提供了一些运维工具,能够自动化 taosX 的配置、一键启动、重启和停止(单机环境上的)所有双活组件。所有命令均通过 taosx replica 子命令体系完成。

启动双活任务

taosx replica start

该命令用于启动双活中的数据复制任务,其所指定的两台主机上的 taosd 和 taosX 均为在线状态。启动方式有两种:

方法一:直接指定源端与目标端

taosx replica start -f source_endpoint -t sink_endpoint [database...]

在本机器所在的 taosx 服务中建立从 source_endpoint 到 sink_endpoint 的同步任务。运行成功后,将打印 replica ID 到控制台(后续记为 id)。其中输入参数 source_endpoint 和 sink_endpoint 为必须,形如 td2:6030,示例如下:

taosx replica start -f td1:6030 -t td2:6030

该示例命令会自动创建除 information_schema、performance_schema、log、audit 库之外的同步任务,并持续监听新增的数据库,当 td1 和 td2 中新增同名数据库时可自动启动新增数据库的数据复制任务。相关参数说明:

  • 可以使用 http://td2:6041 指定该 endpoint 使用 WebSocket 接口(默认是原生接口);
  • 可以使用 --new-database-checking-interval <SECONDS> 指定新增数据库的检查间隔,默认为 30 分钟;
  • 可以使用 --no-new-databases 禁用监听行为;
  • 也可以指定数据库同步:taosx replica start -f td1:6030 -t td2:6030 db1 仅创建指定的数据库同步任务,此时相当于配置了 --no-new-databases,不会开启新增数据库自动同步。

方法二:基于已有 Replica ID 追加数据库

taosx replica start -i id [database...]

使用上面已经创建的 Replica ID(id)以在该同步任务中增加其它数据库。需要注意:

  1. 多次使用该命令,不会创建重复任务,仅将所指定的数据库增加到相应任务中;
  2. replica id 在一个 taosX 实例内是全局唯一的,与 source/sink 的组合无关;
  3. 为便于记忆,replica id 为一个随机常用单词,系统自动将 source/sink 组合对应到一个词库中取得一个唯一可用单词。

查看任务状态

taosx replica status [id...]

返回当前机器上创建的双活同步任务列表和状态。可以指定一个或多个 replica id 获取其任务列表和状态。输出示例如下:

+---------+----------+----------+----------+------+-------------+----------------+
| replica | task | source   | sink     | database | status      | note           |
+---------+----------+----------+----------+------+-------------+----------------+
| a       | 2    | td1:6030 | td2:6030 | opc      | running     |                |
| a       | 3    | td2:6030 | td2:6030 | test     | interrupted | Error reason |
+---------+----------+----------+----------+------+-------------+----------------+

其中 status 列展示每个任务的运行状态(如 running、interrupted),note 列给出中断等异常情况下的错误原因。

停止双活任务

taosx replica stop id [db...]

该命令作用如下:

  1. 停止指定 Replica ID 下所有或指定数据库的双副本同步任务;
  2. 使用 taosx replica stop id1 db1 表示停止 id1 replica 下 db1 的同步任务;
  3. --no-new-databases 选项启用时,不停止新增数据库监听任务,仅停止当前同步中的数据库。

重启双活任务

taosx replica restart id [db...]

该命令作用如下:

  1. 重启指定 Replica ID 下所有或指定数据库的双副本同步任务;
  2. 使用 taosx replica restart id1 db1 仅重启指定数据库 db1 的同步任务(文档中该示例命令行原文为 start,语义为重启,实际使用时以 restart 子命令为准)。

查看同步进度

taosx replica diff id [db....]

该命令能够输出当前双副本同步任务中订阅的 Offset 与最新 WAL 的差值(不代表行数),例如:

+---------+----------+----------+----------+-----------+---------+---------+------+
| replica | database | source   | sink     | vgroup_id | current | latest  | diff |
+---------+----------+----------+----------+-----------+---------+---------+------+
| a       | opc      | td1:6030 | td2:6030 | 2         | 17600   | 17600   | 0    |
| a       | opc      | td2:6030 | td2:6030 | 3         | 17600   | 17600   | 0    |
+---------+----------+----------+----------+-----------+---------+---------+------+

输出按 vgroup(虚拟节点组)粒度展示:current 是订阅已消费到的 WAL Offset,latest 是源端最新 WAL Offset,diff 为两者差值。当 diff 为 0 时表示该 vgroup 的数据已经追平。由于它是 Offset 差值而非行数,不同 vgroup 之间的 diff 不可直接横向对比,但同一 vgroup 的 diff 随时间收敛是同步健康的标志。

删除双活任务

taosx replica remove id [--force]

删除当前所有双活同步任务。正常情况下要想删除同步任务,需要先 stop 该任务;但当 --force 启用时,会强制停止并清除任务。此外:

  • --no-new-databases 选项启用时,不会删除新增数据库同步任务,仅删除当前数据库的同步任务;
  • 当 taosX 重启后,如果删除的数据库任务对应的数据库仍然存在,则会继续创建同步任务;不重启 taosX 或者不更新双活监听任务时,也不会再新建这些数据库的同步任务。

更新双活新增数据库检查间隔

taosx replica update id --new-database-checking-interval <SECONDS>

更新双活新增数据库的检查间隔,单位为秒。该命令允许在不重启任务的前提下动态调整新增数据库的自动发现频率。

推荐使用步骤

  1. 假定在机器 A 上运行,首先使用 taosx replica start 来配置 taosX,其输入参数是待同步的源端和目标端服务器地址,在完成配置后会自动启动同步服务和任务。此处假定 taosX 服务使用标准端口,同步任务使用原生连接;
  2. 在机器 B 上的步骤相同;
  3. 在完成对两台机器的服务启动后,双活系统即可提供服务;
  4. 在已经完成配置后,如果想要再次启动双活系统,请使用 restart 子命令(而非再次 start,避免创建重复任务)。

异常情况与容错处理

双活系统的主要异常场景是宕机恢复与数据丢失的判断:

  • 如果宕机恢复时间超出 WAL 的保存时长,可能会出现丢数据的情况。此时双活系统中自带的 taosX 服务的自动数据同步无法处理;
  • 需要人工判断出哪些数据丢失,然后启动额外的 taosX 任务来复制丢失的数据。

结合前文集群配置一节可知:WAL 保留时长是双活容错窗口的上限。日常运维中应通过 taosx replica diff 持续观察各 vgroup 的同步差值,一旦出现长时间非零的 diff,就要评估是否存在接近或超过 WAL 保留时长的风险;若确认发生数据缺失,则按上述流程人工介入补齐数据,而不是依赖双活自动同步。

小结

TDengine 双活方案以“两台服务器 = 一套业务系统”为设计目标,通过 Java 连接器 WebSocket 模式的 Failover 实现主备切换,通过 taosX 的数据复制实现主备数据同步,并通过 WAL 特殊标记机制避免同步循环。落地时需要注意版本限制(Enterprise 特性、3.3.0.0+、3.4.x 暂不支持)、数据库 WAL 保留时长配置、客户端五个 Failover 相关属性,以及订阅接口、参数绑定、显式 use database 等约束条件;上线后通过 taosx replica status/diff/restart/stop/remove/update 一套命令即可完成双活任务的完整生命周期管理。

登录后查看全文
tdengine