doc: add witness related docs

TOC.md

@@ -162,6 +162,8 @@
   - [使用 TiUP 运维集群](/maintain-tidb-using-tiup.md)
   - [在线修改集群配置](/dynamic-config.md)
   - [在线有损恢复](/online-unsafe-recovery.md)
+  - [使用 Witness 副本节约成本](/use-witness-to-save-costs.md)
+  - [使用 Witness 副本加速恢复](/use-witness-to-speed-up-failover.md)
   - [搭建双集群主从复制](/replicate-between-primary-and-secondary-clusters.md)
 - 监控与告警
   - [监控框架概述](/tidb-monitoring-framework.md)

configure-placement-rules.md

@@ -39,6 +39,7 @@ Placement Rules 示意图如下所示：
 | `StartKey`        | `string`，十六进制编码                | 适用 Range 起始 key                 |
 | `EndKey`          | `string`，十六进制编码                | 适用 Range 终止 key                 |
 | `Role`            | `string` | 副本角色，包括 voter/leader/follower/learner                           |
+| `IsWitness`       | `true`/`false` | 副本是否为 [Witness](/glossary.md#witness)                          |
 | `Count`           | `int`，正整数                     | 副本数量                            |
 | `LabelConstraint` | `[]Constraint`                    | 用于按 label 筛选节点               |
 | `LocationLabels`  | `[]string`                        | 用于物理隔离                        |
@@ -490,3 +491,32 @@ table ttt ranges: (NOTE: key range might be changed after DDL)
   "override": true,
 }
 ```
+
+### 场景六：在高可靠的存储环境下配置 Witness 副本
+
+本场景展示了如何在高可靠存储环境配置 `IsWitness`。下面的例子在 Amazon EBS 环境下配置 [Witness](/glossary.md#witness) 副本用于节约成本。
+
+添加规则示例如下：
+
+```json
+[
+    {
+        "group_id": "pd",
+        "id": "default",
+        "start_key": "",
+        "end_key": "",
+        "role": "voter",
+        "is_witness": false,
+        "count": 2
+    },
+    {
+        "group_id": "pd",
+        "id": "witness",
+        "start_key": "",
+        "end_key": "",
+        "role": "voter",
+        "is_witness": true,
+        "count": 1
+    }
+]
+```

glossary.md

@@ -165,3 +165,12 @@ Top SQL 用于找到一段时间内对某个 TiDB 或 TiKV 节点消耗负载较
 ### TTL
 
 [Time to Live (TTL)](/time-to-live.md) 提供了行级别的生命周期控制策略。通过为表设置 TTL 属性，TiDB 可以周期性地自动检查并清理表中的过期数据。
+
+## W
+
+### Witness
+
+Witness 副本只会存储最近的 Raft 日志来进行多数派确认，不会存储数据。Witness 副本的使用场景如下：
+
+- 在高可靠的存储环境下帮助节约成本。具体使用方法，可参考[使用 Witness 节约成本](/use-witness-to-save-costs.md)。
+- 快速恢复 (failover)，提高系统可用性。具体使用方法，可参考[使用 Witness 副本加速恢复](/use-witness-to-speed-up-failover.md)。

pd-configuration-file.md

@@ -203,6 +203,11 @@ PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/conf
 + 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。
 + 默认：1h
 
+### `switch-witness-interval` <span class="version-mark">从 v7.0.0 版本开始引入</span>
+
++ 控制某个 Region 在 [Witness](/glossary.md#witness) 和 Non-Witness 之间切换的间隔，即一个新切换为 Non-Witness 的 Region 在一段时间内不会被切换为 Witness。
++ 默认值：1h
+
 ### `max-snapshot-count`
 
 + 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。
@@ -253,6 +258,21 @@ PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/conf
 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。
 + 默认值：8
 
+### `witness-schedule-limit` <span class="version-mark">从 v7.0.0 版本开始引入</span>
+
++ 控制并行 Witness 调度任务的个数。
++ 默认值：4
++ 最小值：1
++ 最大值：9
+
+### `enable-witness` <span class="version-mark">从 v7.0.0 版本开始引入</span>
+
++ 控制是否开启 Witness 副本功能。
++ Witness 副本的使用场景如下：
+    - 在高可靠的存储环境下帮助节约成本。具体使用方法，可参考[使用 Witness 副本节约成本](/use-witness-to-save-costs.md)。
+    - 快速恢复 (failover)，提高系统可用性。具体使用方法，可参考[使用 Witness 副本加速恢复](/use-witness-to-speed-up-failover.md)。
++ 默认值：false
+
 ### `high-space-ratio`
 
 + 设置 store 空间充裕的阈值。当节点的空间占用比例小于该阈值时，PD 调度时会忽略节点的剩余空间，主要根据实际数据量进行均衡。此配置仅在 `region-score-formula-version = v1` 时生效。

pd-control.md

@@ -157,6 +157,7 @@ config show
   },
   "schedule": {
     "enable-cross-table-merge": "true",
+    "enable-witness": "true",
     "high-space-ratio": 0.7,
     "hot-region-cache-hits-threshold": 3,
     "hot-region-schedule-limit": 4,
@@ -1433,6 +1434,17 @@ unsafe remove-failed-stores show
 ]
 ```
 
