> 5.0 的插件改动有 14 条，但哪条对你有影响，取决于 `plugins` 目录里装了什么。`bin/plugin` 改名 `bin/elasticsearch-plugin`、插件 zip 必须带顶层 `elasticsearch/` 目录、`isolated` 选项删除（每个插件独立 classloader）、site 插件删除、multicast 插件删除、Cloud AWS/Azure/GCE 拆分改名，另外有一批插件接口从 `onModule(XxxModule)` 换成 `XxxPlugin`。本文按 v5.6.16 逐条列出，并标出哪些是配置改动、哪些要重写插件。

## **说明**

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

实测环境：本地 Elasticsearch 5.6.16 官方 tar 包（配 `.eslab/jdk` 下的 JDK 8），用 `bin/elasticsearch-plugin` 命令行工具做检查；测试插件在 `/tmp` 下临时构造，装完立即卸载，发行版的 `plugins` 目录跑完是空的。

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

![01-plugins](https://developer.qcloudimg.com/http-save/yehe-7348459/4c7cbb39bab4eec9b78992133167bb29.png)

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

## 命令行与包结构

5.0 迁移文档（[migrate_5_0/plugins.asciidoc 第 4–7 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L4-L7)）开篇：

> The command `bin/plugin` has been renamed to `bin/elasticsearch-plugin`. The structure of the plugin ZIP archive has changed. All the plugin files must be contained in a top-level directory called `elasticsearch`. If you use the gradle build, this structure is automatically generated.

两处变化：

1. 命令名：`bin/plugin install x` 改成 `bin/elasticsearch-plugin install x`，部署脚本里的调用都要改；
2. 包结构：插件 zip 内所有文件必须在顶层 `elasticsearch/` 目录下。用 gradle 构建的会自动生成这个结构，手工打包的要注意。

同一节后面还有两条和命令行相关（[第 103–113 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L103-L113)）：

- 以前可以把 `-D` 形式的参数直接传给 plugin 脚本来传 Java 系统属性，5.0 起不允许，必须通过 `ES_JAVA_OPTS` 传；
- 通过 `path.plugins` 指定自定义插件目录的能力被删除。

![02-ListPluginsCommand](https://developer.qcloudimg.com/http-save/yehe-7348459/1ed548922ad0f096b70f86994c641a22.png)

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

## `isolated` 选项删除

> `isolated` option has been removed. Each plugin will have its own classloader.

以前安装插件时可以加 `--isolated` 让它拥有独立的 classloader，避免和核心或其他插件的类冲突。5.0 起这不是可选项，每个插件都有自己的 classloader。

对使用者的影响是去掉 `--isolated` 参数；对插件作者来说，依赖被核心同类库覆盖的问题不再需要自己处理。

![03-PluginCli](https://developer.qcloudimg.com/http-save/yehe-7348459/98a7d3cefd96f0e2ccaded8e3c128f8a.png)

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

## 被删除或替换的几类插件

| 变更 | 官方说法（原文要点） |
|---|---|
| Site 插件删除 | 应改用 Kibana 插件实现（第 13–16 行） |
| Multicast 插件删除 | 改用 unicast 发现或某个云发现插件（第 18–21 行） |
| Delete-By-Query 插件删除 | 改用核心的 Delete By Query API，支持节流、重试、取消，但不再支持 timeout，改取消 API（第 92–96 行） |
| Mapper Attachments 插件废弃 | 改用 `ingest-attachment` 插件（第 98–101 行） |
| Cloud AWS 拆分 | 拆成 discovery-ec2 和 repository-s3（第 40–45 行） |
| Cloud Azure 拆分 | 拆成 discovery-azure-classic、repository-azure、store-smb（第 56–62 行） |
| Cloud GCE 改名 | 改名 discovery-gce（第 88–90 行） |

AWS 拆分之外，代理设置也一起改名了（[第 47–54 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L47-L54)），六组：

```text
cloud.aws.proxy_host     -> cloud.aws.proxy.host
cloud.aws.ec2.proxy_host -> cloud.aws.ec2.proxy.host
cloud.aws.s3.proxy_host  -> cloud.aws.s3.proxy.host
cloud.aws.proxy_port     -> cloud.aws.proxy.port
cloud.aws.ec2.proxy_port -> cloud.aws.ec2.proxy.port
cloud.aws.s3.proxy_port  -> cloud.aws.s3.proxy.port
```

Azure 那条还带一个配置结构变化：原来 `cloud.azure.storage` 下面直接写 `account` 和 `key`，5.0 起要给它一个 id，因为可以定义多个存储账户：

```yaml
cloud:
    azure:
        storage:
            my_account:
                account: your_azure_storage_account
                key: your_azure_storage_key
```

site 插件影响的是一类用法：用插件提供静态页面。升级后这类页面全部不可用，替代方案要提前想好，这是能力没了，不是改个配置能解决的。

multicast 从 2.0 起已经降级为插件，5.0 连插件也没有。必须显式配置 `discovery.zen.ping.unicast.hosts`，或者用云环境发现插件。对零配置测试集群是体验退化，对生产是收敛：集群成员关系变可预期。

## 自定义查询/评分函数插件的接口变更

这一条只影响插件开发者，但改动不小（[第 23–38 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L23-L38)）：

> Plugins implementing custom queries need to implement the `fromXContent(QueryParseContext)` method in their `QueryParser` subclass rather than `parse`. [...] Also, the query builder needs to be registered as a `NamedWriteable`. This is all done by implementing the `SearchPlugin` interface and overriding the `getQueries` method.

> The query object can then transform itself into a lucene query through the new `toQuery(QueryShardContext)` method, which returns a lucene query to be executed on the data node.

核心是把"解析"和"执行"拆成两段：

- `fromXContent(QueryParseContext)`：从请求体解析出一个中间表示，这个中间表示就是 Java API 里的查询对象，并且要注册为 `NamedWriteable`，以便节点间二进制传输；
- `toQuery(QueryShardContext)`：在数据节点上把这个对象转成真正可执行的 Lucene 查询。

评分函数插件同理：`ScoreFunctionParser` 实现 `fromXContent`，函数对象通过 `toFunction(QueryShardContext)` 转成 Lucene function。

这么改的原因是协调节点负责解析、数据节点负责执行，两者之间传输的必须是可序列化的查询对象，而不是"解析完直接生成 Lucene 对象"。这样自定义查询才能像内置查询一样在集群里传输、缓存、分片级执行。

## 一批插件接口从 `onModule` 换成 `XxxPlugin`

同一节后半段是一批接口改动（[第 115–154 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L115-L154)）：

| 插件做什么 | 5.0 做法 | 要删掉的 |
|---|---|---|
| 注册自定义脚本 | 实现 `ScriptPlugin` | `onModule(ScriptModule)` |
| 注册自定义分析组件 | 实现 `AnalysisPlugin` | `onModule(AnalysisModule)` |
| 注册自定义 mapper | 实现 `MapperPlugin` | `onModule(IndicesModule)` |
| 注册自定义 action | 实现 `ActionPlugin` | `onModule(ActionModule)` |
| 注册自定义 `RestHandler` | 实现 `ActionPlugin` | `onModule(NetworkModule)` |
| 注册自定义检索行为（Query、Suggester、ScoreFunction、FetchSubPhase、Highlighter 等） | 实现 `SearchPlugin` | `onModule(SearchModule)` |

另外两条：

- `SearchParseElement` 接口删除。自定义搜索请求段只能放在 `ext` 元素下，插件通过 `SearchPlugin.SearchExtSpec`（`SearchExtParser` 解析 XContent 成 `SearchExtBuilder`）接入；解析现在发生在协调节点，结果随搜索请求序列化到数据节点，存在搜索上下文里供后续取用；
- 测试相关：`ESIntegTestCase#pluginList` 删除，改用 `Arrays.asList`，理由是所有插件都要求 Java 1.8 之后不再需要它。

最后还有一条容易被忽略的数据侧影响（[第 161–164 行](https://github.com/elastic/elasticsearch/blob/v5.6.16/docs/reference/migration/migrate_5_0/plugins.asciidoc#L161-L164)）：mapper-size 插件的 `_size` 元字段，对 2.x 创建的索引，在聚合、脚本、排序里不可访问。需要这些功能要用 5.x 重新索引数据。

## 自研插件怎么评估

原文里"5.0 把 `AbstractSearchScript` 换成 `SearchScript`、构造签名变了"这类说法未逐条核实，以官方迁移文档为准（文档里这一节写的是 `ScriptPlugin` 与 `onModule` 的替换）。不管具体是哪一个扩展点，评估自研插件可以按这几步：

1. 先看这个扩展点在不在上面那张表里。在的话，改动量主要是把 `onModule` 换成对应的 `XxxPlugin`；
2. 确认这个插件还有没有必要存在。有些自定义查询、评分逻辑后来有了官方能力（衰减函数、Painless 脚本能直接表达的逻辑等），能替代的就别再维护自研插件；
3. 自研插件依赖 ES 内部类，而内部类跨版本没有兼容承诺，每次大版本升级都可能要改。插件数量应当当成一项技术债来管理：每加一个都要有明确理由（官方能力确实做不到），并记录它依赖了哪些内部类，下次升级时才能估改动量。

## 部署脚本里要改的地方

```sh
# 命令名变了
bin/plugin install x                    # 5.0 之前
bin/elasticsearch-plugin install x      # 5.0 起

# --isolated 参数删了（现在每个插件本来就隔离）
bin/elasticsearch-plugin install x --isolated   # 删掉参数即可

# Java 系统属性不再能直接传给 plugin 脚本
bin/plugin -Des.some.property=x ...     # 5.0 之前
ES_JAVA_OPTS="-Des.some.property=x" bin/elasticsearch-plugin install x   # 5.0 起
```

排查范围不只是部署脚本：

- Dockerfile 里的安装命令；
- Ansible / Puppet / Chef 的插件安装步骤；
- 启动脚本里的插件检查逻辑（比如判断某个插件是否已安装）；
- 文档和 Runbook 里的命令（照着复制的人会踩坑）。

最后一类最容易漏，因为没人会去执行文档里的命令验证。全局搜 `bin/plugin`、`--isolated`、`path.plugins`，把所有命中处一起改掉。

## 升级检查清单

1. 先列出每个节点实际安装的插件（见下一节），再对照本文各条；
2. 脚本里 `bin/plugin` 全量替换成 `bin/elasticsearch-plugin`；
3. 自研插件检查压缩包结构（顶层 `elasticsearch/` 目录），去掉 `--isolated`；
4. 传 `-D` 系统属性的改成 `ES_JAVA_OPTS`；用了 `path.plugins` 的改回默认插件目录；
5. 清点 site 插件，寻找 Kibana 插件或独立工具替代；
6. 还在用 multicast 的集群改成 unicast 显式配置；
7. `cloud-aws` 按用途换成 `discovery-ec2` / `repository-s3`，并按新名字改代理设置；`cloud-azure` 拆成三个并给存储账户加 id；`cloud-gce` 改名 `discovery-gce`；
8. delete-by-query 插件换成核心 API，去掉 timeout 参数的用法；
9. mapper-attachments 换成 `ingest-attachment`；
10. 自研插件按上面的对照表换成 `XxxPlugin`；自定义查询/评分按 `SearchPlugin` + `fromXContent` + `toQuery`/`toFunction` 重写；
11. 2.x 创建的索引如果在聚合、脚本、排序里用了 `_size`，规划重新索引。

## 先列插件，再读清单

插件相关的改动麻烦在它依赖你装了什么插件。官方列的变更对有没有影响，取决于 `plugins` 目录里有什么。

所以排查的第一步是先列一遍实际安装的插件，变更列表留到后面读，再逐个对照，没装的那些可以直接跳过。这一节能省不少时间：变更列表有十几条，实际用到的插件也许只有两三个，做完这个过滤，剩下要细看的只有少数几条。

```sh
# 每个节点上已安装的插件
bin/elasticsearch-plugin list

# 通过 API 看各节点的插件情况
curl -s 'localhost:9200/_cat/plugins?v'
```

`list` 是 `elasticsearch-plugin` 的子命令之一（[ListPluginsCommand](https://github.com/elastic/elasticsearch/blob/v5.6.16/distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/ListPluginsCommand.java)、[PluginCli](https://github.com/elastic/elasticsearch/blob/v5.6.16/distribution/tools/plugin-cli/src/main/java/org/elasticsearch/plugins/PluginCli.java)），`_cat/plugins` 在 5.6.16 里也有（[RestPluginsAction](https://github.com/elastic/elasticsearch/blob/v5.6.16/core/src/main/java/org/elasticsearch/rest/action/cat/RestPluginsAction.java)）。

顺着一个思路再想一层：插件是升级风险的主要来源之一。核心功能的变更官方会重点说明、社区讨论也多；插件的变更容易被忽略，而且不同插件的维护状态差异很大，有的跟着主版本走，有的长期不更新。

所以给插件做一次清点，不只是为了这次升级：

- 哪些是必需的（业务依赖）；
- 哪些是历史遗留（当初试过、现在没人用）；
- 哪些已经不再维护。

我的判断是第三类最值得处理：它们迟早会成为升级的阻塞项，早处理比晚处理便宜。清掉之后集群启动更快，故障面也更小。

## 在 5.6.16 上跑一遍

「先看装了什么，再对照改动」这个顺序，用一次目录检查和一次插件安装就能走完。

![04-plugin-command-renamed](https://developer.qcloudimg.com/http-save/yehe-7348459/4e622521c8e14fd49403255b3809e535.png)

*图 4：5.6.16 的 `bin/` 里只有 `elasticsearch-plugin` 与 `elasticsearch-plugin.bat`，`bin/plugin` 显示 `MISSING`；`elasticsearch-plugin list` 输出为空（没装任何插件）。本地实测输出。*

![05-site-plugin-still-installable](https://developer.qcloudimg.com/http-save/yehe-7348459/be668bc2432340a9614820645105ced5.png)

*图 5：构造一个 `site=true` 的 `plugin-descriptor.properties`（放在 zip 的顶层 `elasticsearch/` 目录下）后，`elasticsearch-plugin install` 回 `-> Installed test-site`，`list` 里出现 `test-site`，`remove` 后列表重新为空。本地实测输出。*

```bash
ls -1 bin/ | grep -i plugin
# elasticsearch-plugin
# elasticsearch-plugin.bat

bin/elasticsearch-plugin list
# （空）
```

命令改名这一条验得很直接：5.6.16 里根本没有 `bin/plugin` 这个文件，部署脚本中残留的 `bin/plugin install x` 会直接 `command not found`。图 5 同时也把「zip 必须带顶层 `elasticsearch/` 目录」走了一遍——本次正是按这个结构打包才装上的。

有一处与官方说法对不上，原样记在这里：官方把 site 插件列为「删除」，升级后静态页面不可用；本机 5.6.16 却能把 `site=true` 的插件**装得上、也列得出来**。安装成功不等于页面还能访问——本机没有起节点去请求插件提供的静态资源，所以「下线」到底指不再 serve 页面，还是连安装都不允许，本地判断不了。这一条挂起，不替官方圆，也不据这次安装结果推翻原文。

结论是清点时不能只看 `install` 是否成功，还得按用途验证能力还在不在。我的建议是升级前把 `elasticsearch-plugin list` 的结果逐项对照 14 条改动，脚本里的 `bin/plugin` 全量替换；对 site 类插件单独起一次实例、实际请求一下页面，再决定用 Kibana 插件还是独立工具替代。

边界：

* 图 4、图 5 出自 5.6.16 的命令行工具，只验了 `install` / `list` / `remove`，没有起节点验证插件加载或静态页面；
* 测试插件只写了最小的 descriptor，没有 Java 类，安装后能否被节点正常加载未实测；
* `--isolated`、`path.plugins`、multicast 与云插件拆分、插件接口重写等条目未逐个验；
* 5.0 之前没有对应版本二进制，`bin/plugin` 的实际形态未做运行期对照。


## 写在最后

5.0 的插件改动分成三层：命令行和包结构（`bin/elasticsearch-plugin`、顶层 `elasticsearch/` 目录、`ES_JAVA_OPTS`、`path.plugins` 删除），插件的存废（site、multicast、delete-by-query、mapper-attachments、三个云插件的拆分改名），插件接口（`XxxPlugin` 取代 `onModule`、`SearchPlugin` 加 `fromXContent` 加 `toQuery`、`SearchParseElement` 删除）。

前两层改配置和脚本，第三层要改代码。我的建议是先列一遍装了什么插件，能直接跳过大部分条目。

## 参考

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

> 本文对照 Elasticsearch `v5.6.16` 标签的官方文档核对，引文逐字取自原文。「在 5.6.16 上跑一遍」里已实际检查 bin 目录（`bin/plugin` 不存在、只有 `elasticsearch-plugin`）并装/卸过一个测试插件（见该节）。本次实测与官方「site 插件删除」不完全一致：`site=true` 的插件在 5.6.16 上仍能安装并列出，本机未起节点验证静态页面是否可用，该条挂起、未据此下结论。`--isolated`、`path.plugins` 等其余条目与 5.0 之前的形态未实测。


5.0 的插件改动有 14 条，但哪条对你有影响，取决于 plugins 目录里装了什么。bin/plugin 改名 bin/elasticsearch-plugin、插件 zip 必须带顶层 elasticsearch/ 目录、isolated 选项删除（每个插件独立 classloader）、site 插件删除、multicast 插件删除、Cloud AWS/Azure/GCE 拆分改名，另外有一批插件接口从 onModule(XxxModule) 换成 XxxPlugin。本文按 v5.6.16 逐条列出，并标出哪些是配置改动、哪些要重写插件。

考古｜ES 5.0 插件改动要先列已装插件再对照，site 插件下线、bin/plugin 改名

5.0 的插件改动有 14 条，但哪条对你有影响，取决于 plugins 目录里装了什么。

官方产研

云计算

后端

大数据

Elasticsearch 5.0插件系统14项重大变更详解，涵盖命令行工具改名、插件包结构要求、classloader机制调整及多款插件存废。重点解析XxxPlugin接口替换onModule、SearchPlugin新API等开发者必读内容，附带自研插件评估与升级排查清单，并针对5.6.16版本进行实操验证。

命令行工具

Elasticsearch 

代码解释

Java

腾讯云双十一大促

bigdata-class

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

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

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

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

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

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

社区新版编辑器体验调研

考古｜ES 5.0 插件改动要先列已装插件再对照，site 插件下线、bin/plugin 改名-腾讯云开发者社区-腾讯云

考古｜ES 5.0 插件改动要先列已装插件再对照，site 插件下线、bin/plugin 改名

考古｜ES 5.0 插件改动要先列已装插件再对照，site 插件下线、bin/plugin 改名

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