elasticdump

用于移动和保存 Elasticsearch 和 OpenSearch 索引的工具

---

版本警告!

• Elasticdump 的 1.0.0 版本改变了转储创建的文件格式。用该工具 0.x.x 版本创建的文件可能无法与未来的版本兼容。要了解更多关于重大变更的信息，请访问 1.0.0 版本的发布说明。如果您收到"内存不足"错误，这很可能是原因。
• Elasticdump 的 2.0.0 版本移除了 bulk 选项。这些选项存在错误，并且在不同版本的 Elasticsearch 之间有差异。如果您需要导出多个索引，请查看该工具的 multielasticdump 部分。
• Elasticdump 的 2.1.0 版本从使用 scan/scroll(ES 1.x)转变为仅使用 scroll(ES 2.x)。这是 Elasticsearch 内部向后兼容的更改，但在 2.x 之前的 Elasticsearch 版本上性能可能会下降。
• Elasticdump 的 3.0.0 版本更新了默认查询，仅适用于 ElasticSearch 5+ 版本。该工具可能与早期版本的 Elasticsearch 兼容，但我们的版本检测方法可能不适用于所有 ES 集群拓扑。
• Elasticdump 的 5.0.0 版本包含 s3 传输的重大变更。不再支持 s3Bucket 和 s3RecordKey 参数，请改用 s3urls。
• Elasticdump 的 6.1.0 及更高版本包含对上传/转储过程的更改。此更改允许重叠的 promise 处理。其好处是由于增加了并行处理而提高了性能，但存在一个副作用，即记录(数据集)不会按顺序处理(不再保证顺序)。
• Elasticdump 的 6.67.0 及更高版本如果 node 版本不符合所需的最低要求(v10.0.0)，将会退出。
• Elasticdump 的 6.76.0 及更高版本增加了对 OpenSearch 的支持(从 Elasticsearch 7.10.2 分叉)

安装

(本地)

npm install elasticdump
./bin/elasticdump

(全局)

npm install elasticdump -g
elasticdump

使用

标准安装

Elasticdump 通过将"输入"发送到"输出"来工作。两者都可以是 elasticsearch URL 或文件。

Elasticsearch/OpenSearch:

• 格式: {protocol}://{host}:{port}/{index}
• 示例: http://127.0.0.1:9200/my_index

文件:

• 格式: {FilePath}
• 示例: /Users/evantahler/Desktop/dump.json

标准输入/输出:

• 格式: stdin / stdout
• 格式: $

然后您可以执行以下操作:

# 将索引从生产环境复制到测试环境，包括分析器和映射:
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=http://staging.es.com:9200/my_index \
  --type=analyzer
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=http://staging.es.com:9200/my_index \
  --type=mapping
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=http://staging.es.com:9200/my_index \
  --type=data

# 将索引数据备份到文件:
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=/data/my_index_mapping.json \
  --type=mapping
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=/data/my_index.json \
  --type=data

# 使用 stdout 将索引备份到 gzip:
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=$ \
  | gzip > /data/my_index.json.gz

# 将查询结果备份到文件
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=query.json \
  --searchBody="{\"query\":{\"term\":{\"username\": \"admin\"}}}"
  
# 从文件指定 searchBody
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=query.json \
  --searchBody=@/data/searchbody.json  

# 复制单个分片数据:
elasticdump \
  --input=http://es.com:9200/api \
  --output=http://es.com:9200/api2 \
  --input-params="{\"preference\":\"_shards:0\"}"

# 将别名备份到文件
elasticdump \
  --input=http://es.com:9200/index-name/alias-filter \
  --output=alias.json \
  --type=alias

# 将别名导入到 ES
elasticdump \
  --input=./alias.json \
  --output=http://es.com:9200 \
  --type=alias

# 将模板备份到文件
elasticdump \
  --input=http://es.com:9200/template-filter \
  --output=templates.json \
  --type=template

# 将模板导入到 ES
elasticdump \
  --input=./templates.json \
  --output=http://es.com:9200 \
  --type=template

# 将文件拆分为多个部分
elasticdump \
  --input=http://production.es.com:9200/my_index \
  --output=/data/my_index.json \
  --fileSize=10mb

