印刻数据库

外观

PD 控制工具 ​

PD（Placement Driver）是 TiDB 集群的核心组件之一，负责管理 TiKV 集群的元数据、调度 Region、处理节点上下线等。pd-ctl 是 PD 官方提供的命令行工具，用于管理和监控 PD 集群。通过 pd-ctl，您可以查看 PD 集群的状态、调整调度策略、管理 Region 等。本文档介绍 pd-ctl 工具的安装、配置和使用方法。

pd-ctl 工具介绍 ​

pd-ctl 是 PD 官方提供的命令行工具，用于管理和监控 PD 集群。通过 pd-ctl，您可以：

  • 查看 PD 集群的状态和监控指标
  • 调整 PD 集群的调度策略和参数
  • 管理 Region 和 Store
  • 处理节点上下线
  • 查看和修改 PD 集群的配置

pd-ctl 安装 ​

1. 使用 TiUP 安装 ​

bash
# 安装 pd-ctl
tiup install pd-ctl

# 查看 pd-ctl 版本
tiup pd-ctl --version

2. 从源码编译 ​

bash
# 克隆 PD 源码
mkdir -p $GOPATH/src/github.com/pingcap
cd $GOPATH/src/github.com/pingcap
git clone https://github.com/pingcap/pd.git

# 进入 pd-ctl 目录
cd pd/cmd/pd-ctl

# 编译 pd-ctl
go build -o pd-ctl

# 将 pd-ctl 移动到 PATH 目录
mv pd-ctl /usr/local/bin/

3. 从 PD 二进制包获取 ​

您也可以从 PD 二进制包中获取 pd-ctl 工具。下载 PD 二进制包后，解压即可得到 pd-ctl 可执行文件。

bash
# 下载 PD 二进制包
wget https://download.pingcap.org/pd-v7.5.0-linux-amd64.tar.gz

# 解压 PD 二进制包
tar -xzf pd-v7.5.0-linux-amd64.tar.gz

# 进入 PD 目录
cd pd-v7.5.0-linux-amd64

# 将 pd-ctl 移动到 PATH 目录
mv pd-ctl /usr/local/bin/

pd-ctl 基本用法 ​

1. 连接 PD 集群 ​

使用 pd-ctl 连接 PD 集群时，需要指定 PD 集群的地址和端口。默认情况下，PD 集群的端口为 2379。

bash
# 连接 PD 集群
tiup pd-ctl -u http://<pd-host>:<pd-port>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379

2. 查看帮助信息 ​

bash
# 查看 pd-ctl 帮助信息
tiup pd-ctl --help

# 在 pd-ctl 交互模式下查看帮助信息
help

3. 查看版本信息 ​

bash
# 查看 pd-ctl 版本信息
tiup pd-ctl --version

pd-ctl 主要功能 ​

1. 查看 PD 集群状态 ​

查看 PD 集群成员信息 ​

bash
# 查看 PD 集群成员信息
tiup pd-ctl -u http://127.0.0.1:2379 member

查看 PD 集群状态 ​

bash
# 查看 PD 集群状态
tiup pd-ctl -u http://127.0.0.1:2379 cluster

查看 PD Leader 信息 ​

bash
# 查看 PD Leader 信息
tiup pd-ctl -u http://127.0.0.1:2379 leader

2. 查看 Store 信息 ​

查看所有 Store 信息 ​

bash
# 查看所有 Store 信息
tiup pd-ctl -u http://127.0.0.1:2379 store

查看指定 Store 信息 ​

bash
# 查看指定 Store 信息
tiup pd-ctl -u http://127.0.0.1:2379 store <store-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 store 1

查看 Store 统计信息 ​

bash
# 查看 Store 统计信息
tiup pd-ctl -u http://127.0.0.1:2379 store --stat

3. 查看 Region 信息 ​

查看所有 Region 信息 ​

bash
# 查看所有 Region 信息
tiup pd-ctl -u http://127.0.0.1:2379 region

查看指定 Region 信息 ​

