From 506af29cd1d5040859ec46cbc1d075bc0573f39a Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 17:28:52 +0800 Subject: [PATCH 1/3] docs: recommend matching TiDB Lightning and TiDB versions --- get-started-with-tidb-lightning.md | 10 +++++----- tidb-lightning/deploy-tidb-lightning.md | 6 +++--- tidb-lightning/tidb-lightning-faq.md | 4 ++-- tidb-lightning/troubleshoot-tidb-lightning.md | 2 +- tidb-troubleshooting-map.md | 2 +- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index 85b60fc8773d..9612437d5b66 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -1,7 +1,7 @@ --- title: TiDB Lightning 快速上手 aliases: ['/docs-cn/dev/get-started-with-tidb-lightning/','/docs-cn/dev/how-to/get-started/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 快速上手 @@ -51,10 +51,10 @@ summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首 ## 第 3 步：安装 TiDB Lightning -运行如下命令，安装 TiDB Lightning 的最新版本： +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。运行如下命令安装 TiDB Lightning，请将 `` 替换为目标 TiDB 集群的版本号（例如 `v8.5.0`）： ```shell -tiup install tidb-lightning +tiup install tidb-lightning: ``` ## 第 4 步：启动 TiDB Lightning @@ -96,11 +96,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` 命令放入脚本中。在以下示例中，请将 `` 替换为第 3 步中安装的版本号： ```shell #!/bin/bash - nohup tiup tidb-lightning -config tidb-lightning.toml > nohup.out & + nohup tiup tidb-lightning: -config tidb-lightning.toml > nohup.out & ``` ## 第 5 步：检查数据 diff --git a/tidb-lightning/deploy-tidb-lightning.md b/tidb-lightning/deploy-tidb-lightning.md index 706be30ee866..25a13f2c358b 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/tidb-lightning/deploy-tidb-lightning.md @@ -23,19 +23,19 @@ aliases: ['/docs-cn/dev/tidb-lightning/deploy-tidb-lightning/','/docs-cn/dev/ref 安装完成后，`~/.bashrc` 已将 TiUP 加入到路径中，你需要新开一个终端或重新声明全局变量 `source ~/.bashrc` 来使用 TiUP。(也可能是`~/.profile`，以 TiUP 输出为准。) -2. 安装 TiUP Lightning 组件： +2. 使用 TiUP 安装 TiDB Lightning。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。请将 `` 替换为目标 TiDB 集群的版本号（例如 `v8.5.0`）： {{< copyable "shell-regular" >}} ```shell - tiup install tidb-lightning + tiup install tidb-lightning: ``` ## 手动部署 ### 下载 TiDB Lightning 安装包 -参考[工具下载](/download-ecosystem-tools.md)文档下载 TiDB Lightning 安装包（TiDB Lightning 完全兼容较低版本的 TiDB 集群，建议选择最新稳定版本）。 +参考[工具下载](/download-ecosystem-tools.md)文档下载 TiDB Lightning 安装包。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。 解压 Lightning 压缩包即可获得 `tidb-lightning` 可执行文件。 diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index f575aedac2e7..6d612f754f4e 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -10,7 +10,7 @@ summary: TiDB Lightning 常见问题的摘要：TiDB Lightning 对TiDB/TiKV/PD ## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ -TiDB Lightning 的版本应与集群相同。如果使用 Local-backend 模式，最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。如果使用 Local-backend 模式，最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式最低版本要求是 2.0.9。 ## TiDB Lightning 支持导入多个库吗？ @@ -27,7 +27,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: -config tidb-lightning.toml`。请将 `` 替换为原导入任务使用的 TiDB Lightning 版本号。 ## 如何校验导入的数据的正确性？ diff --git a/tidb-lightning/troubleshoot-tidb-lightning.md b/tidb-lightning/troubleshoot-tidb-lightning.md index 7e41fe91ccc1..76b79e5f0100 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -37,7 +37,7 @@ strict-format = true **原因 4**：TiDB Lightning 版本太旧。 -建议试试最新的版本，可能会有改善。 +较新的版本可能会改善导入速度。升级时，建议保持 TiDB Lightning 与目标 TiDB 集群的版本一致。 ## `tidb-lightning` 进程意外退出 diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md index 0b36512b331c..36f7b3b609e6 100644 --- a/tidb-troubleshooting-map.md +++ b/tidb-troubleshooting-map.md @@ -419,7 +419,7 @@ TiDB 支持完整的分布式事务，自 v3.0 版本起，提供乐观事务与 - 表结构太复杂。每条索引都会额外增加 KV 对，如果有 N 条索引，实际导入的大小就差不多是 [Dumpling](/dumpling-overview.md) 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - - TiDB Lightning 版本太旧。尝试使用最新的版本，可能会有改善。 + - TiDB Lightning 版本太旧。较新的版本可能会改善导入速度。升级时，建议保持 TiDB Lightning 与目标 TiDB 集群的版本一致。 - 6.2.3 `checksum failed: checksum mismatched remote vs local` From 640516909e281491d7f95c22c4e4f27b1e1d6648 Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 18:34:46 +0800 Subject: [PATCH 2/3] docs: focus Lightning FAQ on version selection --- tidb-lightning/tidb-lightning-faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index 6d612f754f4e..f688765ddbb4 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -1,16 +1,16 @@ --- title: TiDB Lightning 常见问题 aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-faq/','/docs-cn/dev/faq/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 集群相同版本的 TiDB Lightning。如果使用 Local-backend 模式，最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式最低版本要求是 2.0.9。 +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。 ## TiDB Lightning 支持导入多个库吗？ From a2ba3049c0d100a4f03de28c16e17a636e3c9b5e Mon Sep 17 00:00:00 2001 From: YangKeao Date: Sun, 20 Sep 2026 18:41:54 +0800 Subject: [PATCH 3/3] docs: address Lightning version guidance review --- get-started-with-tidb-lightning.md | 4 ++-- migrate-from-sql-files-to-tidb.md | 4 +++- migrate-large-mysql-to-tidb.md | 4 +++- tidb-lightning/deploy-tidb-lightning.md | 2 +- tidb-lightning/tidb-lightning-faq.md | 2 +- tidb-lightning/troubleshoot-tidb-lightning.md | 2 +- tidb-troubleshooting-map.md | 2 +- 7 files changed, 12 insertions(+), 8 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index 9612437d5b66..f84d73944b6b 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -51,7 +51,7 @@ summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首 ## 第 3 步：安装 TiDB Lightning -建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。运行如下命令安装 TiDB Lightning，请将 `` 替换为目标 TiDB 集群的版本号（例如 `v8.5.0`）： +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。运行如下命令安装 TiDB Lightning，请将 `` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）： ```shell tiup install tidb-lightning: @@ -96,7 +96,7 @@ tiup install tidb-lightning: pd-addr = "172.16.31.3:2379,56.78.90.12:3456" ``` -2. 运行 `tidb-lightning`。为避免直接在命令行使用 `nohup` 启动程序时因 `SIGHUP` 信号导致的程序退出，建议将 `nohup` 命令放入脚本中。在以下示例中，请将 `` 替换为第 3 步中安装的版本号： +2. 运行 `tidb-lightning`。为避免直接在命令行使用 `nohup` 启动程序时因 `SIGHUP` 信号导致的程序退出，建议将 `nohup` 命令放入脚本中。在以下示例中，请将 `` 替换为[第 3 步](#第-3-步安装-tidb-lightning)中安装的 TiDB Lightning 的版本号： ```shell #!/bin/bash diff --git a/migrate-from-sql-files-to-tidb.md b/migrate-from-sql-files-to-tidb.md index d09d2445c2ae..26e2937b91c2 100644 --- a/migrate-from-sql-files-to-tidb.md +++ b/migrate-from-sql-files-to-tidb.md @@ -73,12 +73,14 @@ pd-addr = "${ip}:${port}" # 集群 PD 的地址，Lightning 通过 PD 获取 若从 Amazon S3 导入，则需将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 Lightning 节点。 +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。将 `` 替换为目标 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: -config tidb-lightning.toml > nohup.out 2>&1 & ``` 同时，TiDB Lightning 还支持从 `~/.aws/credentials` 读取凭证文件。 diff --git a/migrate-large-mysql-to-tidb.md b/migrate-large-mysql-to-tidb.md index 57cbf273ef72..98ee7d7e609f 100644 --- a/migrate-large-mysql-to-tidb.md +++ b/migrate-large-mysql-to-tidb.md @@ -140,11 +140,13 @@ LIMIT 若从 Amazon S3 导入，则需将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 TiDB Lightning 节点。同时还支持从 `~/.aws/credentials` 读取凭证文件。 + 建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。将 `` 替换为目标 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: -config tidb-lightning.toml > nohup.out 2>&1 & ``` 再使用脚本启动 tidb-lightning。 diff --git a/tidb-lightning/deploy-tidb-lightning.md b/tidb-lightning/deploy-tidb-lightning.md index 25a13f2c358b..261ba66d4137 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/tidb-lightning/deploy-tidb-lightning.md @@ -23,7 +23,7 @@ aliases: ['/docs-cn/dev/tidb-lightning/deploy-tidb-lightning/','/docs-cn/dev/ref 安装完成后，`~/.bashrc` 已将 TiUP 加入到路径中，你需要新开一个终端或重新声明全局变量 `source ~/.bashrc` 来使用 TiUP。(也可能是`~/.profile`，以 TiUP 输出为准。) -2. 使用 TiUP 安装 TiDB Lightning。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。请将 `` 替换为目标 TiDB 集群的版本号（例如 `v8.5.0`）： +2. 使用 TiUP 安装 TiDB Lightning。建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。请将 `` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）： {{< copyable "shell-regular" >}} diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index f688765ddbb4..5cd0286cfb59 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -27,7 +27,7 @@ summary: TiDB Lightning 常见问题的摘要：TiDB Lightning 的版本选择 ## 如何正确重启 TiDB Lightning？ 1. [结束 `tidb-lightning` 进程](#如何正确结束-tidb-lightning-进程)。 -2. 启动一个新的 `tidb-lightning` 任务：执行之前的启动命令，例如 `nohup tiup tidb-lightning: -config tidb-lightning.toml`。请将 `` 替换为原导入任务使用的 TiDB Lightning 版本号。 +2. 重新执行原导入任务的启动命令，以启动一个新的 `tidb-lightning` 任务，例如 `nohup tiup tidb-lightning: -config tidb-lightning.toml`。请将 `` 替换为原导入任务使用的 TiDB Lightning 版本号。 ## 如何校验导入的数据的正确性？ diff --git a/tidb-lightning/troubleshoot-tidb-lightning.md b/tidb-lightning/troubleshoot-tidb-lightning.md index 76b79e5f0100..227141887d9b 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -37,7 +37,7 @@ strict-format = true **原因 4**：TiDB Lightning 版本太旧。 -较新的版本可能会改善导入速度。升级时，建议保持 TiDB Lightning 与目标 TiDB 集群的版本一致。 +较新的 TiDB Lightning 版本可能会改善导入性能。升级时，建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。 ## `tidb-lightning` 进程意外退出 diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md index 36f7b3b609e6..907d8cd0380c 100644 --- a/tidb-troubleshooting-map.md +++ b/tidb-troubleshooting-map.md @@ -419,7 +419,7 @@ TiDB 支持完整的分布式事务，自 v3.0 版本起，提供乐观事务与 - 表结构太复杂。每条索引都会额外增加 KV 对，如果有 N 条索引，实际导入的大小就差不多是 [Dumpling](/dumpling-overview.md) 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 - - TiDB Lightning 版本太旧。较新的版本可能会改善导入速度。升级时，建议保持 TiDB Lightning 与目标 TiDB 集群的版本一致。 + - TiDB Lightning 版本太旧。较新的 TiDB Lightning 版本可能会改善导入性能。升级时，建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。 - 6.2.3 `checksum failed: checksum mismatched remote vs local`