# 从 S3 导入数据到 ES (使用 s3urls)
elasticdump \
  --s3AccessKeyId "${access_key_id}" \
  --s3SecretAccessKey "${access_key_secret}" \
  --input "s3://${bucket_name}/${file_name}.json" \
  --output=http://production.es.com:9200/my_index

# 将 ES 数据导出到 S3 (使用 s3urls)
elasticdump \
  --s3AccessKeyId "${access_key_id}" \
  --s3SecretAccessKey "${access_key_secret}" \
  --input=http://production.es.com:9200/my_index \
  --output "s3://${bucket_name}/${file_name}.json"

# 从 MINIO (s3 兼容) 导入数据到 ES (使用 s3urls)
elasticdump \
  --s3AccessKeyId "${access_key_id}" \
  --s3SecretAccessKey "${access_key_secret}" \
  --input "s3://${bucket_name}/${file_name}.json" \
  --output=http://production.es.com:9200/my_index
  --s3ForcePathStyle true
  --s3Endpoint https://production.minio.co

# 将 ES 数据导出到 MINIO (s3 兼容) (使用 s3urls)
elasticdump \
  --s3AccessKeyId "${access_key_id}" \
  --s3SecretAccessKey "${access_key_secret}" \
  --input=http://production.es.com:9200/my_index \
  --output "s3://${bucket_name}/${file_name}.json"
  --s3ForcePathStyle true
  --s3Endpoint https://production.minio.co

# 从 CSV 文件导入数据到 ES (使用 csvurls)
elasticdump \
  # 必须包含 csv:// 前缀以允许解析 csv 文件
  # --input "csv://${file_path}.csv" \
  --input "csv:///data/cars.csv"
  --output=http://production.es.com:9200/my_index \
  --csvSkipRows 1    # 用于跳过已解析的行 (不包括标题行)
  --csvDelimiter ";" # 默认 csvDelimiter 为 ','

非标准安装

如果 Elasticsearch/OpenSearch 没有从根目录提供服务，则需要 --input-index 和 --output-index。如果没有提供这些参数，将解析额外的子目录以获取索引和类型。

Elasticsearch/OpenSearch:

• 格式: {protocol}://{host}:{port}/{sub}/{directory...}
• 示例: http://127.0.0.1:9200/api/search

# 从 elasticsearch 复制单个索引:
elasticdump \
  --input=http://es.com:9200/api/search \
  --input-index=my_index \
  --output=http://es.com:9200/api/search \
  --output-index=my_index \
  --type=mapping

# 复制单个类型:
elasticdump \
  --input=http://es.com:9200/api/search \
  --input-index=my_index/my_type \
  --output=http://es.com:9200/api/search \
  --output-index=my_index \
  --type=mapping

Docker 安装

如果您更喜欢使用 docker 来使用 elasticdump，可以从 docker hub 下载此项目:

docker pull elasticdump/elasticsearch-dump

然后您可以通过以下方式使用它:

• 使用 docker run --rm -ti elasticdump/elasticsearch-dump
• 您需要将文件存储目录挂载到 docker 容器 -v <your dumps dir>:<your mount point>

示例:

# 将索引从生产环境复制到测试环境，包括映射:
docker run --rm -ti elasticdump/elasticsearch-dump \
  --input=http://production.es.com:9200/my_index \
  --output=http://staging.es.com:9200/my_index \
  --type=mapping
docker run --rm -ti elasticdump/elasticsearch-dump \
  --input=http://production.es.com:9200/my_index \
  --output=http://staging.es.com:9200/my_index \
  --type=data

# 将索引数据备份到文件:
docker run --rm -ti -v /data:/tmp elasticdump/elasticsearch-dump \
  --input=http://production.es.com:9200/my_index \
  --output=/tmp/my_index_mapping.json \
  --type=data

如果您需要使用 localhost 作为 ES 主机:

docker run --net=host --rm -ti elasticdump/elasticsearch-dump \
  --input=http://staging.es.com:9200/my_index \
  --output=http://localhost:9200/my_index \
  --type=data

转储格式

