> 5.0 起所有设置在生效前都要校验：节点级和默认索引级设置在启动时校验，动态设置在更新前校验，且每个设置必须是"已注册"的。同时一批老设置被改名或删除：索引级设置不能再在节点级配置、`name` 换成 `node.name`、节点属性必须放 `node.attr.` 命名空间、`node.client` 删除、带 `netty` 中缀的设置换成 `transport` 同义项。本文对照 v5.6.16 源码，把"未知设置""节点级索引设置"两种启动失败的报错原文和处理办法写出来。

## **说明**

本文描述问题及解决方法同样适用于 [腾讯云 Elasticsearch Service（ES）](https://cloud.tencent.com/document/product/845)。

来源和边界先交代：本文的依据出自 v5.6.16 标签下的官方文件（`settings.asciidoc`、`AbstractScopedSettings.java`、`Plugin.java`），文中引用的原文均来自这些文件。我没有启动集群、也没有跑测试，示例取自官方示例；哪些是文档写明、哪些是我的推断，正文里逐处标注。

![01-settings](https://developer.qcloudimg.com/http-save/yehe-7348459/31a0e37cddfba95b76494c2afe11c18f.png)

*图 1：官方文件 settings.asciidoc（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 settings.asciidoc*

## 校验变严

5.0 迁移文档 Settings 一节（[migrate_5_0/settings.asciidoc 第 4–13 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/settings.asciidoc#L4-L13)）开头：

> From Elasticsearch 5.0 on all settings are validated before they are applied. Node level and default index level settings are validated on node startup, dynamic cluster and index setting are validated before they are updated/added to the cluster state.

> Every setting must be a *known* setting. All settings must have been registered with the node or transport client they are used with.

按这段说法，以前没有这层校验，拼错的设置名不会让节点起不来。5.0 起，未注册的设置会让节点启动失败。源码里报错的位置是 [AbstractScopedSettings.validate 第 268–296 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/common/settings/AbstractScopedSettings.java#L268-L296)，消息格式是：

```text
unknown setting [xxx] did you mean [yyy]?
unknown setting [xxx] please check that any required plugins are installed, or check the breaking changes documentation for removed settings
```

前一种是和已注册设置的编辑距离超过 0.7 时给出的拼写建议，后一种是找不到相近项时的兜底提示。看到第二种，先查是下面几节就是这张对照表，不是被删除或改名的老设置。

对插件作者，迁移文档要求自定义设置在插件加载时注册。5.6.16 里的入口是 [Plugin#getSettings()](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/plugins/Plugin.java#L147)，返回要注册的 `Setting` 列表；文档里写的 `SettingsModule#registerSettings` 是 5.0 发布时的说法，写新插件按 `getSettings()` 来。SettingsModule 的注释也说明，没有注册的设置不可用，指定了就会在启动时被节点拒绝。

![02-AbstractScopedSettings](https://developer.qcloudimg.com/http-save/yehe-7348459/f5090324f35c69fa8b651331809a4fa3.png)

*图 2：官方文件 AbstractScopedSettings.java（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 AbstractScopedSettings.java*

## 升级要先过启动校验，而不是先看功能

这类改动没有"部分生效"，要么校验通过，要么节点起不来。所以我的判断是：升级 5.x 最先要做的，是用目标版本把现有 `elasticsearch.yml` 校验一遍，功能变化可以往后放。在灰度节点上先起一个，把所有未知设置的报错一次看完，再滚动升级其余节点，比一个节点一个节点地试省事。

![03-templates](https://developer.qcloudimg.com/http-save/yehe-7348459/ad09a176ac9a5bde4b0e5480b7a06e1a.png)

*图 3：官方文件 templates.asciidoc（v5.6.16 标签）。来源：GitHub elastic/elasticsearch v5.6.16 templates.asciidoc*

## 升级前怎么把未知设置找出来

难点是找出配置里有哪些设置已经不认识。可以先把配置文件里实际写了的设置列出来：

```sh
grep -v '^\s*#' $ES_PATH_CONF/elasticsearch.yml | grep -v '^\s*$'
```

然后拿目标版本起一个灰度节点（哪怕只在容器里起一下再停），让它自己报。报错一次只显示一个未知设置，改一个再起一次，直到启动成功。重点看这几类：

- 拼写错误的设置：报 `unknown setting [..] did you mean [..]?`，最容易改；
- 已经改名或删除的设置：按迁移表逐个改，下面几节列了；
- 索引级设置写在节点级：是另一条报错，见下一节，不是"未知设置"。

我的默认做法是在 CI 里加一步配置校验：每次升级前，把 `elasticsearch.yml` 拿去新版本里启动一次。5.0 之后每次升级都可以这么做，比靠人记着省事。

## 索引级设置不能再写在节点级

官方原文（[第 15–22 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/settings.asciidoc#L15-L22)）：

> In previous versions Elasticsearch allowed to specify index level setting as _defaults_ on the node level, inside the `elasticsearch.yaml` file or even via command-line parameters. From Elasticsearch 5.0 on only selected settings like for instance `index.codec` can be set on the node level. All other settings must be set on each individual index. To set default values on every index, index templates should be used instead.

源码在 [SettingsModule 第 82–132 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/common/settings/SettingsModule.java#L82-L132)：节点设置里凡是以 `index.` 开头、又不是集群级注册设置的，会先打一段 WARN 日志，再抛 `IllegalArgumentException`：

```text
node settings must not contain any index level settings
```

WARN 日志里的说明是：5.x 起索引级设置不能写在节点配置、系统属性或命令行参数里；要升级已有索引，用 `/${index}/_settings` 更新；如果设置不都是动态的，要先关闭索引；以后新建的索引用索引模板设默认值。

所以这类报错的处理动作是：把设置搬到索引模板里（新索引）并用 `_settings` 更新现有索引，不是简单删掉，否则默认值就丢了。5.x 的模板用 `template` 字段匹配索引名（[templates 文档开头示例](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/indices/templates.asciidoc#L15-L25)），不是 `index_patterns`（那是后续大版本的写法）：

```json
PUT _template/defaults
{
  "template": "*",
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}
```

模板只在索引创建时生效，改模板不影响已有索引。

## 节点相关设置的改名与删除

对应迁移文档第 24–48 行：

| 旧 | 新/状态 |
|---|---|
| `name` | 改为 `node.name`；`-Dname=xxx` 不再支持 |
| `node.add_id_to_custom_path` | 改名 `add_lock_id_to_custom_path` |
| `node.name` 默认值 | 改为节点 ID 的前 7 个字符（节点 ID 是随机 UUID） |
| `node.mode`、`node.local` | 删除；本地模式用 `transport.type: local`，关 HTTP 用 `http.enabled: false` |
| `node.client` | 删除；配了它的节点无法启动 |
| 节点属性 `node.xxx` | 必须放 `node.attr.` 命名空间（`node.master`、`node.data`、`node.ingest` 例外） |

`node.name` 默认值的变化要看 2.4.6 的实现：[InternalSettingsPreparer 第 177–190 行](https://github.com/elastic/elasticsearch/blob/v2.4.6/core/src/main/java/org/elasticsearch/node/internal/InternalSettingsPreparer.java#L177-L190)在没设置 `node.name` 时调用 `randomNodeName`，从 `names.txt` 里随机取一个名字。所以 2.x 默认的是一个随机的名字，不是主机名；5.0 起改成节点 ID 的前 7 位。无论哪个版本，默认名都不能对应到具体机器。如果日志、监控、告警里需要靠节点名找机器，显式配置，官方配置文档里的示例就是（[configuration.asciidoc 第 62 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/setup/configuration.asciidoc#L62)）：

```yaml
node.name: ${HOSTNAME}
```

`node.client` 删除之后，"客户端节点"这个打包角色没有了。迁移文档要求每个角色单独设置，只做协调的节点写成：

```yaml
node.master: false
node.data: false
node.ingest: false
```

文档原文说的是"各个角色要用已有的 `node.master`、`node.data`、`node.ingest` 分别设置"。是否要关掉 ingest，取决于这个节点是否还要承担 ingest 任务，上面是纯协调节点的写法。

老的配置模板里可能还留着 `node.client`，升级前 grep 一遍比等启动失败快：

```sh
grep -rn 'node.client' $ES_PATH_CONF
```

## 节点属性命名空间

分配过滤（allocation filtering）、forced awareness、节点分组用到的属性，都要带 `node.attr.` 前缀：

```yaml
# 2.x
node.rack: r1

# 5.0
node.attr.rack: r1
```

源码里 [Node.NODE_ATTRIBUTES](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/node/Node.java#L193) 是一个 group setting，前缀是 `node.attr.`；`DiscoveryNode` 从这里读属性。旧的 `node.rack` 在 5.0 里没有注册，按上文的校验会在启动时被拒绝，不是静默失效。迁移时仍然要验证一次属性读到了没有：

```sh
curl -s 'localhost:9200/_cat/nodeattrs?v'
```

这个 cat 接口在 5.6.16 里存在（[RestNodeAttrsAction](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/rest/action/cat/RestNodeAttrsAction.java)），列出每个节点的属性。分配过滤规则（如 `index.routing.allocation.require.rack`）里引用的属性名，要和 `node.attr.` 之后的名字一致。

## 传输层设置去掉 netty 中缀

> All settings with a `netty` infix have been replaced by their already existing `transport` synonyms. For instance `transport.netty.bind_host` is no longer supported and should be replaced by the superseding setting `transport.bind_host`.

`transport.netty.bind_host` 这类带 netty 的写法，改成已经存在的同义设置 `transport.bind_host`。做全局替换前先确认目标名在 5.x 里存在，不是所有带 `netty` 的设置都有同义项；哪些没有，以启动时的 `unknown setting` 提示为准。

## 同一页里还有几处会让节点起不来的删除

迁移文档同一页还列出这些，没有在本文逐项展开，升级前一并 grep：

- `gateway.format` 删除，默认用 `smile`（第 50–53 行）；
- `security.manager.enabled` 删除，要加权限只能改本地 Java 安全策略（第 62–66 行）；
- `network.host` 等设置里的 `_non_loopback_` 值删除，改用 `_local_,_site_` 这类地址范围或明确的接口、地址（第 68–73 行）；
- 线程池设置前缀 `threadpool` 改成 `thread_pool`，线程池类型不能再改，`suggest` 线程池删除（第 79–108 行）；
- `discovery.zen.initial_ping_timeout`、`discovery.zen.ping.timeout` 删除，只保留 `discovery.zen.ping_timeout`（第 116–122 行）；
- `index.analysis.analyzer.default_index` 不再支持，改用 `index.analysis.analyzer.default`（第 110–114 行）。

## 升级前的检查清单

1. 把 `elasticsearch.yml` 逐行过一遍，拼错或已删除的设置先清掉，5.0 会拒绝启动；
2. 节点级写的索引默认设置迁移到索引模板，已有索引用 `_settings` 更新；
3. `name` 改 `node.name`，`node.add_id_to_custom_path` 改 `add_lock_id_to_custom_path`；
4. 自定义节点属性加 `node.attr.` 前缀，并确认分配过滤规则仍生效；
5. 用 `node.client: true` 的节点改成显式的角色设置；
6. 所有 `transport.netty.*` 改成 `transport.*`；
7. 自带插件按 `Plugin#getSettings()` 注册设置，第三方插件确认有 5.x 版本；
8. 同一页其余的删除项（见上节）过一遍。

## 写在最后

设置校验从严带来的变化是：配置错误从"悄悄没生效"变成"启动就失败"。这是按迁移文档"5.0 起所有设置都要校验"的说法得出的理解。代价是升级时会一次性遇到积累下来的问题，好处是以后配置里的拼写错误会在启动时暴露。

做法上，先用灰度节点把报错一次跑完，再滚动升级；同时把配置里没人知道为什么存在的旧项清掉，之后每次升级的配置校验也会轻松些。

## 参考

- [migrate_5_0/settings.asciidoc @ v5.6.16](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/settings.asciidoc)

> 本文对照 Elasticsearch `v5.6.16` 标签的官方文档核对，引文逐字取自原文。撰写时未启动集群、未运行测试。


5.0 起所有设置在生效前都要校验：节点级和默认索引级设置在启动时校验，动态设置在更新前校验，且每个设置必须是"已注册"的。同时一批老设置被改名或删除：索引级设置不能再在节点级配置、name 换成 node.name、节点属性必须放 node.attr. 命名空间、node.client 删除、带 netty 中缀的设置换成 transport 同义项。本文对照 v5.6.16 源码，把"未知设置""节点级索引设置"两种启动失败的报错原文和处理办法写出来。

考古｜未知设置直接不让 ES 5.0 启动，设置现在全部要过校验

5.0 起所有设置在生效前都要校验：节点级和默认索引级设置在启动时校验，动态设置在更新前校验，且每个设置必须是"已注册"的。

官方产研

云计算

后端

大数据

5.0起Elasticsearch设置需先校验方可生效，未知设置导致启动失败。本文对照v5.6.16源码，解析"unknown setting"及节点级索引设置报错，提供改名对照表与升级前检查清单，解决配置迁移问题，适用腾讯云ES。

Elasticsearch 

代码解释

容器

Java

让每一个 Agent，都跑在云上

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

考古｜未知设置直接不让 ES 5.0 启动，设置现在全部要过校验-腾讯云开发者社区-腾讯云

考古｜未知设置直接不让 ES 5.0 启动，设置现在全部要过校验

考古｜未知设置直接不让 ES 5.0 启动，设置现在全部要过校验

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