bash
# 查看指定 Region 信息
tiup pd-ctl -u http://127.0.0.1:2379 region <region-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 region 1

查看指定 Key 对应的 Region 信息 ​

bash
# 查看指定 Key 对应的 Region 信息
tiup pd-ctl -u http://127.0.0.1:2379 region key <key>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 region key "t\x00\x00\x00\x00\x00\x00\x00\x01_r\x00\x00\x00\x00\x00\x00\x00\x01"

查看 Region 统计信息 ​

bash
# 查看 Region 统计信息
tiup pd-ctl -u http://127.0.0.1:2379 region --stat

4. 调整调度策略 ​

查看当前调度策略 ​

bash
# 查看当前调度策略
tiup pd-ctl -u http://127.0.0.1:2379 config show scheduler

开启调度器 ​

bash
# 开启调度器
tiup pd-ctl -u http://127.0.0.1:2379 scheduler enable <scheduler-name>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 scheduler enable balance-region

关闭调度器 ​

bash
# 关闭调度器
tiup pd-ctl -u http://127.0.0.1:2379 scheduler disable <scheduler-name>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 scheduler disable balance-region

添加调度器 ​

bash
# 添加调度器
tiup pd-ctl -u http://127.0.0.1:2379 scheduler add <scheduler-type> <scheduler-args>

# 例如：添加 balance-leader 调度器
tiup pd-ctl -u http://127.0.0.1:2379 scheduler add balance-leader

删除调度器 ​

bash
# 删除调度器
tiup pd-ctl -u http://127.0.0.1:2379 scheduler remove <scheduler-name>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 scheduler remove balance-region-1

5. 调整调度参数 ​

查看当前调度参数 ​

bash
# 查看当前调度参数
tiup pd-ctl -u http://127.0.0.1:2379 config show

修改调度参数 ​

bash
# 修改调度参数
tiup pd-ctl -u http://127.0.0.1:2379 config set <param-name> <param-value>

# 例如：修改 region-score-formula 参数
tiup pd-ctl -u http://127.0.0.1:2379 config set region-score-formula v2

# 例如：修改 max-snapshot-count 参数
tiup pd-ctl -u http://127.0.0.1:2379 config set max-snapshot-count 64

6. 管理 Store ​

标记 Store 为下线 ​

bash
# 标记 Store 为下线
tiup pd-ctl -u http://127.0.0.1:2379 store delete <store-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 store delete 1

标记 Store 为上线 ​

bash
# 标记 Store 为上线
tiup pd-ctl -u http://127.0.0.1:2379 store resume <store-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 store resume 1

设置 Store 标签 ​

bash
# 设置 Store 标签
tiup pd-ctl -u http://127.0.0.1:2379 store label <store-id> <label-key> <label-value>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 store label 1 zone zone1

7. 管理 Region ​

拆分 Region ​

bash
# 拆分 Region
tiup pd-ctl -u http://127.0.0.1:2379 operator add split-region <region-id> <split-key>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 operator add split-region 1 "t\x00\x00\x00\x00\x00\x00\x00\x01_r\x00\x00\x00\x00\x00\x00\x00\x02"

合并 Region ​

bash
# 合并 Region
tiup pd-ctl -u http://127.0.0.1:2379 operator add merge-region <region-id1> <region-id2>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 operator add merge-region 1 2

转移 Region Leader ​

bash
# 转移 Region Leader
tiup pd-ctl -u http://127.0.0.1:2379 operator add transfer-leader <region-id> <target-store-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 operator add transfer-leader 1 2

转移 Region Peer ​

bash
# 转移 Region Peer
tiup pd-ctl -u http://127.0.0.1:2379 operator add transfer-peer <region-id> <source-store-id> <target-store-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 operator add transfer-peer 1 2 3

8. 查看和管理 Operator ​

查看当前 Operator ​

bash
# 查看当前 Operator
tiup pd-ctl -u http://127.0.0.1:2379 operator

移除指定 Operator ​

bash
# 移除指定 Operator
tiup pd-ctl -u http://127.0.0.1:2379 operator remove <operator-id>

