自訂外掛程式安裝錯誤的排查與解決方案 - Elasticsearch

本文介紹在安裝自訂外掛程式時，出現控制台報錯、變更卡住、無法驗證通過等問題的排查與解決方案。

問題現象

在上傳與安裝自訂外掛程式時，出現控制台報錯、變更卡住、無法驗證通過或其他異常問題。

通用解決方案

在上傳與安裝自訂外掛程式前，需要先在自建環境中，將外掛程式放入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支援人員工程師。
說明對於符合規則的外掛程式，外掛程式安裝後，您可以在主日誌上查看外掛程式日誌。

控制台報錯

問題原因
外掛程式不符合規則，導致控制台驗證失敗。
解決方案
參見通用解決方案，修改外掛程式資訊。例如重新命名外掛程式、修改外掛程式的設定檔等。

變更卡住

導致該問題的原因有兩個，需要按照以下步驟排查解決：

確認是否外掛程式太大（預設小於50 MB）。
外掛程式太大，會出現安裝過程中外掛程式載入慢的情況。出現該情況，需要中斷變更，刪除該外掛程式，然後修改外掛程式配置（例如減少分詞類外掛程式的分詞），確認外掛程式小於50 MB後，再重新上傳安裝。
確認是否有資料節點在寫入資料。
- 是。需要耐心等待，說明上傳過程屬於業務高峰期，導致節點安裝過程變更緩慢。
- 否。需要中斷變更，等待中斷變更結束後，手動將該外掛程式從自訂外掛程式中刪除，然後重新驗證外掛程式是否可用。

外掛程式無法通過驗證

導致該問題的常見原因以及解決方案請參見下表。

問題分類	常見原因	解決方案
版本不一致	外掛程式指定的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命令進行安裝測試。如果測試異常，需要通過異常說明重新測試，測試成功後再上傳。