文档中心

云搜索服务

自定义插件

自定义插件安装异常处理方案

本文介绍在使用自定义插件时，出现上传失败、安装卡住或者卸载卡住等问题的排查与解决方法。

插件上传失败

插件包的通用要求如下：

插件包名和插件名是有区别的，包名指上传的 ZIP 文件名，插件名是从 ZIP 包中的描述文件 plugin-descriptor.properties 中提取出来的。出现插件上传失败可能的原因如下。

问题类型	常见原因	解决方法
与系统或者自定义插件名重名	系统不支持上传同名的插件。	如果与系统插件重名，可以直接使用系统插件。如果与自定义插件重名，确认是否为误传。如果是升级自定义插件，需要先卸载并删除当前自定义插件，再上传高版本的同名插件。
与实例版本不匹配	插件指定的 Elasticsearch 版本与云搜索实例的版本不匹配。	确认插件声明的 Elasticsearch 版本与云搜索实例是否一致。如果版本不一致，请更新插件并在本地同版本 Elasticsearch 服务安装成功后，再上传。
缺少描述文件	描述文件plugin-descriptor.properties不存在或者没有位于 ZIP 解压后的根目录下。	重新打包一个拥有正确目录的 ZIP 插件包，该 ZIP 包解压后根目录下应出现描述文件和 JAR 文件。
安全问题	插件中定义了操作文件、网络等敏感类权限，导致权限过大被拒绝。	查看插件plugin-security.policy中的权限定义，将相关敏感权限进行删除。如需了解插件安全文件的更多信息，请参见插件安全文件（plugin-security.policy）。

注意

在云搜索服务实例安装插件会触发集群重启，如果插件存在代码缺陷，将会导致节点安装后启动失败，同时影响集群的稳定性。

任何需要上传并安装到云搜索服务实例中的自定义插件，都需要先在本地自建的 Elasticsearch 服务中进行安装测试，只有安装测试通过后的插件才可以上传并安装到云搜索服务实例。

在本地安装插件的命令为：./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip

插件长时间处于“安装中”状态

插件长时间处于安装中状态，可能的原因如下：

说明

强烈建议您先在自建环境中对插件进行安装测试，测试验证无误后，再上传到云搜索服务实例中进行安装。如果已经发生因插件缺陷造成云搜索服务实例启动失败，请联系技术支持。

插件长时间处于“卸载中”状态

插件长时间处于卸载中状态，可能原因如下：

说明

强烈建议您先确认待卸载插件没有任何从索引使用后，再进行卸载操作。如果因为卸载正被使用的插件而导致集群状态异常，请联系技术支持。

最近更新时间：2026.03.25 17:29:45

这个页面对您有帮助吗？

有用

无用