cherry pick #6096 to release-3.0

Signed-off-by: ti-srebot <[email protected]>
pingcap · Apr 21, 2021 · 0809190 · 0809190
1 parent 43b4536
commit 0809190
Show file tree

Hide file tree

Showing 4 changed files with 202 additions and 1 deletion.
diff --git a/pd-control.md b/pd-control.md
@@ -9,8 +9,18 @@ PD Control 是 PD 的命令行工具，用于获取集群状态信息和调整
 
 ## 源码编译
 
+<<<<<<< HEAD
 1. [Go](https://golang.org/) Version 1.13 以上
 2. 在 PD 项目根目录使用 `make` 命令进行编译，生成 bin/pd-ctl
+=======
+> **注意：**
+>
+> 建议使用的 Control 工具版本与集群版本保持一致。
+
+### 使用 TiUP
+
+可直接通过 `tiup ctl pd:<pd_version> -u http://<pd_ip>:<pd_port> [-i]` 使用。
+>>>>>>> ab487f7a... ctl: add a note for all ctl docs (#6096)
 
 ## 下载安装包
 
@@ -901,12 +911,50 @@ Encoding 格式示例：
 {{< copyable "" >}}
 
 ```bash
+<<<<<<< HEAD
 >> scheduler show                             // 显示所有的 schedulers
 >> scheduler add grant-leader-scheduler 1     // 把 store 1 上的所有 Region 的 leader 调度到 store 1
 >> scheduler add evict-leader-scheduler 1     // 把 store 1 上的所有 Region 的 leader 从 store 1 调度出去
 >> scheduler add shuffle-leader-scheduler     // 随机交换不同 store 上的 leader
 >> scheduler add shuffle-region-scheduler     // 随机调度不同 store 上的 Region
 >> scheduler remove grant-leader-scheduler-1  // 把对应的 scheduler 删掉
+=======
+>> scheduler show                                 // 显示所有的 schedulers
+>> scheduler add grant-leader-scheduler 1         // 把 store 1 上的所有 Region 的 leader 调度到 store 1
+>> scheduler add evict-leader-scheduler 1         // 把 store 1 上的所有 Region 的 leader 从 store 1 调度出去
+>> scheduler config evict-leader-scheduler        // v4.0.0 起，展示该调度器具体在哪些 store 上
+>> scheduler add shuffle-leader-scheduler         // 随机交换不同 store 上的 leader
+>> scheduler add shuffle-region-scheduler         // 随机调度不同 store 上的 Region
+>> scheduler remove grant-leader-scheduler-1      // 把对应的调度器删掉，`-1` 对应 store ID
+>> scheduler pause balance-region-scheduler 10    // 暂停运行 balance-region 调度器 10 秒
+>> scheduler pause all 10                         // 暂停运行所有的调度器 10 秒
+>> scheduler resume balance-region-scheduler      // 继续运行 balance-region 调度器
+>> scheduler resume all                           // 继续运行所有的调度器
+>> scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调度器的配置
+```
+
+### `scheduler config balance-hot-region-scheduler`
+
+用于查看和控制 `balance-hot-region-scheduler` 策略。
+
+示例：
+
+```bash
+>> scheduler config balance-hot-region-scheduler  // 显示 balance-hot-region 调度器的所有配置
+{
+  "min-hot-byte-rate": 100,
+  "min-hot-key-rate": 10,
+  "max-zombie-rounds": 3,
+  "max-peer-number": 1000,
+  "byte-rate-rank-step-ratio": 0.05,
+  "key-rate-rank-step-ratio": 0.05,
+  "count-rank-step-ratio": 0.01,
+  "great-dec-ratio": 0.95,
+  "minor-dec-ratio": 0.99,
+  "src-tolerance-ratio": 1.02,
+  "dst-tolerance-ratio": 1.02
+}
+>>>>>>> ab487f7a... ctl: add a note for all ctl docs (#6096)
 ```
 
 ### `store [delete | label | weight] <store_id>  [--jq="<query string>"]`

diff --git a/tidb-binlog/binlog-control.md b/tidb-binlog/binlog-control.md
@@ -0,0 +1,135 @@
+---
+title: binlogctl 工具
+summary: 介绍 binlogctl 的使用方法。
+aliases: ['/docs-cn/dev/tidb-binlog/binlog-control/']
+---
+
+# binlogctl 工具
+
+Binlog Control（以下简称 binlogctl）是 TiDB Binlog 的命令行工具，用于管理 TiDB Binlog 集群。
+
+binlogctl 支持如下这些功能：
+
+* 查看 Pump/Drainer 状态
+* 暂停/下线 Pump/Drainer
+* Pump/Drainer 异常状态处理
+
+使用 binlogctl 的场景：
+
+* 同步出现故障/检查运行情况，需要查看 Pump/Drainer 的状态
+* 维护集群，需要暂停/下线 Pump/Drainer
+* Pump/Drainer 异常退出，状态没有更新，或者状态不符合预期，对业务造成影响
+
+## binlogctl 下载
+
+> **注意：**
+>
+> 建议使用的 Control 工具版本与集群版本保持一致。
+
+binlogctl 下载链接：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz &&
+wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256
+```
+
+检查文件完整性，返回 ok 则正确：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+sha256sum -c tidb-{version}-linux-amd64.sha256
+```
+
+检查文件完整性，返回 ok 则正确：
+
+{{< copyable "shell-regular" >}}
+
+```bash
+sha256sum -c tidb-enterprise-tools-latest-linux-amd64.sha256
+```
+
+## binlogctl 使用说明
+
+命令行参数：
+
+```bash
+Usage of binlogctl:
+-V
+输出 binlogctl 的版本信息
+-cmd string
+    命令模式，包括 "generate_meta"（已废弃）, "pumps", "drainers", "update-pump" ,"update-drainer", "pause-pump", "pause-drainer", "offline-pump", "offline-drainer"
+-data-dir string
+    保存 Drainer 的 checkpoint 的文件的路径 (默认 "binlog_position")（已废弃）
+-node-id string
+    Pump/Drainer 的 ID
+-pd-urls string
+    PD 的地址，如果有多个，则用"," 连接 (默认 "http://127.0.0.1:2379")
+-ssl-ca string
+    SSL CAs 文件的路径
+-ssl-cert string
+        PEM 格式的 X509 认证文件的路径
+-ssl-key string
+        PEM 格式的 X509 key 文件的路径
+-time-zone string
+    如果设置时区，在 "generate_meta" 模式下会打印出获取到的 tso 对应的时间。例如 "Asia/Shanghai" 为 CST 时区，"Local" 为本地时区
+-show-offline-nodes
+    在用 `-cmd pumps` 或 `-cmd drainers` 命令时使用，这两个命令默认不显示 offline 的节点，仅当明确指定 `-show-offline-nodes` 时会显示
+```
+
+命令示例：
+
+- 查询所有的 Pump/Drainer 的状态：
+
+    设置 `cmd` 为 `pumps` 或者 `drainers` 来查看所有 Pump 或者 Drainer 的状态。例如：
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps
+    ```
+
+    ```
+    [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=pump] [node="{NodeID: 1.1.1.1:8250, Addr: pump:8250, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"]
+    ```
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd drainers
+    ```
+
+    ```
+    [2019/04/28 09:29:59.016 +00:00] [INFO] [nodes.go:48] ["query node"] [type=drainer] [node="{NodeID: 1.1.1.1:8249, Addr: 1.1.1.1:8249, State: online, MaxCommitTS: 408012403141509121, UpdateTime: 2019-04-28 09:29:57 +0000 UTC}"]
+    ```
+
+- 暂停/下线 Pump/Drainer
+
+    binlogctl 提供以下命令暂停/下线服务：
+
+    | cmd             | 说明           | 示例                                                                                             |
+    | --------------- | ------------- | ------------------------------------------------------------------------------------------------|
+    | pause-pump      | 暂停 Pump      | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-pump -node-id ip-127-0-0-1:8250`       |
+    | pause-drainer   | 暂停 Drainer   | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pause-drainer -node-id ip-127-0-0-1:8249`    |
+    | offline-pump    | 下线 Pump      | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-pump -node-id ip-127-0-0-1:8250`     |
+    | offline-drainer | 下线 Drainer   | `bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd offline-drainer -node-id ip-127-0-0-1:8249`  |
+
+    binlogctl 会发送 HTTP 请求给 Pump/Drainer，Pump/Drainer 收到命令后会主动执行对应的退出流程。
+
+- 异常情况下修改 Pump/Drainer 的状态
+
+    在服务正常运行以及符合流程的暂停、下线过程中，Pump/Drainer 的状态都是可以正确的。但是在一些异常情况下 Pump/Drainer 无法正确维护自己的状态，可能会影响数据同步任务，在这种情况下需要使用 binlogctl 修复状态信息。
+
+    设置 `cmd` 为 `update-pump` 或者 `update-drainer` 来更新 Pump 或者 Drainer 的状态。Pump 和 Drainer 的状态可以为 paused 或者 offline。例如：
+
+    {{< copyable "shell-regular" >}}
+
+    ```bash
+    bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd update-pump -node-id ip-127-0-0-1:8250 -state paused
+    ```
+
+    > **注意：**
+    >
+    > Pump/Drainer 在正常运行过程中会定期在 PD 中更新自己的状态，而这条命令是直接去修改 Pump/Drainer 保存在 PD 中的状态，所以在 Pump/Drainer 服务正常的情况下使用这些命令是没有意义的。仅在 Pump/Drainer 服务异常的情况下使用，具体哪些场景下使用这条命令可以参考 FAQ。
diff --git a/tidb-control.md b/tidb-control.md
@@ -11,7 +11,15 @@ TiDB Control 是 TiDB 的命令行工具，用于获取 TiDB 状态信息，多
 
 本节提供了两种方式获取 TiDB Control 工具。
 
+<<<<<<< HEAD
 ### 通过 TiDB Ansible 安装
+=======
+> **注意：**
+>
+> 建议使用的 Control 工具版本与集群版本保持一致。
+
+### 通过 TiUP 安装
+>>>>>>> ab487f7a... ctl: add a note for all ctl docs (#6096)
 
 对于使用 [TiDB Ansible](/online-deployment-using-ansible.md) 部署的 TiDB 集群，在 TiDB 的安装路径下可以找到 TiDB Control 的二进制程序 `tidb-ctl`。
 
@@ -132,7 +140,7 @@ tid 子命令用来通过表的 id 获取数据库中表的表结构。
  "collate": "utf8mb4_bin",
   ...
 }
-``` 
+```
 
 同 in 子命令一样，如果使用的 TiDB 地址不是默认的地址和端口，需要通过 `--host` 和 `--port` 参数指定 TiDB 的地址和 status 端口。
 

diff --git a/tikv-control.md b/tikv-control.md
@@ -10,7 +10,17 @@ TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管
 * 如果是使用 TiDB Ansible 部署的集群，在 `ansible` 目录下的 `resources/bin` 子目录下。
 * 如果是使用 TiUP 部署的集群，在 `~/.tiup/components/ctl/{VERSION}/` 目录下。
 
+<<<<<<< HEAD
 [TiUP](https://github.com/pingcap/tiup) 是晚于 `tidb-ansible` 推出的部署工具，使用方式更加简化，`tikv-ctl` 也集成在了 `tiup` 命令中。执行以下命令，即可调用 `tikv-ctl` 工具：
+=======
+## 通过 TiUP 使用 TiKV Control
+
+> **注意：**
+>
+> 建议使用的 Control 工具版本与集群版本保持一致。
+
+`tikv-ctl` 也集成在了 `tiup` 命令中。执行以下命令，即可调用 `tikv-ctl` 工具：
+>>>>>>> ab487f7a... ctl: add a note for all ctl docs (#6096)
 
 {{< copyable "shell-regular" >}}