TiKV Importer 镜像文档

镜像概述和主要用途

本镜像为分布式事务型键值数据库TiKV的专用数据导入工具，旨在提供高效、可靠的批量数据导入能力。通过该工具可将外部数据源（如CSV文件、SQL导出数据等）高效导入TiKV集群，支持大规模数据迁移与初始化，是TiKV生态中数据集成的核心组件之一。

核心功能和特性

核心功能

多数据源支持：兼容CSV、TSV等结构化文本格式，以及主流数据库（如MySQL、PostgreSQL）导出的数据文件。
高效批量导入：基于TiKV的批量写入接口优化，减少网络交互开销，提升导入吞吐量。
事务一致性：导入过程中保证数据的事务一致性，避免部分导入导致的数据不一致问题。
集群兼容性：适配TiKV v4.0及以上版本集群，支持与TiKV集群动态扩容/缩容协同工作。

关键特性

并行处理：支持多线程并行导入，可通过配置调整并发度以匹配集群资源。
灵活配置：提供丰富的配置选项，支持自定义导入模式（追加/覆盖）、数据映射规则及性能参数。
监控集成：支持导出Prometheus监控指标，便于跟踪导入进度与性能瓶颈。
容错机制：具备断点续传能力，网络中断或节点故障后可恢复导入进度。

使用场景和适用范围

典型场景

TiKV集群初始化：新部署TiKV集群时，批量导入初始业务数据（如历史订单、用户信息等）。
跨数据库迁移：从关系型数据库（MySQL、PostgreSQL）或其他KV数据库（如Redis）迁移数据至TiKV。
定期数据同步：业务系统每日/每周批量导出数据并同步至TiKV集群（如报表数据、日志归档）。
大数据量加载：TB级以上数据高效导入TiKV，适用于数据仓库、时序数据存储等场景。

适用范围

数据量：支持MB至PB级数据导入，建议单批次数据量不小于1GB以发挥批量导入优势。
数据源：本地文件、NFS共享存储或对象存储（需通过数据卷挂载至容器）。
TiKV集群：需运行正常且网络可访问的TiKV集群（含PD服务）。

使用方法和配置说明

基本使用示例

1. 基础Docker Run命令

bash
docker run -d \
  --name tikv-importer \
  -v /host/data:/data  `# 挂载本地数据源目录至容器内/data` \
  -v /host/config:/config  `# 挂载配置文件目录` \
  -e TIKV_PD_ADDRESSES="pd-node1:2379,pd-node2:2379"  `# TiKV集群PD服务地址（必填）` \
  -e DATA_SOURCE_PATH="/data/input.csv"  `# 数据源文件路径（容器内路径，必填）` \
  -e IMPORT_MODE="append"  `# 导入模式：append（追加）/overwrite（覆盖），默认append` \
  -e WORKERS=4  `# 并行工作线程数，默认2` \
  tikv-importer:latest

2. 查看导入日志

bash
docker logs -f tikv-importer

环境变量配置

环境变量名	说明	是否必填	默认值
`TIKV_PD_ADDRESSES`	TiKV集群PD服务地址列表，多个地址用逗号分隔（如"pd1:2379,pd2:2379"）	是	-
`DATA_SOURCE_PATH`	数据源文件路径（容器内绝对路径，如"/data/input.csv"）	是	-
`IMPORT_MODE`	导入模式：`append`（追加数据）/`overwrite`（覆盖现有数据）	否	`append`
`WORKERS`	并行导入线程数，建议设置为CPU核心数的1-2倍	否	2
`BATCH_SIZE`	每批导入记录数（单位：条），调整该值可优化内存占用与吞吐量	否	1000
`LOG_LEVEL`	日志级别：`debug`/`info`/`warn`/`error`	否	`info`
`TIMEOUT`	导入超时时间（如"30m"表示30分钟），0表示无超时	否	"60m"

配置文件使用

对于复杂配置场景，可通过配置文件定义详细规则（优先级高于环境变量）。配置文件为TOML格式，示例如下：

toml
# /host/config/importer.toml（本地配置文件）
[pd]
addresses = ["pd-node1:2379", "pd-node2:2379"]  # TiKV PD地址列表
timeout = "10s"  # PD连接超时时间

[data_source]
path = "/data/input.csv"  # 数据源路径（容器内路径）
format = "csv"  # 数据格式：csv/tsv
delimiter = ","  # 字段分隔符（csv默认","，tsv默认"\t"）
header = true  # 是否包含表头行（用于字段映射）
skip_rows = 1  # 跳过开头行数（若header=true，默认跳过1行表头）

[import]
mode = "overwrite"  # 导入模式
workers = 8  # 并行线程数
batch_size = 2000  # 每批记录数
checksum = true  # 是否校验导入数据完整性

[log]
level = "debug"  # 日志级别
file = "/var/log/importer.log"  # 日志文件路径（容器内路径，需挂载日志目录）

启动容器时挂载配置文件：

bash
docker run -d \
  --name tikv-importer \
  -v /host/data:/data \
  -v /host/config:/config \  # 本地配置目录挂载至容器/config
  -v /host/log:/var/log \  # 挂载日志目录（可选）
  tikv-importer:latest --config /config/importer.toml  `# 指定配置文件路径`

导入进度监控

通过容器日志或Prometheus指标监控导入进度：

日志关键字："import progress: X%"（显示当前导入百分比）、"import completed successfully"（导入完成）。
Prometheus指标：容器暴露9090端口，指标包括tikv_importer_records_total（总导入记录数）、tikv_importer_duration_seconds（导入耗时）等。

注意事项

网络连通性：确保容器与TiKV集群（含PD服务）网络互通，可通过docker exec -it tikv-importer ping pd-node1测试连通性。
数据格式校验：导入前建议校验数据源文件格式（如字段数一致、无非法字符），避免格式错误导致导入失败。
资源配置：根据数据量调整容器CPU/内存资源（建议至少2核4GB内存），避免资源不足导致OOM。
数据备份：使用overwrite模式时，建议先备份TiKV集群数据，防止误操作覆盖重要数据。
权限设置：挂载的数据卷（数据源、配置、日志目录）需赋予容器读取/写入权限（如chmod 755 /host/data）。