# 例如：
tiup pd-ctl -u http://127.0.0.1:2379 operator remove transfer-leader-1-2

移除所有 Operator ​

bash
# 移除所有 Operator
tiup pd-ctl -u http://127.0.0.1:2379 operator remove

9. 查看监控指标 ​

查看 PD 监控指标 ​

bash
# 查看 PD 监控指标
tiup pd-ctl -u http://127.0.0.1:2379 metrics

查看 PD 监控指标（JSON 格式） ​

bash
# 查看 PD 监控指标（JSON 格式）
tiup pd-ctl -u http://127.0.0.1:2379 metrics --json

pd-ctl 最佳实践 ​

1. 合理使用 pd-ctl ​

  • 监控集群状态：定期使用 pd-ctl 查看 PD 集群的状态和监控指标，及时发现和解决问题
  • 调整调度策略：根据集群的实际情况，合理调整 PD 集群的调度策略和参数
  • 管理 Region：在需要时，使用 pd-ctl 拆分、合并或转移 Region
  • 处理节点上下线：在节点需要维护或替换时，使用 pd-ctl 标记节点为下线或上线

2. 注意事项 ​

  • 权限控制：pd-ctl 工具需要连接到 PD 集群的 API 端口（默认为 2379），请确保该端口的访问权限
  • 谨慎修改配置：修改 PD 集群配置参数时，请谨慎操作，避免因配置不当导致集群异常
  • 版本兼容性：pd-ctl 工具的版本应与 PD 集群的版本保持一致，避免因版本不兼容导致功能异常
  • 备份配置：在修改 PD 集群配置前，请备份当前配置，以便在出现问题时快速恢复

常见问题（FAQ） ​

Q1: pd-ctl 工具无法连接到 PD 集群怎么办？ ​

A1: 请检查以下几点：

  • 确保 PD 集群正在运行
  • 确保 PD 集群的 API 端口（默认为 2379）已开放
  • 确保 pd-ctl 工具的版本与 PD 集群的版本兼容
  • 检查网络连接是否正常

Q2: 如何使用 pd-ctl 查看 PD 集群的 Leader 信息？ ​

A2: 可以使用以下命令查看 PD 集群的 Leader 信息：

bash
tiup pd-ctl -u http://pd-host:pd-port leader

Q3: 如何使用 pd-ctl 调整 PD 集群的调度参数？ ​

A3: 可以使用以下命令调整 PD 集群的调度参数：

bash
tiup pd-ctl -u http://pd-host:pd-port config set param-name param-value

Q4: 如何使用 pd-ctl 标记 Store 为下线？ ​

A4: 可以使用以下命令标记 Store 为下线：

bash
tiup pd-ctl -u http://pd-host:pd-port store delete store-id

Q5: 如何使用 pd-ctl 查看当前的调度器？ ​

A5: 可以使用以下命令查看当前的调度器：

bash
tiup pd-ctl -u http://pd-host:pd-port config show scheduler

Q6: 如何使用 pd-ctl 开启或关闭调度器？ ​

A6: 可以使用以下命令开启或关闭调度器：

bash
# 开启调度器
tiup pd-ctl -u http://pd-host:pd-port scheduler enable scheduler-name

# 关闭调度器
tiup pd-ctl -u http://pd-host:pd-port scheduler disable scheduler-name

Q7: 如何使用 pd-ctl 查看指定 Key 对应的 Region 信息？ ​

A7: 可以使用以下命令查看指定 Key 对应的 Region 信息：

bash
tiup pd-ctl -u http://pd-host:pd-port region key key

Q8: 如何使用 pd-ctl 移除所有 Operator？ ​

A8: 可以使用以下命令移除所有 Operator：

bash
tiup pd-ctl -u http://pd-host:pd-port operator remove

Q9: 如何使用 pd-ctl 查看 PD 集群的监控指标？ ​

A9: 可以使用以下命令查看 PD 集群的监控指标：

