add dttool version 3 docs (pingcap#8077)

tiflash/tiflash-command-line-flags.md

@@ -12,3 +12,64 @@ aliases: ['/docs-cn/dev/tiflash/tiflash-command-line-flags/']
 + 指定 TiFlash 的配置文件路径
 + 默认：""
 + 必须指定配置文件，详细的配置项请参阅 [TiFlash 配置参数](/tiflash/tiflash-configuration.md)
+
+## `dttool migrate`
+
+- 迁移 DTFile 的文件格式 （用于测试和原地降级）。数据迁移的单位为单个 DTFile。如果想进行整表迁移，通常需要定位到所有形如 `<data dir>/t_<table id>/stable/dmf_<file id>` 的路径，逐一进行迁移。可以结合脚本来自动进行这一操作。
+
+- 使用场景：
+    - 当需要从开启了数据校验功能 (`storage.format_version` >= 3) 的 TiFlash v5.4 及以上版本降级回以前的版本时，可以使用此工具完成数据格式降级。
+    - 当升级到 TiFlash v5.4 及以上，并希望对存量数据也加上数据校验功能以加固数据检验时，可以使用此工具完成数据格式升级。
+    - 测试不同配置的 DTFile 空间占用和读取速度。
+
+- 参数：
+    - `--imitative`：当不使用 DTFile 的加密功能时，可以使用本选项避免使用配置文件和连接 PD。
+    - `--version`：DTFile 的版本，可选值为 1 和 2，默认为 2。1 为传统格式，2 为新版 checksum 对应的 DTFile 格式。
+    - `--algorithm`：检验哈希算法，可选值为 xxh3，city128，crc32，crc64，none，默认为 xxh3，仅在 version=2 时有用。
+    - `--frame`：校验帧大小，默认为 1048576，仅在 version=2 时有用。
+    - `--compression`：目标压缩算法，可选值为 lz4，lz4hc，zstd，none。默认值为 lz4。
+    - `--level`：目标压缩等级，默认值 -1 （表示自动模式）；不同压缩算法取值范围不同。
+    - `--config-file`：dttool migrate 的配置文件应当与 server 模式下的[配置文件](/tiflash/tiflash-command-line-flags.md#server---config-file)保持一致；使用配置文件时，需要退出本地的 TiFlash 服务器实例。见 `--imitative` 选项。
+    - `--file-id`：对应 DTFile 的 ID，如 `dmf_123` 对应的 ID 是 123。
+    - `--workdir`：指向 `dmf_xxx` 的父级目录。
+    - `--dry`：空跑模式，只输出迁移过程。
+    - `--nokeep`：不保留原数据。不开启该选项时，会产生 `dmf_xxx.old` 文件。
+
+> **警告：**
+>
+> 虽然 TiFlash 可以读取自定义压缩算法和压缩等级的 DTFile，但目前正式支持的只有默认压缩等级的 LZ4 算法。自定义压缩参数并未经过大量测试，仅作实验。
+
+> **注意：**
+>
+> 为保证安全 DTTool 在迁移模式下会尝试对工作目录进行加锁，因此同一工作目录下同一时间只能有一个 DTTool 执行迁移工作。如果您在中途强制停止 DTTool，可能会因锁未释放导致后面在运行 DTTool 时工具拒绝进行迁移工作。
+> 如果您遇到这种情况，在保证安全的前提下，可以手动删除工作目录下的 LOCK 文件来释放锁。
+
+## `dttool bench`
+
+- 提供 DTFile 的简单 IO 速度测试。
+- 参数：
+    - `--version`：DTFile 的版本，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--algorithm`：检验哈希算法，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--frame`：校验帧大小，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--column`：测试表宽度，默认为 100。
+    - `--size`：测试表长度，默认为 1000。
+    - `--field`：测试表字段长度上限，默认为 1024。
+    - `--random`：随机数种子。如未提供，该值从系统熵池抽取。
+    - `--encryption`：启用加密功能。
+    - `--repeat`：性能测试采样次数，默认为 5。
+    - `--workdir`：临时数据文件夹，应指向需要测试的文件系统下的路径，默认为 /tmp/test。
+
+## `dttool inspect`
+
+- 检查 DTFile 的完整性。数据校验的单位为单个 DTFile。如果想进行整表校验，通常需要定位到所有形如 `<data dir>/t_<table id>/stable/dmf_<file id>` 的路径，逐一进行校验。可以结合脚本来自动进行这一操作。
+
+- 使用场景：
+    - 完成格式升降级后进行完整性检测。
+    - 将原有数据文件搬迁至新环境后进行完整性检测。
+
+- 参数：
+    - `--config-file`：dttool bench 的配置文件，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--check`：进行哈希校验。
+    - `--file-id`：对应 DTFile 的 ID，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--imitative`：模拟数据库上下文，见 [dttool migrate](#dttool-migrate) 对应参数。
+    - `--workdir`：数据文件夹，见 [dttool migrate](#dttool-migrate) 对应参数。

tiflash/tiflash-configuration.md

@@ -62,6 +62,12 @@ delta_index_cache_size = 0
 [storage]
     ## 该参数从 v5.2.0 开始废弃，请使用 `[storage.io_rate_limit]` 相关配置
     # bg_task_io_rate_limit = 0
+
+    ## DTFile 储存文件格式
+    ## * format_version = 1 老旧文件格式，已废弃
+    ## * format_version = 2 默认文件格式
+    ## * format_version = 3 新文件格式，具有更完善的检验功能
+    # format_version = 2
 
     [storage.main]
     ## 用于存储主要的数据，该目录列表中的数据占总数据的 90% 以上。

tiflash/use-tiflash.md

@@ -83,7 +83,7 @@ SELECT * FROM information_schema.tiflash_replica WHERE TABLE_SCHEMA = '<db_name>
 
 在配置副本时，如果为了考虑容灾，需要将 TiFlash 的不同数据副本分布到多个数据中心，则可以按如下步骤进行配置：
 
-1. 在集群配置文件中为 TiFlash 节点指定 label. 
+1. 在集群配置文件中为 TiFlash 节点指定 label：
 
     ```
     tiflash_servers:
@@ -432,9 +432,46 @@ TiFlash 提供了两个全局/会话变量决定是否选择 Broadcast Hash Join
 - [`tidb_broadcast_join_threshold_size`](/system-variables.md#tidb_broadcast_join_threshold_count-从-v50-版本开始引入)，单位为 bytes。如果表大小（字节数）小于该值，则选择 Broadcast Hash Join 算法。否则选择 Shuffled Hash Join 算法。
 - [`tidb_broadcast_join_threshold_count`](/system-variables.md#tidb_broadcast_join_threshold_count-从-v50-版本开始引入)，单位为行数。如果 join 的对象为子查询，优化器无法估计子查询结果集大小，在这种情况下通过结果集行数判断。如果子查询的行数估计值小于该变量，则选择 Broadcast Hash Join 算法。否则选择 Shuffled Hash Join 算法。
 
+## TiFlash 数据校验
+
+### 使用场景
+
+数据损坏通常意味着严重的硬件故障。在这种情形下，即使尝试自主修复，也会使得数据的可靠性下降。TiFlash 默认对数据文件进行基础的校验，使用固定的 City128 算法。一旦发现数据校验不符的情况，TiFlash 将立刻报错退出，避免因错误数据造成次生灾害。此时，您需要手动检查干预并重新同步数据，才可以恢复节点的使用。
+
+自 v5.4.0 起，TiFlash 完善了数据校验功能，默认使用 XXH3 算法，并允许用户调整校验帧大小和校验算法。
+
+### 校验机制简介
+
+TiFlash 的数据校验功能基于 DTFile（即 DeltaTree File）提供。DTFile 是 TiFlash 落盘数据的存储文件，共有三版格式：
+
+| 版本 | 状态 | 校验机制 | 备注 |
+| :-- | :-- | :-- |:-- |
+| V1 | 已废弃 | 在数据文件中内嵌哈希值 | |
+| V2 | 默认格式 | 在数据文件中内嵌哈希值 | 在 V1 的基础上增加了列数据的统计信息 |
+| V3 | 需手动开启 | 包含元数据，标记数据校验，支持多种哈希算法 | 于 v5.4 版本引入 |
+
+DTFile 存储在数据文件夹目录下的 stable 文件夹内。目前启用的格式均为文件夹形式，即具体数据均储存在名字类似 `dmf_<file id>` 的文件夹下的多个子文件中。
+
+#### 使用数据校验
+
+TiFlash 支持自动和手动进行数据校验：
+
+- 自动数据校验 （`storage.format_version` 配置项）：
+    - 默认使用 DTFile V2 版本校验机制。
+    - 如需开启 DTFile V3 版本校验机制，参见 [TiFlash 配置文件](/tiflash/tiflash-configuration.md#配置文件-tiflashtoml)。
+- 手动数据校验，参见 [DTTool 使用文档](/tiflash/tiflash-command-line-flags.md#dttool-inspect)。
+
+> **警告：**
+>
+> 设置使用 V3 版本后，新生成的 DTFile 将无法被 v5.4.0 以前 TiFlash 直接正常读取。v5.4.0 后 TiFlash 同时支持 V2，V3 版本，不会主动进行版本的升降级。如果需要迁移到新的版本，或者需要回退到旧的版本，需要手动使用 DTTool 进行[版本切换](/tiflash/tiflash-command-line-flags.md#dttool-migrate)。
+
+#### 校验工具
+
+除了 TiFlash 在读取所需数据时进行的自动校验，在 v5.4.0 版本时还引入了手动检查文件完整性的工具，详情请见 DTTool 的[使用文档](/tiflash/tiflash-command-line-flags.md#dttool-inspect)。
+
 ## 注意事项
 
-TiFlash 目前尚不支持的一些功能，与原生 TiDB 可能存在不兼容的问题，具体如下：
+TiFlash 在以下情况与 TiDB 存在不兼容问题：
 
 * TiFlash 计算层：
     * 不支持检查溢出的数值。例如将两个 `BIGINT` 类型的最大值相加 `9223372036854775807 + 9223372036854775807`，该计算在 TiDB 中预期的行为是返回错误 `ERROR 1690 (22003): BIGINT value is out of range`，但如果该计算在 TiFlash 中进行，则会得到溢出的结果 `-2` 且无报错。