TiKV Control 使用说明

TiKV Control（以下简称 tikv-ctl）是 TiKV 的命令行工具，用于管理 TiKV 集群。它的安装目录如下：

  • 如果是使用 TiDB Ansible 部署的集群，在 ansible 目录下的 resources/bin 子目录下。
  • 如果是使用 TiUP 部署的集群，在 ~/.tiup/components/ctl/{VERSION}/ 目录下。

通过 TiUP 使用 TiKV Control

tikv-ctl 也集成在了 tiup 命令中。执行以下命令，即可调用 tikv-ctl 工具：

  1. tiup ctl tikv
  1. Starting component `ctl`: /home/tidb/.tiup/components/ctl/v4.0.8/ctl tikv
  2. TiKV Control (tikv-ctl) 
  3. Release Version:   4.0.8
  4. Edition:           Community
  5. Git Commit Hash:   83091173e960e5a0f5f417e921a0801d2f6635ae
  6. Git Commit Branch: heads/refs/tags/v4.0.8
  7. UTC Build Time:    2020-10-30 08:40:33
  8. Rust Version:      rustc 1.42.0-nightly (0de96d37f 2019-12-19)
  9. Enable Features:   jemalloc mem-profiling portable sse protobuf-codec
  10. Profile:           dist_release
  12. A tool for interacting with TiKV deployments.
  14. USAGE:
  15.     TiKV Control (tikv-ctl) [FLAGS] [OPTIONS] [SUBCOMMAND]
  17. FLAGS:
  18.     -h, --help                    Prints help information
  19.         --skip-paranoid-checks    Skip paranoid checks when open rocksdb
  20.     -V, --version                 Prints version information
  22. OPTIONS:
  23.         --ca-path <ca_path>              Set the CA certificate path
  24.         --cert-path <cert_path>          Set the certificate path
  25.         --config <config>                Set the config for rocksdb
  26.         --db <db>                        Set the rocksdb path
  27.         --decode <decode>                Decode a key in escaped format
  28.         --encode <encode>                Encode a key in escaped format
  29.         --to-hex <escaped-to-hex>        Convert an escaped key to hex key
  30.         --to-escaped <hex-to-escaped>    Convert a hex key to escaped key
  31.         --host <host>                    Set the remote host
  32.         --key-path <key_path>            Set the private key path
  33.         --pd <pd>                        Set the address of pd
  34.         --raftdb <raftdb>                Set the raft rocksdb path
  36. SUBCOMMANDS:
  37.     bad-regions           Get all regions with corrupt raft
  38.     cluster               Print the cluster id
  39.     compact               Compact a column family in a specified range
  40.     compact-cluster       Compact the whole cluster in a specified range in one or more column families
  41.     consistency-check     Force a consistency-check for a specified region
  42.     decrypt-file          Decrypt an encrypted file
  43.     diff                  Calculate difference of region keys from different dbs
  44.     dump-snap-meta        Dump snapshot meta file
  45.     encryption-meta       Dump encryption metadata
  46.     fail                  Inject failures to TiKV and recovery
  47.     help                  Prints this message or the help of the given subcommand(s)
  48.     metrics               Print the metrics
  49.     modify-tikv-config    Modify tikv config, eg. tikv-ctl --host ip:port modify-tikv-config -n
  50.                           rocksdb.defaultcf.disable-auto-compactions -v true
  51.     mvcc                  Print the mvcc value
  52.     print                 Print the raw value
  53.     raft                  Print a raft log entry
  54.     raw-scan              Print all raw keys in the range
  55.     recover-mvcc          Recover mvcc data on one node by deleting corrupted keys
  56.     recreate-region       Recreate a region with given metadata, but alloc new id for it
  57.     region-properties     Show region properties
  58.     scan                  Print the range db range
  59.     size                  Print region size
  60.     split-region          Split the region
  61.     store                 Print the store id
  62.     tombstone             Set some regions on the node to tombstone by manual
  63.     unsafe-recover        Unsafely recover the cluster when the majority replicas are failed

你可以在 tiup ctl tikv 后面再接上相应的参数与子命令。

通用参数

tikv-ctl 提供以下两种运行模式：

  • 远程模式。通过 --host 选项接受 TiKV 的服务地址作为参数。在此模式下，如果 TiKV 启用了 SSL，则 tikv-ctl 也需要指定相关的证书文件，例如：

    1.   tikv-ctl --ca-path ca.pem --cert-path client.pem --key-path client-key.pem --host 127.0.0.1:20160 <subcommands>

    某些情况下，tikv-ctl 与 PD 进行通信，而不与 TiKV 通信。此时你需要使用 --pd 选项而非 --host 选项，例如：

    1.   tikv-ctl --pd 127.0.0.1:2379 compact-cluster
    1.   store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success!

  • 本地模式。通过 --db 选项来指定本地 TiKV 数据的目录路径。在此模式下，需要停止正在运行的 TiKV 实例。

