From d75aea9306fdd220873c92b8af2bb3688778a767 Mon Sep 17 00:00:00 2001 From: YangKeao Date: Mon, 21 Sep 2026 09:49:43 +0800 Subject: [PATCH 1/2] This is an automated cherry-pick of #21945 Signed-off-by: ti-chi-bot --- get-started-with-tidb-lightning.md | 13 +++++++++---- migrate-from-sql-files-to-tidb.md | 4 +++- migrate-large-mysql-to-tidb.md | 4 +++- tidb-lightning/deploy-tidb-lightning.md | 6 +++--- tidb-lightning/tidb-lightning-faq.md | 11 ++++++++--- tidb-lightning/troubleshoot-tidb-lightning.md | 2 +- tidb-troubleshooting-map.md | 2 +- 7 files changed, 28 insertions(+), 14 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index 14c40503ecc6..78ec64a413b8 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -1,6 +1,11 @@ --- title: TiDB Lightning 快速上手 +<<<<<<< HEAD summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首先使用 Dumpling 导出数据，然后部署 TiDB 集群。安装最新版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 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 集群相同版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 TiDB Lightning 简介。 +>>>>>>> d1ddc4d189 (tidb-lightning: recommend matching TiDB Lightning and TiDB versions (#21945)) --- # TiDB Lightning 快速上手 @@ -50,10 +55,10 @@ summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首 ## 第 3 步：安装 TiDB Lightning -运行如下命令，安装 TiDB Lightning 的最新版本： +建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。运行如下命令安装 TiDB Lightning，请将 `` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）： ```shell -tiup install tidb-lightning +tiup install tidb-lightning: ``` ## 第 4 步：启动 TiDB Lightning @@ -95,11 +100,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 步](#第-3-步安装-tidb-lightning)中安装的 TiDB Lightning 的版本号： ```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/migrate-from-sql-files-to-tidb.md b/migrate-from-sql-files-to-tidb.md index b46ddeda2553..b0247f35b742 100644 --- a/migrate-from-sql-files-to-tidb.md +++ b/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。将 `` 替换为目标 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 a7cd87c8b4ba..ff79c0372277 100644 --- a/tidb-lightning/deploy-tidb-lightning.md +++ b/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。请将 `` 替换为目标 TiDB 集群的版本号（例如 `v{{{ .tidb-version }}}`）： {{< 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 9e59d6151d71..227ddce5de35 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -1,15 +1,20 @@ --- title: TiDB Lightning 常见问题 +<<<<<<< HEAD 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 的步骤。 +======= +aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-faq/','/docs-cn/dev/faq/tidb-lightning/'] +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 的步骤。 +>>>>>>> d1ddc4d189 (tidb-lightning: recommend matching TiDB Lightning and TiDB versions (#21945)) --- # 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 +31,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 ee9565901d3f..ccc90ed48a46 100644 --- a/tidb-lightning/troubleshoot-tidb-lightning.md +++ b/tidb-lightning/troubleshoot-tidb-lightning.md @@ -36,7 +36,7 @@ strict-format = true **原因 4**：TiDB Lightning 版本太旧。 -建议试试最新的版本，可能会有改善。 +较新的 TiDB Lightning 版本可能会改善导入性能。升级时，建议使用与目标 TiDB 集群相同版本的 TiDB Lightning。 ## `tidb-lightning` 进程意外退出 diff --git a/tidb-troubleshooting-map.md b/tidb-troubleshooting-map.md index 43b055b51ae0..e8676179692e 100644 --- a/tidb-troubleshooting-map.md +++ b/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` From 18f7d361245d6ea6b85e4c75436df964a0d34809 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Mon, 21 Sep 2026 10:19:39 +0800 Subject: [PATCH 2/2] Apply suggestions from code review --- get-started-with-tidb-lightning.md | 5 ----- tidb-lightning/tidb-lightning-faq.md | 5 ----- 2 files changed, 10 deletions(-) diff --git a/get-started-with-tidb-lightning.md b/get-started-with-tidb-lightning.md index 78ec64a413b8..566a97da61d3 100644 --- a/get-started-with-tidb-lightning.md +++ b/get-started-with-tidb-lightning.md @@ -1,11 +1,6 @@ --- title: TiDB Lightning 快速上手 -<<<<<<< HEAD -summary: TiDB Lightning 可快速将 MySQL 数据导入到 TiDB 集群中。首先使用 Dumpling 导出数据，然后部署 TiDB 集群。安装最新版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 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 集群相同版本的 TiDB Lightning 并启动，最后检查数据导入情况。详细功能和使用请参考 TiDB Lightning 简介。 ->>>>>>> d1ddc4d189 (tidb-lightning: recommend matching TiDB Lightning and TiDB versions (#21945)) --- # TiDB Lightning 快速上手 diff --git a/tidb-lightning/tidb-lightning-faq.md b/tidb-lightning/tidb-lightning-faq.md index 227ddce5de35..675310c72ba0 100644 --- a/tidb-lightning/tidb-lightning-faq.md +++ b/tidb-lightning/tidb-lightning-faq.md @@ -1,11 +1,6 @@ --- title: TiDB Lightning 常见问题 -<<<<<<< HEAD -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 的步骤。 -======= -aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-faq/','/docs-cn/dev/faq/tidb-lightning/'] 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 的步骤。 ->>>>>>> d1ddc4d189 (tidb-lightning: recommend matching TiDB Lightning and TiDB versions (#21945)) --- # TiDB Lightning 常见问题