> 5.3 的 breaking 只有三条，都不是"不能用了"而是"提前打招呼，6.0 才移除"：日志系统属性从单个 `es.logs` 拆成 `es.logs.base_path`、`es.logs.cluster_name`、`es.logs.node_name`；`transport.type=netty3` 和 `http.type=netty3` 标记废弃；布尔设置只接受 `true`/`"true"`/`false`/`"false"`。第三条的实际行为值得说清楚：v5.6.16 里 `yes`/`no`/`on`/`off`/`1`/`0` 仍能用，只是会往 deprecation 日志写一条，真正抛异常的是这几个之外的值。本文按 v5.6.16 源码把这一点和其它两条的落地写法列出来。

## **说明**

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

实测环境：本地起两个单节点实例——Elasticsearch 5.6.16 与 6.8.23（官方 tar 包直接跑，堆内存 512MB），curl 连本地 9200 端口，两个版本分两次启动；弃用日志读的是实例目录下的 `logs/elasticsearch_deprecation.log`。图 4、图 5 出自 5.6.16，图 6 出自 6.8.23。

来源和边界先交代：本文的依据出自 v5.6.16 标签下的官方文件（`migrate_5_3.asciidoc`、`Netty4Plugin.java`、`Netty3Plugin.java`），文中引用的原文均来自这些文件。示例取自官方示例；哪些是文档写明、哪些是我的推断，正文里逐处标注。

