|
1 | 1 | --- |
2 | 2 | title: TiDB Lightning 常见问题 |
3 | | -aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-faq/','/docs-cn/dev/faq/tidb-lightning/'] |
| 3 | +aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-faq/','/docs-cn/dev/faq/tidb-lightning/','/docs-cn/dev/troubleshoot-tidb-lightning/','/docs-cn/dev/how-to/troubleshoot/tidb-lightning/','/docs-cn/dev/reference/tools/error-case-handling/lightning-misuse-handling/','/docs-cn/dev/tidb-lightning/tidb-lightning-misuse-handling/','/zh/tidb/dev/tidb-lightning-faq/'] |
4 | 4 | --- |
5 | 5 |
|
6 | 6 | # TiDB Lightning 常见问题 |
7 | 7 |
|
8 | 8 | 本文列出了一些使用 TiDB Lightning 时可能会遇到的问题与解决办法。 |
9 | 9 |
|
10 | | ->**注意：** |
11 | | -> |
12 | | -> 使用 TiDB Lightning 的过程中如遇错误，参考 [TiDB Lightning 故障诊断](/troubleshoot-tidb-lightning.md)进行排查。 |
13 | | -
|
14 | 10 | ## TiDB Lightning 对 TiDB/TiKV/PD 的最低版本要求是多少？ |
15 | 11 |
|
16 | 12 | TiDB Lightning 的版本应与集群相同。如果使用 Local-backend 模式，最低版本要求为 4.0.0。如果使用 Importer-backend 或 TiDB-backend 模式 最低版本要求是 2.0.9，但建议使用最新的稳定版本 3.0。 |
@@ -61,7 +57,7 @@ Local-backend 和 Importer-backend 无需以上两个权限，因为数据直接 |
61 | 57 | 4. 重启 `tikv-importer`。 |
62 | 58 | 5. 重启 `tidb-lightning` 并等待，**直到程序因校验和错误（如果有的话）而失败**。 |
63 | 59 | * 重启 `tikv-importer` 将清除所有仍在写入的引擎文件，但是 `tidb-lightning` 并不会感知到该操作。从 v3.0 开始，最简单的方法是让 `tidb-lightning` 继续，然后再重试。 |
64 | | -6. [清除失败的表及断点](/troubleshoot-tidb-lightning.md#checkpoint-for--has-invalid-status错误码)。 |
| 60 | +6. [清除失败的表及断点](#checkpoint-for--has-invalid-status错误码)。 |
65 | 61 | 7. 再次重启 `tidb-lightning`。 |
66 | 62 |
|
67 | 63 | 如果使用 Local-backend 和 TiDB-backend，操作和 Importer-backend 的 `tikv-importer` 仍在运行时相同。 |
@@ -191,10 +187,156 @@ upload-speed-limit = "100MB" |
191 | 187 |
|
192 | 188 | 如果出于某些原因而无法运行该命令，你可以尝试手动删除 `/tmp/tidb_lightning_checkpoint.pb` 文件。 |
193 | 189 |
|
194 | | -2. 删除 `tikv-importer` 所在机器上的整个 “import” 文件目录。 |
| 190 | +2. 如果使用 Local-backend，删除配置中 `sorted-kv-dir` 对应的目录；如果使用 Importer-backend，删除 `tikv-importer` 所在机器上的整个 `import` 文件目录。 |
195 | 191 |
|
196 | 192 | 3. 如果需要的话，删除 TiDB 集群上创建的所有表和库。 |
197 | 193 |
|
198 | 194 | ## TiDB Lightning 报错 `could not find first pair, this shouldn't happen` |
199 | 195 |
|
200 | 196 | 报错原因是遍历本地排序的文件时出现异常，可能在 lightning 打开的文件数量超过系统的上限时发生。在 linux 系统中，可以使用 `ulimit -n` 命令确认此值是否过小。建议在 lightning 导入期间将此设置调整为 1000000（`ulimit -n 1000000`）。 |
| 197 | + |
| 198 | +## TiDB Lightning 导入速度太慢 |
| 199 | + |
| 200 | +TiDB Lightning 的正常速度为每条线程每 2 分钟导入一个 256 MB 的数据文件，如果速度远慢于这个数值就是有问题。导入的速度可以检查日志提及 `restore chunk … takes` 的记录，或者观察 Grafana 的监控信息。 |
| 201 | + |
| 202 | +导入速度太慢一般有几个原因： |
| 203 | + |
| 204 | +**原因 1**：`region-concurrency` 设定太高，线程间争用资源反而减低了效率。 |
| 205 | + |
| 206 | +1. 从日志的开头搜寻 `region-concurrency` 能知道 Lightning 读到的参数是多少。 |
| 207 | +2. 如果 Lightning 与其他服务（如 Importer）共用一台服务器，必需**手动**将 `region-concurrency` 设为该服务器 CPU 数量的 75%。 |
| 208 | +3. 如果 CPU 设有限额（例如从 Kubernetes 指定的上限），Lightning 可能无法自动判断出来，此时亦需要**手动**调整 `region-concurrency`。 |
| 209 | + |
| 210 | +**原因 2**：表结构太复杂。 |
| 211 | + |
| 212 | +每条索引都会额外增加键值对。如果有 N 条索引，实际导入的大小就差不多是 Dumpling 文件的 N+1 倍。如果索引不太重要，可以考虑先从 schema 去掉，待导入完成后再使用 `CREATE INDEX` 加回去。 |
| 213 | + |
| 214 | +**原因 3**: 单个文件过大。 |
| 215 | + |
| 216 | +把源数据分割为单个大小约为 256 MB 的多个文件时，TiDB Lightning 会并行处理数据，达到最佳效果。如果导入的单个文件过大，TiDB Lightning 可能无响应。 |
| 217 | + |
| 218 | +如果源数据是 CSV 格式文件，并且所有的 CSV 文件内都不存在包含字符换行符的字段 (U+000A 及 U+000D)，则可以启用 `strict-format`，TiDB Lightning 会自动分割大文件。 |
| 219 | + |
| 220 | +```toml |
| 221 | +[mydumper] |
| 222 | +strict-format = true |
| 223 | +``` |
| 224 | + |
| 225 | +**原因 4**：TiDB Lightning 版本太旧。 |
| 226 | + |
| 227 | +试试最新的版本吧！可能会有改善。 |
| 228 | + |
| 229 | +## `checksum failed: checksum mismatched remote vs local` |
| 230 | + |
| 231 | +**原因**：本地数据源跟目标数据库某个表的校验和不一致。这通常有更深层的原因： |
| 232 | + |
| 233 | +1. 这张表可能本身已有数据，影响最终结果。 |
| 234 | +2. 如果目标数据库的校验和全是 0，表示没有发生任何导入，有可能是集群太忙无法接收任何数据。 |
| 235 | +3. 如果数据源是由机器生成而不是从 Dumpling 备份的，需确保数据符合表的限制，例如： |
| 236 | + |
| 237 | + * 自增 (AUTO_INCREMENT) 的列需要为正数，不能为 0。 |
| 238 | + * 唯一键和主键 (UNIQUE and PRIMARY KEYs) 不能有重复的值。 |
| 239 | +4. 如果 TiDB Lightning 之前失败停机过，但没有正确重启，可能会因为数据不同步而出现校验和不一致。 |
| 240 | + |
| 241 | +**解决办法**： |
| 242 | + |
| 243 | +1. 使用 `tidb-lightning-ctl` 把出错的表删除，然后重启 Lightning 重新导入那些表。 |
| 244 | + |
| 245 | + {{< copyable "shell-regular" >}} |
| 246 | + |
| 247 | + ```sh |
| 248 | + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all |
| 249 | + ``` |
| 250 | + |
| 251 | +2. 把断点存放在外部数据库（修改 `[checkpoint] dsn`），减轻目标集群压力。 |
| 252 | + |
| 253 | +3. 参考[如何正确重启 TiDB Lightning](/tidb-lightning/tidb-lightning-faq.md#如何正确重启-tidb-lightning)中的解决办法。 |
| 254 | + |
| 255 | +## `Checkpoint for … has invalid status:`（错误码） |
| 256 | + |
| 257 | +**原因**：[断点续传](/tidb-lightning/tidb-lightning-checkpoints.md)已启用。Lightning 或 Importer 之前发生了异常退出。为了防止数据意外损坏，Lightning 在错误解决以前不会启动。 |
| 258 | + |
| 259 | +错误码是小于 25 的整数，可能的取值是 0、3、6、9、12、14、15、17、18、20、21。整数越大，表示异常退出所发生的步骤在导入流程中越晚。 |
| 260 | + |
| 261 | +**解决办法**： |
| 262 | + |
| 263 | +如果错误原因是非法数据源，使用 `tidb-lightning-ctl` 删除已导入数据，并重启 Lightning。 |
| 264 | + |
| 265 | +{{< copyable "shell-regular" >}} |
| 266 | + |
| 267 | +```sh |
| 268 | +tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all |
| 269 | +``` |
| 270 | + |
| 271 | +其他解决方法请参考[断点续传的控制](/tidb-lightning/tidb-lightning-checkpoints.md#断点续传的控制)。 |
| 272 | + |
| 273 | +## `ResourceTemporarilyUnavailable("Too many open engines …: …")` |
| 274 | + |
| 275 | +**原因**：并行打开的引擎文件 (engine files) 超出 `tikv-importer` 里的限制。这可能由配置错误引起。即使配置没问题，如果 `tidb-lightning` 曾经异常退出，也有可能令引擎文件残留在打开的状态，占据可用的数量。 |
| 276 | + |
| 277 | +**解决办法**： |
| 278 | + |
| 279 | +1. 提高 `tikv-importer.toml` 内 `max-open-engines` 的值。这个设置主要由内存决定，计算公式为： |
| 280 | + |
| 281 | + 最大内存使用量 ≈ `max-open-engines` × `write-buffer-size` × `max-write-buffer-number` |
| 282 | + |
| 283 | +2. 降低 `table-concurrency` + `index-concurrency`，使之低于 `max-open-engines`。 |
| 284 | + |
| 285 | +3. 重启 `tikv-importer` 来强制移除所有引擎文件 (默认值为 `./data.import/`)。这样也会丢弃导入了一半的表，所以启动 Lightning 前必须清除过期的断点记录： |
| 286 | + |
| 287 | + {{< copyable "shell-regular" >}} |
| 288 | + |
| 289 | + ```sh |
| 290 | + tidb-lightning-ctl --config conf/tidb-lightning.toml --checkpoint-error-destroy=all |
| 291 | + ``` |
| 292 | + |
| 293 | +## `cannot guess encoding for input file, please convert to UTF-8 manually` |
| 294 | + |
| 295 | +**原因**：Lightning 只支持 UTF-8 和 GB-18030 编码的表架构。此错误代表数据源不是这里任一个编码。也有可能是文件中混合了不同的编码，例如，因为在不同的环境运行过 `ALTER TABLE`，使表架构同时出现 UTF-8 和 GB-18030 的字符。 |
| 296 | + |
| 297 | +**解决办法**： |
| 298 | + |
| 299 | +1. 编辑数据源，保存为纯 UTF-8 或 GB-18030 的文件。 |
| 300 | +2. 手动在目标数量库创建所有的表，然后设置 `[mydumper] no-schema = true` 跳过创建表的步骤。 |
| 301 | +3. 设置 `[mydumper] character-set = "binary"` 跳过这个检查。但是这样可能使数据库出现乱码。 |
| 302 | + |
| 303 | +## [sql2kv] sql encode error = [types:1292]invalid time format: '{1970 1 1 …}' |
| 304 | + |
| 305 | +**原因**: 一个 `timestamp` 类型的时间戳记录了不存在的时间值。时间值不存在是由于夏时制切换或超出支持的范围（1970 年 1 月 1 日至 2038 年 1 月 19 日）。 |
| 306 | + |
| 307 | +**解决办法**: |
| 308 | + |
| 309 | +1. 确保 Lightning 与数据源时区一致。 |
| 310 | + |
| 311 | + * 手动部署的话，通过设定 `$TZ` 环境变量强制时区设定。 |
| 312 | + |
| 313 | + 强制使用 Asia/Shanghai 时区： |
| 314 | + |
| 315 | + {{< copyable "shell-regular" >}} |
| 316 | + |
| 317 | + ```sh |
| 318 | + TZ='Asia/Shanghai' bin/tidb-lightning -config tidb-lightning.toml |
| 319 | + ``` |
| 320 | + |
| 321 | +2. 导出数据时，必须加上 `--skip-tz-utc` 选项。 |
| 322 | + |
| 323 | +3. 确保整个集群使用的是同一最新版本的 `tzdata` (2018i 或更高版本)。 |
| 324 | + |
| 325 | + 如果你使用的是 CentOS 机器，你可以运行 `yum info tzdata` 命令查看 `tzdata` 的版本及是否有更新。然后运行 `yum upgrade tzdata` 命令升级 `tzdata`。 |
| 326 | + |
| 327 | +## `[Error 8025: entry too large, the max entry size is 6291456]` |
| 328 | + |
| 329 | +**原因**：TiDB Lightning 生成的单行 KV 超过了 TiDB 的限制。 |
| 330 | + |
| 331 | +**解决办法**: |
| 332 | + |
| 333 | +目前无法绕过 TiDB 的限制，只能忽略这张表，确保其它表顺利导入。 |
| 334 | + |
| 335 | +## switch-mode 时遇到 `rpc error: code = Unimplemented ...` |
| 336 | + |
| 337 | +**原因**：集群中有不支持 switch-mode 的节点。目前已知的组件中，4.0.0-rc.2 之前的 TiFlash [不支持 switch-mode 操作](https://github.com/pingcap/tidb-lightning/issues/273)。 |
| 338 | + |
| 339 | +**解决办法**： |
| 340 | + |
| 341 | +- 如果集群中有 TiFlash 节点，可以将集群更新到 4.0.0-rc.2 或更新版本。 |
| 342 | +- 如果不方便升级，可以临时禁用 TiFlash。 |
0 commit comments