以下如无特殊说明，所有命令都同时支持这两种模式。

除此之外，tikv-ctl 还有两个简单的命令 --to-hex 和 --to-escaped，用于对 key 的形式作简单的变换。一般使用 escaped 形式，示例如下：

  1. tikv-ctl --to-escaped 0xaaff
  1. \252\377
  1. tikv-ctl --to-hex "\252\377"
  1. AAFF

注意：

在命令行上指定 escaped 形式的 key 时，需要用双引号引起来，否则 bash 会将反斜杠吃掉，导致结果错误。

各项子命令及部分参数、选项

下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数，要查看全部细节，可运行 tikv-ctl --help <subcommand>。

查看 Raft 状态机的信息

raft 子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 RegionLocalState、RaftLocalState 和 RegionApplyState 三个结构体，及某一条 log 对应的 Entries。

你可以使用 region 和 log 两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。其用法及输出内容如下所示：

  1. tikv-ctl --host 127.0.0.1:20160 raft region -r 2
  1. region id: 2
  2. region state key: \001\003\000\000\000\000\000\000\000\002\001
  3. region state: Some(region {id: 2 region_epoch {conf_ver: 3 version: 1} peers {id: 3 store_id: 1} peers {id: 5 store_id: 4} peers {id: 7 store_id: 6}})
  4. raft state key: \001\002\000\000\000\000\000\000\000\002\002
  5. raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617)
  6. apply state key: \001\002\000\000\000\000\000\000\000\002\003
  7. apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151})

查看 Region 的大小

使用 size 命令可以查看 Region 的大小：

  1. tikv-ctl --db /path/to/tikv/db size -r 2
  1. region id: 2
  2. cf default region size: 799.703 MB
  3. cf write region size: 41.250 MB
  4. cf lock region size: 27616

扫描查看给定范围的 MVCC

scan 命令的 --from 和 --to 参数接受两个 escaped 形式的 raw key，并用 --show-cf 参数指定只需要查看哪些列族。

  1. tikv-ctl --db /path/to/tikv/db scan --from 'zm' --limit 2 --show-cf lock,default,write
  1. key: zmBootstr\377a\377pKey\000\000\377\000\000\373\000\000\000\000\000\377\000\000s\000\000\000\000\000\372
  2.          write cf value: start_ts: 399650102814441473 commit_ts: 399650102814441475 short_value: "20"
  3. key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371
  4.          write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002"
  5.          write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001"

查看给定 key 的 MVCC

与 scan 命令类似，mvcc 命令可以查看给定 key 的 MVCC：

  1. tikv-ctl --db /path/to/tikv/db mvcc -k "zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371" --show-cf=lock,write,default
  1. key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371
  2.          write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002"
  3.          write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001"

注意：

该命令中，key 同样需要是 escaped 形式的 raw key。

打印某个 key 的值

打印某个 key 的值需要用到 print 命令。示例从略。

打印 Region 的 properties 信息

为了记录 Region 的状态信息，TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 region-properties 运行 tikv-ctl 来查看这些 properties 信息。例如：

  1. tikv-ctl --host localhost:20160 region-properties -r 2
  1. num_files: 0
  2. num_entries: 0
  3. num_deletes: 0
  4. mvcc.min_ts: 18446744073709551615
  5. mvcc.max_ts: 0
  6. mvcc.num_rows: 0
  7. mvcc.num_puts: 0
  8. mvcc.num_versions: 0
  9. mvcc.max_row_versions: 0
  10. middle_key_by_approximate_size:

这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如，使用 middle_key_approximate_size 可以手动分裂 Region。

手动 compact 单个 TiKV 的数据

compact 命令可以对单个 TiKV 进行手动 compact。如果指定 --from 和 --to 选项，那么它们的参数也是 escaped raw key 形式的。

  • --host 参数可以指定要 compact 的 TiKV。
  • -d 参数可以指定要 compact 的 RocksDB，有 kv 和 raft 参数值可以选。
  • --threads 参数可以指定 compact 的并发数，默认值是 8。一般来说，并发数越大，compact 的速度越快，但是也会对服务造成影响，所以需要根据情况选择合适的并发数。
  1. tikv-ctl --host 127.0.0.1:20160 compact -d kv
  1. success!