bash
tiup pd-ctl -u http://pd-host:pd-port metrics

Q10: 如何使用 pd-ctl 添加新的调度器？ ​

A10: 可以使用以下命令添加新的调度器：

bash
tiup pd-ctl -u http://pd-host:pd-port scheduler add scheduler-type scheduler-args

pd-ctl 命令参考 ​

1. 集群管理命令 ​

命令描述示例
member查看 PD 集群成员信息tiup pd-ctl member
cluster查看 PD 集群状态tiup pd-ctl cluster
leader查看 PD 集群 Leader 信息tiup pd-ctl leader
metrics查看 PD 集群监控指标tiup pd-ctl metrics

2. Store 管理命令 ​

命令描述示例
store查看所有 Store 信息tiup pd-ctl store
store store-id查看指定 Store 信息tiup pd-ctl store 1
store --stat查看 Store 统计信息tiup pd-ctl store --stat
store delete store-id标记 Store 为下线tiup pd-ctl store delete 1
store resume store-id标记 Store 为上线tiup pd-ctl store resume 1
store label store-id key value设置 Store 标签tiup pd-ctl store label 1 zone zone1

3. Region 管理命令 ​

命令描述示例
region查看所有 Region 信息tiup pd-ctl region
region region-id查看指定 Region 信息tiup pd-ctl region 1
region key key查看指定 Key 对应的 Region 信息tiup pd-ctl region key "t\x00\x00\x00\x00\x00\x00\x00\x01_r\x00\x00\x00\x00\x00\x00\x00\x01"
region --stat查看 Region 统计信息tiup pd-ctl region --stat

4. 调度管理命令 ​

命令描述示例
config show查看 PD 集群配置tiup pd-ctl config show
config show scheduler查看 PD 集群调度器配置tiup pd-ctl config show scheduler
config set param value修改 PD 集群配置tiup pd-ctl config set region-score-formula v2
scheduler查看当前调度器tiup pd-ctl scheduler
scheduler enable name开启调度器tiup pd-ctl scheduler enable balance-region
scheduler disable name关闭调度器tiup pd-ctl scheduler disable balance-region
scheduler add type [args]添加调度器tiup pd-ctl scheduler add balance-leader
scheduler remove name删除调度器tiup pd-ctl scheduler remove balance-region-1

5. Operator 管理命令 ​

命令描述示例
operator查看当前 Operatortiup pd-ctl operator
operator remove移除所有 Operatortiup pd-ctl operator remove
operator remove id移除指定 Operatortiup pd-ctl operator remove transfer-leader-1-2
operator add split-region region-id key添加拆分 Region Operatortiup pd-ctl operator add split-region 1 "t\x00\x00\x00\x00\x00\x00\x00\x01_r\x00\x00\x00\x00\x00\x00\x00\x02"
operator add merge-region region-id1 region-id2添加合并 Region Operatortiup pd-ctl operator add merge-region 1 2
operator add transfer-leader region-id store-id添加转移 Leader Operatortiup pd-ctl operator add transfer-leader 1 2
operator add transfer-peer region-id from-store-id to-store-id添加转移 Peer Operatortiup pd-ctl operator add transfer-peer 1 2 3

pd-ctl 交互模式 ​

除了使用命令行参数执行 pd-ctl 命令外，您还可以进入 pd-ctl 的交互模式，在交互模式下执行多个命令。

1. 进入交互模式 ​

bash
# 进入 pd-ctl 交互模式
tiup pd-ctl -u http://pd-host:pd-port

2. 在交互模式下执行命令 ​

在 pd-ctl 交互模式下，您可以直接输入命令，无需再次指定 PD 集群的地址和端口。

bash
# 查看 PD 集群成员信息
member

# 查看所有 Store 信息
store

# 查看所有 Region 信息
region

# 查看当前调度器
config show scheduler

3. 退出交互模式 ​

在 pd-ctl 交互模式下，您可以使用以下命令退出：

bash
# 退出 pd-ctl 交互模式
exit

或使用 Ctrl+D 快捷键退出。