基于 elasticdump 的一站式 Elasticsearch 数据迁移解决方案
Elasticdump Plus 是基于 elasticdump 的增强工具集，旨在解决实际使用 elasticdump 过程中遇到的核心问题，为 Elasticsearch 数据迁移提供更稳定、更易用的解决方案。
本项目专注于解决 elasticdump 在实际生产环境中使用的痛点问题，通过脚本封装、参数优化、错误处理等方式，打造一个开箱即用、稳定可靠的一站式 dump 解决方案。
- 问题：初次使用 elasticdump 时，长时间运行的 dump 任务可能因 session 过期而失败
- 解决方案：脚本支持后台执行，提供日志追踪功能，任务失败后可查看详细日志进行排查
- 问题：每次使用 elasticdump 都需要在命令行中拼接复杂的 URL 和认证信息
- 解决方案：通过配置文件（JSON）统一管理 input 和 output 的 ES 连接信息，支持多种配置方式
- 问题：默认参数可能导致大索引 dump 失败，缺乏重试和错误处理机制
- 解决方案：
- 优化超时、重试等参数，提高 dump 成功率
- 支持
--ignore-errors参数，单条文档失败不影响整体任务 - 可调整批量大小（
--limit），适配不同大小的文档
- 问题：elasticdump 默认使用 scroll API，在某些场景下效率较低
- 解决方案：支持两种 dump 方式
- Scroll API：默认方式，更稳定，适合大多数场景
- Search After + PIT：更高效，支持断点续传，适合大数据量场景
- 问题：超大索引（TB 级别）一次性 dump 成功率低，失败后需要重新开始
- 解决方案：
- 支持
--shard参数，实现分片级别的 dump - 可以按分片逐个导出，大大提高成功率
- 支持断点续传（search_after 模式）
- 支持
- Linux 系统（优先支持 Ubuntu/Debian）
- 需要 root 或 sudo 权限（用于安装依赖）
# 添加执行权限
chmod +x install.sh
# 运行安装脚本
./install.sh安装脚本会自动：
- 检测并安装 Node.js 和 npm（如果未安装）
- 全局安装 elasticdump
- 检查可选依赖（jq、python3）
# 1. 安装 Node.js 和 npm（Ubuntu/Debian）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
# 2. 安装 elasticdump
sudo npm install -g elasticdump
# 3. 安装可选依赖（用于 JSON 解析）
sudo apt-get install -y jq python3{
"url": "https://username:password@hostname:9200"
}或者使用节点列表方式：
{
"url": "https://username:password@hostname:9200",
"nodes": [
"node1.example.com",
"node2.example.com",
"node3.example.com"
],
"port": 9200,
"user": "username",
"password": "password"
}格式与 config_input.json 相同。
如果不需要从源索引自动获取 mapping，可以手动配置：
{
"settings": {
"index": {
"number_of_shards": 1,
"number_of_replicas": 1
}
},
"mappings": {
"properties": {
"field1": {
"type": "text"
}
}
}
}# 查看帮助
./run_elasticdump.sh --help
# 启动 dump 任务（使用默认配置）
./run_elasticdump.sh start <索引名>
# 指定输入输出配置
./run_elasticdump.sh start <索引名> -i config_input.json -o config_output.json
# 指定输出索引名（默认与输入索引名相同）
./run_elasticdump.sh start <输入索引名> --output-index <输出索引名>启动指定索引的 elasticdump 后台任务。
必需参数：
<输入索引名>- 源索引名称
选项参数：
| 参数 | 简写 | 说明 | 默认值 |
|---|---|---|---|
--output-index |
-O |
输出索引名称 | 与输入索引名相同 |
--input-config |
-i |
输入 ES 配置文件路径 | config_input.json |
--output-config |
-o |
输出 ES 配置文件路径 | config_output.json |
--offset |
- | 从第 N 个文档开始导出（断点续传） | - |
--shard |
- | 仅导出指定分片ID的数据 | - |
--limit |
-l |
每次读取的文档数量 | 1000 |
--use-source-mapping |
- | 从源索引自动获取 mapping | false |
--use-search-after |
- | 使用 search_after + PIT 模式 | false（使用 scroll） |
--sort-field |
- | 指定排序字段（必须与 --use-search-after 一起使用） | - |
--debug |
-d |
启用 debug 模式 | false |
--help |
-h |
显示帮助信息 | - |
# 停止指定索引的任务
./run_elasticdump.sh stop <索引名>
# 停止所有任务
./run_elasticdump.sh stop-all# 查看指定索引的状态
./run_elasticdump.sh status <索引名>
# 查看所有任务状态
./run_elasticdump.sh status
# 或
./run_elasticdump.sh list./run_elasticdump.sh restart <索引名> [选项]# 测试输入输出 ES 连接和索引是否存在
./run_elasticdump.sh test <索引名> [input_config] [output_config]# 查看索引的分片配置和列表
./run_elasticdump.sh list-shards <索引名> [input_config]# 手动关闭指定索引的 PIT（Point in Time）
./run_elasticdump.sh close-pit <索引名>最简单的使用方式，使用默认配置：
./run_elasticdump.sh start my_index对于超大索引，按分片逐个导出，提高成功率：
# 1. 先查看分片信息
./run_elasticdump.sh list-shards my_large_index
# 2. 按分片导出（例如导出分片 0）
./run_elasticdump.sh start my_large_index --shard=0
# 3. 导出其他分片
./run_elasticdump.sh start my_large_index --shard=1
./run_elasticdump.sh start my_large_index --shard=2
# ...适合大数据量场景，支持断点续传：
# 启动任务（必须指定排序字段）
./run_elasticdump.sh start my_index \
--use-search-after \
--sort-field=doc_id
# 如果任务失败，可以从指定位置继续
./run_elasticdump.sh start my_index \
--use-search-after \
--sort-field=doc_id \
--offset=50000无需手动创建 mapping.json：
./run_elasticdump.sh start my_index --use-source-mapping如果索引中包含大文档，可以减小批量大小：
./run_elasticdump.sh start my_index --limit=100./run_elasticdump.sh start my_index \
-i /path/to/input_config.json \
-o /path/to/output_config.json./run_elasticdump.sh start source_index --output-index target_index-
优点：
- 更稳定，不需要排序字段
- 适合大多数场景
- 支持分片过滤（
--shard）
-
缺点：
- 不支持断点续传
- 深度分页时效率较低
使用示例：
./run_elasticdump.sh start my_index-
优点：
- 更高效，适合大数据量
- 支持断点续传（
--offset） - 使用 PIT 保证数据一致性
-
缺点：
- 必须指定排序字段
- 不支持分片过滤（
--shard）
使用示例：
./run_elasticdump.sh start my_index \
--use-search-after \
--sort-field=doc_id当索引很大时，可以按分片逐个导出：
-
查看分片信息：
./run_elasticdump.sh list-shards my_index
-
导出指定分片：
./run_elasticdump.sh start my_index --shard=0
注意： 使用 --shard 参数时，会自动使用 scroll API（因为 PIT 不支持 preference 参数）。
仅在 --use-search-after 模式下有效：
# 从第 50000 个文档开始继续 dump
./run_elasticdump.sh start my_index \
--use-search-after \
--sort-field=doc_id \
--offset=50000默认每次读取 1000 个文档。如果文档很大，可以减小批量大小：
# 减小批量大小，避免请求过大
./run_elasticdump.sh start my_index --limit=100每个索引使用独立的日志文件：
elasticdump.<索引名>.log
# 实时查看日志
tail -f elasticdump.my_index.log
# 查看最近 100 行
tail -n 100 elasticdump.my_index.log任务失败时会保存进度到：
elasticdump.<索引名>.progress
格式：文档数|时间戳
-
Search After 模式必须指定排序字段
- 使用
--use-search-after时必须同时指定--sort-field - 排序字段必须在索引中存在且可排序
- 使用
-
分片导出限制
- 使用
--shard参数时，会自动使用 scroll API - PIT 不支持 preference 参数，因此 search_after 模式不支持分片过滤
- 使用
-
PIT 管理
- search_after 任务成功时 PIT 会自动关闭
- 任务失败时 PIT 会保留（1 小时后自动过期）
- 可以使用
close-pit命令手动关闭保留的 PIT
-
配置文件格式
- URL 中的密码如果包含特殊字符，需要进行 URL 编码
- 例如：
#需要编码为%23
-
权限要求
- 需要 ES 的读写权限
- 使用
--use-source-mapping时需要读取源索引 mapping 的权限
错误信息：
错误: elasticdump 未安装
请先安装: npm install -g elasticdump
解决方案：
# 运行安装脚本
./install.sh
# 或手动安装
sudo npm install -g elasticdump错误信息：
错误: 输入节点连接失败
解决方案：
- 检查配置文件中的 URL 是否正确
- 检查网络连接
- 检查 ES 服务是否正常运行
- 使用
test命令测试连接：./run_elasticdump.sh test my_index
错误信息：
错误: 使用 --use-search-after 时必须指定 --sort-field 参数
解决方案： 必须同时指定排序字段：
./run_elasticdump.sh start my_index \
--use-search-after \
--sort-field=doc_id解决方案：
- 查看日志文件，找到已导出的文档数
- 使用
--offset参数继续：./run_elasticdump.sh start my_index \ --use-search-after \ --sort-field=doc_id \ --offset=<已导出的文档数>
欢迎提交 Issue 和 Pull Request！
MIT License
- elasticdump - 本项目基于 elasticdump 构建
如有问题或建议，请提交 Issue。