建索引時給
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