doc: refactor doc

2024-07-24 10:19:49 +08:00 · 2024-07-24 10:19:49 +08:00 · ef1830e14e
parent 208af8eeae
commit ef1830e14e
11 changed files with 700 additions and 130 deletions
--- a/docs/zh/07-operation/04-maintenance.md
+++ b/docs/zh/07-operation/04-maintenance.md
@ -0,0 +1,96 @@
+---
+toc_max_heading_level: 4
+title: 集群维护
+sidebar_label: 集群维护
+---
+
+## 简介
+
+本节介绍 TDengine Enterprise 中提供的高阶集群维护手段，能够使 TDengine 集群长期运行得更健壮和高效。
+
+## 数据重整
+
+TDengine 面向多种写入场景，而很多写入场景下，TDengine 的存储会导致数据存储的放大或数据文件的空洞等。这一方面影响数据的存储效率，另一方面也会影响查询效率。为了解决上述问题，TDengine 企业版提供了对数据的重整功能，即 DATA COMPACT 功能，将存储的数据文件重新整理，删除文件空洞和无效数据，提高数据的组织度，从而提高存储和查询的效率。
+
+### 语法
+
+```SQL
+COMPACT DATABASE db_name [start with 'XXXX'] [end with 'YYYY']； 
+SHOW COMPACTS [compact_id]；
+KILL COMPACT compact_id；
+```
+
+### 效果
+
+-   扫描并压缩指定的 DB 中所有 VGROUP 中 VNODE 的所有数据文件
+-   COMPCAT 会删除被删除数据以及被删除的表的数据
+-   COMPACT 会合并多个 STT 文件
+-   可通过 start with 关键字指定 COMPACT 数据的起始时间
+-   可通过 end with 关键字指定 COMPACT 数据的终止时间
+-   COMPACT 命令会返回 COMPACT 任务的 ID
+-   COMPACT 任务会在后台异步执行，可以通过 SHOW COMPACTS 命令查看 COMPACT 任务的进度
+-   SHOW 命令会返回 COMPACT 任务的 ID，可以通过 KILL COMPACT 命令终止 COMPACT 任务
+
+
+### 补充说明
+
+-   COMPACT 为异步，执行 COMPACT 命令后不会等 COMPACT 结束就会返回。如果上一个 COMPACT 没有完成则再发起一个 COMPACT 任务，则会等上一个任务完成后再返回。
+-   COMPACT 可能阻塞写入，尤其是在 stt_trigger = 1 的数据库中，但不阻塞查询。
+
+## Vgroup Leader 再平衡
+
+当多副本集群中的一个或多个节点因为升级或其它原因而重启后，有可能出现集群中各个 dnode 负载不均衡的现象，极端情况下会出现所有 vgroup 的 leader 都位于同一个 dnode 的情况。为了解决这个问题，可以使用下面的命令
+
+```SQL
+balance vgroup leader; # 再平衡所有 vgroup 的 leader
+balance vgroup leader on <vgroup_id>; # 再平衡一个 vgroup 的 leader
+balance vgroup leader database <database_name>; # 再平衡一个 database 内所有 vgroup 的 leader
+```
+
+### 功能
+
+尝试让一个或所有 vgroup 的 leader在各自的replica节点上均匀分布。这个命令会让 vgroup 强制重新选举，通过重新选举，在选举的过程中，改变 vgroup 的leader，通过这个方式，最终让leader均匀分布。
+
+### 注意
+
+Vgroup 选举本身带有随机性，所以通过选举的重新分布产生的均匀分布也是带有一定的概率，不会完全的均匀。该命令的副作用是影响查询和写入，在vgroup重新选举时，从开始选举到选举出新的 leader 这段时间，这 个vgroup 无法写入和查询。选举过程一般在秒级完成。所有的vgroup会依次逐个重新选举。
+
+## 恢复数据节点
+
+当集群中的某个数据节点（dnode）的数据全部丢失或被破坏，比如磁盘损坏或者目录被误删除，可以通过 restore dnode 命令来恢复该数据节点上的部分或全部逻辑节点，该功能依赖多副本中的其它副本进行数据复制，所以只在集群中 dnode 数量大于等于 3 且副本数为 3 的情况下能够工作。
+
+```sql
+restore dnode <dnode_id>；# 恢复dnode上的mnode，所有vnode和qnode
+restore mnode on dnode <dnode_id>；# 恢复dnode上的mnode
+restore vnode on dnode <dnode_id> ；# 恢复dnode上的所有vnode
+restore qnode on dnode <dnode_id>；# 恢复dnode上的qnode
+```
+
+### 限制
+
+- 该功能是基于已有的复制功能的恢复，不是灾难恢复或者备份恢复，所以对于要恢复的 mnode 和 vnode来说，使用该命令的前提是还存在该 mnode 或 vnode 的其它两个副本仍然能够正常工作。
+- 该命令不能修复数据目录中的个别文件的损坏或者丢失。例如，如果某个 mnode 或者 vnode 中的个别文件或数据损坏，无法单独恢复损坏的某个文件或者某块数据。此时，可以选择将该  mnode/vnode 的数据全部清空再进行恢复。
+
+## 分裂虚拟组
+
+当一个 vgroup 因为子表数过多而导致 CPU 或 Disk 资源使用量负载过高时，增加 dnode 节点后，可通过split vgroup命令把该vgroup分裂为两个虚拟组。分裂完成后，新产生的两个 vgroup 承担原来由一个 vgroup 提供的读写服务。
+
+```sql
+split vgroup <vgroup_id>
+```
+
+### 注意
+
+- 单副本库虚拟组，在分裂完成后，历史时序数据总磁盘空间使用量，可能会翻倍。所以，在执行该操作之前，通过增加 dnode 节点方式，确保集群中有足够的 CPU 和磁盘资源，避免资源不足现象发生。
+- 该命令为 DB 级事务；执行过程，当前DB的其它管理事务将会被拒绝。集群中，其它DB不受影响。
+- 分裂任务执行过程中，可持续提供读写服务；期间，可能存在可感知的短暂的读写业务中断。
+- 在分裂过程中，不支持流和订阅。分裂结束后，历史 WAL 会清空。
+- 分裂过程中，可支持节点宕机重启容错；但不支持节点磁盘故障容错。
+
+## 在线更新集群配置
+
+从 3.1.1.0 版本开始，TDengine Enterprise 支持在线热更新 `supportVnodes` 这个很重要的 dnode 配置参数。这个参数的原始配置方式是在 `taos.cfg` 配置文件中，表示该 dnode 能够支持的最大的 vnode 数量。当创建一个数据库时需要分配新的 vnode，当删除一个数据库时其 vnode 都会被销毁。
+
+但在线更新 `supportVnodes` 不会产生持久化，当系统重启后，允许的最大 vnode 数量仍然由 taos.cfg 中配置的 `supportVnodes` 决定。
+
+如果通过在线更新或配置文件方式设置的 `supportVnodes` 小于 dnode 当前已经实际存在的 vnode 数量，已经存在的 vnode 不会受影响。但当尝试创建新的 database 时，是否能够创建成功则仍然受实际生效的 `supportVnodes` 参数决定。
--- a/docs/zh/07-operation/05-monitor.md
+++ b/docs/zh/07-operation/05-monitor.md
--- a/docs/zh/07-operation/06-backup.md
+++ b/docs/zh/07-operation/06-backup.md
@ -31,8 +31,62 @@ taosdump -i /file/path -h localhost -P 6030
 TDengine Enterprise 提供了一个高效的增量备份功能，具体流程如下。

 第 1 步，通过浏览器访问 taosExplorer 服务，访问地址通常为 TDengine 集群所在 IP 地址的端口 6060，如 http://localhost:6060。
