Elasticsearch Service
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > Elasticsearch Service > ES 集群指南 > 升级 > ES 版本升级检查

ES 版本升级检查

最近更新时间：2023-12-13 16:55:31

我的收藏

本页目录：

Elasticsearch 不同版本之间有部分不兼容的配置，如果您已设置，升级后，使用集群可能会受到影响。您可通过升级检查的功能，检查是否有不兼容的配置，并进行调整。以下是 ES 对 Elasticsearch 版本升级时检查的配置说明。
升级检查操作入口，在 Elasticsearch Service 控制台 详情页，单击右上角升级，操作步骤详见 升级 ES 集群。
警告
需特别留意本文中需要人工检查的部分（无法自动检查），并在升级前完成代码兼容性改造，避免升级后造成集群无法正常访问，例如，6.8版本升级到7.5版本后默认无法创建包含 type 的索引，详情见下文 需人工自查的不兼容配置。

Elasticsearch 5.x 版本升级到 6.x 版本配置检查

检查的配置项列表

序号
配置维度
配置信息
兼容性
详细说明
1
集群级别
集群快照设置（Snapshot settings）
CRITICAL
集群设置cluster.routing.allocation.snapshot.relocation_enabled，在6.0版本开始被废弃，详见 Breaking changes in 6.0
2
集群级别
集群存储限流设置（Store throttling settings）
CRITICAL
集群设置indices.store.throttle.type和indices.store.throttle.max_bytes_per_sec，在6.0版本开始被废弃，详见 Breaking changes in 6.0
3
索引级别
索引相似性设置（Similarity settings）
WARNING
索引设置index.similarity.base，在6.0版本开始被废弃，详见 Breaking changes in 6.0
4
索引级别
索引影子副本设置（Shadow Replicas settings）
CRITICAL
索引设置index.shared_filesystem和index.shadow_replicas，在6.0版本开始被废弃，详见 Breaking changes in 6.0
5
索引级别
索引存储设置（Index Store settings）
CRITICAL
索引设置index.store.type为 default，在6.0版本开始被废弃，详见 Breaking changes in 6.0
6
索引级别
索引存储限流设置（Index Store throttling settings）
CRITICAL
索引设置index.store.throttle.type和index.store.throttle.max_bytes_per_sec，在6.0版本开始被废弃，详见 Breaking changes in 6.0
7
索引级别
索引 Mapping 参数 include_in_all
WARNING
索引 mapping 参数include_in_all，在6.0版本之后创建的索引中无法使用（5.x 版本创建包含此设置的索引在升级 6.x 版本后可以兼容），详见 Breaking changes in 6.0
8
索引级别
索引创建版本
CRITICAL
索引创建版本index.version.created不允许跨 ES 主版本，例如，无法将在 5.x 版本创建的索引直接升级到 7.x 版本，需要将失败的索引 reindex 迁移到新索引并删除后再进行升级。
9
索引模板级别
索引模板相似性设置（Similarity settings）
CRITICAL
索引设置index.similarity.base，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
10
索引模板级别
索引模板影子副本设置（Shadow Replicas settings）
CRITICAL
索引设置index.shared_filesystem和index.shadow_replicas，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
11
索引模板级别
索引模板存储设置（Index Store settings）
CRITICAL
索引设置index.store.type为 default，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
12
索引模板级别
索引模板存储限流设置（Index Store throttling settings）
CRITICAL
索引设置index.store.throttle.type和index.store.throttle.max_bytes_per_sec，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
13
索引模板级别
索引模板 Mapping 参数 include_in_all
CRITICAL
索引 Mapping 参数include_in_all，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
14
索引模板级别
索引模板 Mapping 元字段 _all
CRITICAL
索引 Mapping 元字段_all，在6.0版本开始被废弃，详见 Breaking changes in 6.0，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
15
索引模板级别
索引模板 Mapping 多个 Types
CRITICAL
索引 Mapping 包含多个 Types，在6.0版本开始被废弃，详见 Removal of mapping types，模板中存在该设置将导致版本升级后该模板无法用于创建新索引。
说明
警告（WARNING）：检查失败时仍可以升级。此类型检查项对应设置在升级后将被忽略。
错误（CRITICAL）：检查失败时无法升级。此类型检查项对应设置在目标版本无法兼容。

配置不兼容调整方法

集群级别

