重要

你正在查看 TiDB 数据库的归档文档，归档文档不再提供任何更新。如无特殊需求，建议使用 TiDB 数据库的最新 LTS 版本。

TiKV 配置文件描述

TiKV 配置文件比命令行参数支持更多的选项。你可以在 etc/config-template.toml 找到默认值的配置文件，重命名为 config.toml 即可。

本文档只阐述未包含在命令行参数中的参数，命令行参数参见 TiKV 配置参数。

小贴士

如果你需要调整配置项的值，请参考修改配置参数进行操作。

全局配置

`abort-on-panic`

设置 TiKV panic 时是否调用 abort() 退出进程。此选项影响 TiKV 是否允许系统生成 core dump 文件。
- 如果此配置项值为 false，当 TiKV panic 时，TiKV 调用 exit() 退出进程。
- 如果此配置项值为 true，当 TiKV panic 时，TiKV 调用 abort() 退出进程。此时 TiKV 允许系统在退出时生成 core dump 文件。要生成 core dump 文件，你还需要进行 core dump 相关的系统配置（比如打开 ulimit -c 和配置 core dump 路径，不同操作系统配置方式不同）。建议将 core dump 生成路径设置在 TiKV 数据的不同磁盘分区，避免 core dump 文件占用磁盘空间过大，造成 TiKV 磁盘空间不足。
默认值：false

`slow-log-file`

存储慢日志的文件。
如果未设置本项但设置了 log.file.filename，慢日志将输出至 log.file.filename 指定的日志文件中。
如果本项和 log.file.filename 均未设置，所有日志默认输出到 "stderr"。
如果同时设置了两项，普通日志会输出至 log.file.filename 指定的日志文件中，而慢日志则会输出至本配置项指定的日志文件中。
默认值：""

`slow-log-threshold`

输出慢日志的阈值。处理时间超过该阈值后会输出慢日志。
默认值："1s"

`memory-usage-limit`

TiKV 实例的内存使用限制。当 TiKV 的内存使用量接近此阈值时，内部缓存会被清除以释放内存。
在大多数情况下，TiKV 实例被设置为占系统可用总内存的 75%，因此你不需要显式指定此配置项。剩余 25% 的内存用于操作系统的页缓存，详情参见 storage.block-cache.capacity。
在单个物理机上部署多个 TiKV 节点时，你也不需要设置此配置项。在这种情况下，TiKV 实例使用 5/3 * block-cache.capacity 的内存。
不同系统内存容量的默认值如下：
- system=8G block-cache=3.6G memory-usage-limit=6G page-cache=2G
- system=16G block-cache=7.2G memory-usage-limit=12G page-cache=4G
- system=32G block-cache=14.4G memory-usage-limit=24G page-cache=8G

log 从 v5.4.0 版本开始引入

日志相关的配置项。

自 v5.4.0 版本起，废弃原 log 参数 log-rotation-timespan，并将 log-level、log-format、log-file、log-rotation-size 变更为下列参数，与 TiDB 的 log 参数保持一致。如果只设置了原参数、且把其值设为非默认值，原参数与新参数会保持兼容；如果同时设置了原参数和新参数，则会使用新参数。

`level` 从 v5.4.0 版本开始引入

日志等级。
可选值："debug"，"info"，"warn"，"error"，"fatal"
默认值："info"

`format` 从 v5.4.0 版本开始引入

日志的格式。
可选值："json"，"text"
默认值："text"

`enable-timestamp` 从 v5.4.0 版本开始引入

是否开启日志中的时间戳。
可选值："true"，"false"
默认值："true"

log.file 从 v5.4.0 版本开始引入

日志文件相关的配置项。

`filename` 从 v5.4.0 版本开始引入

log 文件。如果未设置该参数，日志会默认输出到 "stderr"；如果设置了该参数，log 会输出到对应的文件中。
默认值：""

`max-size` 从 v5.4.0 版本开始引入

单个 log 文件最大大小，超过设定的参数值后，系统自动切分成多个文件。
默认值：300
最大值：4096
单位：MiB

