tidb-lightning: recommend matching TiDB Lightning and TiDB versions (#21945)

get-started-with-tidb-lightning.md

@@ -1,6 +1,6 @@
 ---
 title: TiDB Lightning 快速上手
-summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首先使用 Dumpling 导出数据，然后部署 TiDB 集群。安装最新版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 TiDB Lightning 简介。
+summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首先使用 Dumpling 导出数据，然后部署 TiDB 集群。安装与目标 TiDB 集群相同版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 TiDB Lightning 简介。
 ---
 
 # TiDB Lightning 快速上手
@@ -50,10 +50,10 @@ summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首
 
 ## 第 3 步：安装 TiDB Lightning
 
-运行如下命令，安装 TiDB Lightning 的最新版本：
+建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。运行如下命令安装 TiDB Lightning，请将 `<version>` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）：
 
 ```shell
-tiup install tidb-lightning
+tiup install tidb-lightning:<version>
 ```
 
 ## 第 4 步：启动 TiDB Lightning
@@ -95,11 +95,11 @@ tiup install tidb-lightning
     pd-addr = "172.16.31.3:2379,56.78.90.12:3456"
     ```
 
-2. 运行 `tidb-lightning`。为避免直接在命令行使用 `nohup` 启动程序时因 `SIGHUP` 信号导致的程序退出，建议将 `nohup` 命令放入脚本中。示例如下：
+2. 运行 `tidb-lightning`。为避免直接在命令行使用 `nohup` 启动程序时因 `SIGHUP` 信号导致的程序退出，建议将 `nohup` 命令放入脚本中。在以下示例中，请将 `<version>` 替换为[第 3 步](#第-3-步安装-tidb-lightning)中安装的 TiDB Lightning 的版本号：
 
     ```shell
     #!/bin/bash
-    nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out &
+    nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out &
     ```
 
 ## 第 5 步：检查数据

migrate-from-sql-files-to-tidb.md

@@ -72,12 +72,14 @@ pd-addr = "${ip}:${port}"     # 集群 PD 的地址，Lightning 通过 PD 获取
 
 若从 Amazon S3 导入，则需将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 Lightning 节点。
 
+建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。将 `<version>` 替换为目标 TiDB 集群的版本号。
+
 {{< copyable "shell-regular" >}}
 
 ```shell
 export AWS_ACCESS_KEY_ID=${access_key}
 export AWS_SECRET_ACCESS_KEY=${secret_key}
-nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out 2>&1 &
+nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out 2>&1 &
 ```
 
 同时，TiDB Lightning 还支持从 `~/.aws/credentials` 读取凭证文件。

migrate-large-mysql-to-tidb.md

@@ -140,11 +140,13 @@ LIMIT
 
     若从 Amazon S3 导入，则需将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 TiDB Lightning 节点。同时还支持从 `~/.aws/credentials` 读取凭证文件。
 
+    建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。将 `<version>` 替换为目标 TiDB 集群的版本号。
+
     ```shell
     #!/bin/bash
     export AWS_ACCESS_KEY_ID=${access_key}
     export AWS_SECRET_ACCESS_KEY=${secret_key}
-    nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out 2>&1 &
+    nohup tiup tidb-lightning:<version> -config tidb-lightning.toml > nohup.out 2>&1 &
     ```
 
     再使用脚本启动 tidb-lightning。

tidb-lightning/deploy-tidb-lightning.md

@@ -22,19 +22,19 @@ summary: 了解如何部署 TiDB Lightning，包括在线部署和离线部署
 
    安装完成后，`~/.bashrc` 已将 TiUP 加入到路径中，你需要新开一个终端或重新声明全局变量 `source ~/.bashrc` 来使用 TiUP。(也可能是`~/.profile`，以 TiUP 输出为准。)
 
-2. 安装 TiUP Lightning 组件：
+2. 使用 TiUP 安装 TiDB Lightning。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。请将 `<version>` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）：
 
     {{< copyable "shell-regular" >}}
 
     ```shell
-    tiup install tidb-lightning
+    tiup install tidb-lightning:<version>
     ```
 
 ## 手动部署
 
 ### 下载 TiDB Lightning 安装包
 
-参考[工具下载](/download-ecosystem-tools.md)文档下载 TiDB Lightning 安装包（TiDB Lightning 完全兼容较低版本的 TiDB 集群，建议选择最新稳定版本）。
+参考[工具下载](/download-ecosystem-tools.md)文档下载 TiDB Lightning 安装包。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。
 
 解压 Lightning 压缩包即可获得 `tidb-lightning` 可执行文件。
 

tidb-lightning/tidb-lightning-faq.md

@@ -1,15 +1,15 @@
 ---
 title: TiDB Lightning 常见问题
-summary: TiDB Lightning 常见问题的摘要：TiDB Lightning 对TiDB/TiKV/PD 的最低版本要求，支持导入多个库，对下游数据库的账号权限要求，导数据过程中某个表报错不会影响其他表，正确重启 TiDB Lightning 的步骤，校验导入数据的正确性方法，支持的数据源格式，禁止导入不合规数据的方法，结束 tidb-lightning 进程的操作，使用千兆网卡的建议，TiDB Lightning 预留空间的原因，清除与 TiDB Lightning 相关的中间数据的步骤，获取 TiDB Lightning 运行时的 goroutine 信息的方法，TiDB Lightning 不兼容 Placement Rules in SQL 的原因，使用 TiDB Lightning 和 Dumpling 复制 schema 的步骤。
+summary: TiDB Lightning 常见问题的摘要：TiDB Lightning 的版本选择建议，支持导入多个库，对下游数据库的账号权限要求，导数据过程中某个表报错不会影响其他表，正确重启 TiDB Lightning 的步骤，校验导入数据的正确性方法，支持的数据源格式，禁止导入不合规数据的方法，结束 tidb-lightning 进程的操作，使用千兆网卡的建议，TiDB Lightning 预留空间的原因，清除与 TiDB Lightning 相关的中间数据的步骤，获取 TiDB Lightning 运行时的 goroutine 信息的方法，TiDB Lightning 不兼容 Placement Rules in SQL 的原因，使用 TiDB Lightning 和 Dumpling 复制 schema 的步骤。
 ---
 
 # TiDB Lightning 常见问题
 
 本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与答案。
 
-## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？
+## 应该使用哪个版本的 TiDB Lightning？
 
-TiDB Lightning 的版本应与集群相同。如果使用 Local-backend 模式，最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。
+建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。
 
 ## TiDB Lightning 支持导入多个库吗？
 
@@ -26,7 +26,7 @@ TiDB Lightning 的版本应与集群相同。如果使用 Local-backend 模式
 ## 如何正确重启 TiDB Lightning？
 
 1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。
-2. 启动一个新的 `tidb-lightning` 任务：执行之前的启动命令，例如 `nohup tiup tidb-lightning -config tidb-lightning.toml`。
+2. 重新执行原导入任务的启动命令，以启动一个新的 `tidb-lightning` 任务，例如 `nohup tiup tidb-lightning:<version> -config tidb-lightning.toml`。请将 `<version>` 替换为原导入任务使用的 TiDB Lightning 版本号。
 
 ## 如何校验导入的数据的正确性？
 

tidb-lightning/troubleshoot-tidb-lightning.md

@@ -36,7 +36,7 @@ strict-format = true
 
 **原因 4**：TiDB Lightning 版本太旧。
 
-建议试试最新的版本，可能会有改善。
+较新的 TiDB Lightning 版本可能会改善导入性能。升级时，建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。
 
 ## `tidb-lightning` 进程意外退出
 

tidb-troubleshooting-map.md

@@ -418,7 +418,7 @@ TiDB 支持完整的分布式事务，自 v3.0 版本起，提供乐观事务与
 
     - 表结构太复杂。每条索引都会额外增加 KV 对，如果有 N 条索引，实际导入的大小就差不多是 [Dumpling](/dumpling-overview.md) 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。
 
-    - TiDB Lightning 版本太旧。尝试使用最新的版本，可能会有改善。
+    - TiDB Lightning 版本太旧。较新的 TiDB Lightning 版本可能会改善导入性能。升级时，建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。
 
 - 6.2.3 `checksum failed: checksum mismatched remote vs local`