印刻数据库

外观

TiDB TiKV 控制工具详解 ​

tikv-ctl 是 TiKV 提供的命令行控制工具，用于管理和诊断 TiKV 集群，支持集群诊断、配置管理、数据管理、调试工具和 Raft 操作等功能。使用时需确保 tikv-ctl 版本与 TiKV 版本匹配，建议使用与 TiKV 集群相同版本的 tikv-ctl。

安装与配置 ​

安装方式 ​

通过 TiUP 安装 ​

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

# 安装 tikv 组件（包含 tikv-ctl）
tiup install tikv

# 直接使用 tiup 运行 tikv-ctl
tiup ctl tikv

手动编译安装 ​

bash
# 克隆 TiKV 代码库
git clone https://github.com/tikv/tikv.git
cd tikv

# 编译 tikv-ctl
cargo build --release --bin tikv-ctl

# 安装到系统路径
sudo cp target/release/tikv-ctl /usr/local/bin/

配置文件 ​

tikv-ctl 可以通过配置文件指定默认参数：

bash
# 创建配置文件目录
mkdir -p ~/.config/tikv

# 创建配置文件
cat > ~/.config/tikv/tikv-ctl.toml << EOF
# 默认 TiKV 地址
host = "127.0.0.1"
port = 20160

# 默认 PD 地址
pd = "http://127.0.0.1:2379"

# 默认数据目录
data-dir = "/path/to/tikv/data"
EOF

基本使用 ​

连接 TiKV 节点 ​

bash
# 连接本地 TiKV 节点
tiup ctl tikv --host 127.0.0.1 --port 20160 <command>

# 使用 PD 地址获取集群信息
tiup ctl tikv --pd http://<pd-host>:<pd-port> <command>

# 使用配置文件
tiup ctl tikv --config ~/.config/tikv/tikv-ctl.toml <command>

查看帮助信息 ​

bash
# 查看所有命令
tiup ctl tikv --help

# 查看特定命令的帮助
tiup ctl tikv <command> --help

核心功能详解 ​

1. 集群诊断 ​

查看节点状态 ​

bash
# 查看 TiKV 节点详细状态
tiup ctl tikv --host <tikv-host> --port <tikv-port> status

# 查看简化状态
tiup ctl tikv --host <tikv-host> --port <tikv-port> status --simple

状态信息包括：

  • 基本信息：版本、启动时间、监听地址
  • 性能指标：QPS、延迟、内存使用
  • Raft 状态：Raft 组数量、Leader 数量
  • 存储状态：总容量、已使用容量、Region 数量

查看监控指标 ​

bash
# 查看所有监控指标
tiup ctl tikv --host <tikv-host> --port <tikv-port> metrics

# 查看特定指标
tiup ctl tikv --host <tikv-host> --port <tikv-port> metrics | grep <metric-name>

查看日志 ​

bash
# 查看 TiKV 日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> log

# 查看特定级别日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> log --level error

# 查看最近 N 条日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> log --tail 100

2. Raft 管理 ​

查看 Raft 状态 ​

bash
# 查看所有 Raft 组状态
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft status

# 查看特定 Raft 组信息
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft region <region-id>

# 查看 Raft 日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft log <region-id>

Raft 操作 ​

bash
# 触发 Raft 快照
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft snapshot <region-id>

# 强制 Raft 选举
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft transfer-leader <region-id> <peer-id>

# 验证 Raft 日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft verify <region-id>

3. 数据管理 ​

查看 Region 信息 ​

bash
# 查看所有 Region 信息
tiup ctl tikv --pd <pd-host>:<pd-port> region list

# 查看特定 Region 信息
tiup ctl tikv --pd <pd-host>:<pd-port> region <region-id>

# 根据 Key 查找 Region
tiup ctl tikv --pd <pd-host>:<pd-port> region key <key>

# 查看 Region 分布
tiup ctl tikv --pd <pd-host>:<pd-port> region distribution

查看和修改数据 ​

bash
# 从本地数据目录读取数据
tiup ctl tikv --data-dir <data-dir> raw get <key>

# 从本地数据目录读取范围数据
tiup ctl tikv --data-dir <data-dir> raw scan <start-key> <end-key>

# 向本地数据目录写入数据
tiup ctl tikv --data-dir <data-dir> raw put <key> <value>

# 从本地数据目录删除数据
tiup ctl tikv --data-dir <data-dir> raw delete <key>

数据验证 ​

bash
# 验证数据完整性
tiup ctl tikv --data-dir <data-dir> checksum <start-key> <end-key>

# 验证 SST 文件
tiup ctl tikv --data-dir <data-dir> sst dump <sst-file>

4. 配置管理 ​

查看配置 ​

bash
# 查看当前 TiKV 配置
tiup ctl tikv --host <tikv-host> --port <tikv-port> config show

# 查看特定配置项
tiup ctl tikv --host <tikv-host> --port <tikv-port> config show <config-key>

# 查看配置文件
tiup ctl tikv --host <tikv-host> --port <tikv-port> config file

修改配置 ​

bash
# 动态修改 TiKV 配置
tiup ctl tikv --host <tikv-host> --port <tikv-port> config set <config-key> <config-value>

# 重置配置到默认值
tiup ctl tikv --host <tikv-host> --port <tikv-port> config reset <config-key>