手动 compact 整个 TiKV 集群的数据

compact-cluster 命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 compact 命令一样。

设置一个 Region 副本为 tombstone 状态

tombstone 命令常用于没有开启 sync-log，因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 的副本设置为 Tombstone 状态，从而在重启时跳过这些 Region，避免因为这些 Region 的副本的 Raft 状态机损坏而无法启动服务。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。

一般情况下，可以先在 PD 上将 Region 的副本通过 remove-peer 命令删除掉：

  1. pd-ctl>> operator add remove-peer <region_id> <store_id>

然后再用 tikv-ctl 在那个 TiKV 实例上将 Region 的副本标记为 tombstone 以便跳过启动时对他的健康检查：

  1. tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r <region_id>
  1. success!

但是有些情况下，当不能方便地从 PD 上移除这个副本时，可以指定 tikv-ctl 的 --force 选项来强制设置它为 tombstone：

  1. tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r <region_id>,<region_id> --force
  1. success!

注意：

  • 该命令只支持本地模式
  • -p 选项的参数指定 PD 的 endpoints，无需 http 前缀。指定 PD 的 endpoints 是为了询问 PD 是否可以安全切换至 Tombstone 状态。

向 TiKV 发出 consistency-check 请求

consistency-check 命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败，TiKV 自身会 panic。如果 --host 指定的 TiKV 不是这个 Region 的 Leader，则会报告错误。

  1. tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2
  1. success!
  1. tikv-ctl --host 127.0.0.1:20161 consistency-check -r 2
  1. DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, details: Some("StringError(\"Leader is on store 1\")") })

注意：

  • 该命令只支持远程模式。
  • 即使该命令返回了成功信息，也需要检查是否有 TiKV panic 了。因为该命令只是向 Leader 请求进行一致性检查，但整个检查流程是否成功并不能在客户端知道。

Dump snapshot 元文件

这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。

打印 Raft 状态机出错的 Region

前面 tombstone 命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态，避免 TiKV 启动时对它们进行检查。在运行 tombstone 命令之前，可使用 bad-regions 命令找到出错的 Region，以便将多个工具组合起来进行自动化的处理。

  1. tikv-ctl --db /path/to/tikv/db bad-regions
  1. all regions are healthy

命令执行成功后会打印以上信息，否则会打印出有错误的 Region 列表。目前可以检出的错误包括 last index、commit index 和 apply index 之间的不匹配，以及 Raft log 的丢失。其他一些情况，比如 Snapshot 文件损坏等仍然需要后续的支持。

查看 Region 属性

本地查看部署在 /path/to/tikv 的 TiKV 上面 Region 2 的 properties 信息：

  1. tikv-ctl --db /path/to/tikv/data/db region-properties -r 2

在线查看运行在 127.0.0.1:20160 的 TiKV 上面 Region 2 的 properties 信息：

  1. tikv-ctl --host 127.0.0.1:20160 region-properties -r 2

动态修改 TiKV 的配置

使用 modify-tikv-config 命令可以动态修改配置参数。目前可动态修改的 TiKV 配置与具体的修改行为与 SQL 动态修改配置功能相同，可参考在线修改 TiKV 配置。

  • -n 用于指定完整的配置名。支持动态修改的配置名可以参考在线修改 TiKV 配置中支持的配置项列表。
  • -v 用于指定配置值。

设置 shared block cache 的大小：

  1. tikv-ctl --host ip:port modify-tikv-config -n storage.block-cache.capacity -v 10GB
  1. success

当禁用 shared block cache 时，为 write CF 设置 block cache size：

  1. tikv-ctl --host ip:port modify-tikv-config -n rocksdb.writecf.block-cache-size -v 256MB
  1. success
  1. tikv-ctl --host ip:port modify-tikv-config -n raftdb.defaultcf.disable-auto-compactions -v true
  1. success
  1. tikv-ctl --host ip:port modify-tikv-config -n raftstore.sync-log -v false
  1. success

强制 Region 从多副本失败状态恢复服务

unsafe-recover remove-fail-stores 命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前，需要目标 TiKV 先停掉服务以便释放文件锁。

-s 选项接受多个以逗号分隔的 store_id，并使用 -r 参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作，可简单指定 --all-regions。

  1. tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 3 -r 1001,1002
  1. success!
  1. tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 4,5 --all-regions

之后启动 TiKV，这些 Region 便可以使用剩下的健康副本继续提供服务了。此命令常用于多个 TiKV store 损坏或被删除的情况。