+开启 [Witness 副本](/glossary.md#witness)功能：
+
+```bash
+config set enable-witness true
+```
+
+Witness 副本的使用场景如下：
+
+- 在高可靠的存储环境下帮助节约成本。具体使用方法，可参考[使用 Witness 副本节约成本](/use-witness-to-save-costs.md)。
+- 快速恢复 (failover)，提高系统可用性。具体使用方法，可参考[使用 Witness 副本加速恢复](/use-witness-to-speed-up-failover.md)。
+
 ## jq 格式化 JSON 输出示例
 
 ### 简化 `store` 的输出

use-witness-to-save-costs.md

@@ -0,0 +1,48 @@
+---
+title: 使用 Witness 副本节约成本
+summary: 了解如何使用 Witness 副本在高可靠的存储环境中节约成本。
+---
+
+# 使用 Witness 副本节约成本
+
+本文介绍如何在高可靠存储环境中使用 Witness 副本节约成本。如果需要使用 Witness 副本提高 TiKV Down 场景下的持久性，请参考[使用 Witness 副本来加速恢复](/use-witness-to-speed-up-failover.md)。
+
+## 功能说明
+
+在云环境中，推荐使用持久性为 99.8%~99.9% 的 Amazon Elastic Block Store (EBS) 或持久性为 99.99%~99.999% 的 Google Cloud Platform (GCP) 的 Persistent Disk 作为 TiKV 单节点存储。此时，TiKV 使用 3 个 Raft 副本虽然可行，但并不必要。为了降低成本，TiKV 引入了 Witness 副本功能，即 2 Replicas With 1 Log Only 机制。其中 1 Log Only 副本仅存储 Raft 日志但不进行数据 apply，依然可以通过 Raft 协议保证数据一致性。与标准的 3 副本架构相比，Witness 副本可以节省存储资源及 CPU 使用率。
+
+> **警告：**
+>
+> Witness 副本功能自 v7.0.0 开始引入，与低版本不兼容，因此不支持降级。
+
+## 适用场景
+
+高可靠的存储环境 (99.8%~99.9%)，例如使用 Amazon EBS 或 GCP Persistent Disk 时，可以开启并配置 Witness 副本来节约成本。
+
+## 使用步骤
+
+### 第 1 步：开启 Witness
+
+使用 PD Control 执行 `config set enable-witness true` 命令开启 Witness：
+
+```bash
+pd-ctl config set enable-witness true
+```
+
+命令输出 `Success` 表示开启成功。如果 Placement Rules 没有配置 Witness 副本，则默认不会有 Witness 产生。只有出现 TiKV Down 后，才会立刻添加一个 Witness 节点，后续系统将其转换为普通的 Voter。
+
+### 第 2 步：配置 Witness 副本
+
+以三副本为例，修改 `rule.json` 为[场景六：在高可靠的存储环境下配置 Witness 副本](/configure-placement-rules.md#场景六在高可靠的存储环境下配置-witness-副本)中的配置。
+
+编辑完文件后，使用下面的命令将配置保存至 PD 服务器：
+
+```bash
+pd-ctl config placement-rules save --in=rule.json
+```
+
+## 注意事项
+
+- 建议只在高可靠的存储环境中设置 Witness 副本。例如，使用持久性为 99.8%~99.9% 的 Amazon EBS 或持久性为 99.99%~99.999% 的 GCP Persistent Disk 作为单节点存储。
+- 由于 Witness 副本没有应用 Raft 日志，因此无法对外提供读写服务。当 Leader Down 后且剩余的 Voter 没有最新的 Raft 日志时，Raft 会选举 Witness 副本临时成为 Leader。Witness 副本当选后，会向 Voter 补发 Raft 日志后 transfer leader 给 Voter。若无法及时 transfer leader，当客户端 Backoff 超时后，应用可能收到 `IsWitness` 错误。
+- 当系统存在 Pending Voter 时，为防止 Witness 积攒过多的 Raft 日志，导致占满整个磁盘空间，系统会将 Witness 晋升为普通 Voter。

use-witness-to-speed-up-failover.md

@@ -0,0 +1,30 @@
+---
+title: 使用 Witness 副本加速恢复
+summary: 了解如何使用 Witness 副本来加速恢复。
+---
+
+# 使用 Witness 副本加速恢复
+
+本文介绍如何使用 Witness 副本提高 TiKV Down 场景下的持久性。如果需要在高可靠存储环境中使用 Witness 副本节约成本，请参考[使用 Witness 副本节约成本](/use-witness-to-save-costs.md)。
+
+## 功能说明
+
+Witness 副本功能可用于快速恢复 (failover)，以提高系统的可用性和数据持久性。例如在 3 缺 1 的情况下，虽然满足多数派要求，但是系统很脆弱，而完整恢复一个新成员的时间通常很长（需要先拷贝 snapshot 然后 apply 最新的日志），特别是 Region snapshot 比较大时，恢复的时间会更长。而且，拷贝副本的过程可能会对不健康的 Group member 造成更多的压力。因此，先添加一个 Witness 副本可以快速移除不健康的节点，降低在恢复一个新成员的过程中，又一个节点挂掉导致 Raft Group 不可用的风险（Learner 无法参与选举和提交），从而保证恢复数据过程中日志的安全性。
+
+> **警告：**
+>
+> Witness 副本功能自 v7.0.0 开始引入，与低版本不兼容，因此不支持降级。
+
+## 适用场景
+
+在快速恢复以提高持久性的场景下，可以开启 Witness 功能但不配置 Witness 副本。
+
+## 使用方法
+
+使用 PD Control 执行 `config set enable-witness true` 命令开启 Witness：
+
+```bash
+pd-ctl config set enable-witness true
+```
+
+命令输出 `Success` 表示开启成功。如果没有按照[使用 Witness 节约成本](/use-witness-to-save-costs.md)配置 Witness 副本，则集群正常状态下不会有 Witness 副本产生。只有出现 TiKV Down 后，才会立刻添加一个 Witness 节点，后续系统会将其转换为普通的 Voter。