pingcap · ti-chi-bot · Oct 15, 2024 · Aug 12, 2024 · Aug 12, 2024 · Aug 12, 2024
diff --git a/best-practices/massive-regions-best-practices.md b/best-practices/massive-regions-best-practices.md
@@ -123,8 +123,8 @@ Hibernate Region 在 [TiKV master](https://github.com/tikv/tikv/tree/master) 分
 {{< copyable "" >}}
 
 ```
-config set max-merge-region-size 20
-config set max-merge-region-keys 200000
+config set max-merge-region-size 54
+config set max-merge-region-keys 540000
 config set merge-schedule-limit 8
 ```
 
@@ -134,7 +134,11 @@ config set merge-schedule-limit 8
 
 ### 方法六：调整 Region 大小
 
-Region 默认的大小约为 96 MiB，将其调大也可以减少 Region 个数，具体介绍可参考[使用更大的 Region](/tune-region-performance.md)。
+Region 的默认大小为 256 MiB，将其调大可以减少 Region 个数，详情参见 [Region 性能调优](/tune-region-performance.md)。
+
+> **注意：**
+>
+> 从 v8.4.0 开始，Region 的默认值从 96 MiB 调整为 256 MiB。如果你并未手动调整过 Region 大小，将 TiKV 集群从 v8.4.0 之前升级至 v8.4.0 或更高的版本后，集群 Region 的默认值将自动更新为 256 MiB。
 
 > **警告：**
 >

diff --git a/best-practices/pd-scheduling-best-practices.md b/best-practices/pd-scheduling-best-practices.md
@@ -105,8 +105,8 @@ Region merge 指的是为了避免删除数据后大量小甚至空的 Region
 
 具体来说，当某个新分裂出来的 Region 存在的时间超过配置项 [`split-merge-interval`](/pd-configuration-file.md#split-merge-interval) 的值（默认 1h）后，如果同时满足以下情况，该 Region 会触发 Region merge 调度：
 
-- 该 Region 大小小于配置项 [`max-merge-region-size`](/pd-configuration-file.md#max-merge-region-size) 的值（默认 20 MiB）
-- 该 Region 中 key 的数量小于配置项 [`max-merge-region-keys`](/pd-configuration-file.md#max-merge-region-keys) 的值（默认 200000）
+- 该 Region 大小小于配置项 [`max-merge-region-size`](/pd-configuration-file.md#max-merge-region-size) 的值。从 v8.4.0 开始，该配置项的默认值从 20 MiB 调整为 54 MiB。该变更仅对新集群生效，已有集群不受影响。
+- 该 Region 中 key 的数量小于配置项 [`max-merge-region-keys`](/pd-configuration-file.md#max-merge-region-keys) 的值。从 v8.4.0 开始，该配置项的默认值从 200000 调整为 540000。该变更仅对新集群生效，已有集群不受影响。
 
 ## 查询调度状态
 

diff --git a/glossary.md b/glossary.md
@@ -139,7 +139,7 @@ Pending 和 Down 是 Peer 可能出现的两种特殊状态。其中 Pending 表
 
 ### Region/Peer/Raft Group
 
-每个 Region 负责维护集群的一段连续数据（默认配置下平均约 96 MiB），每份数据会在不同的 Store 存储多个副本（默认配置是 3 副本），每个副本称为 Peer。同一个 Region 的多个 Peer 通过 raft 协议进行数据同步，所以 Peer 也用来指代 raft 实例中的成员。TiKV 使用 multi-raft 模式来管理数据，即每个 Region 都对应一个独立运行的 raft 实例，我们也把这样的一个 raft 实例叫做一个 Raft Group。
+每个 Region 负责维护集群的一段连续数据（默认配置下平均约 256 MiB），每份数据会在不同的 Store 存储多个副本（默认配置是 3 副本），每个副本称为 Peer。同一个 Region 的多个 Peer 通过 raft 协议进行数据同步，所以 Peer 也用来指代 raft 实例中的成员。TiKV 使用 multi-raft 模式来管理数据，即每个 Region 都对应一个独立运行的 raft 实例，我们也把这样的一个 raft 实例叫做一个 Raft Group。
 
 ### Region Split
 

diff --git a/information-schema/information-schema-cluster-config.md b/information-schema/information-schema-cluster-config.md
@@ -46,10 +46,10 @@ SELECT * FROM cluster_config WHERE type='tikv' AND `key` LIKE 'coprocessor%';
 | TYPE | INSTANCE        | KEY                               | VALUE   |
 +------+-----------------+-----------------------------------+---------+
 | tikv | 127.0.0.1:20165 | coprocessor.batch-split-limit     | 10      |
-| tikv | 127.0.0.1:20165 | coprocessor.region-max-keys       | 1440000 |
-| tikv | 127.0.0.1:20165 | coprocessor.region-max-size       | 144MiB  |
-| tikv | 127.0.0.1:20165 | coprocessor.region-split-keys     | 960000  |
-| tikv | 127.0.0.1:20165 | coprocessor.region-split-size     | 96MiB   |
+| tikv | 127.0.0.1:20165 | coprocessor.region-max-keys       | 3840000 |
+| tikv | 127.0.0.1:20165 | coprocessor.region-max-size       | 384MiB  |
+| tikv | 127.0.0.1:20165 | coprocessor.region-split-keys     | 2560000  |
+| tikv | 127.0.0.1:20165 | coprocessor.region-split-size     | 256MiB   |
 | tikv | 127.0.0.1:20165 | coprocessor.split-region-on-table | false   |
 +------+-----------------+-----------------------------------+---------+
 6 rows in set (0.00 sec)

diff --git a/pd-configuration-file.md b/pd-configuration-file.md
@@ -256,13 +256,13 @@ pd-server 相关配置项。
 ### `max-merge-region-size`
 
 + 控制 Region Merge 的 size 上限，当 Region Size 大于指定值时 PD 不会将其与相邻的 Region 合并。
-+ 默认：20
++ 默认：54。在 v8.4.0 之前，默认值为 20；从 v8.4.0 开始，默认值为 54。
 + 单位：MiB
 
 ### `max-merge-region-keys`
 
 + 控制 Region Merge 的 key 上限，当 Region key 大于指定值时 PD 不会将其与相邻的 Region 合并。
-+ 默认：200000
++ 默认：540000。在 v8.4.0 之前，默认值为 200000；从 v8.4.0 开始，默认值为 540000。
 
 ### `patrol-region-interval`
 

diff --git a/pd-control.md b/pd-control.md
@@ -164,8 +164,8 @@ config show
     "leader-schedule-limit": 4,
     "leader-schedule-policy": "count",
     "low-space-ratio": 0.8,
-    "max-merge-region-keys": 200000,
-    "max-merge-region-size": 20,
+    "max-merge-region-keys": 540000,
+    "max-merge-region-size": 54,
     "max-pending-peer-count": 64,
     "max-snapshot-count": 64,
     "max-store-down-time": "30m0s",

diff --git a/tidb-storage.md b/tidb-storage.md
@@ -48,7 +48,7 @@ TiKV 利用 Raft 来做数据复制，每个数据变更都会落地为一条 Ra
 * Hash：按照 Key 做 Hash，根据 Hash 值选择对应的存储节点。
 * Range：按照 Key 分 Range，某一段连续的 Key 都保存在一个存储节点上。
 
-TiKV 选择了第二种方式，将整个 Key-Value 空间分成很多段，每一段是一系列连续的 Key，将每一段叫做一个 Region，可以用 [StartKey，EndKey) 这样一个左闭右开区间来描述。每个 Region 中保存的数据量默认维持在 96 MiB 左右（可以通过配置修改）。
+TiKV 选择了第二种方式，将整个 Key-Value 空间分成很多段，每一段是一系列连续的 Key，将每一段叫做一个 Region，可以用 [StartKey，EndKey) 这样一个左闭右开区间来描述。每个 Region 中保存的数据量默认维持在 256 MiB 左右（可以通过配置修改）。
 
 ![Region in TiDB](/media/tidb-storage-2.png)
 

diff --git a/tikv-configuration-file.md b/tikv-configuration-file.md
@@ -1081,7 +1081,7 @@ Coprocessor 相关的配置项。
 ### `region-split-size`
 
 + 分裂后新 Region 的大小，此值属于估算值。
-+ 默认值：96MiB
++ 默认值：`"256MiB"`。在 v8.4.0 之前，默认值为 `"96MiB"`。
 + 单位：KiB|MiB|GiB
 
 ### `region-max-keys`
@@ -1092,7 +1092,7 @@ Coprocessor 相关的配置项。
 ### `region-split-keys`
 
 + 分裂后新 Region 的 key 的个数，此值属于估算值。
-+ 默认值：960000
++ 默认值：`2560000`。在 v8.4.0 之前，默认值为 `960000`。
 
 ### `consistency-check-method`
 
@@ -2150,7 +2150,7 @@ Raft Engine 相关的配置项。
 
 + 备份 SST 文件大小的阈值。如果 TiKV Region 中备份文件的大小超过该阈值，则将该文件备份到 Region 分割的多个 Region 文件中，每个分割 Region 中的文件大小均为 `sst-max-size`（或略大）。
 + 例如，当 Region `[a,e)` 中备份文件大小超过 `sst-max-size` 时，该文件会被备份到多个 Region 范围中，分别为 Region `[a,b)`、`[b,c)`、`[c,d)` 和 `[d,e)`，并且 `[a,b)`、`[b,c)` 和 `[c,d)` 的大小均为 `sst-max-size`（或略大）。
-+ 默认值：`"144MiB"`
++ 默认值：`"384MiB"`。在 v8.4.0 之前，默认值为 `"144MiB"`。
 
 ### `enable-auto-tune` <span class="version-mark">从 v5.4 版本开始引入</span>
 

diff --git a/tikv-overview.md b/tikv-overview.md
@@ -22,7 +22,7 @@ TiKV 是一个分布式事务型的键值数据库，提供了满足 ACID 约束
 
 Region 与副本之间通过 Raft 协议来维持数据一致性，任何写请求都只能在 Leader 上写入，并且需要写入多数副本后（默认配置为 3 副本，即所有请求必须至少写入两个副本成功）才会返回客户端写入成功。
 
-TiKV 会尽量保持每个 Region 中保存的数据在一个合适的大小，目前默认是 96 MB，这样更有利于 PD 进行调度决策。当某个 Region 的大小超过一定限制（默认是 144 MiB）后，TiKV 会将它分裂为两个或者更多个 Region。同样，当某个 Region 因为大量的删除请求而变得太小时（默认是 20 MiB），TiKV 会将比较小的两个相邻 Region 合并为一个。
+TiKV 会尽量保持每个 Region 中保存的数据在一个合适的大小，目前默认是 256 MB，这样更有利于 PD 进行调度决策。当某个 Region 的大小超过一定限制（默认是 384 MiB）后，TiKV 会将它分裂为两个或者更多个 Region。同样，当某个 Region 因为大量的删除请求而变得太小时（默认是 54 MiB），TiKV 会将比较小的两个相邻 Region 合并为一个。
 
 当 PD 需要把某个 Region 的一个副本从一个 TiKV 节点调度到另一个上面时，PD 会先为这个 Raft Group 在目标节点上增加一个 Learner 副本（虽然会复制 Leader 的数据，但是不会计入写请求的多数副本中）。当这个 Learner 副本的进度大致追上 Leader 副本时，Leader 会将它变更为 Follower，之后再移除操作节点的 Follower 副本，这样就完成了 Region 副本的一次调度。
 

diff --git a/tune-region-performance.md b/tune-region-performance.md
@@ -11,7 +11,13 @@ summary: 了解如何通过调整 Region 大小等方法对 Region 进行性能
 
 TiKV 自动将底层数据进行[分片](/best-practices/tidb-best-practices.md#数据分片)，所有数据按照 key 的范围划分为若干个 Region。当某个 Region 的大小超过一定限制后，TiKV 会将它分裂为多个 Region。
 
-在大量数据的场景下，如果 Region 较小，可能会出现 Region 数量过多的情况，从而带来更多的资源开销和导致[性能回退](/best-practices/massive-regions-best-practices.md#性能问题)的问题。从 v6.1.0 开始，TiDB 支持设置自定义的 Region 大小。Region 默认的大小约为 96 MiB，将其调大可以减少 Region 个数。
+在大量数据的场景下，如果 Region 较小，可能会出现 Region 数量过多的情况，从而带来更多的资源开销和导致[性能回退](/best-practices/massive-regions-best-practices.md#性能问题)的问题。
+
+> **说明：**
+>
+> - 在 v6.1.0 中，TiDB 支持设置自定义的 Region 大小，该特性为实验特性。
+> - 从 v6.5.0 开始，该特性成为正式功能（GA）。
+> - 从 v8.4.0 开始，Region 默认的大小从 96 MiB 调整为 256 MiB，将其调大可以减少 Region 个数。
 
 开启 [Hibernate Region](/best-practices/massive-regions-best-practices.md#方法四开启-hibernate-region-功能) 或 [`Region Merge`](/best-practices/massive-regions-best-practices.md#方法五开启-region-merge) 也可以减少过多 Region 带来的性能开销。
 

diff --git a/tune-tikv-memory-performance.md b/tune-tikv-memory-performance.md
@@ -1,7 +1,7 @@
 ---
 title: TiKV 内存参数性能调优
 aliases: ['/docs-cn/dev/tune-tikv-memory-performance/','/docs-cn/dev/reference/performance/tune-tikv/', '/docs-cn/dev/tune-tikv-performance/']
-summary: TiKV 内存参数性能调优，根据机器配置情况调整参数以达到最佳性能。TiKV 使用 RocksDB 作为持久化存储，配置项包括 block-cache 大小和 write-buffer 大小。除此之外，系统内存还会被用于 page cache 和处理大查询时的数据结构生成。推荐将 TiKV 部署在 CPU 核数不低于 8 或内存不低于 32GB 的机器上，对写入吞吐要求高时使用吞吐能力较好的磁盘，对读写延迟要求高时使用 IOPS 较高的 SSD 盘。
+summary: TiKV 内存参数性能调优，根据机器配置情况调整参数以达到最佳性能。TiKV 使用 RocksDB 作为持久化存储，配置项包括 block-cache 大小和 write-buffer 大小。除此之外，系统内存还会被用于 page cache 和处理大查询时的数据结构生成。推荐将 TiKV 部署在 CPU 核数不低于 8 或内存不低于 32GiB 的机器上，对写入吞吐要求高时使用吞吐能力较好的磁盘，对读写延迟要求高时使用 IOPS 较高的 SSD 盘。
 ---
 
 # TiKV 内存参数性能调优
@@ -105,14 +105,14 @@ job = "tikv"
 
 # 当 Region 写入的数据量超过该阈值的时候，TiKV 会检查该 Region 是否需要分裂。为了减少检查过程
 # 中扫描数据的成本，导入数据过程中可以将该值设置为 32 MB，正常运行状态下使用默认值即可。
-region-split-check-diff = "32MB"
+region-split-check-diff = "32MiB"
 
 [coprocessor]
 
 ## 当区间为 [a,e) 的 Region 的大小超过 `region_max_size`，TiKV 会尝试分裂该 Region，例如分裂成 [a,b)、[b,c)、[c,d)、[d,e) 等区间的 Region 后
 ## 这些 Region [a,b), [b,c), [c,d) 的大小为 `region_split_size` (或者稍大于 `region_split_size`）
-# region-max-size = "144MB"
-# region-split-size = "96MB"
+# region-max-size = "384MiB"
+# region-split-size = "256MiB"
 
 [rocksdb]
 # RocksDB 进行后台任务的最大线程数，后台任务包括 compaction 和 flush。具体 RocksDB 为什么需要进行 compaction，
@@ -124,7 +124,7 @@ region-split-check-diff = "32MB"
 # max-open-files = 40960
 
 # RocksDB MANIFEST 文件的大小限制.# 更详细的信息请参考：https://github.com/facebook/rocksdb/wiki/MANIFEST
-max-manifest-file-size = "20MB"
+max-manifest-file-size = "20MiB"
 
 # RocksDB write-ahead logs 目录。如果机器上有两块盘，可以将 RocksDB 的数据和 WAL 日志放在
 # 不同的盘上，提高 TiKV 的性能。
@@ -138,8 +138,8 @@ max-manifest-file-size = "20MB"
 # RocksDB WAL 日志的最大总大小，通常情况下使用默认值就可以了。
 # max-total-wal-size = "4GB"
 
-# 开启 RocksDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。
-# compaction-readahead-size = "2MB"
+# 开启 RocksDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MiB。
+# compaction-readahead-size = "2MiB"
 
 [rocksdb.defaultcf]
 # 数据块大小。RocksDB 是按照 block 为单元对数据进行压缩的，同时 block 也是缓存在 block-cache
@@ -162,7 +162,7 @@ block-size = "64KB"
 compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"]
 
 # RocksDB memtable 的大小。
-write-buffer-size = "128MB"
+write-buffer-size = "128MiB"
 
 # 最多允许几个 memtable 存在。写入到 RocksDB 的数据首先会记录到 WAL 日志里面，然后会插入到
 # memtable 里面，当 memtable 的大小到达了 write-buffer-size 限定的大小的时候，当前的
@@ -193,45 +193,45 @@ level0-stop-writes-trigger = 36
 # level1 都没有压缩，而且 level0 触发 compaction 的条件是 sst 的个数到达 4（默认值）。在
 # level0 和 level1 都采取了压缩的情况下，就需要分析下 RocksDB 的日志，看一个 memtable 的压
 # 缩成一个 sst 文件的大小大概是多少，例如 32MB，那么 max-bytes-for-level-base 的建议值就应
-# 该是 32MB * 4 = 128MB。
-max-bytes-for-level-base = "512MB"
+# 该是 32MiB * 4 = 128MiB。
+max-bytes-for-level-base = "512MiB"
 
 # sst 文件的大小。level0 的 sst 文件的大小受 write-buffer-size 和 level0 采用的压缩算法的
 # 影响，target-file-size-base 参数用于控制 level1-level6 单个 sst 文件的大小。
-target-file-size-base = "32MB"
+target-file-size-base = "32MiB"
 
 [rocksdb.writecf]
 # 保持和 rocksdb.defaultcf.compression-per-level 一致。
 compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"]
 
 # 保持和 rocksdb.defaultcf.write-buffer-size 一致。
-write-buffer-size = "128MB"
+write-buffer-size = "128MiB"
 max-write-buffer-number = 5
 min-write-buffer-number-to-merge = 1
 
 # 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。
-max-bytes-for-level-base = "512MB"
-target-file-size-base = "32MB"
+max-bytes-for-level-base = "512MiB"
+target-file-size-base = "32MiB"
 
 [raftdb]
 # RaftDB 能够打开的最大文件句柄数。
 # max-open-files = 40960
 
-# 开启 RaftDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MB。
-# compaction-readahead-size = "2MB"
+# 开启 RaftDB compaction 过程中的预读功能，如果使用的是机械磁盘，建议该值至少为2MiB。
+# compaction-readahead-size = "2MiB"
 
 [raftdb.defaultcf]
 # 保持和 rocksdb.defaultcf.compression-per-level 一致。
 compression-per-level = ["no", "no", "lz4", "lz4", "lz4", "zstd", "zstd"]
 
 # 保持和 rocksdb.defaultcf.write-buffer-size 一致。
-write-buffer-size = "128MB"
+write-buffer-size = "128MiB"
 max-write-buffer-number = 5
 min-write-buffer-number-to-merge = 1
 
 # 保持和 rocksdb.defaultcf.max-bytes-for-level-base 一致。
-max-bytes-for-level-base = "512MB"
-target-file-size-base = "32MB"
+max-bytes-for-level-base = "512MiB"
+target-file-size-base = "32MiB"
 ```
 
 ## TiKV 内存使用情况
@@ -243,6 +243,6 @@ target-file-size-base = "32MB"
 
 ## TiKV 机器配置推荐
 
-1. 生产环境中，不建议将 TiKV 部署在 CPU 核数小于 8 或内存低于 32GB 的机器上
+1. 生产环境中，不建议将 TiKV 部署在 CPU 核数小于 8 或内存低于 32GiB 的机器上
 2. 如果对写入吞吐要求比较高，建议使用吞吐能力比较好的磁盘
 3. 如果对读写的延迟要求非常高，建议使用 IOPS 比较高的 SSD 盘