cafdataprocessing/elastic-mapping-updater

Elasticsearch映射更新工具 Docker镜像文档

镜像概述与主要用途

该Docker镜像提供了一个实用工具，专门用于更新Elasticsearch中的索引映射，确保其与当前使用的模板保持一致。通过自动比对和同步映射与模板，解决因映射不匹配导致的数据索引异常、字段类型冲突等问题，简化Elasticsearch日常维护流程。

核心功能与特性

• 自动差异比对：智能识别当前索引映射与模板的字段差异（类型、分析器、属性等）
• 增量更新支持：仅同步新增或变更的映射字段，避免全量重建索引
• 版本兼容性：兼容Elasticsearch 6.x/7.x/8.x主流版本
• 操作安全性：提供预执行检查模式，支持模拟更新并生成变更报告
• 日志与审计：输出详细的更新过程日志、变更记录及错误信息，便于问题排查

使用场景与适用范围

• 模板更新后同步：当Elasticsearch模板（index template）更新后，批量同步现有索引映射
• 映射异常修复：索引创建后发现字段类型、分析器等与模板定义不一致时进行修正
• 定期维护任务：纳入自动化运维流程，定期检查并同步映射与模板
• 多环境一致性管理：在开发、测试、生产环境间保持映射与模板的配置统一
• 跨集群同步：需保持多Elasticsearch集群间映射与模板配置一致的场景

使用方法与配置说明

前置条件

• 目标Elasticsearch集群可访问（网络连通性、端口开放）
• 具备足够操作权限的Elasticsearch用户（需manage索引权限）
• 已定义并存在有效的Elasticsearch模板

环境变量配置

Docker部署示例

基础使用（无认证）

bash
docker run -d \
  -e ES_HOST=192.168.1.100 \
  -e TEMPLATE_NAME=product-catalog-template \
  -e INDEX_PATTERN=products-* \
  your-registry/elasticsearch-mapping-updater:latest

带认证与HTTPS配置

bash
docker run -d \
  -e ES_HOST=es-prod.example.com \
  -e ES_PORT=9200 \
  -e ES_USER=admin \
  -e ES_PASSWORD=P@ssw0rd! \
  -e ES_SSL=true \
  -e TEMPLATE_NAME=orders-template \
  -e INDEX_PATTERN=order-logs-* \
  -e LOG_LEVEL=debug \
  your-registry/elasticsearch-mapping-updater:latest

预检查模式（仅生成报告）

bash
docker run --rm \
  -e ES_HOST=es-test.example.com \
  -e TEMPLATE_NAME=users-template \
  -e INDEX_PATTERN=user-profiles-* \
  -e CHECK_ONLY=true \
  your-registry/elasticsearch-mapping-updater:latest

输出与结果查看

• 容器日志可通过docker logs <container-id>查看，包含：
  • 差异比对结果（新增/变更字段列表）
  • 更新执行状态（成功/失败及原因）
  • 受影响的索引名称及数量
• 预检查模式下仅输出报告，不执行实际更新

注意事项

• 执行更新前建议备份重要索引数据
• 对包含大量文档的索引，映射更新可能短暂影响查询性能
• 部分映射变更（如字段类型修改）可能需要重建索引，工具会提示此类不支持的变更类型
• 确保Elasticsearch集群状态健康（green）后再执行更新操作