Merge pull request #29258 from taosdata/fix/internal

docs: add ha

docs/zh/08-operation/18-ha/01-replica3.md

@@ -0,0 +1,68 @@
+---
+title: 三副本方案
+sidebar_label: 三副本方案
+toc_max_heading_level: 4
+---
+
+本节介绍 TDengine 三副本方案的配置与使用。
+
+TDengine 的三副本方案采用 RAFT 算法来实现数据的一致性，包括元数据和时序数据。一个虚拟节点组（VGroup）构成了一个 RAFT 组；虚拟节点组的虚拟数据节点（Vnode），便是该 RAFT 组的成员节点，也称之为副本。
+
+1. 每个 Vnode 都有自己的角色，它们可以是 Leader（领导者）、Follower（跟随者）、Candidate（候选人）。
+2. 每个 Vnode 都维护了一份连续的日志（Log），用于记录数据写入、变更、或删除等操作的所有指令。日志是由一系列有序的日志条目 (Log Entry) 组成，每个 Log Entry 都有唯一的编号（Index），用于标识日志协商或执行的进度。
+3. Leader 角色的 Vnode 提供读写服务，在故障节点不超过半数的情况下保证集群的高可用性。此外，即使发生了节点重启及 Leader 重新选举等事件后，RAFT 也能够始终保证新产生的 Leader 可以提供已经写入成功的全部完整数据的读写服务。
+4. 每一次对数据库的变更请求（比如 insert），都对应一个 Log Entry。在持续写入数据的过程中，会按照协议机制在每个成员节点上产生完全相同的日志记录，并且以相同的顺序执行数据变更操作，以 WAL 的形式存储在数据文件目录中。
+5. 只有当过半数的节点把该条写入信息追加到文件系统上的 WAL，并且收到确认消息之后，这条 Log entry 才会被 Leader 认为是安全的；此时该日志进入 committed 状态，完成数据的插入，随后该 Log Entry 便被标记为 applied 的状态。
+
+多副本工作原理参见 [数据写入与复制流程](../../26-tdinternal/01-arch.md#数据写入与复制流程)   
+
+## 集群配置
+
+三副本要求集群至少配置三个服务器节点，基本部署与配置步骤如下
+1. 确定服务器节点数量、主机名或域名，配置好所有节点的域名解析：DNS 或 /etc/hosts
+2. 各节点分别安装 TDengine 企业版服务端安装包，按需编辑好各节点 taos.cfg
+3. 启动各节点 taosd 服务 (其他服务可按需启动：taosadapter/taosx/taoskeeper/taos-explorer)
+
+## 运维命令
+
+### 创建集群
+
+创建三节点的集群
+
+```sql
+CREATE dnode <dnode_ep> port <dnode_port>;
+CREATE dnode <dnode_ep> port <dnode_port>;
+```
+
+创建三副本的 Mnode，保证 Mnode 高可用
+
+```sql
+CREATE mnode on dnode <dnode_id>;
+CREATE mnode on dnode <dnode_id>;
+```
+
+### 数据库创建
+
+创建三副本数据库。DBA 按需创建指定的三副本数据库
+
+```sql
+create database <dbname> replica 3 vgroups xx buffer xx ...
+```
+
+### 修改数据库副本数
+
+创建了一个单副本数据库后，希望改为三副本时，可通过 alter 命令来实现，反之亦然
+
+```sql
+alter database <dbname> replica 3|1
+```
+
+## 常见问题
+
+### 1. 创建三副本数据库或修改为三副本时，报错：DB error: Out of dnodes
+- 服务器节点数不足：原因是服务器节点数少于三个。
+- 解决方案：增加服务器节点数量，满足最低要求。
+
+### 2. 创建三副本数据库或 split vgroup 时，报错：DB error: Vnodes exhausted
+- 服务器可用 Vnodes 不足：原因是某些服务器节点可用 Vnodes 数少于建库或 split vgroup 的需求数。
+- 解决方案：调整服务器 CPU 数量、SupportVnodes 数量，满足建库要求。

docs/zh/08-operation/18-ha/02-replica2.md

@@ -0,0 +1,85 @@
+---
+title: 双副本方案
+sidebar_label: 双副本方案
+toc_max_heading_level: 4
+---
+
+本节介绍 TDengine 双副本方案的配置与使用。
+
+部分用户期望在保证一定可靠性、可用性条件下，尽可能压缩部署成本。为此，TDengine 提出基于 Arbitrator 的双副本方案，可提供集群中**只有单个服务故障且不出现连续故障**的容错能力。
+
+双副本选主由高可用的 Mnode 提供仲裁服务，不由 Raft 组内决定。
+1. Arbitrator：仲裁服务，不存储数据，VGroup 因某一 Vnode 故障而无法提供服务时，Arbitrator 可根据数据同步情况指定 VGroup 内另一 Vnode 成为 Assigned Leader
+2. AssignedLeader：被强制设置为 Leader 的 Vnode，无论其他副本 Vnode 是否存活，均可一直响应用户请求
+
+![replica2.png](../pic/replica2.png)
+
+## 集群配置
+
+双副本要求集群至少配置三个节点，基本部署与配置步骤如下：
+1. 确定服务器节点数量、主机名或域名，配置好所有节点的域名解析：DNS 或 /etc/hosts
+2. 各节点分别安装 TDengine 企业版服务端安装包，按需编辑好各节点 taos.cfg，选择其中一个节点作为仲裁节点，该节点可配置为仅部署 Mnode（将 SupportVnodes 参数设置为 0），除提供仲裁服务之外，不存储时序数据
+3. 启动各节点 taosd 服务 (其他服务可按需启动：taosadapter/taosx/taoskeeper/taos-explorer)
+
+## 约束条件
+1. 最小配置的服务器节点数为 2+1 个，其中两个数据节点，一个仲裁节点；仲裁节点可与其他应用共用，但需与前两个数据节点在同一网段；该节点占用资源少， 仅 1~2 核；如部署 3 个以上数据节点，无需单独部署仲裁节点
+2. 双副本为数据库建库参数，不同数据库可按需选择副本数
+3. 支持 TDengine 集群的完整特性，包括：读缓存、数据订阅、流计算等
+4. 支持 TDengine 所有语言连接器以及连接方式
+5. 支持单副本与双副本之间切换（前提是节点数量满足需求、各节点可用 vnode 数量/内存/存储空间足够）
+6. 不支持双副本与三副本之间的切换
+7. 不支持双副本切换为双活，除非另外部署一套实例与当前实例组成双活方案
+
+## 运维命令
+
+### 创建集群
+
+创建三节点的集群
+
+```sql
+CREATE dnode <dnode_ep> port <dnode_port>;
+CREATE dnode <dnode_ep> port <dnode_port>;
+```
+
+创建三副本的 Mnode，保证 Mnode 高可用，确保仲裁服务的高可用
+
+```sql
+CREATE mnode on dnode <dnode_id>;
+CREATE mnode on dnode <dnode_id>;
+```
+
+### 数据库创建
+
+创建双副本数据库。DBA 按需创建指定的双副本数据库
+
+```sql
+create database <dbname> replica 2 vgroups xx buffer xx ...
+```
+
+### 修改数据库副本数
+
+创建了一个单副本数据库后，希望改为双副本时，可通过alter命令来实现。反之亦然
+
+```sql
+alter database <dbname> replica 2|1
+```
+
+## 异常情况
+
+| 异常场景 | 集群状态 |
+| ------- | ------ |
+| 没有 Vnode 发生故障： Arbitrator 故障（Mnode 宕机节点超过一个，导致 Mnode 无法选主）| **持续提供服务** |
+| 仅一个 Vnode 故障：VGroup 已经达成同步后，某一个 Vnode 才发生故障的                |  **持续提供服务** |
+| 仅一个 Vnode 故障：离线 Vnode 启动后，VGroup 未达成同步前，另一个 Vnode 服务故障的  |  **无法提供服务** |
+| 两个 Vnode 都发生故障                                                         |  **无法提供服务** |
+
+
+## 常见问题
+
+### 1. 创建双副本数据库或修改为双副本时，报错：DB error: Out of dnodes
+- 服务器节点数不足：原因是，数据服务器节点数少于两个。
+- 解决方案：增加服务器节点数量，满足最低要求。
+
+### 2. 创建双副本数据库或 split vgroup 时，报错：DB error: Vnodes exhausted
+- 服务器可用 Vnodes 不足：原因是某些服务器节点可用 Vnodes 数少于建库或 split vgroup 的需求数。
+- 解决方案：调整服务器 CPU 数量、SupportVnodes 数量，满足建库要求。

docs/zh/08-operation/18-ha/03-dual.md

@@ -1,31 +1,31 @@
 ---
-title: TDengine 双活系统
+title: 双活系统
 sidebar_label: 双活系统
 toc_max_heading_level: 4
 ---
 
 本节介绍 TDengine 双活系统的配置和使用。
 
-1. 部分用户因为部署环境的特殊性只能部署两台服务器，同时希望实现一定的服务高可用和数据高可靠。本文主要描述基于数据复制和客户端 Failover 两项关键技术的 TDengine 双活系统的产品行为，包括双活系统的架构、配置、运维等。TDengine 双活既可以用于前面所述资源受限的环境，也可用于在两套 TDengine 集群（不限资源）之间的灾备场景。双活是 TDengine Enterprise 特有功能，在 3.3.0.0 版本中第一次发布，建议使用最新版本。
+部分用户因为部署环境的特殊性只能部署两台服务器，同时希望实现一定的服务高可用和数据高可靠。本文主要描述基于数据复制和客户端 Failover 两项关键技术的 TDengine 双活系统的产品行为，包括双活系统的架构、配置、运维等。TDengine 双活既可以用于前面所述资源受限的环境，也可用于在两套 TDengine 集群（不限资源）之间的灾备场景。双活是 TDengine Enterprise 特有功能，在 3.3.0.0 版本中第一次发布，建议使用最新版本。
 
-2. 双活系统的定义是：业务系统中有且仅有两台服务器，其上分别部署一套服务，在业务层看来这两台机器和两套服务是一个完整的系统，对其中的细节业务层不需要感知。双活中的两个节点通常被称为 Master-Slave，意为”主从“或”主备“，本文档中可能会出现混用的情况。
+双活系统的定义是：业务系统中有且仅有两台服务器，其上分别部署一套服务，在业务层看来这两台机器和两套服务是一个完整的系统，对其中的细节业务层不需要感知。双活中的两个节点通常被称为 Master-Slave，意为”主从“或”主备“，本文档中可能会出现混用的情况。
+
+TDengine 双活系统的部署架构图如下, 其中涉及到三个关键点：
 
-3. TDengine 双活系统的部署架构图如下, 其中涉及到三个关键点：
 1. 由 Client Driver 实现对双系统的 Failover，即主节点宕机时的主从切换
 2. 由 taosX 从（当前的）主节点到从节点实现数据复制
 3. 由数据订阅的写接口在写入复制过来的数据时在 WAL 中加入特殊标记，由数据订阅的读接口在读取数据时自动过滤掉带有该特殊标记的数据，避免重复复制形成 infinite loop
 
 注：下图中仅以一个单机版 TDengine 作为示例，但在实际部署中图中的一个 Host 也可以被任意节点数量的 TDengine 集群代替。
 
-![Active-Standby.png](./Active-Standby.png)
+![Active-Standby.png](../pic/Active-Standby.png)
 
-## 配置
 
-### 集群配置
+## 集群配置
 
 双活对 TDengine 集群本身的配置没有任何要求，但对要在双活系统之间同步的数据库的 WAL 保留时长有一定要求，WAL 保留时长越大双活系统的容错率越高；如果备节点宕机时长超过主节点上的 WAL 保留时长，必定会导致备节点上有数据缺失；如果备节点宕机时长虽未超过主节点上的 WAL 保留时长，也有一定概率丢失数据，取决于接近的程度以及数据同步的速度。
 
-### 客户端配置
+## 客户端配置
 
 目前只有 Java 连接器在 WebSocket 连接模式下支持双活，其配置示例如下
 
@@ -42,19 +42,19 @@ connection = DriverManager.getConnection(url, properties);
 
 其中的配置属性及含义如下表
 
-| 属性名                             | 含义                                                                                                              |
+| 属性名                              | 含义 |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| ---------------------------------- | --- |
-| PROPERTY_KEY_SLAVE_CLUSTER_HOST    | 第二节点的主机名或者 ip，默认空                                                                                   |
+| PROPERTY_KEY_SLAVE_CLUSTER_HOST    | 第二节点的主机名或者 ip，默认空 |
-| PROPERTY_KEY_SLAVE_CLUSTER_PORT    | 第二节点的端口号，默认空                                                                                          |
+| 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_INTERVAL_MS | 重连的时间间隔，单位毫秒：默认 2000 毫秒，也就是 2 秒；最小值为 0， 表示立即重试；最大值不做限制 |
-| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 每节点最多重试次数：默认值为 3；最小值为 0，表示不进行重试；最大值不做限制                                        |
+| PROPERTY_KEY_RECONNECT_RETRY_COUNT | 每节点最多重试次数：默认值为 3；最小值为 0，表示不进行重试；最大值不做限制 |
 
-### 约束条件
+## 约束条件
 
-1. 应用程序不能使用订阅接口，如果配置了双活参数会导致创建消费者失败。
+1. 应用程序不能使用订阅接口，如果配置了双活参数会导致创建消费者失败
-2. 不建议应用程序使用参数绑定的写入和查询方式，如果使用应用需要自己解决连接切换后的相关对象失效问题。
+2. 不建议应用程序使用参数绑定的写入和查询方式，如果使用应用需要自己解决连接切换后的相关对象失效问题
-3. 在双活场景下，不建议用户应用程序显示调用 use database，应该在连接参数中指定 database。
+3. 在双活场景下，不建议用户应用程序显示调用 use database，应该在连接参数中指定 database
 4. 双活的两端集群必须同构（即数据库的命名和所有配置参数以及用户名密码和权限设置等完全相同）
 5. 只支持 WebSocket 连接模式
 
@@ -73,7 +73,7 @@ taosx replica start
 1. 方法一
 
 ```shell
-    - taosx replica start -f source_endpoint -t sink_endpoint [database...] 
+taosx replica start -f source_endpoint -t sink_endpoint [database...] 
 ```
 
 在本机器所在的 taosx 服务中建立从 source_endpoint 到 sink_endpoint 的同步任务。运行该命令成功后，将打印 replica ID 到控制台（后续记为 id）。
@@ -82,6 +82,7 @@ taosx replica start
 ```shell
 taosx replica start -f td1:6030 -t td2:6030 
 ```
+
 该示例命令会自动创建除 information_schema、performance_schema、log、audit 库之外的同步任务。可以使用 `http://td2:6041` 指定该 endpoint 使用 websocket 接口（默认是原生接口）。也可以指定数据库同步：taosx replica start -f td1:6030 -t td2:6030 db1 仅创建指定的数据库同步任务。
 
 2. 方法二
@@ -93,9 +94,9 @@ taosx replica start -i id [database...]
 使用上面已经创建的 Replica ID (id) 以在该同步任务中增加其它数据库。
 
 注意：
-- 多次使用该命令，不会创建重复任务，仅将所指定的数据库增加到相应任务中。
+1. 多次使用该命令，不会创建重复任务，仅将所指定的数据库增加到相应任务中。
-- replica id 在一个 taosX 实例内是全局唯一的，与 source/sink 的组合无关
+2. replica id 在一个 taosX 实例内是全局唯一的，与 source/sink 的组合无关
-- 为便于记忆，replica id 为一个随机常用单词，系统自动将 source/sink 组合对应到一个词库中取得一个唯一可用单词。
+3. 为便于记忆，replica id 为一个随机常用单词，系统自动将 source/sink 组合对应到一个词库中取得一个唯一可用单词。
 
 ### 查看任务状态
 
@@ -120,8 +121,8 @@ taosx replica stop id [db...]
 ```
 
 该命令作用如下：
-- 停止指定 Replica ID 下所有或指定数据库的双副本同步任务。
+1. 停止指定 Replica ID 下所有或指定数据库的双副本同步任务。
-- 使用 `taosx replica stop id1 db1` 表示停止 id1 replica 下 db1的同步任务。
+2. 使用 `taosx replica stop id1 db1` 表示停止 id1 replica 下 db1的同步任务。
 
 ### 重启双活任务
 
@@ -130,8 +131,8 @@ taosx replica restart id [db...]
 ```
 
 该命令作用如下：
-- 重启指定 Replica ID 下所有或指定数据库的双副本同步任务。
+1. 重启指定 Replica ID 下所有或指定数据库的双副本同步任务。
-- 使用 `taosx replica start id1 db1` 仅重启指定数据库 db1的同步任务。
+2. 使用 `taosx replica start id1 db1` 仅重启指定数据库 db1的同步任务。
 
 ### 查看同步进度
 

docs/zh/08-operation/18-ha/index.md

@@ -0,0 +1,25 @@
+---
+sidebar_label: HA
+title: High availability
+---
+
+TDengine 作为分布式时序数据库，支持高可用特性。默认高可用方案为基于 RAFT 协议的标准三副本方案；为适应不同用户场景的需要，提供基于 RAFT 协议改造的双副本方案；为满足传统双机主备架构的需求，提供基于 WAL 数据同步的双活方案。
+
+- 标准三副本方案：时序数据的副本数目为 3，确保了最高的可用性，成本也最高。
+- 双副本结合 Arbitrator 方案：时序数据的副本数目为 2，但节点数目至少为 3，以确保高可用性和良好的数据一致性，可显著降低成本；与三副本方案相比，此方案在显著降低成本的同时，依然保持了较高的可用性。
+- 双活方案：可仅部署两个节点，高可用性较好，数据一致性弱（最终一致性）。
+
+以下为三种方案的特点：
+
+| # | **三副本** | **双副本** | **双活** |
+|:--|:----------|:----------|:--------|
+| **集群数目**   | 部署一个集群 | 部署一个集群 | 部署两个不同集群 |
+| **最小节点数** | 三个数据节点 | 两个数据节点，一个仲裁节点 | 两个数据节点 |
+| **选主原理**   | Raft 协议 | 管理节点仲裁选主 | 无需选主 |
+| **同步原理**   | Raft 协议 | Raft 协议 | 通过 taosX 进行数据同步 |      
+| **同步延迟**   | 无延迟 | 无延迟 | 依赖于 taosX 的同步速度，秒级延迟 |
+| **数据安全性** | 无数据丢失 | 无数据丢失 | 依赖于 WAL 的保存时长 |
+| **数据一致性** | RAFT 一致性 | RAFT 一致性 | 最终一致性 |     
+| **高可用性**   | 任一节点宕机不影响服务 | 任一节点宕机不影响服务，但不能处理连续宕机场景 | 一个实例存活即可提供服务 |
+
+