+
 第 2 步，在 taosExplorer 服务页面中的“系统管理 - 备份”页面新增一个数据备份任务，在任务配置信息中填写需要备份的数据库名称和备份存储文件路径，完成创建任务
-后即可启动数据备份。
+后即可启动数据备份。 在数据备份配置页面中可以配置三个参数：
+  - 备份周期：必填项，配置每次执行数据备份的时间间隔，可通过下拉框选择每天、每 7 天、每 30 天执行一次数据备份，配置后，会在对应的备份周期的0:00时启动一次数据备份任务；
+  - 数据库：必填项，配置需要备份的数据库名（数据库的 wal_retention_period 参数需大于0）；
+  - 目录：必填项，配置将数据备份到 taosX 所在运行环境中指定的路径下，如 /root/data_backup；
+
 第 3 步，在数据备份任务完成后，在相同页面的已创建任务列表中找到创建的数据备份任务，直接执行一键恢复，就能够将数据恢复到 TDengine 中。

-与 taosdump 相比，如果对相同的数据在指定存储路径下进行多次备份操作，由于TDengine Enterprise 不仅备份效率高，而且实行的是增量处理，因此每次备份任务都会很快完成。而由于 taosdump 永远是全量备份，因此 TDengine Enterprise 在数据量较大的场景下可以显著减小系统开销，而且更加方便。
+与 taosdump 相比，如果对相同的数据在指定存储路径下进行多次备份操作，由于TDengine Enterprise 不仅备份效率高，而且实行的是增量处理，因此每次备份任务都会很快完成。而由于 taosdump 永远是全量备份，因此 TDengine Enterprise 在数据量较大的场景下可以显著减小系统开销，而且更加方便。
+
+**常见错误排查**
+
+1. 如果任务启动失败并报以下错误：
+
+```text
+Error: tmq to td task exec error
+
+Caused by:
+    [0x000B] Unable to establish connection
+```
+产生原因是与数据源的端口链接异常，需检查数据源 FQDN 是否联通及端口 6030 是否可正常访问。
+
+2. 如果使用 WebSocket 连接，任务启动失败并报以下错误：
+
+```text
+Error: tmq to td task exec error
+
+Caused by:
+    0: WebSocket internal error: IO error: failed to lookup address information: Temporary failure in name resolution
+    1: IO error: failed to lookup address information: Temporary failure in name resolution
+    2: failed to lookup address information: Temporary failure in name resolution
+```
+
+使用 WebSocket 连接时可能遇到多种错误类型，错误信息可以在 ”Caused by“ 后查看，以下是几种可能的错误：
+
+- "Temporary failure in name resolution": DNS 解析错误，检查 IP 或 FQDN 是否能够正常访问。
+- "IO error: Connection refused (os error 111)": 端口访问失败，检查端口是否配置正确或是否已开启和可访问。
+- "IO error: received corrupt message": 消息解析失败，可能是使用了 wss 方式启用了 SSL，但源端口不支持。
+- "HTTP error: *": 可能连接到错误的 taosAdapter 端口或 LSB/Nginx/Proxy 配置错误。
+- "WebSocket protocol error: Handshake not finished": WebSocket 连接错误，通常是因为配置的端口不正确。
+
+3. 如果任务启动失败并报以下错误：
+
+```text
+Error: tmq to td task exec error
+
+Caused by:
+    [0x038C] WAL retention period is zero
+```
+
+是由于源端数据库 WAL 配置错误，无法订阅。
+
+解决方式：
+修改数据 WAL 配置：
+
+```sql
+alter database test wal_retention_period 3600;
+```
--- a/docs/zh/07-operation/07-disaster.md
+++ b/docs/zh/07-operation/07-disaster.md
--- a/docs/zh/07-operation/07-multi.md
+++ b/docs/zh/07-operation/07-multi.md
@ -1,54 +0,0 @@
---
-sidebar_label: 多级存储
-title: 多级存储
-toc_max_heading_level: 4
---
-
-TDengine  特有的多级存储功能，其作用是将较近的热度较高的数据存储在高速介质上，而时间久远热度很低的数据存储在低成本介质上，达成了以下目标：
- 降低存储成本 -- 将数据分级存储后，海量极冷数据存入廉价存储介质带来显著经济性
- 提升写入性能 -- 得益于每级存储可支持多个挂载点，WAL 预写日志也支持 0 级的多挂载点并行写入，极大提升写入性能（实际场景测得支持持续写入每秒 3 亿测点以上），在机械硬盘上可获得极高磁盘 IO 吞吐（实测可达 2GB/s）
- 方便维护 -- 配置好各级存储挂载点后，系统数据迁移等工作，无需人工干预；存储扩容更灵活、方便
- 对 SQL 透明 -- 无论查询的数据是否跨级，一条 SQL 可返回所有数据，简单高效
-
-## 配置方式
-
-多级存储支持 3 级，每级最多可配置 16 个挂载点。
-
-**Tips** 典型的配置方案有：0 级配置多个挂载点，每个挂载点对应单块 SAS 硬盘；1 级配置多个挂载点，每个挂载点对应单块或多块 SATA 硬盘；2 级可配置 S3 存储或其他廉价网络存储。
-
-TDengine 多级存储配置方式如下（在配置文件/etc/taos/taos.cfg 中）：
-```shell
-dataDir [path] <level> <primary>
-```
-
- path: 挂载点的文件夹路径。
- level: 介质存储等级，取值为 0，1，2。 0 级存储最新的数据，1 级存储次新的数据，2 级存储最老的数据，省略默认为 0。 各级存储之间的数据流向：0 级存储 -> 1 级存储 -> 2 级存储。 同一存储等级可挂载多个硬盘，同一存储等级上的数据文件分布在该存储等级的所有硬盘上。 需要说明的是，数据在不同级别的存储介质上的移动，是由系统自动完成的，用户无需干预。
- primary: 是否为主挂载点，0（否）或 1（是），省略默认为 1。
-在配置中，只允许一个主挂载点的存在（level=0，primary=1），例如采用如下的配置方式：
-```shell
-dataDir /mnt/data1 0 1
-dataDir /mnt/data2 0 0
-dataDir /mnt/data3 1 0
-dataDir /mnt/data4 1 0
-dataDir /mnt/data5 2 0
-dataDir /mnt/data6 2 0
-```
-
-**注意** 1. 多级存储不允许跨级配置，合法的配置方案有：仅 0 级，仅 0 级+ 1 级，以及 0 级+ 1 级+ 2 级。而不允许只配置 level=0 和 level=2，而不配置 level=1。
-2. 禁止手动移除使用中的挂载盘，挂载盘目前不支持非本地的网络盘。
-
-## 负载均衡
-
-在多级存储中，有且只有一个主挂载点，主挂载点承担了系统中最重要的元数据存储，同时各个 vnode 的主目录均存在于当前 dnode 主挂载点上，从而导致该 dnode 的写入性能受限于单个磁盘的 IO 吞吐能力。
-
-从 TDengine 3.1.0.0 开始，如果一个 dnode 配置了多个 0 级挂载点，我们将该 dnode 上所有 vnode 的主目录均衡分布在所有的 0 级挂载点上，由这些 0 级挂载点共同承担写入负荷。
-
-在网络 I/O 及其它处理资源不成为瓶颈的情况下，通过优化集群配置，测试结果证明整个系统的写入能力和 0 级挂载点的数量呈现线性关系，即随着 0 级挂载点数量的增加，整个系统的写入能力也成倍增加。
-
-## 同级挂载点选择策略
-
-一般情况下，当 TDengine 要从同级挂载点中选择一个用于生成新的数据文件时，采用 round robin 策略进行选择。但现实中有可能每个磁盘的容量不相同，或者容量相同但写入的数据量不相同，这就导致会出现每个磁盘上的可用空间不均衡，在实际进行选择时有可能会选择到一个剩余空间已经很小的磁盘。
-
-为了解决这个问题，从 3.1.1.0 开始引入了一个新的配置 minDiskFreeSize，当某块磁盘上的可用空间小于等于这个阈值时，该磁盘将不再被选择用于生成新的数据文件。该配置项的单位为字节，其值应该大于 2GB，即会跳过可用空间小于 2GB 的挂载点。
-
-从 3.3.2.0 版本开始，引入了一个新的配置 disable_create_new_file，用于控制在某个挂载点上禁止生成新文件，其缺省值为 false，即每个挂载点上默认都可以生成新文件。
--- a/docs/zh/07-operation/08-multi.md
+++ b/docs/zh/07-operation/08-multi.md
@ -0,0 +1,114 @@
+---
+sidebar_label: 存储配置
+title: 多级存储与对象存储
+toc_max_heading_level: 4
+---
+
+TDengine  特有的多级存储功能，其作用是将较近的热度较高的数据存储在高速介质上，而时间久远热度很低的数据存储在低成本介质上，达成了以下目标：
+- 降低存储成本 -- 将数据分级存储后，海量极冷数据存入廉价存储介质带来显著经济性
+- 提升写入性能 -- 得益于每级存储可支持多个挂载点，WAL 预写日志也支持 0 级的多挂载点并行写入，极大提升写入性能（实际场景测得支持持续写入每秒 3 亿测点以上），在机械硬盘上可获得极高磁盘 IO 吞吐（实测可达 2GB/s）
+- 方便维护 -- 配置好各级存储挂载点后，系统数据迁移等工作，无需人工干预；存储扩容更灵活、方便
+- 对 SQL 透明 -- 无论查询的数据是否跨级，一条 SQL 可返回所有数据，简单高效
+
+
+多级存储所涉及的各层存储介质都是本地存储设备。除了本地存储设备之外，TDengine 还支持使用对象存储(S3)，将最冷的一批数据保存在最廉价的介质上，以进一步降低存储成本，并在必要时仍然可以进行查询，且数据存储在哪里也对 SQL 透明。
+
+## 多级存储
+
+### 配置方式
+
+多级存储支持 3 级，每级最多可配置 16 个挂载点。
+
+**Tips** 典型的配置方案有：0 级配置多个挂载点，每个挂载点对应单块 SAS 硬盘；1 级配置多个挂载点，每个挂载点对应单块或多块 SATA 硬盘；2 级可配置 S3 存储或其他廉价网络存储。
+
+TDengine 多级存储配置方式如下（在配置文件/etc/taos/taos.cfg 中）：
+```shell
+dataDir [path] <level> <primary>
+```
+
+- path: 挂载点的文件夹路径。
+- level: 介质存储等级，取值为 0，1，2。 0 级存储最新的数据，1 级存储次新的数据，2 级存储最老的数据，省略默认为 0。 各级存储之间的数据流向：0 级存储 -> 1 级存储 -> 2 级存储。 同一存储等级可挂载多个硬盘，同一存储等级上的数据文件分布在该存储等级的所有硬盘上。 需要说明的是，数据在不同级别的存储介质上的移动，是由系统自动完成的，用户无需干预。
+- primary: 是否为主挂载点，0（否）或 1（是），省略默认为 1。
+在配置中，只允许一个主挂载点的存在（level=0，primary=1），例如采用如下的配置方式：
+```shell
+dataDir /mnt/data1 0 1
+dataDir /mnt/data2 0 0
+dataDir /mnt/data3 1 0
+dataDir /mnt/data4 1 0
+dataDir /mnt/data5 2 0
+dataDir /mnt/data6 2 0
+```
+
+**注意** 1. 多级存储不允许跨级配置，合法的配置方案有：仅 0 级，仅 0 级+ 1 级，以及 0 级+ 1 级+ 2 级。而不允许只配置 level=0 和 level=2，而不配置 level=1。
+2. 禁止手动移除使用中的挂载盘，挂载盘目前不支持非本地的网络盘。
+
+### 负载均衡
+
+在多级存储中，有且只有一个主挂载点，主挂载点承担了系统中最重要的元数据存储，同时各个 vnode 的主目录均存在于当前 dnode 主挂载点上，从而导致该 dnode 的写入性能受限于单个磁盘的 IO 吞吐能力。
+
+从 TDengine 3.1.0.0 开始，如果一个 dnode 配置了多个 0 级挂载点，我们将该 dnode 上所有 vnode 的主目录均衡分布在所有的 0 级挂载点上，由这些 0 级挂载点共同承担写入负荷。
+
+在网络 I/O 及其它处理资源不成为瓶颈的情况下，通过优化集群配置，测试结果证明整个系统的写入能力和 0 级挂载点的数量呈现线性关系，即随着 0 级挂载点数量的增加，整个系统的写入能力也成倍增加。
+
+### 同级挂载点选择策略
+
+一般情况下，当 TDengine 要从同级挂载点中选择一个用于生成新的数据文件时，采用 round robin 策略进行选择。但现实中有可能每个磁盘的容量不相同，或者容量相同但写入的数据量不相同，这就导致会出现每个磁盘上的可用空间不均衡，在实际进行选择时有可能会选择到一个剩余空间已经很小的磁盘。
+
+为了解决这个问题，从 3.1.1.0 开始引入了一个新的配置 minDiskFreeSize，当某块磁盘上的可用空间小于等于这个阈值时，该磁盘将不再被选择用于生成新的数据文件。该配置项的单位为字节，其值应该大于 2GB，即会跳过可用空间小于 2GB 的挂载点。
+
+从 3.3.2.0 版本开始，引入了一个新的配置 disable_create_new_file，用于控制在某个挂载点上禁止生成新文件，其缺省值为 false，即每个挂载点上默认都可以生成新文件。
+
+
+## 对象存储
+
+本节介绍在 TDengine Enterprise 如何使用 S3 对象存储，本功能基于通用 S3 SDK 实现，对各个 S3 平台的访问参数进行了兼容适配，可以访问如 minio，腾讯云 COS，Amazon S3 等对象存储服务。通过适当的参数配置，可以把大部分较冷的时序数据存储到 S3 服务中。
+
+**注意** 在配合多级存储使用时，每一级存储介质上保存的数据都有可能被按规则备份到远程对象存储中并删除本地数据文件。
+
+### 配置方式
+
+在配置文件 /etc/taos/taos.cfg 中，添加用于 S3 访问的参数：
+
+|参数名称        |   参数含义                                      |
+|:-------------:|:-----------------------------------------------:|
+|s3EndPoint | 用户所在地域的 COS 服务域名，支持 http 和 https，bucket 的区域需要与 endpoint 的保持一致，否则无法访问。例如：http://cos.ap-beijing.myqcloud.com |
+|s3AccessKey |冒号分隔的用户 SecretId:SecretKey。例如：AKIDsQmwsfKxTo2A6nGVXZN0UlofKn6JRRSJ:lIdoy99ygEacU7iHfogaN2Xq0yumSm1E |
+|s3BucketName | 存储桶名称，减号后面是用户注册 COS 服务的 AppId。其中 AppId 是 COS 特有，AWS 和阿里云都没有，配置时需要作为 bucket name 的一部分，使用减号分隔。参数值均为字符串类型，但不需要引号。例如：test0711-1309024725 |
+|s3UploadDelaySec | data 文件持续多长时间不再变动后上传至 s3，单位：秒。最小值：1；最大值：2592000 (30天），默认值 60 秒 |
+|s3PageCacheSize |s3 page cache 缓存页数目，单位：页。最小值：4；最大值：1024*1024\*1024。 ，默认值 4096|
+|s3MigrateIntervalSec | 本地数据文件自动上传 S3 的触发周期，单位为秒。最小值：600；最大值：100000。默认值 3600 |
+|s3MigrateEnabled | 是否自动进行 S3 迁移，默认值为 1，表示开启自动 S3 迁移，可配置为 0。 |
+
+### 检查配置参数可用性
+
+在 taos.cfg 中完成对 s3 的配置后，通过 taosd 命令的 checks3 参数可以检查所配置的 S3 服务是否可用：
+
+```
+taosd --checks3
+```
+
+如果配置的 S3 服务无法访问，此命令会在运行过程中输出相应的错误信息。
+
+### 创建使用 S3 的 DB
+
+完成配置后，即可启动 TDengine 集群，创建使用 S3 的数据库，比如：
+
+```sql
+create database demo_db duration 1d s3_keeplocal 3d;
+```
+
+数据库 demo_db 中写入时序数据后，3 天之前的时序数据会自动分块存放到 S3 存储中。
+
+默认情况下，mnode 每小时会下发 S3 数据迁移检查的指令，如果有时序数据需要上传，则自动分块存放到 S3 存储中，也可以使用 SQL 命令手动触发，由用户触发这一操作，语法如下：
+
+```sql
+s3migrate database <db_name>;
+```
+
+详细的 DB 参数见下表：
+
+| #    | 参数         | 默认值 | 最小值 | 最大值  | 描述                                                         |
+| :--- | :----------- | :----- | :----- | :------ | :----------------------------------------------------------- |
+| 1    | s3_keeplocal | 3650   | 1      | 365000  | 数据在本地保留的天数，即 data 文件在本地磁盘保留多长时间后可以上传到 S3。默认单位：天，支持 m（分钟）、h（小时）和 d（天）三个单位 |
+| 2    | s3_chunksize | 262144 | 131072 | 1048576 | 上传对象的大小阈值，与 TSDB_PAGESIZE 参数一样，不可修改，单位为 TSDB 页 |
+| 3    | s3_compact   | 0      | 0      | 1       | TSDB 文件组首次上传 S3 时，是否自动进行 compact 操作。       |
--- a/docs/zh/07-operation/08-user.md
+++ b/docs/zh/07-operation/08-user.md
@ -1,66 +0,0 @@
---
-sidebar_label: 用户管理
-title: TDengine 用户管理
-toc_max_heading_level: 4
---
-
-TDengine 默认仅配置了一个 root 用户，该用户拥有最高权限。
-
-## 创建用户
-
-创建用户的操作只能由 root 用户进行，语法如下。
-```sql
-create user user_name pass'password' [sysinfo {1|0}]
-```
-
-相关参数说明如下。
- user_name：最长为 23 B。
- password：最长为 128 B，合法字符包括字母和数字以及单双引号、撇号、反斜杠和空格以外的特殊字符，且不可以为空。
- sysinfo ：用户是否可以查看系统信息。1 表示可以查看，0 表示不可以查看。系统信息包括服务端配置信息、服务端各种节点信息，如 dnode、查询节点（qnode）等，以及与存储相关的信息等。默认为可以查看系统信息。
-
-如下 SQL 可以创建密码为 123456 且可以查看系统信息的用户 test。
-
-```sql
-create user test pass '123456' sysinfo 1
-```
-
-## 查看用户
-
-查看系统中的用户信息可使用如下 SQL。
-```sql
-show users;
-```
-
-也可以通过查询系统表 information_schema.ins_users 获取系统中的用户信息，示例如下。
-```sql
-select * from information_schema.ins_users;
-```
-
-## 修改用户信息
-
-修改用户信息的 SQL 如下。
-```sql
-alter user user_name alter_user_clause 
-alter_user_clause: { 
- pass 'literal' 
- | enable value 
- | sysinfo value
-}
-```
-
-相关参数说明如下。
- pass：修改用户密码。
- enable：是否启用用户。1 表示启用此用户，0 表示禁用此用户。
- sysinfo ：用户是否可查看系统信息。1 表示可以查看系统信息，0 表示不可以查看系统信息
-
-如下 SQL 禁用 test 用户。
-```sql
-alter user test enable 0
-```
-
-## 删除用户
-
-删除用户的 SQL 如下。
-```sql
-drop user user_name
-```
--- a/docs/zh/07-operation/09-grant.md
+++ b/docs/zh/07-operation/09-grant.md
@ -1,17 +1,76 @@
 ---
-sidebar_label: 权限管理
-title: 权限管理
+sidebar_label: 用户和权限
+title: 用户和权限管理
 toc_max_heading_level: 4
 ---

-TDengine 支持对系统资源、库、表、视图和主题的访问权限控制。root 用户可以为每个用户针对不同的资源设置不同的访问权限。
+TDengine 默认仅配置了一个 root 用户，该用户拥有最高权限。TDengine 支持对系统资源、库、表、视图和主题的访问权限控制。root 用户可以为每个用户针对不同的资源设置不同的访问权限。本节介绍 TDengine 中的用户和权限管理。

-## 资源管理
+## 用户管理
+
+### 创建用户
+
+创建用户的操作只能由 root 用户进行，语法如下。
+```sql
+create user user_name pass'password' [sysinfo {1|0}]
+```
+
+相关参数说明如下。
+- user_name：最长为 23 B。
+- password：最长为 128 B，合法字符包括字母和数字以及单双引号、撇号、反斜杠和空格以外的特殊字符，且不可以为空。
+- sysinfo ：用户是否可以查看系统信息。1 表示可以查看，0 表示不可以查看。系统信息包括服务端配置信息、服务端各种节点信息，如 dnode、查询节点（qnode）等，以及与存储相关的信息等。默认为可以查看系统信息。
+
+如下 SQL 可以创建密码为 123456 且可以查看系统信息的用户 test。
+
+```sql
+create user test pass '123456' sysinfo 1
+```
+
+### 查看用户
+
+查看系统中的用户信息可使用如下 SQL。
+```sql
+show users;
+```
+
+也可以通过查询系统表 information_schema.ins_users 获取系统中的用户信息，示例如下。
+```sql
+select * from information_schema.ins_users;
+```
+
+### 修改用户信息
+
+修改用户信息的 SQL 如下。
+```sql
+alter user user_name alter_user_clause 
+alter_user_clause: { 
+ pass 'literal' 
+ | enable value 
+ | sysinfo value
+}
+```
+
+相关参数说明如下。
+- pass：修改用户密码。
+- enable：是否启用用户。1 表示启用此用户，0 表示禁用此用户。
+- sysinfo ：用户是否可查看系统信息。1 表示可以查看系统信息，0 表示不可以查看系统信息
+
+如下 SQL 禁用 test 用户。
+```sql
+alter user test enable 0
+```
+
+### 删除用户
+
+删除用户的 SQL 如下。
+```sql
+drop user user_name
+```
+
+## 权限管理

 仅 root 用户可以管理用户、节点、vnode、qnode、snode 等系统信息，包括查询、新增、删除和修改。

-## 授权
-
 ### 库和表的授权

 在 TDengine 中，库和表的权限分为 read （读）和 write （写）两种。这些权限可以单独授予，也可以同时授予用户。
@ -124,14 +183,14 @@ priv_level : {
 grant subscribe on topic_name to test
 ```

-## 查看授权
+### 查看授权

 当企业拥有多个数据库用户时，使用如下命令可以查询具体一个用户所拥有的所有授权，SQL 如下。
 ```sql
 show user privileges
 ```

-## 撤销授权
+### 撤销授权

 由于数据库访问、数据订阅和视图的特性不同，针对具体授权的撤销语法也略有差异。下面列出具体的撤销授权对应不同授权对象的语法。
 撤销数据库访问授权的 SQL 如下。
--- a/docs/zh/07-operation/10-security.md
+++ b/docs/zh/07-operation/10-security.md
@ -0,0 +1,197 @@
+---
+sidebar_label: 更多安全策略
+title: 更多安全策略
+toc_max_heading_level: 4
+---
+
+除了传统的用户和权限管理之外，TDengine 还有其他的安全策略，例如 IP 白名单、审计日志、数据加密等。
+
+## IP 白名单
+
+IP 白名单是一种网络安全技术，它使 IT 管理员能够控制“谁”可以访问系统和资源，提升数据库的访问安全性，避免外部的恶意攻击。IP 白名单通过创建可信的 IP 地址列表，将它们作为唯一标识符分配给用户，并且只允许这些 IP 地址访问目标服务器。请注意，用户权限与 IP 白名单是不相关的，两者分开管理。下面是配置 IP 白名单的具体方法。
+
+增加 IP 白名单的 SQL 如下。
+```sql
+create user test pass password [sysinfo value] [host host_name1[,host_name2]] 
+alter user test add host host_name1
+```
+
+查询 IP 白名单的 SQL 如下。
+```sql
+select test, allowed_host from ins_user_privileges;
+show users;
+```
+
+删除 IP 白名单的命令如下。
+```sql
+alter user test drop host host_name1
+```
+
+## 审计日志
+
+TDengine 先对用户操作进行记录和管理，然后将这些作为审计日志发送给taosKeeper，再由 taosKeeper 保存至任意 TDengine 集群。管理员可通过审计日志进行安全监控、历史追溯。TDengine 的审计日志功能开启和关闭操作非常简单，只须修改TDengine 的配置文件后重启服务。审计日志的配置说明如下。
+
+### taosd 配置
+
+审计日志由数据库服务 taosd 产生，其相应参数要配置在 taos.cfg 配置文件中，详细参数如下表。
+
+| 参数名称       | 参数含义                                                  |
+|:-------------:|:--------------------------------------------------------:|
+|audit | 是否打开审计日志，默认值为 0。1 为开启，0 为关闭 |
+|monitorFqdn | 接收审计日志的 taosKeeper 所在服务器的 FQDN | 
+|monitorPort | 接收审计日志的 taosKeeper 服务所用端口 |
+|monitorCompaction | 上报数据时是否进行压缩 |
+
+### taosKeeper 配置
+
+在 taosKeeper 的配置文件 keeper.toml 中配置与审计日志有关的配置参数，如下表所示
+
+| 参数名称       | 参数含义                                                  |
+|:-------------:|:--------------------------------------------------------:|
+|auditDB | 用于存放审计日志的数据库的名字，默认值为 "audit" ，taosKeeper 在收到上报的审计日志后会判断该数据库是否存在，如果不存在会自动创建它 |
+
+### 数据格式
+
+上报的审计日志格式如下
+
+```json
+{
+    "ts": timestamp,
+    "cluster_id": string,
+    "user": string,
+    "operation": string,
+    "db": string,
+    "resource": string,
+    "client_add": string,
+    "details": string
+}
+```
+
+### 表结构
+
+taosKeeper 会依据上报的审计数据在相应的数据库中自动建立超级表用于存储数据。该超级表的定义如下
+
+```sql
+CREATE STABLE operations(ts timestamp, details VARCHAR(64000)， User VARCHAR(25), Operation VARCHAR(20), db VARCHAR(65), resource VARCHAR(193), client_add(25)) TAGS (clusterID VARCHAR(64) );
+```
+
+其中：
+1. db为操作涉及的database，resource为操作涉及的资源。
+2. User 和 Operation 为数据列，表示哪个用户在该对象上进行了什么操作
+3. timestamp 为时间戳列，表示操作发生时的时间
+4. details 为该操作的一些补充细节，在大多数操作下是所执行的操作的SQL语句。
+5. client_add为客户端地址，包括ip和端口
+
+### 操作列表
+
+目前审计日志中所记录的操作列表以及每个操作中各字段的含义如下表（注：因为每个操作的实加者即 user 字段、时间戳字段和client_add在所有操作中的含义相同，下表不包含）
+
+| 操作        | Operation | DB | Resource | Details |
+| ----------------| ----------| ---------| ---------| --------|
+| create database | createDB  | db name  | NULL     | SQL |
+| alter database  | alterDB   | db name  | NULL     | SQL |
+| drop database   | dropDB    | db name  | NULL     | SQL |
+| create stable   | createStb | db name  | stable name | SQL |
+| alter stable    | alterStb  | db name  | stable name | SQL |
+| drop stable     | dropStb   | db name  | stable name | SQL |
+| create user     | createUser | NULL |  被创建的用户名 | 用户属性参数,  (password除外) |
+| alter user      | alterUser | NULL | 被修改的用户名 | 修改密码操作记录的是被修改的参数和新值 (password除外) ；其他操作记录SQL |
+| drop user       | dropUser | NULL | 被删除的用户名 | SQL |
+| create topic    | createTopic | topic 所在 DB | 创建的 topic 名字 | SQL |
+| drop topic      | cropTopic | topic 所在 DB | 删除的 topic 名字 | SQL |
+| create dnode    | createDnode | NULL | IP:Port 或 FQDN:Port | SQL |
+| drop dnode      | dropDnode | NULL | dnodeId | SQL |
+| alter dnode     | alterDnode | NULL | dnodeId | SQL |
+| create mnode    | createMnode | NULL | dnodeId | SQL |
+| drop mnode      | dropMnode | NULL | dnodeId | SQL |
+| create qnode    | createQnode | NULL | dnodeId | SQL |
+| drop qnode      | dropQnode | NULL | dnodeId | SQL |
+| login           | login  | NULL | NULL | appName |
+| create stream   | createStream | NULL | 所创建的 strem 名 | SQL |
+| drop stream     | dropStream | NULL | 所删除的 stream 名 | SQL |
+| grant privileges| grantPrivileges | NULL | 所授予的用户 | SQL | 
+| remove privileges | revokePrivileges | NULL | 被收回权限的用户 | SQL | 
+| compact database| compact | database name  | NULL | SQL |
+| balance vgroup leader | balanceVgroupLead | NULL | NULL | SQL |
+| restore dnode | restoreDnode | NULL | dnodeId | SQL |
+| restribute vgroup | restributeVgroup | NULL | vgroupId | SQL |
+| balance vgroup | balanceVgroup | NULL | vgroupId | SQL |
+| create table | createTable | db name | NULL | table name |
+| drop table | dropTable | db name | NULL | table name |
+
+### 查看审计日志
+
+在 taosd 和 taosKeeper 都正确配置并启动之后，随着系统的不断运行，系统中的各种操作（如上表所示）会被实时记录并上报，用户可以登录 taosExplorer，点击 “系统管理”→“审计” 页面，即可查看审计日志; 也可以在 TDengine CLI 中直接查询相应的库和表。
+
+## 数据加密
+
+TDengine 支持透明数据加密（Transparent Data Encryption，TDE），通过对静态数据文件进行加密，阻止可能的攻击者绕过数据库直接从文件系统读取敏感信息。数据库的访问程序是完全无感知的，应用程序不需要做任何修改和编译，就能够直接应用到加密后的数据库，支持国标 SM4 等加密算法。在透明加密中，数据库密钥管理、数据库加密范围是两个最重要的话题。TDengine 采用机器码对数据库密钥进行加密处理，保存在本地而不是第三方管理器中。当数据文件被拷贝到其他机器后，由于机器码发生变化，无法获得数据库密钥，自然无法访问数据文件。TDengine 对所有数据文件进行加密，包括预写日志文件、元数据文件和时序数据文件。加密后，数据压缩率不变，写入性能和查询性能仅有轻微下降。
+
+### 配置密钥
+
+密钥配置分离线设置和在线设置两种方式。
+
+方式一，离线设置。通过离线设置可为每个节点分别配置密钥，命令如下。
+```shell
+taosd -y {encryptKey}
+```
+
+方式二，在线设置。当集群所有节点都在线时，可以使用 SQL 配置密钥，SQL 如下。
+```sql
+create encrypt_key {encryptKey};
+```
+在线设置方式要求所有已经加入集群的节点都没有使用过离线设置方式生成密钥，否则在线设置方式会失败，在线设置密钥成功的同时也自动加载和使用了密钥。
+
+### 创建加密数据库
+
+TDengine 支持通过 SQL 创建加密数据库，SQL 如下。
+```sql
+create database [if not exists] db_name [database_options]
+database_options:
+ database_option ...
+database_option: {
+ encrypt_algorithm {'none' |'sm4'}
+}
+```
+
+主要参数说明如下。
+encrypt_algorithm：指定数据采用的加密算法。默认是 none，即不采用加密。sm4 表示采用 SM4 加密算法
+
+### 查看加密配置
+
+用户可通过查询系统数据库 ins_databases 获取数据库当前加密配置，SQL 如下。
+```sql
+select name, `encrypt_algorithm` from ins_databases;
+              name              | encrypt_algorithm |
+=====================================================
+ power1                         | none              |
+ power                          | sm4               |
+```
+
+### 查看节点密钥状态
+
+通过以下的SQL命令参看节点密钥状态：
+
+```sql
+show encryptions;
+
+select * from information_schema.ins_encryptions;
+  dnode_id   |           key_status           |
+===============================================
+           1 | loaded                         |
+           2 | unset                          |
+           3 | unknown                        |
+```
+key_status 有三种取值：
+- 当节点未设置密钥时，状态列显示 unset。
+- 当密钥被检验成功并且加载后，状态列显示 loaded.
+- 当节点未启动，key的状态无法被探知时，状态列显示 unknown
+
+### 更新密钥配置
+
+当节点的硬件配置发生变更时，需要通过以下命令更新密钥，与离线配置密钥的命令相同：
+
+```shell
+taosd -y  {encryptKey}
+```
+更新密钥配置，需要先停止 taosd，并且使用完全相同的密钥，也即密钥在数据库创建后不能修改。
--- a/docs/zh/07-operation/15-dual.md
+++ b/docs/zh/07-operation/15-dual.md
@ -0,0 +1,170 @@
+---
+title: TDengine 双活系统
+sidebar_label: 双活系统
+toc_max_heading_level: 4
+---
+
+## 简介
+
+1. 部分用户因为部署环境的特殊性只能部署两台服务器，同时希望实现一定的服务高可用和数据高可靠。本文主要描述基于数据复制和客户端 Failover 两项关键技术的 TDengine 双活系统的产品行为，包括双活系统的架构、配置、运维等。TDengine 双活既可以用于前面所述资源受限的环境，也可用于在两套 TDengine 集群（不限资源）之间的灾备场景。
+
+2. 双活系统的定义是：业务系统中有且仅有两台服务器，其上分别部署一套服务，在业务层看来这两台机器和两套服务是一个完整的系统，对其中的细节业务层不需要感知。双活中的两个节点通常被称为 Master-Slave，意为”主从“或”主备“，本文档中可能会出现混用的情况。
+
+3. TDengine 双活系统的部署架构图如下, 其中涉及到三个关键点：
+1. 由 Client Driver 实现对双系统的 Failover，即主节点宕机时的主从切换
+2. 由 taosX 从（当前的）主节点到从节点实现数据复制
+3. 由数据订阅的写接口在写入复制过来的数据时在 WAL 中加入特殊标记，由数据订阅的读接口在读取数据时自动过滤掉带有该特殊标记的数据，避免重复复制形成 infinite loop
+
+注：下图中仅以一个单机版 TDengine 作为示例，但在实际部署中图中的一个 Host 也可以被任意节点数量的 TDengine 集群代替。
+
+![Active-Standby.png](./Active-Standby.png)
+
+## 配置
+
+### 集群配置
+
+双活对 TDengine 集群本身的配置没有任何要求，但对要在双活系统之间同步的数据库的 WAL 保留时长有一定要求，WAL 保留时长越大双活系统的容错率越高；如果备节点宕机时长超过主节点上的 WAL 保留时长，必定会导致备节点上有数据缺失；如果备节点宕机时长虽未超过主节点上的 WAL 保留时长，也有一定概率丢失数据，取决于接近的程度以及数据同步的速度。
+
+### 客户端配置
+
+目前只有 Java 连接器在 WebSocket 连接模式下支持双活，其配置示例如下
+
+```java
+url = "jdbc:TAOS-RS://" + host + ":6041/?user=root&password=taosdata";
+Properties properties = new Properties();
+properties.setProperty(TSDBDriver.PROPERTY_KEY_BATCH_LOAD, "true");
+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，表示不进行重试；最大值不做限制 |
+
+### 约束条件
+
+1. 应用程序不能使用订阅接口，如果配置了双活参数会导致创建消费者失败。
+2. 不建议应用程序使用参数绑定的写入和查询方式，如果使用应用需要自己解决连接切换后的相关对象失效问题。
+3. 在双活场景下，不建议用户应用程序显示调用 use database，应该在连接参数中指定 database。
+4. 双活的两端集群必须同构（即数据库的命名和所有配置参数以及用户名密码和权限设置等完全相同）
+5. 只支持 WebSocket 连接模式
+
+## 运维命令
+
+TDengine 双活系统提供了一些运维工具能够自动化 taosX 的配置、一键启动、重启和停止（单机环境上的）所有双活组件。
+
+### 启动双活任务
+
+```shell
+taosx replica start
+```
+
+该命令用于启动双活中的数据复制任务，其所指定的两台主机上的 taosd 和 taosX 均为在线状态。
+
+1. 方法一
+
+```shell
+    - taosx replica start -f source_endpoint -t sink_endpoint [database...] 
+```
+
+在本机器所在的 taosx 服务中建立从 source_endpoint 到 sink_endpoint 的同步任务。运行该命令成功后，将打印 replica ID 到控制台（后续记为 id）。
+其中输入参数 source_endpoint 和 sink_endpoiint 为必须，形如 td2:6030 ，示例如下
+
+```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. 方法二
+
+```shell
+taosx replica start -i id [database...]
+```
+
+使用上面已经创建的 Replica ID (id) 以在该同步任务中增加其它数据库。
+
+注意：
+- 多次使用该命令，不会创建重复任务，仅将所指定的数据库增加到相应任务中。
+- replica id 在一个 taosX 实例内是全局唯一的，与 source/sink 的组合无关
+- 为便于记忆，replica id 为一个随机常用单词，系统自动将 source/sink 组合对应到一个词库中取得一个唯一可用单词。
+
+### 查看任务状态
+
+```shell
+taosx replica status [id...]
+```
+
+返回当前机器上创建的双活同步任务列表和状态。可以指定一个或多个 replica id 获取其任务列表和状态。输出示例如下：
+
+```shell
+---------+----------+----------+----------+------+-------------+----------------+
+| 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 |
+```
+
+### 停止双活任务
+
+```shell
+taosx replica stop id [db...]
+```
+
+该命令作用如下：
+- 停止指定 Replica ID 下所有或指定数据库的双副本同步任务。
+- 使用 `taosx replica stop id1 db1` 表示停止 id1 replica 下 db1的同步任务。
+
+### 重启双活任务
+
+```shell
+taosx replica restart id [db...]
+```
+
+该命令作用如下：
+- 重启指定 Replica ID 下所有或指定数据库的双副本同步任务。
+- 使用 `taosx replica start id1 db1` 仅重启指定数据库 db1的同步任务。
+
+### 查看同步进度
+
+```shell
+taosx replica diff id [db....]
+```
+
+该命令能够输出当前双副本同步任务中订阅的 Offset  与最新 WAL 的差值（不代表行数）， 例如：
+
+```shell
+---------+----------+----------+----------+-----------+---------+---------+------+
+| replica | database | source   | sink     | vgroup_id | current | latest  | diff |
+---------+----------+----------+----------+-----------+---------+---------+------+
+| a       | opc      | td1:6030 | td2:6030 | 2         | 17600   | 17600   | 0    |
+| ad       | opc      | td2:6030 | td2:6030 | 3         | 17600   | 17600   | 0    |
+``` 
+
+### 删除双活任务
+
+```shell
+taosx replica remove id [--force]
+```
+
+删除当前所有双活同步任务。正常情况下要想删除同步任务，需要先 stop 该任务；但当 --force 启用时，会强制停止并清除任务。
+
+### 推荐使用步骤
+
+1. 假定在机器 A 上运行，需要首先使用 taosx replica start 来配置 taosX，其输入参数是待同步的源端和目标端服务器地址 ，在完成配置后会自动启动同步服务和任务。此处假定 taosx 服务使用标准端口，同步任务使用原生连接。
+2. 在机器 B 上的步骤相同
+3. 在完成对两台机器的服务启动后，双活系统即可提供服务
+4. 在已经完成配置后，如果想要再次启动双活系统，请使用 restart 子命
+
+## 异常情况
+
+如果宕机恢复时间超出了 WAL 的保存时长，可能会出现丢数据的情况。此时双活系统中自带的 taosX 服务的自动数据同步无法处理。需要人工判断出哪些数据丢失，然后启动额外的 taosX 任务来复制丢失的数据。
--- a/docs/zh/07-operation/Active-Standby.png
+++ b/docs/zh/07-operation/Active-Standby.png