本文介绍在安装自定义插件时,出现控制台报错、变更卡住、无法验证通过等问题的排查与解决方法。

问题现象

上传与安装自定义插件时,出现控制台报错、变更卡住、无法验证通过或其他异常问题。

通用解决方案

在上传与安装自定义插件前,需要先在自建环境中,将插件放入Elasticsearch集群安装目录中的plugins目录下,然后重启集群加载插件,最后通过GET /_cat/plugins?v命令,获取插件安装成功的信息。在安装插件时,需要注意:
  • 不允许上传与阿里云Elasticsearch的系统默认插件同名的插件。
    如果您要上传同名的系统插件,需要先修改待上传的插件的名称。对于pingyin、IK等插件,在自建环境测试安装时,需要先删除对应的原生插件,然后手动修改插件名称,最后通过原生插件安装命令在自建环境中进行安装验证,验证无误后,即可上传至阿里云Elasticsearch进行安装。
    ./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip
  • 任何上传的插件都需要在自建Elasticsearch中,通过原生插件安装命令安装通过,才可上传至阿里云Elasticsearch进行安装。
    ./bin/elasticsearch-plugin install file:///path-to-your-plugins.zip
  • 热更新只支持IK和analysis-aliws插件。
  • 插件的安全策略文件中包含了增删改查的权限时,阿里云Elasticsearch不支持上传该类插件。例如:elasticsearch-analysis-hanlp插件。
  • 对于Logstash插件和Kibana插件,不支持安装自定义插件。如果需要安装,建议在自建环境中,通过原生插件安装命令安装成功后,再提交工单给阿里云Elasticsearch技术支持工程师。
    说明 对于符合规则的插件,插件安装后,您可以在主日志上查看插件日志。

控制台报错

  • 问题原因

    插件不符合规则,导致控制台验证失败。

  • 解决方法

    参见通用解决方案,修改插件信息。例如重命名插件、修改插件的配置文件等。

变更卡住

导致该问题的原因有两个,需要按照以下步骤排查解决:
  1. 确认是否插件太大(默认小于50 MB)。

    插件太大,会出现安装过程中插件加载慢的情况。出现该情况,需要中断变更,删除该插件,然后修改插件配置(例如减少分词类插件的分词),确认插件小于50 MB后,再重新上传安装。

  2. 确认是否有数据节点在写入数据。
    • 是。需要耐心等待,说明上传过程属于业务高峰期,导致节点安装过程变更缓慢。
    • 否。需要中断变更,等待中断变更结束后,手动将该插件从自定义插件中删除,然后重新验证插件是否可用。

插件无法通过验证

导致该问题的常见原因以及解决方法请参见下表。

问题分类 常见原因 解决方法
版本不一致 插件指定的Elasticsearch版本与当前阿里云Elasticsearch实例版本不一致,导致版本不匹配。 对于某些插件(例如jieba分词),如果插件指定的Elasticsearch版本与当前阿里云Elasticsearch实例版本不一致,则需要手动修改插件指定的Elasticsearch版本号,使其与当前阿里云Elasticsearch实例版本号一致,再重新打包插件。确保版本一致的具体步骤,请参见常见问题
缺少或无法找到插件描述文件plugin-descriptor.properties 目录层级解压后多了一层目录,导致系统无法找到插件描述文件plugin-descriptor.properties。 解压插件包后,检查目录层级是否多一层级。例如:在本地电脑使用WinRAR解压,选择解压到当前文件夹,解压后的文件直接是JAR文件,则为正常目录层级。如果JAR文件外层多一层级目录,则为非正常目录层级,此时需要按照正确的方法重新打包,详情请参见下面的“正确的打包方法”。
插件打包有问题 没有按照规定进行打包,导致插件打包有问题。
正确的打包方法:
  • 借助WinRAR工具:选择JAR相关文件,右键单击添加到压缩文件,压缩文件格式为zip,压缩文件名以elasticsearch开头,且必须加对应elasticsearch版本号,例如:elasticsearch-analysis-ik-6.7.0.zip。
  • zip工具:按照递归压缩方式进行打包,即执行zip -r命令进行zip压缩即可。
插件存在安全问题 插件中定义了权限类敏感信息,导致插件存在安全问题。 不支持上传存在安全隐患的插件,解决方法请参见通用解决方案
说明 确认版本号、插件描述文档属性(plugin-descriptor.properties)、打包方式以及安全性均没有问题后,建议先将插件包移动至plugins目录下,在本地测试环境中通过./bin/elasticsearch-plugins install命令进行安装测试。如果测试异常,需要通过异常说明重新测试,测试成功后再上传。