`max-days` 从 v5.4.0 版本开始引入

保留 log 文件的最长天数。
- 如果未设置本参数或把此参数设置为默认值 0，TiKV 不清理 log 文件。
- 如果把此参数设置为非 0 的值，在 max-days 之后，TiKV 会清理过期的日志文件。
默认值：0

`max-backups` 从 v5.4.0 版本开始引入

可保留的 log 文件的最大数量。
- 如果未设置本参数或把此参数设置为默认值 0，TiKV 会保存所有的 log 文件；
- 如果把此参数设置为非 0 的值，TiKV 最多会保留 max-backups 中指定的数量的旧日志文件。比如，如果该值设置为 7，TiKV 最多会保留 7 个旧的日志文件。
默认值：0

server

服务器相关的配置项。

`addr`

服务器监听的 IP 地址和端口号。
默认值："127.0.0.1:20160"

`advertise-addr`

用于客户端通信的对外访问地址。
如果没有设置该配置项，则使用 addr 的值。
默认值：""

`status-addr`

通过 HTTP 直接报告 TiKV 状态的地址。
警告
如果该值暴露在公网，TiKV 服务器的状态可能会泄露。
要禁用 status-addr，请将该值设置为 ""。
默认值："127.0.0.1:20180"

`status-thread-pool-size`

HTTP API 服务的工作线程数量。
默认值：1
最小值：1

`grpc-compression-type`

gRPC 消息的压缩算法。
可选值："none"、"deflate"、"gzip"
默认值："none"

`grpc-concurrency`

gRPC 工作线程的数量。调整 gRPC 线程池的大小时，请参考 TiKV 线程池调优。
默认值：5
最小值：1

`grpc-concurrent-stream`

一个 gRPC 链接中最多允许的并发请求数量。
默认值：1024
最小值：1

`grpc-memory-pool-quota`

gRPC 可使用的内存大小限制。
默认值：无限制
建议仅在出现内存不足 (OOM) 的情况下限制内存使用。需要注意，限制内存使用可能会导致卡顿。

`grpc-raft-conn-num`

TiKV 节点之间用于 Raft 通讯的链接最大数量。
默认值：1
最小值：1

`max-grpc-send-msg-len`

设置可发送的最大 gRPC 消息长度。
默认值：10485760
单位：Bytes
最大值：2147483647

`grpc-stream-initial-window-size`

gRPC stream 的 window 大小。
默认值：2MB
单位：KB|MB|GB
最小值：1KB

`grpc-keepalive-time`

gRPC 发送 keep alive ping 消息的间隔时长。
默认值：10s
最小值：1s

`grpc-keepalive-timeout`

关闭 gRPC 链接的超时时长。
默认值：3s
最小值：1s

`concurrent-send-snap-limit`

同时发送 snapshot 的最大个数。
默认值：32
最小值：1

`concurrent-recv-snap-limit`

同时接受 snapshot 的最大个数。
默认值：32
最小值：1

`end-point-recursion-limit`

endpoint 下推查询请求解码消息时，最多允许的递归层数。
默认值：1000
最小值：1

`end-point-request-max-handle-duration`

endpoint 下推查询请求处理任务最长允许的时长。
默认值：60s
最小值：1s

`snap-io-max-bytes-per-sec`

处理 snapshot 时最大允许使用的磁盘带宽。
默认值：100MB
单位：KB|MB|GB
最小值：1KB

`enable-request-batch`

控制是否开启批处理请求。
默认值：true

`labels`

指定服务器属性，例如 { zone = "us-west-1", disk = "ssd" }。
默认值：{}

`background-thread-count`

后台线程池的工作线程数量，包括 endpoint 线程、BR 线程、split check 线程、Region 线程以及其他延迟不敏感的任务线程。
默认值：当 CPU 核数小于 16 时，默认值为 2。否则，默认值为 3。

`end-point-slow-log-threshold`

endpoint 下推查询请求输出慢日志的阈值，处理时间超过阈值后会输出慢日志。
默认值：1s
最小值：0

`raft-client-queue-size`