注意：

  • 该命令只支持本地模式。在运行成功后，会打印 success!。
  • 一般来说，您需要为指定 Region 的 peers 所在的每个 store 运行此命令。
  • 如果使用 --all-regions，通常需要在集群剩余所有健康的 store 上执行此命令。

恢复损坏的 MVCC 数据

recover-mvcc 命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复，该命令会交叉检查 3 个 CF (“default”, “write”, “lock”)。

  • -r 选项可以通过 region_id 指定包含的 Region。
  • -p 选项可以指定 PD 的 endpoints。
  1. tikv-ctl --db /path/to/tikv/db recover-mvcc -r 1001,1002 -p 127.0.0.1:2379
  1. success!

注意：

  • 该命令只支持本地模式。在运行成功后，会打印 success!。
  • -p 选项指定 PD 的 endpoint，不使用 http 前缀，用于查询指定的 region_id 是否有效。
  • 对于指定 Region 的 peers 所在的每个 store，均须执行该命令。

Ldb 命令

ldb 命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 tikv-ctl ldb 命令时查看帮助消息或查阅 RocksDB 文档。

数据访问序列的示例如下：

用 HEX 格式 dump 现有 RocksDB 数据：

  1. tikv-ctl ldb --hex --db=/tmp/db dump

Dump 现有 RocksDB 的声明：

  1. tikv-ctl ldb --hex manifest_dump --path=/tmp/db/MANIFEST-000001

您可以通过 --column_family=<string> 指定查询的目标列族。

通过 --try_load_options 命令加载数据库选项文件以打开数据库。在数据库运行时，建议您保持该命令为开启的状态。如果您使用默认配置打开数据库，LSM-tree 存储组织可能会出现混乱，且无法自动恢复。

打印加密元数据

encryption-meta 命令用于打印加密元数据。该子命令可以打印两种加密元数据：数据文件的加密信息，以及所有的数据加密密钥。

使用 encryption-meta dump-file 子命令打印数据文件的加密信息。你需要创建一个 TiKV 配置文件用以指定 TiKV 的数据目录：

  1. # conf.toml
  2. [storage]
  3. data-dir = "/path/to/tikv/data"

--path 选项可以指定数据文件的绝对或者相对路径。如果指定的文件是明文存储的，本命令有可能没有输出。如果不指定 --path 选项，本命令打印所有数据文件的加密信息。

  1. $ tikv-ctl --config=./conf.toml encryption-meta dump-file --path=/path/to/tikv/data/db/CURRENT
  2. /path/to/tikv/data/db/CURRENT: key_id: 9291156302549018620 iv: E3C2FDBF63FC03BFC28F265D7E78283F method: Aes128Ctr

使用 encryption-meta dump-key 打印数据加密密钥。使用本命令的时候，除了在 TiKV 配置文件中指定 TiKV 的数据目录以外，还需要指定当前的主加密密钥。请参阅静态加密文档关于配置 TiKV 主加密密钥的说明。使用本命令时 security.encryption.previous-master-key 配置项不生效，即使配置文件中使用了该配置，本命令也不会触发更换主加密密钥。

  1. # conf.toml
  2. [storage]
  3. data-dir = "/path/to/tikv/data"
  5. [security.encryption.master-key]
  6. type = "kms"
  7. key-id = "0987dcba-09fe-87dc-65ba-ab0987654321"
  8. region = "us-west-2"

注意如果使用了 AWS KMS 作为主加密密钥，使用本命令时 tikv-ctl 需要该 KMS 密钥的访问权限。KMS 访问权限可以通过环境变量、AWS 默认配置文件或 IAM 的方式传递给 tikv-ctl。详情请参阅相关 AWS 文档。

--ids 选项可以指定以逗号分隔的数据加密密钥 id 列表。如果不指定 --ids 选项，本命令打印所有的数据加密密钥，以及最新的数据加密密钥的 id。

本命令会输出一个警告，提示本命令会泄漏敏感数据。根据提示输入 “I consent” 即可。

  1. $ ./tikv-ctl --config=./conf.toml encryption-meta dump-key
  2. This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
  3. Type "I consent" to continue, anything else to exit: I consent
  4. current key id: 9291156302549018620
  5. 9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357
  1. $ ./tikv-ctl --config=./conf.toml encryption-meta dump-key --ids=9291156302549018620
  2. This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
  3. Type "I consent" to continue, anything else to exit: I consent
  4. 9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357

注意：

本命令会以明文方式打印数据加密密钥。在生产环境中，请勿将本命令的输出重定向到磁盘文件中。即使使用以后删除该文件也不能保证文件内容从磁盘中干净清除。