5. 调试工具 ​

查看线程信息 ​

bash
# 查看 TiKV 线程信息
tiup ctl tikv --host <tikv-host> --port <tikv-port> threads

# 查看线程堆栈
tiup ctl tikv --host <tikv-host> --port <tikv-port> threads --stack

查看内存使用 ​

bash
# 查看 TiKV 内存使用情况
tiup ctl tikv --host <tikv-host> --port <tikv-port> memory

# 查看内存分配详情
tiup ctl tikv --host <tikv-host> --port <tikv-port> memory --detail

查看 RocksDB 状态 ​

bash
# 查看 RocksDB 状态
tiup ctl tikv --host <tikv-host> --port <tikv-port> rocksdb status

# 查看 RocksDB 统计信息
tiup ctl tikv --host <tikv-host> --port <tikv-port> rocksdb stats

# 查看 RocksDB 压缩状态
tiup ctl tikv --host <tikv-host> --port <tikv-port> rocksdb compaction-stats

高级功能 ​

1. 批量操作 ​

bash
# 批量查看多个 Region 信息
tiup ctl tikv --pd <pd-host>:<pd-port> region batch <region-id-1> <region-id-2> <region-id-3>

# 批量验证多个 Region 的 Raft 日志
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft batch-verify <region-id-1> <region-id-2>

2. 数据导入导出 ​

bash
# 导出 Region 数据
tiup ctl tikv --data-dir <data-dir> export <region-id> <output-file>

# 导入 Region 数据
tiup ctl tikv --data-dir <data-dir> import <region-id> <input-file>

3. 性能分析 ​

bash
# 生成火焰图
tiup ctl tikv --host <tikv-host> --port <tikv-port> profile --duration 30

# 查看 CPU 分析
tiup ctl tikv --host <tikv-host> --port <tikv-port> profile --type cpu

# 查看内存分析
tiup ctl tikv --host <tikv-host> --port <tikv-port> profile --type memory

最佳实践 ​

1. 生产环境使用建议 ​

  • 避免直接操作生产数据：除非必要，否则不要使用 tikv-ctl 直接修改生产环境数据
  • 使用 PD 地址获取集群信息：在集群环境中，建议使用 --pd 参数获取集群信息
  • 定期备份配置：在修改配置前，建议备份当前配置
  • 记录操作：在执行重要操作前，建议记录操作内容和预期结果
  • 测试环境验证：在生产环境执行操作前，建议先在测试环境验证

2. 故障排查流程 ​

  1. 检查节点状态：tiup ctl tikv status
  2. 查看日志：tiup ctl tikv log --level error
  3. 查看 Raft 状态：tiup ctl tikv raft status
  4. 查看监控指标：tiup ctl tikv metrics
  5. 分析线程和内存：tiup ctl tikv threads 和 tiup ctl tikv memory
  6. 验证数据完整性：tiup ctl tikv checksum

3. 常用命令组合 ​

bash
# 快速查看集群状态
tiup ctl pd -u http://<pd-host>:<pd-port> cluster && tiup ctl tikv --host <tikv-host> --port <tikv-port> status

# 查看热点 Region 并分析
tiup ctl pd -u http://<pd-host>:<pd-port> hot read && tiup ctl tikv --pd http://<pd-host>:<pd-port> region <hot-region-id>

# 诊断 Raft 问题
tiup ctl tikv --host <tikv-host> --port <tikv-port> raft status | grep -i error && tiup ctl tikv --host <tikv-host> --port <tikv-port> raft log <problematic-region-id>

常见问题（FAQ） ​

Q1: tikv-ctl 无法连接到 TiKV 节点怎么办？ ​

A1: 请检查以下几点：

  • TiKV 节点是否正常运行
  • TiKV 节点的地址和端口是否正确
  • 网络连接是否正常，防火墙是否开放了相应端口
  • TiKV 节点是否启用了安全认证，是否需要提供认证信息

Q2: 如何使用 tikv-ctl 查看特定 Key 的值？ ​

A2: 可以使用以下步骤：

  1. 先使用 PD Control 查找 Key 所在的 Region：tiup ctl pd -u http://pd-host:2379 region key key
  2. 然后使用 tikv-ctl 连接到对应的 TiKV 节点，查看数据：tiup ctl tikv --host tikv-host --port tikv-port raw get key

Q3: 如何修改 TiKV 的日志级别？ ​

A3: 可以使用以下命令动态修改：

bash
tiup ctl tikv --host <tikv-host> --port <tikv-port> config set log-level <level>

其中，<level> 可以是 debug、info、warn、error 或 fatal。

Q4: 如何查看 TiKV 节点的 RocksDB 版本？ ​

A4: 可以使用以下命令：

bash
tiup ctl tikv --host <tikv-host> --port <tikv-port> rocksdb status | grep -i version

Q5: tikv-ctl 与 tiup ctl tikv 有什么区别？ ​

A5: tikv-ctl 是原生的 TiKV 控制工具，而 tiup ctl tikv 是通过 TiUP 调用 tikv-ctl 工具。两者功能基本相同，但使用 TiUP 可以更方便地管理不同版本的 tikv-ctl 工具，避免版本兼容性问题。在生产环境中，建议使用 tiup ctl tikv 命令。