该配置项指定 TiKV 中发送 Raft 消息的缓冲区大小。如果存在消息发送不及时导致缓冲区满、消息被丢弃的情况，可以适当调大该配置项值以提升系统运行的稳定性。
默认值：8192

`simplify-metrics` 从 v6.2.0 版本开始引入

是否精简返回的监控指标 Metrics 数据。设置为 true 后，TiKV 可以通过过滤部分 Metrics 采样数据以减少每次请求返回的 Metrics 数据量。
默认值：false

`forward-max-connections-per-address` 从 v5.0.0 版本开始引入

设置服务与转发请求的连接池大小。设置过小会影响请求的延迟和负载均衡。
默认值：4

readpool.unified

统一处理读请求的线程池相关的配置项。该线程池自 4.0 版本起取代原有的 storage 和 coprocessor 线程池。

`min-thread-count`

统一处理读请求的线程池最少的线程数量。
默认值：1

`max-thread-count`

统一处理读请求的线程池最多的线程数量，即 UnifyReadPool 线程池的大小。调整该线程池的大小时，请参考 TiKV 线程池调优。
可调整范围：[min-thread-count, MAX(4, CPU quota * 10)]。其中，MAX(4, CPU quota * 10) 表示：如果 CPU 配额乘 10 小于 4，取 4；如果 CPU 配额乘 10 大于 4，即 CPU 配额大于 0.4，则取 CPU 配额乘 10。
默认值：MAX(4, CPU quota * 0.8)

注意

增加线程数量会导致上下文切换增多，可能会导致性能下降，因此不推荐修改此配置。

`stack-size`

统一处理读请求的线程池中线程的栈大小。
类型：整数 + 单位
默认值：10MB
单位：KB|MB|GB
最小值：2MB
最大值：在系统中执行 ulimit -sH 命令后，输出的千字节数。

`max-tasks-per-worker`

统一处理读请求的线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`auto-adjust-pool-size` 从 v6.3.0 版本开始引入

是否开启自动调整线程池的大小。开启此配置可以基于当前的 CPU 使用情况，自动调整统一处理读请求的线程池 (UnifyReadPool) 的大小，优化 TiKV 的读性能。目前线程池自动调整的范围为：[max-thread-count, MAX(4, CPU)](上限与 max-thread-count 可设置的最大值相同)。
默认值：false

readpool.storage

存储线程池相关的配置项。

`use-unified-pool`

是否使用统一的读取线程池（在 readpool.unified 中配置）处理存储请求。该选项值为 false 时，使用单独的存储线程池。通过本节 (readpool.storage) 中的其余配置项配置单独的线程池。
默认值：如果本节 (readpool.storage) 中没有其他配置，默认为 true。否则，为了升级兼容性，默认为 false，请根据需要更改 readpool.unified 中的配置后再启用该选项。

`high-concurrency`

处理高优先级读请求的线程池线程数量。
当 8 ≤ cpu num ≤ 16 时，默认值为 cpu_num * 0.5；当 cpu num 小于 8 时，默认值为 4；当 cpu num 大于 16 时，默认值为 8。
最小值：1

`normal-concurrency`

处理普通优先级读请求的线程池线程数量。
当 8 ≤ cpu num ≤ 16 时，默认值为 cpu_num * 0.5；当 cpu num 小于 8 时，默认值为 4；当 cpu num 大于 16 时，默认值为 8。
最小值：1

`low-concurrency`

处理低优先级读请求的线程池线程数量。
当 8 ≤ cpu num ≤ 16 时，默认值为 cpu_num * 0.5；当 cpu num 小于 8 时，默认值为 4；当 cpu num 大于 16 时，默认值为 8。
最小值：1

`max-tasks-per-worker-high`

高优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`max-tasks-per-worker-normal`

普通优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`max-tasks-per-worker-low`

低优先级线程池中单个线程允许积压的最大任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`stack-size`

Storage 读线程池中线程的栈大小。
类型：整数 + 单位
默认值：10MB
单位：KB|MB|GB
最小值：2MB
最大值：在系统中执行 ulimit -sH 命令后，输出的千字节数。

