title | aliases | ||
---|---|---|---|
TiKV Control 使用说明 |
|
TiKV Control(以下简称 tikv-ctl)是 TiKV 的命令行工具,用于管理 TiKV 集群。它的安装目录如下:
- 如果是使用 TiDB Ansible 部署的集群,在
ansible
目录下的resources/bin
子目录下。 - 如果是使用 TiUP 部署的集群,在
~/.tiup/components/ctl/{VERSION}/
目录下。
TiUP 是晚于 tidb-ansible
推出的部署工具,使用方式更加简化,tikv-ctl
也集成在了 tiup
命令中。执行以下命令,即可调用 tikv-ctl
工具:
{{< copyable "shell-regular" >}}
tiup ctl tikv
Starting component `ctl`: ~/.tiup/components/ctl/v4.0.0-rc.2/ctl tikv
TiKV Control (tikv-ctl)
Release Version: 4.0.0-rc.2
Edition: Community
Git Commit Hash: 2fdb2804bf8ffaab4b18c4996970e19906296497
Git Commit Branch: heads/refs/tags/v4.0.0-rc.2
UTC Build Time: 2020-05-15 11:58:49
Rust Version: rustc 1.42.0-nightly (0de96d37f 2019-12-19)
Enable Features: jemalloc portable sse protobuf-codec
Profile: dist_release
你可以在 tiup ctl tikv
后面再接上相应的参数与子命令。
tikv-ctl 提供以下两种运行模式:
-
远程模式。通过
--host
选项接受 TiKV 的服务地址作为参数。在此模式下,如果 TiKV 启用了 SSL,则 tikv-ctl 也需要指定相关的证书文件,例如:{{< copyable "shell-regular" >}}
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
选项,例如:{{< copyable "shell-regular" >}}
tikv-ctl --pd 127.0.0.1:2379 compact-cluster
store:"127.0.0.1:20160" compact db:KV cf:default range:([], []) success!
-
本地模式。通过
--db
选项来指定本地 TiKV 数据的目录路径。在此模式下,需要停止正在运行的 TiKV 实例。
以下如无特殊说明,所有命令都同时支持这两种模式。
除此之外,tikv-ctl 还有两个简单的命令 --to-hex
和 --to-escaped
,用于对 key 的形式作简单的变换。一般使用 escaped
形式,示例如下:
{{< copyable "shell-regular" >}}
tikv-ctl --to-escaped 0xaaff
\252\377
{{< copyable "shell-regular" >}}
tikv-ctl --to-hex "\252\377"
AAFF
注意:
在命令行上指定
escaped
形式的 key 时,需要用双引号引起来,否则 bash 会将反斜杠吃掉,导致结果错误。
下面逐一对 tikv-ctl 支持的子命令进行举例说明。有的子命令支持很多可选参数,要查看全部细节,可运行 tikv-ctl --help <subcommand>
。
raft
子命令可以查看 Raft 状态机在某一时刻的状态。状态信息包括 RegionLocalState、RaftLocalState 和 RegionApplyState 三个结构体,及某一条 log 对应的 Entries。
你可以使用 region
和 log
两个子命令分别查询以上信息。两条子命令都同时支持远程模式和本地模式。其用法及输出内容如下所示:
{{< copyable "shell-regular" >}}
tikv-ctl --host 127.0.0.1:20160 raft region -r 2
region id: 2
region state key: \001\003\000\000\000\000\000\000\000\002\001
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}})
raft state key: \001\002\000\000\000\000\000\000\000\002\002
raft state: Some(hard_state {term: 307 vote: 5 commit: 314617} last_index: 314617)
apply state key: \001\002\000\000\000\000\000\000\000\002\003
apply state: Some(applied_index: 314617 truncated_state {index: 313474 term: 151})
使用 size
命令可以查看 Region 的大小:
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db size -r 2
region id: 2
cf default region size: 799.703 MB
cf write region size: 41.250 MB
cf lock region size: 27616
scan
命令的 --from
和 --to
参数接受两个 escaped 形式的 raw key,并用 --show-cf
参数指定只需要查看哪些列族。
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db scan --from 'zm' --limit 2 --show-cf lock,default,write
key: zmBootstr\377a\377pKey\000\000\377\000\000\373\000\000\000\000\000\377\000\000s\000\000\000\000\000\372
write cf value: start_ts: 399650102814441473 commit_ts: 399650102814441475 short_value: "20"
key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371
write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002"
write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001"
与 scan
命令类似,mvcc
命令可以查看给定 key 的 MVCC:
{{< copyable "shell-regular" >}}
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
key: zmDB:29\000\000\377\000\374\000\000\000\000\000\000\377\000H\000\000\000\000\000\000\371
write cf value: start_ts: 399650105239273474 commit_ts: 399650105239273475 short_value: "\000\000\000\000\000\000\000\002"
write cf value: start_ts: 399650105199951882 commit_ts: 399650105213059076 short_value: "\000\000\000\000\000\000\000\001"
注意:
该命令中,key 同样需要是 escaped 形式的 raw key。
打印某个 key 的值需要用到 print
命令。示例从略。
为了记录 Region 的状态信息,TiKV 将一些数据写入 Region 的 SST 文件中。你可以用子命令 region-properties
运行 tikv-ctl 来查看这些 properties 信息。例如:
{{< copyable "shell-regular" >}}
tikv-ctl --host localhost:20160 region-properties -r 2
num_files: 0
num_entries: 0
num_deletes: 0
mvcc.min_ts: 18446744073709551615
mvcc.max_ts: 0
mvcc.num_rows: 0
mvcc.num_puts: 0
mvcc.num_versions: 0
mvcc.max_row_versions: 0
middle_key_by_approximate_size:
这些 properties 信息可以用于检查某个 Region 是否健康或者修复不健康的 Region。例如,使用 middle_key_approximate_size
可以手动分裂 Region。
compact
命令可以对单个 TiKV 进行手动 compact。如果指定 --from
和 --to
选项,那么它们的参数也是 escaped raw key 形式的。
--host
参数可以指定要 compact 的 TiKV。-d
参数可以指定要 compact 的 RocksDB,有kv
和raft
参数值可以选。--threads
参数可以指定 compact 的并发数,默认值是 8。一般来说,并发数越大,compact 的速度越快,但是也会对服务造成影响,所以需要根据情况选择合适的并发数。
{{< copyable "shell-regular" >}}
tikv-ctl --host 127.0.0.1:20160 compact -d kv
success!
compact-cluster
命令可以对整个 TiKV 集群进行手动 compact。该命令参数的含义和使用与 compact
命令一样。
tombstone
命令常用于没有开启 sync-log,因为机器掉电导致 Raft 状态机丢失部分写入的情况。它可以在一个 TiKV 实例上将一些 Region 的副本设置为 Tombstone 状态,从而在重启时跳过这些 Region,避免因为这些 Region 的副本的 Raft 状态机损坏而无法启动服务。这些 Region 应该在其他 TiKV 上有足够多的健康的副本以便能够继续通过 Raft 机制进行读写。
一般情况下,可以先在 PD 上将 Region 的副本通过 remove-peer
命令删除掉:
{{< copyable "" >}}
pd-ctl>> operator add remove-peer <region_id> <store_id>
然后再用 tikv-ctl 在那个 TiKV 实例上将 Region 的副本标记为 tombstone 以便跳过启动时对他的健康检查:
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r <region_id>
success!
但是有些情况下,当不能方便地从 PD 上移除这个副本时,可以指定 tikv-ctl 的 --force
选项来强制设置它为 tombstone:
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db tombstone -p 127.0.0.1:2379 -r <region_id>,<region_id> --force
success!
注意:
- 该命令只支持本地模式
-p
选项的参数指定 PD 的 endpoints,无需http
前缀。指定 PD 的 endpoints 是为了询问 PD 是否可以安全切换至 Tombstone 状态。
consistency-check
命令用于在某个 Region 对应的 Raft 副本之间进行一致性检查。如果检查失败,TiKV 自身会 panic。如果 --host
指定的 TiKV 不是这个 Region 的 Leader,则会报告错误。
{{< copyable "shell-regular" >}}
tikv-ctl --host 127.0.0.1:20160 consistency-check -r 2
success!
{{< copyable "shell-regular" >}}
tikv-ctl --host 127.0.0.1:21061 consistency-check -r 2
DebugClient::check_region_consistency: RpcFailure(RpcStatus { status: Unknown, details: Some("StringError(\"Leader is on store 1\")") })
注意:
- 该命令只支持远程模式。
- 即使该命令返回了成功信息,也需要检查是否有 TiKV panic 了。因为该命令只是向 Leader 请求进行一致性检查,但整个检查流程是否成功并不能在客户端知道。
这条子命令可以用于解析指定路径下的 Snapshot 元文件并打印结果。
前面 tombstone
命令可以将 Raft 状态机出错的 Region 设置为 Tombstone 状态,避免 TiKV 启动时对它们进行检查。在运行 tombstone
命令之前,可使用 bad-regions
命令找到出错的 Region,以便将多个工具组合起来进行自动化的处理。
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db bad-regions
all regions are healthy
命令执行成功后会打印以上信息,否则会打印出有错误的 Region 列表。目前可以检出的错误包括 last index
、commit index
和 apply index
之间的不匹配,以及 Raft log 的丢失。其他一些情况,比如 Snapshot 文件损坏等仍然需要后续的支持。
本地查看部署在 /path/to/tikv
的 TiKV 上面 Region 2 的 properties 信息:
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/data/db region-properties -r 2
在线查看运行在 127.0.0.1:20160
的 TiKV 上面 Region 2 的 properties 信息:
{{< copyable "shell-regular" >}}
tikv-ctl --host 127.0.0.1:20160 region-properties -r 2
使用 modify-tikv-config
命令可以动态修改配置参数。目前可动态修改的 TiKV 配置与具体的修改行为与 SQL 动态修改配置功能相同,可参考在线修改 TiKV 配置。
-n
用于指定完整的配置名。支持动态修改的配置名可以参考在线修改 TiKV 配置中支持的配置项列表。-v
用于指定配置值。
设置 shared block cache
的大小:
{{< copyable "shell-regular" >}}
tikv-ctl --host ip:port modify-tikv-config -n storage.block-cache.capacity -v 10GB
success
当禁用 shared block cache
时,为 write
CF 设置 block cache size
:
{{< copyable "shell-regular" >}}
tikv-ctl --host ip:port modify-tikv-config -n rocksdb.writecf.block-cache-size -v 256MB
success
{{< copyable "shell-regular" >}}
tikv-ctl --host ip:port modify-tikv-config -n raftdb.defaultcf.disable-auto-compactions -v true
success
{{< copyable "shell-regular" >}}
tikv-ctl --host ip:port modify-tikv-config -n raftstore.sync-log -v false
success
unsafe-recover remove-fail-stores
命令可以将故障机器从指定 Region 的 peer 列表中移除。运行命令之前,需要目标 TiKV 先停掉服务以便释放文件锁。
-s
选项接受多个以逗号分隔的 store_id
,并使用 -r
参数来指定包含的 Region。如果要对某一个 store 上的全部 Region 都执行这个操作,可简单指定 --all-regions
。
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db unsafe-recover remove-fail-stores -s 3 -r 1001,1002
success!
{{< copyable "shell-regular" >}}
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 上执行此命令。
recover-mvcc
命令用于 MVCC 数据损坏导致 TiKV 无法正常运行的情况。为了从不同种类的不一致情况中恢复,该命令会交叉检查 3 个 CF ("default", "write", "lock")。
-r
选项可以通过region_id
指定包含的 Region。-p
选项可以指定 PD 的 endpoints。
{{< copyable "shell-regular" >}}
tikv-ctl --db /path/to/tikv/db recover-mvcc -r 1001,1002 -p 127.0.0.1:2379
success!
注意:
- 该命令只支持本地模式。在运行成功后,会打印
success!
。-p
选项指定 PD 的 endpoint,不使用http
前缀,用于查询指定的region_id
是否有效。- 对于指定 Region 的 peers 所在的每个 store,均须执行该命令。
ldb
命令行工具提供多种数据访问以及数据库管理命令。下方列出了一些示例用法。详细信息请在运行 tikv-ctl ldb
命令时查看帮助消息或查阅 RocksDB 文档。
数据访问序列的示例如下:
用 HEX 格式 dump 现有 RocksDB 数据:
{{< copyable "shell-regular" >}}
tikv-ctl ldb --hex --db=/tmp/db dump
Dump 现有 RocksDB 的声明:
{{< copyable "shell-regular" >}}
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 的数据目录:
# conf.toml
[storage]
data-dir = "/path/to/tikv/data"
--path
选项可以指定数据文件的绝对或者相对路径。如果指定的文件是明文存储的,本命令有可能没有输出。如果不指定 --path
选项,本命令打印所有数据文件的加密信息。
$ tikv-ctl --config=./conf.toml encryption-meta dump-file --path=/path/to/tikv/data/db/CURRENT
/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
配置项不生效,即使配置文件中使用了该配置,本命令也不会触发更换主加密密钥。
# conf.toml
[storage]
data-dir = "/path/to/tikv/data"
[security.encryption.master-key]
type = "kms"
key-id = "0987dcba-09fe-87dc-65ba-ab0987654321"
region = "us-west-2"
注意如果使用了 AWS KMS 作为主加密密钥,使用本命令时 tikv-ctl
需要该 KMS 密钥的访问权限。KMS 访问权限可以通过环境变量、AWS 默认配置文件或 IAM 的方式传递给 tikv-ctl
。详情请参阅相关 AWS 文档。
--ids
选项可以指定以逗号分隔的数据加密密钥 id 列表。如果不指定 --ids
选项,本命令打印所有的数据加密密钥,以及最新的数据加密密钥的 id。
本命令会输出一个警告,提示本命令会泄漏敏感数据。根据提示输入 "I consent" 即可。
$ ./tikv-ctl --config=./conf.toml encryption-meta dump-key
This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
Type "I consent" to continue, anything else to exit: I consent
current key id: 9291156302549018620
9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357
$ ./tikv-ctl --config=./conf.toml encryption-meta dump-key --ids=9291156302549018620
This action will expose encryption key(s) as plaintext. Do not output the result in file on disk.
Type "I consent" to continue, anything else to exit: I consent
9291156302549018620: key: 8B6B6B8F83D36BE2467ED55D72AE808B method: Aes128Ctr creation_time: 1592938357
注意:
本命令会以明文方式打印数据加密密钥。在生产环境中,请勿将本命令的输出重定向到磁盘文件中。即使使用以后删除该文件也不能保证文件内容从磁盘中干净清除。