集群快照设置（Snapshot settings） 通过 ES 集群设置更新接口PUT _cluster/settings取消此设置（包括 persistent 和 transient）：
PUT _cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.snapshot.relocation_enabled": null
  },
  "transient": {
    "cluster.routing.allocation.snapshot.relocation_enabled": null
  }
}
集群存储限流设置（Store throttling settings） 通过 ES 集群设置更新接口PUT _cluster/settings取消此设置（包括 persistent 和 transient）：
PUT _cluster/settings
{
  "persistent": {
    "indices.store.throttle.type": null,
    "indices.store.throttle.max_bytes_per_sec": null
  },
  "transient": {
    "indices.store.throttle.type": null,
    "indices.store.throttle.max_bytes_per_sec": null
  }
}

索引级别

索引相似性设置（Similarity settings） 此设置在升级 6.x 后被忽略，但不会影响升级。如需取消设置，可按照如下步骤操作：
此设置需要关闭索引后修改，关闭后的索引无法被读写。关闭索引：
POST my_index/_close
使用 ES 索引设置更新接口取消此设置：
PUT my_index/_settings
{
    "index.similarity.base.*": null
}
最后打开索引：
POST my_index/_open
索引影子副本设置（Shadow Replicas settings）
此设置需要关闭索引后修改，关闭后的索引无法被读写。关闭索引：
POST my_index/_close
使用 ES 索引设置更新接口取消此设置：
PUT my_index/_settings
{
     "index.shared_filesystem": null,
     "index.shadow_replicas": null
}
最后打开索引：
POST my_index/_open
索引存储设置（Index Store settings）
此设置需要关闭索引后修改，关闭后的索引无法被读写。关闭索引：
POST my_index/_close
使用 ES 索引设置更新接口取消此设置：
PUT my_index/_settings
{
    "index.store.type": null
}
最后打开索引：
POST my_index/_open
索引存储限流设置（Index Store throttling settings） 使用 ES 索引设置更新接口取消此设置：
PUT my_index/_settings
{
  "settings": {
    "index.store.throttle.type": null,
    "index.store.throttle.max_bytes_per_sec": null
  }
}
索引 Mapping 参数 include_in_all 对已创建的包含此参数的索引，升级后可以兼容，无需修复。

索引模板级别

1. 使用 API GET _template/my_template 获取不兼容模板my_template。存在以下三个不兼容设置：索引模板存储设置（Index Store settings）、索引模板 Mapping 参数 include_in_all、索引模板 Mapping 元字段_all。
  {
 "my_template": {
   "order": 0,
   "template": "my_*",
   "settings": {
     "index": {
       "store": {
         "throttle": {
           "max_bytes_per_sec": "10m"
         }
       }
     }
   },
   "mappings": {
     "my_type": {
       "_all": {
         "enabled": true
       },
       "properties": {
         "my_field": {
           "type": "text",
           "include_in_all": true
         }
       }
     }
   },
   "aliases": {}
 }
  }
2. 拷贝并去除模板中不兼容配置后，使用 API PUT _template/my_template 更新模板。
  PUT _template/my_template
  {
   "order": 0,
   "template": "my_*",
   "settings": {
   },
   "mappings": {
     "my_type": {
       "properties": {
         "my_field": {
           "type": "text"
         }
       }
     }
   },
   "aliases": {}
  }

Elasticsearch 6.8 版本升级到 7.x 版本配置检查

需人工自查的不兼容配置

对于超过1024个字段数的索引，查询时如果不指定字段会非常消耗性能。建议设置默认查询字段 index.query.default_field。如果仍要查询所有字段，那么可以通过提高“布尔查询最大子句数”设置 indices.query.bool.max_clause_count 来实现。
include_type_name 默认为 false，升级后默认将无法创建包含 type 的索引，需要显式指定参数 include_type_name：
警告
需重点关注集群是否有此项不兼容配置，避免升级后造成集群无法正常访问。
 PUT my_index?include_type_name
 {
   "mappings": {
     "type1": {
       "properties": {
         "name": {
           "type": "text"
         }
       }
     }
   }
 }

可自动检查的配置项列表