此工具生成的文件格式是按行分隔的 JSON 文件。转储文件本身不是有效的 JSON，但每一行都是。我们这样做是为了使转储文件可以流式传输和追加，而不用担心整个文件的解析完整性。

例如，如果您想解析每一行，可以这样做:

while read LINE; do jsonlint-py "${LINE}" ; done < dump.data.json

选项

elasticdump: Elasticsearch 的导入和导出工具
版本: %%version%%

用法: elasticdump --input 源 --output 目标 [选项]

核心选项
--------------------
--input
                    源位置 (必需)

--input-index
                    源索引和类型
                    (默认: all, 示例: index/type)

--output
                    目标位置 (必需)

--output-index
                    目标索引和类型
                    (默认: all, 示例: index/type)


选项
--------------------
--big-int-fields
                    指定应检查大整数支持的字段的逗号分隔列表
                    (默认 '')

--bulkAction
                    设置在准备发送到 elasticsearch 的请求体时要使用的操作类型。
                    更多信息 - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html
                    (默认: index, 选项: [index, update, delete, create)

--ca, --input-ca, --output-ca
                    CA 证书。如果源和目标相同，请使用 --ca。
--fileSize
    支持文件分割。此值必须是**bytes**模块支持的字符串。
    必须使用以下缩写来表示单位大小:
    b 表示字节
    kb 表示千字节 
    mb 表示兆字节
    gb 表示吉字节
    tb 表示太字节
    例如 10mb / 1gb / 1tb
    分区有助于通过将文件高效分割成较小的块来缓解溢出/内存不足异常,然后可以根据需要合并这些块。

--filterSystemTemplates
    是否删除 metrics-*-* 和 logs-*-* 系统模板
    (默认值:true)

--force-os-version
    强制 elasticsearch-dump 使用的 OpenSearch 版本。
    (默认值:7.10.2)

--fsCompress
    在发送输出到文件之前对数据进行 gzip 压缩。
    导入时该命令用于解压 gzip 文件

--handleVersion
    告诉 elasticsearch 传输处理数据集中存在的 `_version` 字段
    (默认值:false) 

--headers
    向 Elasticsearch 请求添加自定义头
    (在 Elasticsearch 实例位于代理后面时很有用)
    (默认值:'{"User-Agent": "elasticdump"}')
    支持基于类型/方向的头,即 input-headers/output-headers
    (这些只会根据当前流类型输入/输出添加)

--help
    显示此页面

--ignore-errors
    写入错误时将继续读/写循环
    (默认值:false)

--ignore-es-write-errors  
    elasticsearch 写入错误时将继续读/写循环
    (默认值:true)

--inputSocksPort, --outputSocksPort
    Socks5 主机端口

--inputSocksProxy, --outputSocksProxy  
    Socks5 主机地址

--inputTransport
    提供自定义 js 文件作为输入传输

--key, --input-key, --output-key
    私钥文件。如果源和目标相同,使用 --key。
    否则,根据需要使用带 --input 或 --output 前缀的。

--limit
    每次操作批量移动多少对象
    对于文件流,limit 是近似值
    (默认值:100)

--maxRows
    支持文件分割。文件按指定的行数分割

--maxSockets
    进程可以同时发出多少个 HTTP 请求?
    (默认值:
      5 [node <= v0.10.x] /
      无限 [node >= v0.11.x] )

--noRefresh
    禁用输入索引刷新。
    优点:
      1. 索引速度大大提高
      2. 硬件要求大大降低
    缺点:
      1. 最近添加的数据可能未被索引
    建议用于大数据索引,
    其中速度和系统健康是比最近添加数据更高的优先级。

--offset
    包含要从输入传输中跳过的行数的整数。当导入大型
    索引时,可能会出现问题,比如连接中断、崩溃、
    有人忘记使用 `screen` 等。这允许你
    从最后已知写入的行(由输出中的 `offset` 记录)
    重新开始导出。请注意,由于
    创建转储时没有指定排序,所以没有真正的方法
    保证跳过的行已经被写入/解析。这更像是一个选项,
    当你想尽可能多地将数据放入索引中,
    而不关心在此过程中丢失一些行,类似于 `timeout` 选项。
    (默认值:0)

--outputTransport
    提供自定义 js 文件作为输出传输 

--overwrite
    如果输出文件存在则覆盖
    (默认值:false)

--params
    向 Elasticsearch 请求 URI 添加自定义参数。在你想使用 elasticsearch preference 等情况下很有用
    --input-params 是一个特定的参数扩展,可用于使用滚动 API 获取数据时
    --output-params 是一个特定的参数扩展,可用于使用批量索引 API 索引数据时
    注意:这些是为了避免在输出源中使用输入参数时出现参数污染问题
    (默认值:null)

--parseExtraFields
    要解析的元字段的逗号分隔列表

--pass, --input-pass, --output-pass
    私钥的密码。如果源和目标相同,使用 --pass。
    否则,根据需要使用带 --input 或 --output 前缀的。

--quiet
    抑制除错误以外的所有消息
    (默认值:false)

--retryAttempts
    指示在连接因以下错误之一失败时应自动重试请求的次数的整数:
    `ECONNRESET`, `ENOTFOUND`, `ESOCKETTIMEDOUT`,
    ETIMEDOUT`, `ECONNREFUSED`, `EHOSTUNREACH`, `EPIPE`, `EAI_AGAIN`
    (默认值:0)

--retryDelay
    指示重试尝试之间的回退/中断期的整数(毫秒)
    (默认值:5000)

--retryDelayBase
    用于操作重试的指数回退的基本毫秒数。(s3)

--scroll-with-post
    使用 HTTP POST 方法执行滚动,而不是默认的 GET
    (默认值:false)

--scrollId
    elasticsearch 返回的最后一个滚动 ID。
    如果 `scrollTime` 未过期,这将允许恢复使用最后一个滚动 ID 的转储。

--scrollTime
    节点将保留请求的搜索的时间。
    (默认值:10m)

--searchBody
    当 ES 是输入时,基于搜索结果执行部分提取,
    默认值为
      如果 ES > 5
        `'{"query": { "match_all": {} }, "stored_fields": ["*"], "_source": true }'`
      否则
        `'{"query": { "match_all": {} }, "fields": ["*"], "_source": true }'`
    [从 6.68.0 版本开始] 如果 searchBody 前面有 @ 符号,elasticdump 将在
    指定位置执行文件查找。注意:文件必须包含有效的 JSON

--searchBodyTemplate
    可以调用 searchBody 的方法/函数
        doc.searchBody = { query: { match_all: {} }, stored_fields: [], _source: true };
    可以多次使用。
    此外,searchBodyTemplate 可以由模块执行。请参阅下面的 [searchBody 模板](#search-template)。

--searchWithTemplate
    使用 --searchBody 时启用搜索模板
    如果使用搜索模板,则 searchBody 必须包含 "id" 字段和 "params" 对象
    如果在搜索模板中定义了 "size" 字段,它将被 --size 参数覆盖
    有关更多信息,请参阅 https://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html
    (默认值:false)

--size
    检索多少对象
    (默认值:-1 -> 无限制)

--skip-existing
    启用时跳过 resource_already_exists_exception 并成功退出
    (默认值:false)

--sourceOnly
    只输出文档 _source 中包含的 json
    正常: {"_index":"","_type":"","_id":"", "_source":{SOURCE}}
    sourceOnly: {SOURCE}
    (默认值:false)

--support-big-int
    支持大整数

--templateRegex
    用于在传递给输出传输之前过滤模板的正则表达式
    (默认值: ((metrics|logs|\..+)(-.+)?)

--timeout
    包含等待请求响应的毫秒数的整数,超时后中止请求。
    直接传递给请求库。主要用于在导入时
    不太关心丢失一些数据,而更希望速度快。

--tlsAuth
    启用 TLS X509 客户端认证

--toLog
    使用自定义 outputTransport 时,日志行
    是否应附加到输出流?
    (默认值:true,除了 `$`)

--transform
    可以调用以在写入目标之前修改文档的方法/函数。
    有一个全局变量 'doc' 可用。
    计算新字段 'f2' 为字段 'f1' 的两倍值的示例脚本:
        doc._source["f2"] = doc._source.f1 * 2;
    可以多次使用。
    此外,transform 可以由模块执行。请参阅下面的 [模块转换](#module-transform)。

--type
    我们要导出什么?
    (默认值:data,选项:[index, settings, analyzer, data, mapping, policy, alias, template, component_template, index_template])

--versionType
    Elasticsearch 版本类型。应为 `internal`、`external`、`external_gte`、`force`。
    注意:类型验证由批量端点处理,而不是由 elasticsearch-dump 处理

--openSearchServerless
    设置为 true 以从 AWS OpenSearch 无服务器集合运行转储。
    (默认值:false)

AWS 特定选项
--------------------
--awsAccessKeyId 和 --awsSecretAccessKey
    当使用由 AWS 身份和访问管理(IAM)保护的 Amazon Elasticsearch Service 时,
    提供您的访问密钥 ID 和秘密访问密钥。
    如果使用临时凭证,也可以选择提供 --sessionToken

--awsChain
    使用[标准](https://aws.amazon.com/blogs/security/a-new-and-standardized-way-to-manage-credentials-in-the-aws-sdks/)
    位置和顺序来解析凭证,包括环境变量、
    配置文件、EC2 和 ECS 元数据位置 _推荐与 AWS 一起使用的选项_

--awsIniFileName
    使用 --awsIniFileProfile 时覆盖默认的 aws ini 文件名
    文件名相对于 ~/.aws/
    (默认值:config)

--awsIniFileProfile
    作为 --awsAccessKeyId 和 --awsSecretAccessKey 的替代方案,
    从 aws ini 文件中的指定配置文件加载凭证。
    为了更大的灵活性,考虑使用 --awsChain
    并设置 AWS_PROFILE 和 AWS_CONFIG_FILE
    环境变量以在需要时覆盖默认值

--awsRegion
    设置将为其生成签名的 AWS 区域
    (默认值:根据主机名或主机计算)

--awsService
    设置将为其生成签名的 AWS 服务
    (默认值:根据主机名或主机计算)

--awsUrlRegex
    覆盖用于验证应签名的 AWS URL 的默认正则表达式
    (默认值:^https?:\/\/.*\.amazonaws\.com.*$)

--s3ACL
    S3 ACL:private | public-read | public-read-write | authenticated-read | aws-exec-read |
    bucket-owner-read | bucket-owner-full-control [默认 private]

--s3AccessKeyId
    AWS 访问密钥 ID

--s3SessionToken
    使用临时凭证时的 AWS 会话令牌

--s3Compress
    在发送到 s3 之前对数据进行 gzip 压缩

--s3Configs
    设置所有 s3 构造函数配置
    可以提供转义的 JSON 字符串或文件。文件位置必须以 @ 符号为前缀
    (默认值:null)

--s3Endpoint
    可用于与 AWS 兼容的后端(如 OpenStack Swift 和 OpenStack Ceph)的 AWS 端点

--s3ForcePathStyle
    强制 S3 对象使用路径样式 URL [默认 false]

--s3Options
    设置此处显示的所有 s3 参数 https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html#createMultipartUpload-property
    可以提供转义的 JSON 字符串或文件。文件位置必须以 @ 符号为前缀
    (默认值:null)

--s3Region
    AWS 区域

--s3SSEKMSKeyId
    用于 aws:kms 上传的 KMS ID

--s3SSLEnabled
    使用 SSL 连接到 AWS [默认 true]

--s3SecretAccessKey
    AWS 秘密访问密钥

--s3ServerSideEncryption
    启用加密上传

--s3StorageClass
    设置用于 s3 的存储类
    (默认值:STANDARD)
```bash
elasticdump --searchBodyTemplate='@./templates/my-template?param1=value&param2=another-value'

在./transforms/my-transform.js中有一个模块,内容如下:

module.exports = function(doc, options) {
  // 结果必须添加到doc.searchBody
  doc.searchBody = {}
};

将加载模块./templates/my-template.js,并执行该函数,传入doc和options = {"param1": "value", "param2": "another-value"}。

templates文件夹中提供了一个使用简单模板引擎修改日期的示例模板。

Elasticdump如何处理CSV中的嵌套数据

Elasticdump能够读取/写入嵌套数据,但采用特定的方式。这是为了在解析/保存CSV时降低复杂性。 该格式将所有嵌套扁平化为单一层级(下面显示了一个示例)

{
   "elasticdump":{
      "version":"6.51.0",
      "formats":[
         "json",
         "csv"
      ]
   },
   "contributors":[
      {
         "name":"ferron",
         "id":3
      }
   ],
   "year":112
}

输出格式

{
  "elasticdump":"{\"version\":\"6.51.0\",\"formats\":[\"json\",\"csv\"]}",
  "contributors":"{\"contributors\":[{\"name\":\"ferron\",\"id\":3}]}",
  "year":2020
}

注意数据被扁平化为1层。对象键用作标题,值用作行数据。 这可能不适用于现有的嵌套数据格式,但由于其简单性,这是为elasticdump选择的格式。 默认情况下该检测被禁用,要启用请使用--csvHandleNestedData标志

注意事项

• 此工具可能需要Elasticsearch 1.0.0或更高版本
• 导入时,Elasticdump(和Elasticsearch一般)会在不存在的情况下创建索引
• 从elasticsearch导出时,可以导出整个索引(--input="http://localhost:9200/index")或该索引中的对象类型(--input="http://localhost:9200/index/type")。这需要ElasticSearch 1.2.0或更高版本
• 如果elasticsearch安装路径在子目录中,必须使用单独的参数提供索引和类型(--input="http://localhost:9200/sub/directory --input-index=index/type")。使用--input-index=/将包括所有索引和类型。
• 我们可以使用put方法来写入对象。这意味着将创建新对象,具有相同ID的旧对象将被更新
• 默认情况下,file传输不会覆盖任何现有文件,如果文件已存在则会抛出异常。您可以使用--overwrite代替。
• 如果需要基本的http身份验证,可以这样使用:--input=http://name:password@production.es.com:9200/my_index
• 如果选择stdio输出(--output=$),还可以使用--format=human请求更易读的输出
• 如果选择stdio输出(--output=$),所有日志输出将被抑制
• 如果使用Elasticsearch 6.0.0或更高版本,scrollContext中不再允许offset参数
• ES 6.x.x及更高版本不再支持_template的template属性。ES 6.0之前的所有模板都必须升级以使用index_patterns
• ES 7.x.x及更高版本不再支持type属性。ES 6.0之前的所有模板都必须升级以删除type属性
• ES 5.x.x忽略搜索主体中的offset(from)参数。将返回所有记录
• ES 6.x.x在启动滚动时,from参数不能再用于搜索请求主体
• 索引模板已被弃用,将被Elasticsearch 7.8中引入的可组合模板取代。
• 确保searchBody中的JSON正确转义以避免解析问题:https://www.freeformatter.com/json-escape.html
• Elasticdump v6.32.0中删除了对Node.JS 8的支持。现在需要Node.JS 10+。
• Elasticdump v6.42.0使用fast-csv库添加了对CSV导入/导出的支持
• Elasticdump v6.68.0添加了指定包含searchBody的文件的支持
• Elasticdump v6.85.0添加了忽略CSV中自动列的支持
• Elasticdump v6.86.0添加了对searchBodyTemplate的支持,允许转换searchBody
• Elasticdump v6.110.1添加了对AWS OpenSearch无服务器集合的支持。注意:默认情况下,AWS OpenSearch无服务器不支持/_search?scroll API和PUT _bulk。作为解决方法,转储仅使用_search和POST _bulk API实现。这可能会影响转储的性能。

关于Elasticdump的文章

• 使用Elasticdump的实用指南
• 使用Elasticdump备份和还原索引
• 使用Elasticdump移动Elasticsearch索引
• Elasticsearch备份和还原
• Elasticdump指南 - 移动和保存Elasticsearch索引
• 使用elasticsearch-dump迁移数据

灵感来自https://github.com/crate/elasticsearch-inout-plugin和https://github.com/jprante/elasticsearch-knapsack