readpool.coprocessor

协处理器线程池相关的配置项。

`use-unified-pool`

是否使用统一的读取线程池（在 readpool.unified 中配置）处理协处理器请求。该选项值为 false 时，使用单独的协处理器线程池。通过本节 (readpool.coprocessor) 中的其余配置项配置单独的线程池。
默认值：如果本节 (readpool.coprocessor) 中没有其他配置，默认为 true。否则，为了升级兼容性，默认为 false，请根据需要更改 readpool.unified 中的配置后再启用该选项。

`high-concurrency`

处理高优先级 Coprocessor 请求（如点查）的线程池线程数量。
默认值：CPU * 0.8
最小值：1

`normal-concurrency`

处理普通优先级 Coprocessor 请求的线程池线程数量。
默认值：CPU * 0.8
最小值：1

`low-concurrency`

处理低优先级 Coprocessor 请求（如扫表）的线程池线程数量。
默认值：CPU * 0.8
最小值：1

`max-tasks-per-worker-high`

高优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`max-tasks-per-worker-normal`

普通优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`max-tasks-per-worker-low`

低优先级线程池中单个线程允许积压的任务数量，超出后会返回 Server Is Busy。
默认值：2000
最小值：2

`stack-size`

Coprocessor 线程池中线程的栈大小。
默认值：10MB
单位：KB|MB|GB
最小值：2MB
最大值：在系统中执行 ulimit -sH 命令后，输出的千字节数。

storage

存储相关的配置项。

`data-dir`

RocksDB 存储路径。
默认值："./"

`engine` 从 v6.6.0 版本开始引入

警告

该功能目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 issue 反馈。

设置存储引擎类型。该配置只能在创建新集群时指定，且后续无法更改。
默认值："raft-kv"
可选值：
- "raft-kv"：TiDB v6.6.0 之前版本的默认存储引擎。
- "partitioned-raft-kv"：TiDB v6.6.0 新引入的存储引擎。

`scheduler-concurrency`

scheduler 内置一个内存锁机制，防止同时对一个 key 进行操作。每个 key hash 到不同的槽。
默认值：524288
最小值：1

`scheduler-worker-pool-size`

Scheduler 线程池中线程的数量。Scheduler 线程主要负责写入之前的事务一致性检查工作。如果 CPU 核心数量大于等于 16，默认为 8；否则默认为 4。调整 scheduler 线程池的大小时，请参考 TiKV 线程池调优。
默认值：4
可调整范围：[1, MAX(4, CPU)]。其中，MAX(4, CPU) 表示：如果 CPU 核心数量小于 4，取 4；如果 CPU 核心数量大于 4，则取 CPU 核心数量。

`scheduler-pending-write-threshold`

写入数据队列的最大值，超过该值之后对于新的写入 TiKV 会返回 Server Is Busy 错误。
默认值：100MB
单位：MB|GB

`enable-async-apply-prewrite`

控制异步提交 (Async Commit) 事务在应用 prewrite 请求之前是否响应 TiKV 客户端。开启该配置项可以降低 apply 耗时较高时的延迟，或者减少 apply 耗时不稳定时的延迟抖动。
默认值：false

`reserve-space`

TiKV 启动时会预留一块空间用于保护磁盘空间。当磁盘剩余空间小于该预留空间时，TiKV 会限制部分写操作。预留空间形式上分为两个部分：预留空间的 80% 用作磁盘空间不足时的运维操作所需要的额外磁盘空间，剩余的 20% 为磁盘临时文件。在回收空间的过程中，如果额外使用的磁盘空间过多，导致存储耗尽时，该临时文件会成为恢复服务的最后一道防御。
临时文件名为 space_placeholder_file，位于 storage.data-dir 目录下。当 TiKV 因磁盘空间耗尽而下线时，重启 TiKV 会自动删除该临时文件，并自动尝试回收空间。
当剩余空间不足时，TiKV 不会创建该临时文件。防御的有效性与预留空间的大小有关。预留空间大小的计算方式为磁盘容量的 5% 与该配置项之间的最大值。当该配置项的值为 0MB 时，TiKV 会关闭磁盘防护功能。
默认值：5GB
单位：MB|GB

