建索引时给
title这类字段指定analyzer: ik_max_word，请求返回 400，错误正文是analyzer [ik_max_word] not found for field [title]。报这个错说明 OpenSearch 进程里根本没有ik_max_word这个分析器——IK 插件没被加载起来。常见三个原因：插件压根没装、装是装了但版本和 OpenSearch 不匹配（启动时校验失败、节点反复重启）、装了之后 OpenSearch 没重启生效。先用GET _cat/plugins看analysis-ik在不在列表里，不在就先把这个解决，再回来建索引。
Issue & Env（案发现场与环境）
- 触发场景：参照教程想建一个带中文分词的索引
books_zh，mapping 里写了"analyzer": "ik_max_word"，PUT 直接弹回 400，服务端报找不到这个分析器。 - 环境：OpenSearch
2.19.0，Docker 单节点；curl 调 REST API，-u admin:Devfix@2026走 HTTPS。 - 前置声明：这个错和「
_analyze报unknown analyzer」是同一根因的两面——都是分析器没注册进节点。 - 关键区分：报错发生在 建索引/写 mapping 阶段，不是查询阶段。它说明插件层面有问题，而不是请求参数写错了。
StackTrace（堆栈日志）
完整响应（HTTP 400，JSON 根因原样保留）：
{
"error": {
"root_cause": [
{
"type": "mapper_parsing_exception",
"reason": "analyzer [ik_max_word] not found for field [title]"
}
],
"type": "mapper_parsing_exception",
"reason": "analyzer [ik_max_word] not found for field [title]"
},
"status": 400
}Reproduce（复现代码）
在没装 IK 插件（或用没有 IK 的官方 opensearchproject/opensearch 镜像）时直接建索引：
curl -sk -u admin:Devfix@2026 -X PUT "https://localhost:9200/books_zh?pretty" \
-H "Content-Type: application/json" \
-d '{
"settings": { "index.number_of_replicas": 0 },
"mappings": {
"properties": {
"title": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" }
}
}
}'返回：
{
"error" : {
"root_cause" : [ {
"type" : "mapper_parsing_exception",
"reason" : "analyzer [ik_max_word] not found for field [title]"
} ],
"type" : "mapper_parsing_exception",
"reason" : "analyzer [ik_max_word] not found for field [title]"
},
"status" : 400
}Root Cause（根因分析）
ik_max_word 不是内置分析器
OpenSearch 内置一大堆分析器（standard、simple、keyword 等），但没有任何中文分析器。ik_max_word、ik_smart 都由 INFINI Labs 的 analysis-ik 插件在启动时注册到节点上。任何分析器在引用前必须已经存在，而 IK 分析器的存在前提就是：插件被正常加载。
插件没被加载的三种常见路径
- 没装：跑的是纯官方镜像，从没安装 analysis-ik。这种最直接，
_cat/plugins里没有analysis-ik。 - 装了但版本不匹配：插件版本和 OpenSearch 版本对不上，节点启动时校验失败、进程反复重启，
9200是能连（在重启间隙）但插件没注册成功。表现和「没装」一样——_cat/plugins缺analysis-ik，但前面的坑是插件版本不匹配导致容器反复重启。 - 装完没重启：极少数用
install后没等节点重启生效的场景（插件加载发生在进程启动阶段，真正进到运行态前）。
关键：先用 _cat/plugins 定位，而不是反复改 mapping
错误信息已经精确告诉你是「找不到分析器」，不是在 index 或字段层面出错。改字段名、改 analyzer 写法都没用——只要 analysis-ik 不在节点插件列表里，再怎么改 mapping 都会被同一个 400 弹回来。
The Fix（解决方案）
第一步：确认插件真的在列表里
curl -sk -u admin:Devfix@2026 "https://localhost:9200/_cat/plugins?v"
# name component version
# a937e... analysis-ik 2.19.0第二步：不在列表，就用带 IK 的镜像重建
如果 analysis-ik 不在列表，说明当前容器没有 IK。做法是走从零跑通 OpenSearch 中文搜索第一步，构建带插件的镜像再起容器：
mkdir -p opensearch-ik && cd opensearch-ik
cat > Dockerfile <<'EOF'
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
EOF
docker build -t opensearch-with-ik:2.19.0 .插件版本必须和 OpenSearch 版本完全一致，否则会落入版本不匹配那个坑。
第三步：重建容器，再回来建索引
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
# 插件就位后再 PUT 索引
curl -sk -u admin:Devfix@2026 -X PUT "https://localhost:9200/books_zh?pretty" \
-H "Content-Type: application/json" \
-d '{ "settings": { "index.number_of_replicas": 0 },
"mappings": { "properties": {
"title": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" }
} } }'
# 期望：{"acknowledged":true,"shards_acknowledged":true,"index":"books_zh"}验证修复
# 已经建好的索引，能直接 _analyze 一把，确认分析器真的可用
curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_analyze?pretty" \
-H "Content-Type: application/json" \
-d '{ "analyzer": "ik_max_word", "text": "中华人民共和国国歌" }'
# 期望返回一组中文 token，而不是 404 / 400注意事项
- 建索引和
_analyze报的「找不到分析器」是同一回事，统一用_cat/plugins一根线索查到底。 - 用直接下载
.zip安装时，确认 zip 是 analysis-ik 而不是别的插件的包，装错插件一样会报这个错。
References（参考来源）
- analysis-ik — INFINI Labs 官方仓库github
- Managing OpenSearch plugins — OpenSearch 官方文档opensearch-docs