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