`enable-ttl`

警告

你只能在部署新的 TiKV 集群时将 enable-ttl 的值设置为 true 或 false，不能在已有的 TiKV 集群中修改该配置项的值。由于该配置项为 true 和 false 的 TiKV 集群所存储的数据格式不相同，如果你在已有的 TiKV 集群中修改该配置项的值，会造成不同格式的数据存储在同一个集群，导致重启对应的 TiKV 集群时 TiKV 报 "can't enable ttl on a non-ttl instance" 错误。
你只能在 TiKV 集群中使用 enable-ttl，不能在有 TiDB 节点的集群中使用该配置项（即在此类集群中把 enable-ttl 设置为 true），否则会导致数据损坏、TiDB 集群升级失败等严重后果。

TTL 即 Time to live。数据超过 TTL 时间后会被自动删除。用户需在客户端写入请求中指定 TTL。不指定 TTL 即表明相应数据不会被自动删除。
默认值：false

`ttl-check-poll-interval`

回收数据物理空间的检查周期。如果数据超过了 TTL 时间，数据的物理空间会在检查时被强制回收。
默认值：12h
最小值：0s

`background-error-recovery-window` 从 v6.1.0 版本开始引入

RocksDB 检测到可恢复的后台错误后，所允许的最长恢复时间。如果后台 SST 文件出现损坏，RocksDB 在检测到故障 SST 文件所属的 Peer 后，会通过心跳上报到 PD。PD 随后会进行调度操作移除该 Peer。最后故障 SST 文件将会被直接删除，随后 TiKV 后台恢复正常。
在恢复操作完成之前，损坏的 SST 文件将一直存在。此时 RocksDB 可以继续写入新的内容，但读到损坏的数据范围时会返回错误。
如果恢复操作未能在该时间窗口内完成，TiKV 会崩溃。
默认值：1h

`api-version` 从 v6.1.0 版本开始引入

TiKV 作为 RawKV 存储数据时使用的存储格式与接口版本。
可选值：
- 1：使用 API V1。不对客户端传入的数据进行编码，而是原样存储。在 v6.1.0 之前的版本，TiKV 都使用 API V1。
- 2：使用 API V2：
  - 数据采用多版本并发控制 (MVCC) 方式存储，其中时间戳由 tikv-server 从 PD 获取（即 TSO）。
  - 数据根据使用方式划分范围，支持单一集群 TiDB、事务 KV、RawKV 应用共存。
  - 需要同时设置 storage.enable-ttl = true。由于 API V2 支持 TTL 特性，因此强制要求打开 enable-ttl 以避免这个参数出现歧义。
  - 启用 API V2 后需要在集群中额外部署至少一个 tidb-server 以回收过期数据。该 tidb-server 可同时提供数据库读写服务。可以部署多个 tidb-server 以保证高可用。
  - 需要客户端的支持。请参考对应客户端的 API V2 使用说明。
  - 从 v6.2.0 版本开始，你可以通过 RawKV CDC 组件实现 RawKV 的 Change Data Capture (CDC)。
默认值：1

警告

由于 API V1 和 API V2 底层存储格式不同，因此仅当 TiKV 中只有 TiDB 数据时，可以平滑启用或关闭 API V2。其他情况下，需要新建集群，并使用 TiKV Backup & Restore 工具进行数据迁移。
启用 API V2 后，不能将 TiKV 集群回退到 v6.1.0 之前的版本，否则可能导致数据损坏。

storage.block-cache

RocksDB 多个 CF 之间共享 block cache 的配置选项。

`capacity`

共享 block cache 的大小。
默认值：
- 当 storage.engine="raft-kv" 时，默认值为系统总内存大小的 45%。
- 当 storage.engine="partitioned-raft-kv" 时，默认值为系统总内存大小的 30%。
单位：KB|MB|GB

storage.flow-control