序号
配置维度
配置信息
兼容性
详细说明
1
集群级别
用户代理预处理器（User agent processor）设置
WARNING
用户代理预处理器（User agent processor）的格式默认值变为ecs，详见 Breaking changes in 7.0
2
集群级别
集群分片数
WARNING
每个节点最大 shard 数cluster.max_shards_per_node默认1000，shard 数超过在升级后将无法创建新分片，详见 Breaking changes in 7.0
3
集群级别
集群设置（discovery.zen.no_master_block）
WARNING
集群设置 discovery.zen.no_master_block 改名为 cluster.no_master_block，详见 Breaking changes in 7.0
4
集群级别
预处理器管道（Ingest pipeline）日期格式
WARNING
预处理器管道（Ingest pipeline）date或date_index_name处理器使用废弃的日期格式，详见 Breaking changes in 7.0
5
索引级别
索引创建版本
CRITICAL
不允许6.0版本之前创建的索引升级到7.x版本，详见 Breaking changes in 7.0
6
索引级别
Delimited payload 词汇单元过滤器（Token filter）索引设置
WARNING
Delimited payload 语汇单元过滤器（Token filter）从 delimited_payload_filter 改名为 delimited_payload，详见 Breaking changes in 7.0
7
索引级别
索引设置（index.percolator.map_unmapped_fields_as_string）
CRITICAL
索引设置index.percolator.map_unmapped_fields_as_string 改名为 index.percolator.map_unmapped_fields_as_text，详见 Breaking changes in 7.0
8
索引级别
索引名
WARNING
索引名不能包含“:”，详见 Breaking changes in 7.0
9
索引级别
索引设置（index.unassigned.node_left.delayed_timeout）
CRITICAL
索引设置 index.unassigned.node_left.delayed_timeout 负数值被废弃，详见 Breaking changes in 7.0
10
索引级别
索引设置（index.shard.check_on_startup）
CRITICAL
索引设置 index.shard.check_on_startup 的值为fix被废弃，详见 Breaking changes in 7.0
11
索引级别
经典相似性（classic similarity）索引 Mapping 参数
WARNING
经典相似性（classic similarity）索引 Mapping 参数被废弃，详见 Breaking changes in 7.0
12
索引级别
经典相似性（classic similarity）索引设置
WARNING
经典相似性（classic similarity）索引设置被废弃，详见 Breaking changes in 7.0
13
索引级别
索引字段数
WARNING
对于超过1024个字段的索引，建议设置默认查询字段（index.query.default_field）或提升最大字段数设置（indices.query.bool.max_clause_count），否则升级后将导致不指定字段的查询无法正常使用，详见 Breaking changes in 7.0
14
索引级别
索引 Mapping 日期格式
WARNING
Joda-Time 格式改为 Java Time，详见 Breaking changes in 7.0
15
索引模板级别
Delimited payload 语汇单元过滤器（Token filter）索引模板设置
WARNING
Delimited payload 语汇单元过滤器（Token filter）从 delimited_payload_filter 改名为 delimited_payload，详见 Breaking changes in 7.0
16
索引模板级别
索引模板设置（index.percolator.map_unmapped_fields_as_string）
CRITICAL
索引模板设置 index.percolator.map_unmapped_fields_as_string 改名为 index.percolator.map_unmapped_fields_as_text，升级后不兼容，详见 Breaking changes in 7.0
17
索引模板级别
索引模板设置（index.unassigned.node_left.delayed_timeout）
CRITICAL
索引模板设置 index.unassigned.node_left.delayed_timeout 负数值被废弃，升级后不兼容，详见 Breaking changes in 7.0
18
索引模板级别
索引模板设置（index.shard.check_on_startup）
CRITICAL
索引模板设置 index.shard.check_on_startup 的值为fix被废弃，升级后不兼容，详见 Breaking changes in 7.0
19
索引模板级别
经典相似性（classic similarity）索引模板 Mapping 参数
CRITICAL
经典相似性（classic similarity）索引模板 Mapping 参数被废弃，升级后不兼容，详见 Breaking changes in 7.0
20
索引模板级别
经典相似性（classic similarity）索引模板设置
CRITICAL
经典相似性（classic similarity）索引模板设置被废弃，升级后不兼容，详见 Breaking changes in 7.0
21
索引模板级别
索引模板字段数
CRITICAL
对于超过1024个字段的索引模板，建议设置默认查询字段（index.query.default_field）或提升最大字段数设置（indices.query.bool.max_clause_count），否则升级后将导致不指定字段的查询无法正常使用，详见 Breaking changes in 7.0
说明：
对于超过1024个字段的索引模板，我们提供以下建议：
查询时如果不指定字段会非常消耗性能。建议设置默认查询字段 index.query.default_field。
如果仍要查询所有字段，那么可以通过提高“布尔查询最大子句数”设置indices.query.bool.max_clause_count来实现（该操作是集群层面的设置）。

22
索引模板级别
索引模板 Mapping 日期格式
WARNING
Joda-Time 格式改为 Java Time，详见 Breaking changes in 7.0

