https://docs.pingcap.com/zh/tidb/stable/pd-control
PD Control 是 PD 的命令行工具，用于获取集群状态信息和调整集群。
可直接通过 tiup ctl:v<CLUSTER_VERSION> pd -u http://<pd_ip>:<pd_port> [-i] 使用。
如需下载最新版本的 pd-ctl，直接下载 TiDB 安装包即可。pd-ctl 位于 TiDB 安装包的 ctl-{version}-linux-{arch}.tar.gz 包中。
| 安装包 | 操作系统 | 架构 | SHA256 校验和 |
|---|---|---|---|
https://download.pingcap.org/tidb-community-server-{version}-linux-amd64.tar.gz (pd-ctl) |
Linux | amd64 | https://download.pingcap.org/tidb-community-server-{version}-linux-amd64.tar.gz.sha256 |
https://download.pingcap.org/tidb-community-server-{version}-linux-arm64.tar.gz (pd-ctl) |
Linux | arm64 | https://download.pingcap.org/tidb-community-server-{version}-linux-arm64.tar.gz.sha256 |
make 或者 make pd-ctl 命令进行编译，生成 bin/pd-ctl单命令模式：
交互模式：
使用环境变量：
使用 TLS 加密：
--cacert--cert--detach / -d--help / -h--interact/-i--key--cert 所指定的证书的私钥--pd/-uhttp://127.0.0.1:2379PD_ADDR--version/-V用于显示集群基本信息。
示例：
config [show | set <option> <value> | placement-rules]用于显示或调整配置信息。示例如下。
显示 scheduling 的相关 config 信息：
显示所有的 config 信息：
显示 replication 的相关 config 信息：
显示目前集群版本，是目前集群 TiKV 节点的最低版本，并不对应 binary 的版本：
max-snapshot-count 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。当需要加快补副本或 balance 速度时可以调大这个值。
设置最大 snapshot 为 64：
max-pending-peer-count 控制单个 store 的 pending peer 上限，调度受制于这个配置来防止在部分节点产生大量日志落后的 Region。需要加快补副本或 balance 速度可以适当调大这个值，设置为 0 则表示不限制。
设置最大 pending peer 数量为 64：
max-merge-region-size 控制 Region Merge 的 size 上限（单位是 MiB）。当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。设置为 0 表示不开启 Region Merge 功能。
设置 Region Merge 的 size 上限为 16 MiB：
max-merge-region-keys 控制 Region Merge 的 keyCount 上限。当 Region KeyCount 大于指定值时 PD 不会将其与相邻的 Region 合并。
设置 Region Merge 的 keyCount 上限为 50000：
split-merge-interval 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。
设置 split 和 merge 的间隔为 1 天：
enable-one-way-merge 用于控制是否只允许和相邻的后一个 Region 进行合并。当设置为 false 时，PD 允许与相邻的前后 Region 进行合并。
设置只允许和相邻的后一个 Region 合并：
enable-cross-table-merge 用于开启跨表 Region 的合并。当设置为 false 时，PD 不会合并不同表的 Region。该选项只在键类型为 "table" 时生效。
设置允许跨表合并：
key-type 用于指定集群的键编码类型。支持的类型有 ["table", "raw", "txn"]，默认值为 "table"。
如果集群中不存在 TiDB 实例，key-type 的值为 "raw" 或 "txn"。此时，无论 enable-cross-table-merge 设置为何，PD 均可以跨表合并 Region。
如果集群中存在 TiDB 实例，key-type 的值应当为 "table"。此时，enable-cross-table-merge 的设置决定了 PD 是否能跨表合并 Region。如果 key-type 的值为 "raw"，placement rules 不生效。
启用跨表合并：
region-score-formula-version 用于设置 Region 算分公式的版本，支持的值有 ["v1", "v2"]。v2 版本公式有助于减少上下线等场景下冗余的 balance Region 调度。
开启 v2 版本 Region 算分公式：
patrol-region-interval 控制 replicaChecker 检查 Region 健康状态的运行频率，越短则运行越快，通常状况不需要调整。
设置 replicaChecker 的运行频率为 10 毫秒：
max-store-down-time 为 PD 认为失联 store 无法恢复的时间，当超过指定的时间没有收到 store 的心跳后，PD 会在其他节点补充副本。
设置 store 心跳丢失 30 分钟开始补副本：
max-store-preparing-time 控制 store 上线阶段的最长等待时间。在 store 的上线阶段，PD 可以查询该 store 的上线进度。当超过该配置项指定的时间后，PD 会认为该 store 已完成上线，无法再次查询这个 store 的上线进度，但是不影响 Region 向这个新上线 store 的迁移。通常用户无需修改该配置项。
设置 store 上线阶段最多等待 4 小时：
通过调整 leader-schedule-limit 可以控制同时进行 leader 调度的任务个数。这个值主要影响 leader balance 的速度，值越大调度得越快，设置为 0 则关闭调度。Leader 调度的开销较小，需要的时候可以适当调大。
最多同时进行 4 个 leader 调度：
通过调整 region-schedule-limit 可以控制同时进行 Region 调度的任务个数。这个值可以避免创建过多的 Region balance operator。默认值为 2048，对所有大小的集群都足够。设置为 0 则关闭调度。Region 调度的速度通常受到 store-limit 的限制，但除非你熟悉该设置，否则不推荐自定义该参数。
最多同时进行 2 个 Region 调度：
通过调整 replica-schedule-limit 可以控制同时进行 replica 调度的任务个数。这个值主要影响节点挂掉或者下线的时候进行调度的速度，值越大调度得越快，设置为 0 则关闭调度。Replica 调度的开销较大，所以这个值不宜调得太大。注意：该参数通常保持为默认值。如需调整，需要根据实际情况反复尝试设置该值大小。
最多同时进行 4 个 replica 调度：
merge-schedule-limit 控制同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。Merge 调度的开销较大，所以这个值不宜调得过大。注意：该参数通常保持为默认值。如需调整，需要根据实际情况反复尝试设置该值大小。
最多同时进行 16 个 merge 调度：
hot-region-schedule-limit 控制同时进行的 Hot Region 调度的任务，设置为 0 则关闭调度。这个值不宜调得过大，否则可能对系统性能造成影响。注意：该参数通常保持为默认值。如需调整，需要根据实际情况反复尝试设置该值大小。
最多同时进行 4 个 Hot Region 调度：
hot-region-cache-hits-threshold 用于设置识别热点 Region 所需的分钟数，只有 Region 处于热点状态持续时间超过该分钟数后，才能参与热点调度。
tolerant-size-ratio 控制 balance 缓冲区大小。当两个 store 的 leader 或 Region 的得分差距小于指定倍数的 Region size 时，PD 会认为此时 balance 达到均衡状态。
设置缓冲区为约 20 倍平均 RegionSize：
low-space-ratio 用于设置 store 空间不足的阈值。当节点的空间占用比例超过指定值时，PD 会尽可能避免往对应节点迁移数据，同时主要针对剩余空间大小进行调度，避免对应节点磁盘空间被耗尽。
设置空间不足阈值为 0.9：
high-space-ratio 用于设置 store 空间充裕的阈值，此配置仅的在 region-score-formula-version = v1 时生效。当节点的空间占用比例小于指定值时，PD 调度时会忽略剩余空间这个指标，主要针对实际数据量进行均衡。
设置空间充裕阈值为 0.5：
cluster-version 集群的版本，用于控制某些 Feature 是否开启，处理兼容性问题。通常是集群正常运行的所有 TiKV 节点中的最低版本，需要回滚到更低的版本时才进行手动设置。
设置 cluster version 为 1.0.8：
leader-schedule-policy 用于选择 Leader 的调度策略，可以选择按照 size 或者 count 来进行调度。
scheduler-max-waiting-operator 用于控制每个调度器同时存在的 operator 的个数。
enable-remove-down-replica 用于开启自动删除 DownReplica 的特性。当设置为 false 时，PD 不会自动清理宕机状态的副本。
enable-replace-offline-replica 用于开启迁移 OfflineReplica 的特性。当设置为 false 时，PD 不会迁移下线状态的副本。
enable-make-up-replica 用于开启补充副本的特性。当设置为 false 时，PD 不会为副本数不足的 Region 补充副本。
enable-remove-extra-replica 用于开启删除多余副本的特性。当设置为 false 时，PD 不会为副本数过多的 Region 删除多余副本。
enable-location-replacement 用于开启隔离级别检查。当设置为 false 时，PD 不会通过调度来提升 Region 副本的隔离级别。
enable-debug-metrics 用于开启 debug 的 metrics。当设置为 true 时，PD 会开启一些 metrics，比如 balance-tolerant-size 等。
enable-placement-rules 用于开启 placement rules，在 v5.0 及以上的版本默认开启。
store-limit-mode 用于控制 store 限速机制的模式。主要有两种模式：auto 和 manual。auto 模式下会根据 load 自动进行平衡调整（弃用）。
store-limit-version 用于设置 store limit 限制模式，目前提供两种方式：v1 和 v2。默认值为 v1。在 v1 模式下，你可以手动修改 store limit 以限制单个 TiKV 调度速度。v2 模式为实验特性，在 v2 模式下，你无需关注 store limit 值，PD 将根据 TiKV Snapshot 执行情况动态调整 TiKV 调度速度。详情请参考 Store Limit v2 原理。
PD 会对流量信息的末尾数字进行四舍五入处理，减少 Region 流量信息变化引起的统计信息更新。该配置项用于指定对 Region 流量信息的末尾进行四舍五入的位数。例如流量 100512 会归约到 101000。默认值为 3。该配置替换了 trace-region-flow。
示例：将 flow-round-by-digit 的值设为 4：
config placement-rules [disable | enable | load | save | show | rule-group]关于 config placement-rules 的具体用法，参考 Placement Rules 使用文档。
用于显示集群健康信息。示例如下。
显示健康信息：
hot [read | write | store| history <start_time> <end_time> [<key> <value>]]用于显示集群热点信息。示例如下。
显示读热点信息：
显示写热点信息：
显示所有 store 的读写信息：
显示历史读写热点信息:
例如查询时间 1629294000000 到 1631980800000 （毫秒）之间的历史热点 Region 信息:
对于参数的值为数组的请用 x, y, ... 的形式进行参数值的设置，所有支持的参数如下所示:
label [store <name> <value>]用于显示集群标签信息。示例如下。
显示所有 label：
显示所有包含 label 为 "zone":"cn" 的 store：
member [delete | leader_priority | leader [show | resign | transfer <member_name>]]用于显示 PD 成员信息，删除指定成员，设置成员的 leader 优先级。示例如下。
显示所有成员的信息：
下线 "pd2"：
使用 id 下线节点：
显示 leader 的信息：
将 leader 从当前成员移走：
将 leader 迁移至指定成员：
operator [check | show | add | remove]用于显示和控制调度操作。
示例：
其中，Region 的分裂都是尽可能地从靠近中间的位置开始。对这个位置的选择支持两种策略，即 scan 和 approximate。它们之间的区别是，前者通过扫描这个 Region 的方式来确定中间的 key，而后者是通过查看 SST 文件中记录的统计信息，来得到近似的位置。一般来说，前者更加精确，而后者消耗更少的 I/O，可以更快地完成。
ping用于显示ping PD 所需要花费的时间
示例：
region <region_id> [--jq="<query string>"]用于显示 Region 信息。使用 jq 格式化输出请参考 jq 格式化 json 输出示例。示例如下。
显示所有 Region 信息：
显示 Region id 为 2 的信息：
region key [--format=raw|encode|hex] <key>用于查询某个 key 位于哪一个 Region 上，支持 raw、encoding 和 hex 格式。使用 encoding 格式时，key 需要使用单引号。
Hex 格式（默认）示例：
Raw 格式示例：
Encoding 格式示例：
region scan用于获取所有 Region。
示例：
region sibling <region_id>用于查询某个 Region 相邻的 Region。
示例：
region keys [--format=raw|encode|hex] <start_key> <end_key> <limit>用于查询某个 key 范围内的所有 Region。支持不带 endKey 的范围。limit 的默认值是 16，设为 -1 则表示无数量限制。示例如下：
显示从 a 开始的所有 Region 信息，数量上限为 16：
显示 [a, z) 范围内的所有 Region 信息，数量上限为 16：
显示 [a, z) 范围内的所有 Region 信息，无数量上限：
显示从 a 开始的所有 Region 信息，数量上限为 20：
region store <store_id>用于查询某个 store 上面所有的 Region。
示例：
region topread [limit]用于查询读流量最大的 Region。limit 的默认值是 16。
示例：
region topwrite [limit]用于查询写流量最大的 Region。limit 的默认值是 16。
示例：
region topconfver [limit]用于查询 conf version 最大的 Region。limit 的默认值是 16。
示例：
region topversion [limit]用于查询 version 最大的 Region。limit 的默认值是 16。
示例：
region topsize [limit]用于查询 approximate size 最大的 Region。limit 的默认值是 16。
示例：
region check [miss-peer | extra-peer | down-peer | pending-peer | offline-peer | empty-region | hist-size | hist-keys] [--jq="<query string>"]用于查询处于异常状态的 Region，使用 jq 格式化输出请参考 jq 格式化 JSON 输出示例。
各类型的意义如下：
示例：
scheduler [show | add | remove | pause | resume | config | describe]用于显示和控制调度策略。
示例：
scheduler describe balance-region-scheduler用于查看 balance-region-scheduler 的运行状态和相应的诊断信息。
从 TiDB v6.3.0 起，PD 为 balance-region-scheduler 和 balance-leader-scheduler 提供了运行状态和简要诊断信息的功能，其余 scheduler 和 checker 暂未支持。你可以通过 pd-ctl 修改 enable-diagnostic 配置项开启该功能。
调度器运行状态有以下几种类型：
disabled：表示当前调度器不可用或被移除。paused：表示当前调度器暂停工作。scheduling：表示当前调度器正在生成调度。pending：表示当前调度器无法产生调度。pending 状态的调度器，会返回一个概览信息，来帮助用户诊断。概览信息包含了 store 的一些状态信息，解释了它们为什么不能被选中进行调度。normal：表示当前调度器无需进行调度。scheduler config balance-leader-scheduler用于查看和控制 balance-leader-scheduler 策略。
从 TiDB v6.0.0 起，PD 为 balance-leader-scheduler 引入了 Batch 参数，用于控制 balance-leader 执行任务的速度。你可以通过 pd-ctl 修改 balance-leader batch 配置项设置该功能。
在 v6.0.0 前，PD 不带有该配置（即 balance-leader batch=1）。在 v6.0.0 或更高版本中，balance-leader batch 的默认值为 4。如果你想为该配置项设置大于 4 的值，你需要同时调大 scheduler-max-waiting-operator（默认值 5）。同时调大两个配置项后，你才能体验预期的加速效果。
scheduler config balance-hot-region-scheduler用于查看和控制 balance-hot-region-scheduler 策略。
示例：
min-hot-byte-rate 指计数的最小字节数，通常为 100。
min-hot-key-rate 指计数的最小 key 数，通常为 10。
min-hot-query-rate 指计数的最小 query 数，通常为 10。
max-zombie-rounds 指一个 operator 可被纳入 pending influence 所允许的最大心跳次数。如果将它设置为更大的值，更多的 operator 可能会被纳入 pending influence。通常用户不需要修改这个值。pending influence 指的是在调度中产生的、但仍生效的影响。
max-peer-number 指最多要被解决的 peer 数量。这个配置可避免调度器处理速度过慢。
byte-rate-rank-step-ratio、key-rate-rank-step-ratio、query-rate-rank-step-ratio 和 count-rank-step-ratio 分别控制 byte、key、query 和 count 的 step ranks。rank-step-ratio 决定了计算 rank 时的 step 值。great-dec-ratio 和 minor-dec-ratio 控制 dec 的 rank。通常用户不需要修改这些配置项。
src-tolerance-ratio 和 dst-tolerance-ratio 是期望调度器的配置项。tolerance-ratio 的值越小，调度就越容易。当出现冗余调度时，你可以适当调大这个值。
read-priorities、write-leader-priorities 和 write-peer-priorities 用于控制调度器优先从哪些维度进行热点均衡，支持配置两个维度。
read-priorities 和 write-leader-priorities 用于控制调度器在处理 read 和 write-leader 类型的热点时优先均衡的维度，可选的维度有 query、byte 和 key。
write-peer-priorities 用于控制调度器在处理 write-peer 类型的热点时优先均衡的维度，支持配置 byte 和 key 维度。
strict-picking-store 是控制热点调度搜索空间的开关，通常为打开。该配置项仅影响 rank-formula-version 为 v1 时的行为。当打开时，热点调度的目标是保证所配置的两个维度的热点均衡。当关闭后，热点调度只保证处于第一优先级的维度的热点均衡表现更好，但可能会导致其他维度的热点不再那么均衡。通常用户不需要修改这个配置项。
rank-formula-version 适用于热点调度，其用来确定调度策略的算法版本，支持的值有 ["v1", "v2"]。目前该配置的默认值为 v2。
v1 版本为 v6.3.0 之前的策略，主要关注调度是否降低了不同 Store 之间的负载差值，以及是否在另一维度引入副作用。
v2 版本是 v6.3.0 引入的实验特性算法，在 v6.4.0 正式发布，主要关注 Store 之间均衡度的提升率，同时降低了对副作用的关注度。对比 strict-picking-store 为 true 的 v1 算法，v2 版本更注重优先均衡第一维度。对比 strict-picking-store 为 false 的 v1 算法，v2 版本兼顾了第二维度的均衡。
strict-picking-store 为 true 的 v1 版本算法较为保守，只有当存在两个维度的负载都偏高的 Store 时才能产生调度。在特定场景下有可能因为维度冲突导致无法继续均衡，需要将 strict-picking-store 改为 false 才能在第一维度取得更好的均衡效果。v2 版本算法则可以在两个维度都取得更好的均衡效果，并减少无效调度。
enable-for-tiflash 是控制热点调度是否对 TiFlash 生效的开关。通常为打开，关闭后将不会产生 TiFlash 实例之间的热点调度。
service-gc-safepoint用于查询当前的 GC safepoint 与 service GC safepoint，输出结果示例如下：
store [delete | cancel-delete | label | weight | remove-tombstone | limit ] <store_id> [--jq="<query string>"]使用 jq 格式化输出请参考 jq 格式化 json 输出示例。
显示所有 store 信息：
获取 id 为 1 的 store：
下线 id 为 1 的 store：
执行 store cancel-delete 命令，你可以撤销已使用 store delete 下线并处于 Offline 状态的 store。撤销后，该 store 会从 Offline 状态变为 Up 状态。注意，store cancel-delete 命令无法使 Tombstone 状态的 store 变回 Up 状态。
撤销通过 store delete 下线 id 为 1 的 store：
删除所有 Tombstone 状态的 store：
store label 命令用于管理 store label。
为 id 为 1 的 store 设置键为 "zone"、值为 "cn" 的 label：
更新 id 为 1 的 store 的 label：
通过 --rewrite 选项重写 id 为 1 的 store 的所有 label，之前的 label 会被覆盖：
删除 id 为 1 的 store 的键为 "disk" 的 label ：
将 id 为 1 的 store 的 leader weight 设为 5，Region weight 设为 10：
通过 store-limit，你可以设置 store 的调度速度。关于 store limit 的原理和使用方法，请参考 store limit。
log [fatal | error | warn | info | debug]用于设置 PD leader 的日志级别。
tso用于解析 TSO 到物理时间和逻辑时间。示例如下。
解析 TSO：
unsafe remove-failed-stores [store-ids | show]用于在多数副本永久损坏造成数据不可用时进行有损恢复。示例如下。详见 Online Unsafe Recovery。
执行 Online Unsafe Recovery，移除永久损坏的节点 (Store):
显示正在运行的 Online Unsafe Recovery 的当前状态或历史状态。
store 的输出例如副本数不为 3 的所有 Region：
例如在 store30 上有副本的所有 Region：
还可以像这样找出在 store30 或 store31 上有副本的所有 Region：
例如当 [store1, store30, store31] 宕机时不可用时，我们可以通过查找所有 Down 副本数量大于正常副本数量的所有 Region：
或者在 [store1, store30, store31] 无法启动时，找出 store1 上可以安全手动移除数据的 Region。我们可以这样过滤出所有在 store1 上有副本并且没有其他 DownPeer 的 Region：
在 [store30, store31] 宕机时，找出能安全地通过创建 remove-peer Operator 进行处理的所有 Region，即有且仅有一个 DownPeer 的 Region：