> 2.2 迁移文档列了几处会影响升级的变更：`geo_point` 换了新的存储格式（`doc_values` 和 `coerce` 参数因此被移除）、脚本受 Java Security Manager 限制、field stats API 的响应格式变化、systemd 下日志默认输出改到 journal、Java 客户端遍历 `ClusterHealthResponse` 的方式变化，另有 AWS 插件代理设置改名和 multicast 插件弃用。

## **说明**

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

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

![01-migrate_2_2](https://developer.qcloudimg.com/http-save/yehe-7348459/b332a70ced83038c93769d993a11bc8a.png)

*图 1：官方文件 migrate_2_2.asciidoc（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 migrate_2_2.asciidoc*

## geo_point 换了格式

2.2 迁移文档（[migrate_2_2.asciidoc @ v2.4.6](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/migration/migrate_2_2.asciidoc)）的原文：

> The `geo_point` format has been changed to reduce index size and the time required to both index and query geo point data. To make these performance improvements possible both `doc_values` and `coerce` are required and therefore cannot be changed. For this reason the `doc_values` and `coerce` parameters have been removed from the `geo_point` field mapping.

新格式要减少索引体积并加快索引与查询，前提是必须启用 `doc_values` 且必须做 `coerce`（坐标值强制转换）。这两项成了前提，就不能再让用户关掉，于是从 mapping 参数里删除。

影响面：

* 老 mapping 里显式写了 `"doc_values": false` 或 `"coerce": false` 的 `geo_point` 字段，要在新建索引的 mapping 里删掉这两个参数。v2.4.6 的新格式解析代码（[BaseGeoPointFieldMapper 第 202–260 行](https://github.com/elastic/elasticsearch/blob/v2.4.6/core/src/main/java/org/elasticsearch/index/mapper/geo/BaseGeoPointFieldMapper.java#L202-L260)）没有处理这两个参数，写了会怎样（报错还是忽略），本文没有实测；
* 新格式的 geo_point 在 2.2 时还没有被 percolator 支持，官方指向 geo-percolate 一节给 workaround；
* 按 [第 206–207 行](https://github.com/elastic/elasticsearch/blob/v2.4.6/core/src/main/java/org/elasticsearch/index/mapper/geo/BaseGeoPointFieldMapper.java#L206-L207)，2.2.0 之前创建的索引仍走 `GeoPointFieldMapperLegacy`，所以老索引的 mapping 不用动。我的判断是想用上新格式，就得在新版本里建新索引再迁移数据，别指望老索引原地升级。

同一段源码里还能看到，新格式的 `geo_point` 对 `lat_lon`、`precision_step`、`geohash`、`geohash_prefix`、`geohash_precision` 这几个参数会写 deprecation 日志，提示下个大版本移除。如果 mapping 里用了它们，升级后日志里会出现告警。

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

*图 2：官方文件 BaseGeoPointFieldMapper.java（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 BaseGeoPointFieldMapper.java*

## 脚本受 Java Security Manager 限制

> The Java Security Manager is being used to lock down the privileges available to the scripting languages and to restrict the classes they are allowed to load to a predefined whitelist. These changes may cause scripts which worked in earlier versions to fail.

从 2.2 起，脚本能用的权限和可加载的类被白名单限制。这是安全加固，后果是之前能跑的脚本在升级后可能失败。

脚本安全一节（[security.asciidoc](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/modules/scripting/security.asciidoc)）说明了两点：Security Manager 默认开启，安全策略把每个类的权限收到运行所需的最小；脚本语言只能加载 `ClassPermission` 里硬编码白名单中的类，加载白名单之外的类"可能"（may）得到 `ClassNotFoundException`。文档给的例子是 Groovy 脚本 `use(java.math.BigInteger)`，响应是 `script_exception`，里面嵌套 `no_class_def_found_error` 和 `class_not_found_exception`。所以症状是 `script_exception` 带这类原因。文档没有给出文件 IO、网络等具体被拦操作的报错样例，本文不猜测异常类型。处理方式：

* 尽量把逻辑收敛到 `doc['field'].value` 这类标准访问上；
* 确实用到白名单外能力的，考虑改成在应用端计算；
* 排障时看报错里被拒绝的类名，判断是脚本写法问题，还是确实需要额外权限。

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

*图 3：官方文件 security.asciidoc（v2.4.6 标签）。来源：GitHub elastic/elasticsearch v2.4.6 security.asciidoc*

## field stats API 响应格式变了

> The field stats' response format has been changed for number based and date fields. The `min_value` and `max_value` elements now return values as number and the new `min_value_as_string` and `max_value_as_string` return the values as string.

数值和日期字段的 `min_value`/`max_value` 从此返回真正的数字，字符串形式挪到新增的 `min_value_as_string`/`max_value_as_string`。

这个改动对解析方是破坏性的：原来按字符串处理 `min_value` 的代码，升级后拿到的是数字，类型断言可能失败；反过来，依赖字符串精度（比如日期格式、高精度数值的原样表示）的地方要改用新的 `_as_string` 字段。

## systemd 下的日志默认值

> In previous versions of Elasticsearch using systemd, the default logging configuration routed standard output to `/dev/null` and standard error to the journal. However, there are often critical error messages at startup that are logged to standard output rather than standard error and these error messages would be lost to the ether. The default has changed to now route standard output to the journal and standard error to inherit this setting.

之前 systemd 部署时 stdout 被丢到 `/dev/null`，而启动阶段的关键错误信息恰恰打在 stdout 上，于是这些错误"消失在以太里"。2.2 起 stdout 也进 journal，stderr 继承该设置。需要改的话编辑 `elasticsearch.service`。

运维上的影响是 stdout 的内容也进 journal，日志量可能变大，以前"看不到启动错误"的问题则不再出现。

## `ClusterHealthResponse` 的遍历方式

> Previously it was possible to iterate over `ClusterHealthResponse` to get information about `ClusterIndexHealth`. While this is still possible, it requires now iterating over the values returned from `getIndices()`.

新写法：

```java
ClusterHealthResponse clusterHealthResponse = client.admin().cluster().prepareHealth().get();
for (Map.Entry<String, ClusterIndexHealth> index : clusterHealthResponse.getIndices().entrySet()) {
    String indexName = index.getKey();
    ClusterIndexHealth health = index.getValue();
}
```

代码里直接 for-each `ClusterHealthResponse` 的地方要改成遍历 `getIndices().entrySet()`。同一节还提到 `ClusterHealthStatus` 从 `org.elasticsearch.action.admin.cluster.health` 搬到了 `org.elasticsearch.cluster.health`，import 要跟着改。

## 同一份迁移文档的另外两条

文档末尾还有两条，和 mapping、脚本无关，但会影响部署：

* Cloud AWS 插件的代理设置改名并标记弃用：`cloud.aws.proxy_host` 改为 `cloud.aws.proxy.host`，`cloud.aws.proxy_port` 改为 `cloud.aws.proxy.port`，`ec2`、`s3` 子级同理（如 `cloud.aws.ec2.proxy_host` 改为 `cloud.aws.ec2.proxy.host`）。文档说旧设置会在下个大版本移除；
* `discovery-multicast` 插件在 2.2.0 弃用，在 5.0 移除。用 multicast 做节点发现的集群，要在 5.0 之前换成单播发现。

原文见 [migrate_2_2.asciidoc](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/migration/migrate_2_2.asciidoc)。

## 升级 2.2 的检查顺序

1. mapping 里 `geo_point` 字段删掉 `doc_values`、`coerce` 参数；用到 percolator + geo 的场景确认 workaround；
2. 灰度跑一遍所有脚本，看有没有 `script_exception`；
3. field stats 的解析代码改成按数字读 `min_value`/`max_value`，字符串用 `*_as_string`；
4. systemd 部署确认 journal 容量；
5. Java 客户端里 `ClusterHealthResponse` 的遍历方式和 `ClusterHealthStatus` 的 import 改掉；
6. 用到 AWS 插件代理设置或 multicast 发现的，按上一节改。

## 脚本沙箱那条比 geo 更容易被忽略

这几条里，geo_point 换格式只影响新建索引的 mapping，写法对不对在建索引时就能看出来，好排查。更容易漏的是脚本受 Security Manager 限制。

原因是它的失败发生在运行时，而且取决于脚本里调用了什么。脚本在灰度环境可能一切正常，到生产因为某个调用被拦住才失败，静态看代码也看不出来。官方文档自己用的措辞是"may result in"，说明连文档也不保证每次的表现一致。

我的建议是把所有脚本列出来，逐个在生产等价环境跑一遍，不要假设编译通过就能跑。上面检查清单里单列"灰度跑一遍所有脚本"，原因就在这里：它没法靠读代码完成。

文档对这个限制的解释是：脚本语言（文中点名 Groovy 和 Javascript）本来就能做 Java 能做的一切，包括写文件系统、向远程服务器开 socket，所以权限限制对它们尤其重要。靠白名单去限制一门通用语言，是在通用能力上做减法。5.0 起有了 Painless（见 Groovy 到 Painless），2.2 这一步可以看作过渡，代价是上面说的"运行时才暴露"。

## 怎么提前找出会踩沙箱的脚本

```sh
# 1) 把索引里的脚本（indexed script）列出来，2.x 存在 .scripts 索引（ScriptService 第 90 行）；文件脚本在各节点的 config/scripts 目录
curl -s 'localhost:9200/.scripts/_search?size=100&pretty'

# 2) 搜索代码里的内联脚本
grep -rn '"script"\s*:' --include=*.json --include=*.java --include=*.py . | head -30

# 3) 逐个在测试环境执行一次，看有没有 script_exception
#    （执行成功不代表生产一定通过，但失败能提前发现）
```

第三条是关键：沙箱问题只能靠执行发现。找到脚本之后，先看有没有加载白名单之外的类，比如 `use(...)` 引入的 JDK 类；文件读写、网络调用这类操作，文档只在说明限制动机时提到，没给具体报错，需要在测试环境实际执行确认。

## 写在最后

2.2 这批改动里，geo_point 的问题在建索引时就能看到，脚本沙箱要到运行时才暴露。升级前把脚本全量执行一遍，比读文档更有用。

systemd 那条：日志默认改到 journal 之后，如果 journal 没配容量上限，日志量增加可能占用更多磁盘。这是推断，文档只说了 stdout 现在也进 journal。

geo 那条：改 mapping 之前，先确认老索引要不要重建。按源码的版本判断，2.2.0 之前创建的索引继续走旧的映射器，只有新建索引才用新格式。这和父子关系那次的处理思路类似，见 2.0 的 _parent 重写。

## 参考

- [migrate_2_2.asciidoc @ v2.4.6](https://github.com/elastic/elasticsearch/blob/v2.4.6/docs/reference/migration/migrate_2_2.asciidoc)

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


2.2 迁移文档列了几处会影响升级的变更：geo_point 换了新的存储格式（doc_values 和 coerce 参数因此被移除）、脚本受 Java Security Manager 限制、field stats API 的响应格式变化、systemd 下日志默认输出改到 journal、Java 客户端遍历 ClusterHealthResponse 的方式变化，另有 AWS 插件代理设置改名和 multicast 插件弃用。

考古｜ES 2.2 升级要查三处，geo_point 格式、脚本沙箱和 field stats

2.2 迁移文档列了几处会影响升级的变更：geopoint 换了新的存储格式（docvalues 和……

官方产研

云计算

后端

大数据

Elasticsearch 2.2升级指南：geo_point新格式移除doc_values/coerce参数，脚本受SecurityManager白名单限制，fieldstats响应结构变更，systemd日志默认转journal，Java客户端遍历方式调整。适用于腾讯云ES，附完整检查清单与脚本排查方法。

Elasticsearch 

文件系统

代码解释

JavaScript

服务器

JSON

Java

2026上云采购 | AI焕新·智启新局

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

考古｜ES 2.2 升级要查三处，geo_point 格式、脚本沙箱和 field stats-腾讯云开发者社区-腾讯云

考古｜ES 2.2 升级要查三处，geo_point 格式、脚本沙箱和 field stats

考古｜ES 2.2 升级要查三处，geo_point 格式、脚本沙箱和 field stats

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