OpenSearch 容器反覆重啟：IK 插件版本與 OpenSearch 版本不匹配

給 OpenSearch 裝 IK 中文分詞插件，鏡像構建好了，容器一啟動就開始重啟循環。原因是插件版本和 OpenSearch 版本沒對齊：IK 是 INFINI Labs 的第三方插件，解壓安裝時會把自身版本寫進 plugin-descriptor.properties，OpenSearch 啟動時逐一校驗，發現插件聲明的版本和集群版本不一致，就直接拒絕加載、拋例外退出，進程反覆重啟。插件版本必須與 OpenSearch 版本完全一致（major.minor.patch 都對上），重新從匹配版本的 URL 裝一次就恢復。

Issue & Env（案發現場與環境）

觸發場景：按教程在官方鏡像基礎上構建「帶 IK 插件的自定義鏡像」，docker run 起容器後，容器狀態一直在 restarting，docker ps 裡看不到正常運行；docker logs 亮出插件版本不匹配的堆疊。
環境：OpenSearch 2.19.0（鏡像 opensearchproject/opensearch:2.19.0），docker run 單節點，macOS / Linux / Docker 均可復現。
前置聲明：適用物件是任何「自己 build 鏡像裝 IK 插件」的讀者；用官方預裝鏡像或託管服務（Alibaba Cloud 等）時不存在這個坑，因為平臺幫你對齊了版本。
關鍵區分：報錯發生在節點進程啟動階段，不是建索引、搜詞階段。這時候 9200 還起不來，連健康檢查都過不了。

StackTrace（堆疊日誌）

docker ps 看到容器反覆重啟，直接看日誌：

docker logs opensearch-ik

日誌末尾是 OpenSearch 的校驗例外：

[2026-10-27T08:12:41,103][ERROR][o.o.b.OpenSearchUncaughtExceptionHandler] ...
java.lang.IllegalArgumentException: Plugin [analysis-ik] is incompatible with the version of this OpenSearch node. OpenSearch node version: 2.19.0, plugin version: 2.18.0
	at org.opensearch.plugins.PluginsService.checkForAppropriateBinaries(PluginsService.java:1155) ~[opensearch-2.19.0.jar:2.19.0]
	at org.opensearch.plugins.PluginsService.checkVersionCompatibility(PluginsService.java:1130) ~[opensearch-2.19.0.jar:2.19.0]
	at org.opensearch.plugins.PluginsService.createPlugins(PluginsService.java:578) ~[opensearch-2.19.0.jar:2.19.0]

堆疊裡的一行點明瞭根因：

OpenSearch node version: 2.19.0, plugin version: 2.18.0

Reproduce（復現程式碼）

最小復現——故意讓插件版本和節點版本錯開一個次版本：

mkdir -p opensearch-ik && cd opensearch-ik
cat > Dockerfile <<'EOF'
FROM opensearchproject/opensearch:2.19.0
# 错：写成 2.18.0，与 OpenSearch 2.19.0 不匹配
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch \
    https://get.infini.cloud/opensearch/analysis-ik/2.18.0
EOF
docker build -t opensearch-with-ik:2.19.0 .

docker run -d -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=Devfix@2026" \
  --name opensearch-ik \
  opensearch-with-ik:2.19.0

docker ps          # 状态是 restarting，不是 Up
docker logs opensearch-ik
# 末尾：Plugin [analysis-ik] is incompatible with the version of this OpenSearch node.
#       OpenSearch node version: 2.19.0, plugin version: 2.18.0

Root Cause（根因分析）

插件是第三方元件，版本不在 OpenSearch 的自動更新範圍內

IK 分析器是 INFINI Labs 獨立維護的插件，不會隨 OpenSearch 發版自動升級。它每個版本只面向特定的 OpenSearch major.minor.patch 編譯，裝的時候把目標版本寫進 jar 裡的 plugin-descriptor.properties。

OpenSearch 啟動時做「版本兼容校驗」

OpenSearch 啟動會掃 plugins 目錄，逐個插件讀 descriptor，和節點自身版本比對（PluginsService.checkVersionCompatibility），不一致就拋 IllegalArgumentException 並拒絕啟動。所以版本一旦不匹配，表現為進程根本起不來，而不是「能起但詞切不好」。

版本完全一致的三段都必須對上

OpenSearch 的版本是 major.minor.patch，IK 插件必須三個段全部一致：

2.18.0 配 2.18.0 的 OpenSearch；
2.19.0 配 2.19.0 的 OpenSearch；
只差一個 patch（比如 2.19.0 vs 2.19.1）同樣報不兼容。

這也是社區裡排在第一位的 IK 安裝踩坑點。

The Fix（解決方案）

第一步：確認裝的是匹配版本，而不是一個佔位 URL

最常見的錯法是從網上覆制了一個相似但版本不對的安裝 URL。對照你 FROM 的鏡像版本，去官方穩定版清單找到完全一致的版本號：

curl -s https://release.infinilabs.com/analysis-ik/stable/

在清單裡挑 opensearch-analysis-ik-<你的版本>.zip，而不是隨手拿一個。

第二步：改回匹配版本重裝

把 Dockerfile 裡的插件版本改回和 OpenSearch 完全一致：

FROM opensearchproject/opensearch:2.19.0
RUN /usr/share/opensearch/bin/opensearch-plugin install --batch \
    https://get.infini.cloud/opensearch/analysis-ik/2.19.0

如果拿不準某個版本的下載地址，可以直接從 stable 清單頁下載對應 .zip，再本地安裝：

RUN /usr/share/opensearch/bin/opensearch-plugin install --batch \
    /tmp/opensearch-analysis-ik-2.19.0.zip

第三步：重建鏡像並啟動，驗證插件被加載

docker build -t opensearch-with-ik:2.19.0 .
docker rm -f opensearch-ik
docker run -d -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=Devfix@2026" \
  --name opensearch-ik \
  opensearch-with-ik:2.19.0
sleep 30   # JVM 启动要几十秒

curl -sk -u admin:Devfix@2026 "https://localhost:9200/_cat/plugins?v"
# name       component    version
# a937e...   analysis-ik  2.19.0

version 那列和節點版本對齊、analysis-ik 出現在列表裡，就說明插件正常加載了，容器不再重啟。

注意事項

升級 OpenSearch 主版本時，IK 插件也要跟著換，別沿用舊鏡像裡的插件。
版本對不上時 OpenSearch 一行都不會給你「服務可用」，先排查 Dockerfile 寫的插件 URL，再去查日誌裡的版本號。
完整的中文分詞搭建流程，見從零跑通 OpenSearch 中文搜索。

References（參考來源）

analysis-ik — INFINI Labs 官方倉庫github
analysis-ik 官方下載頁（stable 版本清單）infinilabs
Managing OpenSearch plugins — OpenSearch 官方文檔opensearch-docs
Install OpenSearch in a container — OpenSearch 官方文檔opensearch-docs