![01-migrate_5_3](https://developer.qcloudimg.com/http-save/yehe-7348459/17c2d126a039ebd6674e9ff5cbf34d8c.png)

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

## 日志属性拆分

5.3 迁移文档（[migrate_5_3.asciidoc 第 9–23 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_3.asciidoc#L9-L23)）：

> Previously Elasticsearch exposed a single system property (`es.logs`) that included the absolute path to the configured logs directory, and the prefix of the filenames used for the various logging files (the main log file, the deprecation log, and the slow logs). This property has been replaced in favor of three properties:

- `es.logs.base_path`：日志目录的绝对路径；
- `es.logs.cluster_name`：各类日志文件名的默认前缀；
- `es.logs.node_name`：配了 `node.name` 时才暴露，可选地用于文件名。

> The property `es.logs` is deprecated and will be removed in Elasticsearch 6.0.0.

拆分的价值：以前 `es.logs` 是"路径 + 前缀"的拼接体，想在 log4j2 配置里只用其中一部分做不到。拆开之后可以自由组合，典型用法是多节点共用日志目录、文件名带节点名：

```properties
appender.rolling.fileName = ${sys:es.logs.base_path}/${sys:es.logs.cluster_name}_${sys:es.logs.node_name}.log
```

多节点共用目录时这一条尤其重要：文件名不带节点名会互相覆盖。

迁移动作：自定义 `log4j2.properties` 的地方把 `${sys:es.logs}` 换掉。因为 `es.logs` 是整体，替换时要判断原配置里实际用到的是哪一部分（路径还是前缀）。

![02-Netty4Plugin](https://developer.qcloudimg.com/http-save/yehe-7348459/2a0cf6ed839f0be27c79b5c610d61aed.png)

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

## Netty 3 废弃

> Usage of Netty 3 for transport (`transport.type=netty3`) or HTTP (`http.type=netty3`) is deprecated and will be removed in Elasticsearch 6.0.0.

5.x 期间两套实现都在：`netty4`（[Netty4Plugin 第 50–51 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/modules/transport-netty4/src/main/java/org/elasticsearch/transport/Netty4Plugin.java#L50-L51)）和 `netty3`（[Netty3Plugin 第 49–50 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/modules/transport-netty3/src/main/java/org/elasticsearch/transport/Netty3Plugin.java#L49-L50)），`transport.type` / `http.type` 可以指定用哪个。5.3 起显式声明 Netty 3 要下线。

处理动作只有一个：配置里写了 `transport.type=netty3` 或 `http.type=netty3` 的，去掉（默认走 netty4）。6.0 里这两个值不再存在，留着会导致启动失败。

官方没在这个条目里写切换的背景。Netty 3 停止维护、Netty 4 在内存管理上更好这类说法本文没有引用官方出处，不作为迁移依据——需要了解的话以 Netty 官方的发布说明为准。

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

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

## 实际行为是什么

> Usage of any value other than `false`, `"false"`, `true` and `"true"` in boolean settings deprecated.

关键词是 deprecated（废弃），不是 removed（移除）。源码里的行为（[Setting.java 第 862–870 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/common/settings/Setting.java#L862-L870)）：

```java
private static Boolean parseBoolean(String key, String value) {
    // let the parser handle all cases for non-proper booleans without a deprecation warning by throwing IAE
    boolean booleanValue = Booleans.parseBooleanExact(value);
    if (Booleans.isStrictlyBoolean(value) == false) {
        DeprecationLogger deprecationLogger = new DeprecationLogger(Loggers.getLogger(Setting.class));
        deprecationLogger.deprecated("Expected a boolean [true/false] for setting [{}] but got [{}]", key, value);
    }
    return booleanValue;
}
```

拆开看：

- `Booleans.parseBooleanExact` 接受的其实是 8 个值（[Booleans.java 第 73–84 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/common/Booleans.java#L73-L84)，报错消息里写的是 `true/1/on/yes OR false/0/off/no`）：`on`、`off`、`yes`、`no`、`1`、`0` 都还能解析；
- `isStrictlyBoolean` 只认 `"true"` 和 `"false"`（[第 88–90 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/common/Booleans.java#L88-L90)），不满足就打一条 deprecation 日志：

```text
Expected a boolean [true/false] for setting [xxx] but got [yyy]
```

- 这 8 个之外的值直接抛 `IllegalArgumentException`。

所以在 5.x 上，`node.data: 0`、`http.enabled: no` 这类写法**仍然生效**（解析成 false），只是每次启动往 deprecation 日志写一条；不是在 5.3 就失效。留到 6.0 才是真的拒绝。这一点和"已经不能用了"要区分开。

让布尔解析收紧的理由和 5.0 "所有设置必须已知"一脉相承：宽松解析的问题是静默——`enabled: off` 到底被当成什么，不同版本、不同入口可能不同，而用户以为自己关掉了某功能。5.3 的做法是先用 deprecation 日志提醒，6.0 再切断。

## 落地：三条怎么改

```sh
# 1) 日志属性：老配置里还有没有单个 es.logs
grep -rn "es\.logs" /etc/elasticsearch/jvm.options /etc/default/elasticsearch 2>/dev/null

# 2) Netty 3：6.0 会直接删除，必须提前去掉
grep -rn "type.*netty3" /etc/elasticsearch/elasticsearch.yml

# 3) 布尔宽松写法
grep -rnE ":\s*(yes|no|on|off|0|1)\s*$" /etc/elasticsearch/elasticsearch.yml

# 4) deprecation 日志汇总（按出现次数排）
grep -ho "\[deprecation[^]]*\].*" /var/log/elasticsearch/*.log 2>/dev/null   | sed 's/[0-9]\+/N/g' | sort | uniq -c | sort -rn | head -20
```

第 3 条把 `0`/`1` 也加进来了（它们同样属于非严格布尔写法）。命中的行要看键名：只有真的是 ES 的布尔设置才改，`on`/`off` 也可能是某个字段的合法字符串值。另外第 3 条只匹配行尾，写在行中间或带注释的形式要人工看。

第 4 条把数字泛化成 N 再聚合，能把同类消息合并（否则每条时间戳不同，统计不出来）。

## deprecation log 是最该被当回事的东西

这三条的共同点是[“”"']官方提前打招呼[“”"']，重点不在改了什么。这类条目最合适的处理工具是 deprecation 日志：它直接告诉你"你正在用的这个东西，下个版本就没了"，而且针对的是实际用法，不是迁移文档里泛泛的清单。

排序按两个维度：

- **会不会导致启动失败**：会失败的排最前（`netty3` 这种 6.0 直接删的）；
- **出现次数**：高频的先改，说明用得多。

每个大版本升级前跑一次第 4 条，比读迁移文档高效——迁移文档列的是所有可能的改动，deprecation 日志只列你实际用到的。

这个动作在升级前做的成本，远低于升级后排查：升级后你面对的是"某个功能突然没了"，却不知道对应哪条弃用。

## 升级 5.3 的检查清单

1. `log4j2.properties` 里 `${sys:es.logs}` 换成三个新属性，改完确认日志文件名符合预期（多节点共用目录时靠 `es.logs.node_name` 区分）；
2. 配置里去掉 `transport.type=netty3` / `http.type=netty3`；
3. 所有布尔设置改成 `true`/`false` 字面量（含模板、Ansible / K8s 配置里生成的 YAML）；
4. 重启后翻 deprecation 日志，确认没有新的废弃警告残留，并按上面两个维度排期。

## 在 5.6.16 和 6.8.23 上各跑一遍

第三条「布尔只认 true/false」最容易被当成文字游戏——反正值还是该意思。实测下来两件事要分开看：**写法**被废弃（只在弃用日志留一句），**值**照样生效；到 6.8 才开始直接拒。

![04-boolean-yes-accepted-with-deprecation](https://developer.qcloudimg.com/http-save/yehe-7348459/2725a8f05fd4b50758d04a2680375bb5.png)

*图 4：5.6.16 上 `read_only` 分别写 `yes`、`on`、`1`，三次都回 `acknowledged: true`；跟着往该索引写一条文档被挡（`FORBIDDEN/5/index read-only`），说明 `yes` 是当真解释成了 true；弃用日志里留下三行 `Expected a boolean [true/false] ... but got [yes]`。本地实测输出。*

```bash
curl -s -XPUT 'http://localhost:9200/r_yes' \
  -H 'Content-Type: application/json' \
  -d '{"settings":{"index":{"blocks":{"read_only":"yes"}}}}'
# {"acknowledged":true,"shards_acknowledged":true,"index":"r_yes"}

curl -s -XPUT 'http://localhost:9200/r_yes/doc/1' \
  -H 'Content-Type: application/json' -d '{"f":1}'
# blocked by: [FORBIDDEN/5/index read-only (api)];
```

这一步把「写错」的两种后果区分开了：值是错的写法，行为是对的。如果只看返回码，`yes` 和 `true` 一模一样，差别全在日志里。我的默认做法是升级前把 deprecation log 当检查项，`grep 'Expected a boolean'` 一条命令就能把这类写法全捞出来。

![05-invalid-value-rejected](https://developer.qcloudimg.com/http-save/yehe-7348459/386bb11720a67b10b0bd2abdc0a63c13.png)

*图 5：上：真正抛异常的是 `yes`/`on`/`1` 之外的值，`maybe` 回 400，错误信息自己列出 `true/1/on/yes OR false/0/off/no`；下：写规范的 `true` 回 200，弃用日志行数没变。本地实测输出。*

到 6.8 才收紧：

![06-68-rejects-yes](https://developer.qcloudimg.com/http-save/yehe-7348459/a853ce35be327d407653f10aea44397d.png)

*图 6：6.8.23 上同一个 `read_only: "yes"` 直接 400：`Failed to parse value [yes] as only [true] or [false] are allowed.`；写 `true` 照常建起来。本地实测输出。*

结论是这条迁移的分界在 6.0，5.x 阶段的信号只有日志一行。逐行检查 yml 里的布尔写法收益有限（大部分配置项根本不接受 `yes`/`on`），更省事的做法是先 grep 出所有 `: yes`、`: on` 这类可疑行，再对着 deprecation log 复核一遍——日志里出现的才是真被解析成布尔的地方。

边界：

* 图 4、图 5 出自 5.6.16 实例，图 6 出自 6.8.23 实例，都是官方 tar 包起的单节点，`read_only` 只是拿来做样本的布尔设置；
* 日志属性拆分（`es.logs` → `es.logs.base_path` 等）和 netty3 废弃没有做运行期对照，前者要改 `log4j2.properties` 重启，后者要装 netty3 传输实现。


## 写在最后

5.3 这三条都是"提前打招呼，6.0 才真移除"。我的判断是：处理它们的最好工具是 deprecation 日志：比读迁移文档准，因为它针对实际用法。

三条各自的要点：日志属性拆分后确认文件名（多节点共用目录要靠 `es.logs.node_name` 区分）；`netty3` 去掉即可，默认就是 netty4；布尔宽松写法在 5.x 还能用但会记 deprecation 日志，6.0 才真正拒绝——我的建议是排查时别只看主日志，deprecation 日志要专门 grep 一遍。

## 参考

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

> 本文对照 Elasticsearch `v5.6.16` 标签的官方文档核对，引文逐字取自原文。图 4、图 5 是本地 5.6.16 实例的实测输出，图 6 是 6.8.23 实例的对照输出；日志属性与 netty3 两条未做运行期实测，正文中已标注。


5.3 的 breaking 只有三条，都不是"不能用了"而是"提前打招呼，6.0 才移除"：日志系统属性从单个 es.logs 拆成 es.logs.base_path、es.logs.cluster_name、es.logs.node_name；transport.type=netty3 和 http.type=netty3 标记废弃；布尔设置只接受 true/"true"/false/"false"。第三条的实际行为值得说清楚：v5.6.16 里 yes/no/on/off/1/0 仍能用，只是会往 deprecation 日志写一条，真正抛异常的是这几个之外的值。本文按 v5.6.16 源码把这一点和其它两条的落地写法列出来。

考古｜ES 5.3 三条提前打招呼的改动，布尔值写 yes/on 的要先 grep 一遍

5.3 的 breaking 只有三条，都不是"不能用了"而是"提前打招呼，6.0 才移除"……

官方产研

云计算

后端

大数据

5.3版本三条breaking change均为弃用警告，6.0才真正移除。es.logs拆分为base_path、cluster_name、node_name三属性；netty3标记废弃；布尔设置仅接受true/false，5.x阶段yes/on/1仍生效但记录弃用日志。建议升级前重点检查deprecation日志，按启动失败风险与使用频率排序处理。

Elasticsearch 

日志文件

内存管理

代码解释

JSON

Java

腾讯云双十一大促

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

5.3版本三条breaking change均为弃用警告，6.0才真正移除。es.logs拆分为base_path、cluster_name、node_name三属性；netty3标记废弃；布尔设置仅接受true/false，5.x阶段yes/on/1仍生效但记录弃用日志。建议升级前重点检查deprecation日志，...

考古｜ES 5.3 三条提前打招呼的改动，布尔值写 yes/on 的要先 grep 一遍-腾讯云开发者社区-腾讯云

考古｜ES 5.3 三条提前打招呼的改动，布尔值写 yes/on 的要先 grep 一遍

考古｜ES 5.3 三条提前打招呼的改动，布尔值写 yes/on 的要先 grep 一遍

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