配置不兼容调整方法

集群级别

用户代理预处理器（User agent processor）设置 使用非ecs格式的 user agent 将被废弃，应调整为：
PUT _ingest/pipeline/my_pipeline1
{
"processors" : [
  {
    "user_agent" : {
      "field" : "agent",
      "ecs": true
    }
  }
]
}
集群分片数 对于超过分片数限制的集群，有两种调整方法：
降低集群分片数（通过清理过期索引、shrink 索引 等）。
修改集群设置提高分片数限制。
PUT _cluster/settings
{
  "persistent": {
 "cluster.max_shards_per_node": 5000
  }
}
集群设置（discovery.zen.no_master_block） 对于使用了集群设置 discovery.zen.no_master_block 的集群，在升级完成后调整为 cluster.no_master_block，例如：
PUT _cluster/settings
{
"persistent": {
  "cluster.no_master_block": "write"
}
}
预处理器管道（Ingest pipeline）日期格式 可参考 Joda based date formatters are replaced with java ones 进行调整。

索引级别

索引创建版本 不允许6.0版本之前创建的索引升级到7.x版本，对于需要保留的索引，需要在升级前执行 reindex ， 例如：
POST _reindex
{
"source": {
  "index": "my_index"
},
"dest": {
  "index": "new_my_index"
}
}
Delimited payload 语汇单元过滤器（Token filter）索引模板设置 将索引设置中的 delimited_payload_filter 改为 delimited_payload，例如原始索引如下：
PUT my_index
{
"settings": {
  "analysis": {
    "analyzer": {
      "whitespace_plus_delimited": {
        "tokenizer": "whitespace",
        "filter": [ "plus_delimited" ]
      }
    },
    "filter": {
      "plus_delimited": {
        "type": "delimited_payload_filter",
        "delimiter": "+",
        "encoding": "int"
      }
    }
  }
}
}
修改后的索引：
PUT my_index
{
"settings": {
  "analysis": {
    "analyzer": {
      "whitespace_plus_delimited": {
        "tokenizer": "whitespace",
        "filter": [ "plus_delimited" ]
      }
    },
    "filter": {
      "plus_delimited": {
        "type": "delimited_payload",
        "delimiter": "+",
        "encoding": "int"
      }
    }
  }
}
}
索引设置（index.percolator.map_unmapped_fields_as_string） 将索引设置 index.percolator.map_unmapped_fields_as_string 调整为 index.percolator.map_unmapped_fields_as_text（此设置调整前需要 close 索引）。
PUT my_index/_settings
{
"index.percolator.map_unmapped_fields_as_text": true
}
索引名 对于包含“:”的索引，需执行 reindex，例如：
POST _reindex
{
"source": {
  "index": "my_index"
},
"dest": {
  "index": "new_my_index"
}
}
索引设置（index.unassigned.node_left.delayed_timeout） 将索引设置 index.unassigned.node_left.delayed_timeout 调整为正整数：
PUT my_index/_settings
{
"index.unassigned.node_left.delayed_timeout": 0
}
索引设置（index.shard.check_on_startup） 将索引设置 index.shard.check_on_startup 值为 fix 调整为其它值，例如：
PUT my_index/_settings
{
"index.shard.check_on_startup": true
}
经典相似性（classic similarity）索引 Mapping 参数、经典相似性（classic similarity）索引设置 对于包含经典相似性（classic similarity）的索引设置或 Mapping，调整为其他类型，例如原始索引如下：
PUT my_index
{
"mappings": {
  "doc": {
    "properties": {
      "field1": {
        "properties": {
          "field4": {
            "type": "text",
            "similarity": "classic"
          }
        }
      }
    }
  }
}
}
修改后的索引为：
PUT my_index
{
"mappings": {
  "doc": {
    "properties": {
      "field1": {
        "properties": {
          "field4": {
            "type": "text",
            "similarity": "BM25"
          }
        }
      }
    }
  }
}
}
索引字段数 对于超过1024个字段的索引，有两种调整方法：
设置默认查询字段设置 index.query.default_field。
PUT my_index/_settings
{
  "index.query.default_field": "field1"
}
通过修改 ES YML 配置文件提升最大字段数设置 indices.query.bool.max_clause_count（后续支持）。
索引 Mapping 日期格式 可参考 Joda based date formatters are replaced with java ones 进行调整。

索引模板级别

索引模板级别的不兼容设置调整请参考 索引级别。
中国站