印刻数据库

外观

TiDB PD 控制工具 ​

PD 控制工具（pd-ctl）是 TiDB 集群中用于管理和监控 PD 集群的命令行工具，可用于查看集群状态、管理 Region 和 TiKV 节点、调整调度策略、查看和修改元数据以及进行故障诊断和处理。

PD 控制工具安装 ​

1. 使用 TiUP 安装 ​

bash
# 安装 TiUP
bash <(curl -fsSL https://tiup-mirrors.pingcap.com/install.sh)

# 使用 TiUP 运行 pd-ctl
tiup ctl pd

2. 独立安装 ​

bash
# 从 GitHub 下载 pd-ctl 二进制文件
wget https://github.com/pingcap/pd/releases/download/v<version>/pd-ctl-v<version>-linux-amd64.tar.gz

# 解压文件
tar -xzf pd-ctl-v<version>-linux-amd64.tar.gz

# 移动到可执行路径
mv pd-ctl-v<version>-linux-amd64/pd-ctl /usr/local/bin/

# 验证安装
pd-ctl --version

PD 控制工具连接 ​

1. 连接到 PD 集群 ​

bash
# 连接到 PD 集群
pd-ctl -u http://<pd-ip>:2379

# 使用 TLS 连接到 PD 集群
pd-ctl -u https://<pd-ip>:2379 --cacert=/path/to/ca.pem --cert=/path/to/client.pem --key=/path/to/client-key.pem

2. 交互式模式 ​

bash
# 进入交互式模式
pd-ctl -u http://<pd-ip>:2379

# 在交互式模式下执行命令
» member

3. 命令行模式 ​

bash
# 在命令行模式下执行命令
pd-ctl -u http://<pd-ip>:2379 member

常用命令 ​

1. 集群状态 ​

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

# 查看 PD 集群状态
pd-ctl -u http://<pd-ip>:2379 status

# 查看 PD 集群健康状态
pd-ctl -u http://<pd-ip>:2379 health

2. Region 管理 ​

bash
# 查看所有 Region 信息
pd-ctl -u http://<pd-ip>:2379 region

# 查看特定 Region 信息
pd-ctl -u http://<pd-ip>:2379 region <region-id>

# 查看 Region 分布
pd-ctl -u http://<pd-ip>:2379 region distribution

# 检查 Region 状态
pd-ctl -u http://<pd-ip>:2379 region check

3. TiKV 节点管理 ​

bash
# 查看所有 TiKV 节点信息
pd-ctl -u http://<pd-ip>:2379 store

# 查看特定 TiKV 节点信息
pd-ctl -u http://<pd-ip>:2379 store <store-id>

# 标记 TiKV 节点为下线
pd-ctl -u http://<pd-ip>:2379 store <store-id> state down

# 标记 TiKV 节点为上线
pd-ctl -u http://<pd-ip>:2379 store <store-id> state up

4. 调度管理 ​

bash
# 查看当前调度策略
pd-ctl -u http://<pd-ip>:2379 config show schedule

# 修改调度策略
pd-ctl -u http://<pd-ip>:2379 config set schedule.max-snapshot-count 6

# 查看当前调度操作
pd-ctl -u http://<pd-ip>:2379 operator show

# 取消特定调度操作
pd-ctl -u http://<pd-ip>:2379 operator remove <operator-id>

# 取消所有调度操作
pd-ctl -u http://<pd-ip>:2379 operator remove --all

5. 配置管理 ​

bash
# 查看 PD 集群配置
pd-ctl -u http://<pd-ip>:2379 config show

# 修改 PD 集群配置
pd-ctl -u http://<pd-ip>:2379 config set cluster-version v5.4.0

# 查看特定配置项
pd-ctl -u http://<pd-ip>:2379 config show replication

6. 元数据管理 ​

bash
# 查看 PD 集群元数据
pd-ctl -u http://<pd-ip>:2379 metadata

# 查看 PD 集群 TSO
pd-ctl -u http://<pd-ip>:2379 tso

# 查看 PD 集群 GC 配置
pd-ctl -u http://<pd-ip>:2379 config show gc

调度策略调整 ​

1. 调整 Region 调度 ​

bash
# 调整 Region 分裂和合并的间隔时间
pd-ctl -u http://<pd-ip>:2379 config set schedule.split-merge-interval 30m

# 调整允许合并的最大 Region 大小
pd-ctl -u http://<pd-ip>:2379 config set schedule.max-merge-region-size 20

# 调整允许合并的最大 Region 键数量
pd-ctl -u http://<pd-ip>:2379 config set schedule.max-merge-region-keys 200000

# 启用跨表合并 Region
pd-ctl -u http://<pd-ip>:2379 config set schedule.enable-cross-table-merge true

2. 调整副本调度 ​

bash
# 调整最大副本数
pd-ctl -u http://<pd-ip>:2379 config set replication.max-replicas 3

# 调整副本放置的标签
pd-ctl -u http://<pd-ip>:2379 config set replication.location-labels ["zone","rack","host"]

# 调整副本调度的优先级
pd-ctl -u http://<pd-ip>:2379 config set schedule.replica-schedule-limit 64

3. 调整热点调度 ​

bash
# 调整热点调度的阈值
pd-ctl -u http://<pd-ip>:2379 config set schedule.hot-region-schedule-limit 4

# 调整热点调度的冷却时间
pd-ctl -u http://<pd-ip>:2379 config set schedule.hot-region-cache-hits-threshold 3

故障诊断和处理 ​

1. 查看异常 Region ​

bash
# 查看异常 Region
pd-ctl -u http://<pd-ip>:2379 region check

# 查看 pending peer
pd-ctl -u http://<pd-ip>:2379 operator show | grep pending

2. 处理 TiKV 节点故障 ​

bash
# 标记故障 TiKV 节点为下线
pd-ctl -u http://<pd-ip>:2379 store <store-id> state down

# 查看 Region 迁移进度
pd-ctl -u http://<pd-ip>:2379 operator show

# 强制移除故障 TiKV 节点上的 Region
pd-ctl -u http://<pd-ip>:2379 unsafe remove-fail-stores <store-id>

3. 处理 Region 分裂和合并问题 ​

bash
# 手动分裂 Region
pd-ctl -u http://<pd-ip>:2379 region split --region <region-id> --policy approximate

# 手动合并 Region
pd-ctl -u http://<pd-ip>:2379 operator add merge-region <region-id-1> <region-id-2>

PD 控制工具最佳实践 ​

1. 定期检查集群状态 ​

  • 定期使用 pd-ctl 检查 PD 集群状态
  • 关注 Region 分布、TiKV 节点状态和调度操作
  • 及时发现和处理异常情况

2. 合理调整调度策略 ​

  • 根据集群规模和业务需求调整调度策略
  • 避免设置过于激进的调度参数，导致集群不稳定
  • 定期监控调度效果，根据实际情况调整

3. 谨慎使用危险命令 ​

  • 对于 unsafe 开头的命令，要谨慎使用
  • 在生产环境中使用前，务必在测试环境中验证
  • 执行危险命令前，备份重要数据

4. 结合监控工具使用 ​

  • 将 pd-ctl 与 Prometheus + Grafana 结合使用
  • 通过监控数据了解集群状态，使用 pd-ctl 进行具体操作
  • 建立监控和操作的闭环

5. 自动化操作 ​

  • 将常用的 pd-ctl 命令脚本化，实现自动化操作
  • 结合监控系统，实现自动化的故障处理
  • 建立标准化的操作流程

常见问题（FAQ） ​

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

A1: 可以从以下几个方面排查：

  • 检查 PD 集群是否正常运行
  • 检查 PD 节点的网络连接是否正常
  • 检查 PD 节点的端口是否开放
  • 检查 TLS 配置是否正确（如果使用了 TLS）

Q2: 如何查看 PD 集群的版本？ ​

A2: 可以使用以下命令查看 PD 集群的版本：

bash
pd-ctl -u http://<pd-ip>:2379 config show cluster-version

Q3: 如何调整 PD 集群的 GC 时间？ ​

A3: 可以使用以下命令调整 PD 集群的 GC 时间：

bash
pd-ctl -u http://<pd-ip>:2379 config set gc.enable true
pd-ctl -u http://<pd-ip>:2379 config set gc.leader-schedule-limit 4
pd-ctl -u http://<pd-ip>:2379 config set gc.safe-point 2023-01-01T00:00:00+08:00

Q4: 如何查看热点 Region？ ​

A4: 可以使用以下命令查看热点 Region：

bash
pd-ctl -u http://<pd-ip>:2379 hot region

Q5: 如何手动触发 Region 调度？ ​

A5: 可以使用以下命令手动触发 Region 调度：

bash
# 手动调度特定 Region
pd-ctl -u http://<pd-ip>:2379 operator add transfer-leader <region-id> <store-id>

# 手动平衡 Region
pd-ctl -u http://<pd-ip>:2379 operator add balance-leader

Q6: 如何查看 PD 集群的调度统计信息？ ​

A6: 可以使用以下命令查看 PD 集群的调度统计信息：

bash
pd-ctl -u http://<pd-ip>:2379 stats schedule