在 scheduler 层进行流量控制代替 RocksDB 的 write stall 机制，可以避免 write stall 机制卡住 Raftstore 或 Apply 线程导致的次生问题。本节介绍 TiKV 流量控制机制相关的配置项。

`enable`

是否开启流量控制机制。开启后，TiKV 会自动关闭 KvDB 的 write stall 机制，还会关闭 RaftDB 中除 memtable 以外的 write stall 机制。
默认值：true

`memtables-threshold`

当 KvDB 的 memtable 的个数达到该阈值时，流控机制开始工作。当 enable 的值为 true 时，会覆盖 rocksdb.(defaultcf|writecf|lockcf).max-write-buffer-number 的配置。
默认值：5

`l0-files-threshold`

当 KvDB 的 L0 文件个数达到该阈值时，流控机制开始工作。当 enable 的值为 true 时，会覆盖 rocksdb.(defaultcf|writecf|lockcf).level0-slowdown-writes-trigger的配置。
默认值：20

`soft-pending-compaction-bytes-limit`

当 KvDB 的 pending compaction bytes 达到该阈值时，流控机制开始拒绝部分写入请求，报错 ServerIsBusy。当 enable 的值为 true 时，会覆盖 rocksdb.(defaultcf|writecf|lockcf).soft-pending-compaction-bytes-limit 的配置。
默认值："192GB"

`hard-pending-compaction-bytes-limit`

当 KvDB 的 pending compaction bytes 达到该阈值时，流控机制拒绝所有写入请求，报错 ServerIsBusy。当 enable 的值为 true 时，会覆盖 rocksdb.(defaultcf|writecf|lockcf).hard-pending-compaction-bytes-limit 的配置。
默认值："1024GB"

storage.io-rate-limit

I/O rate limiter 相关的配置项。

`max-bytes-per-sec`

限制服务器每秒从磁盘读取数据或写入数据的最大 I/O 字节数，I/O 类型由下面的 mode 配置项决定。达到该限制后，TiKV 倾向于放缓后台操作为前台操作节流。该配置项值应设为磁盘的最佳 I/O 带宽，例如云盘厂商指定的最大 I/O 带宽。
默认值："0MB"

`mode`

确定哪些类型的 I/O 操作被计数并受 max-bytes-per-sec 阈值的限流。当前 TiKV 只支持 write-only 只写模式。
可选值："read-only"，"write-only"，"all-io"
默认值："write-only"

pd

`enable-forwarding` 从 v5.0.0 版本开始引入

控制 TiKV 中的 PD client 在疑似网络隔离的情况下是否通过 follower 将请求转发给 leader。
默认值：false
如果确认环境存在网络隔离的可能，开启这个参数可以减少服务不可用的窗口期。
如果无法准确判断隔离、网络中断、宕机等情况，这个机制存在误判情况从而导致可用性、性能降低。如果网络中从未发生过网络故障，不推荐开启此选项。

`endpoints`

PD 的地址。当指定多个地址时，需要用逗号 , 分隔。
默认值：["127.0.0.1:2379"]

`retry-interval`

设置 PD 连接的重试间隔。
默认值："300ms"

`retry-log-every`

指定 PD 客户端在观察到错误时跳过报错的频率。例如，当配置项值为 5 时，每次 PD 观察到错误时，将跳过 4 次报错，直到第 5 次错误时才报告。
要禁用此功能，请将值设置为 1。
默认值：10

`retry-max-count`

初始化 PD 连接的最大重试次数。
要禁用重试，请将该值设置为 0。要解除重试次数的限制，请将该值设置为 -1。
默认值：-1

raftstore

raftstore 相关的配置项。

`prevote`

开启 Prevote 的开关，开启有助于减少隔离恢复后对系统造成的抖动。
默认值：true

`capacity`

存储容量，即允许的最大数据存储大小。如果没有设置，则使用当前磁盘容量。如果要将多个 TiKV 实例部署在同一块物理磁盘上，需要在 TiKV 配置中添加该参数，参见混合部署的关键参数介绍。
默认值：0
单位：KB|MB|GB