本地搜索与索引服务的部署、配置和查询坑，目前覆盖 Meilisearch，后续扩展到更多检索技术。
master key、生产模式、环境变量与访问控制
OpenSearch demo security 默认对 9200 启用 TLS，用 http:// 访问时服务端握手失败直接断连，curl 报 (52) Empty reply from server。改用 https 加 -k 和凭据即可恢复。
production 模式启动 Meilisearch 未设 MEILI_MASTER_KEY 时进程直接 abort，根因是 production 强制要求 ≥16 字节 master key，设上即可。
primary key、文档添加、批量导入与索引设置
_bulk 报 400 illegal_argument_exception：Malformed action/metadata line 是文档 JSON 被换行拆开，must be terminated by a newline 是结尾缺换行。根因是 NDJSON 逐行成帧，行边界即记录边界。
POST 文档时未传 primaryKey 且文档无以 id 结尾的字段，Meilisearch 报 primary key inference failed，根因是自动推断机制找不到候选字段，需显式指定 primaryKey。
taskUid、任务状态轮询与等待
filterableAttributes、排序、分面与查询语法
搜索带 facets 参数，某分面属性在 facetDistribution 中缺失或为空，且无任何报错，根因是该属性未加入 filterableAttributes 被静默忽略——与 filter 未声明报 invalid_search_filter 截然不同。解法：先把属性声明为 filterable 再搜索。
POST /indexes/{uid}/facet-search 做分面值自动补全时，facetName 不在 filterableAttributes 列表（拼错或忘声明）返回 400 invalid_facet_search_facet_name；facetName 参数缺失则报 missing_facet_search_facet_name。解法：先声明 filterableAttributes 并等任务完成，再核对 facetName 拼写。
filter 字符串中 AND 优先级高于 OR，`A OR B AND C` 被解析为 `A OR (B AND C)`，结果与预期不符且不报错。跨条件组合必须显式加括号：`(A OR B) AND C`；官方规范 BNF 可交叉验证。
同一请求同时传 filter 与 sort 时，排序属性未在 sortableAttributes 声明，返回 400 invalid_search_sort。filter 用 filterableAttributes、sort 用 sortableAttributes，两套列表独立——filter 正常不代表能 sort。解法：先声明 sortableAttributes 并等任务完成。
搜索时传 filter 参数报 invalid_search_filter，根因是属性未在 filterableAttributes 中声明，需先 PUT settings 再搜索。这是有意设计，避免每次搜索遍历全部字段。
近实时搜索、refresh 间隔、translog 与 segment 可见性
green/yellow/red、unassigned 分片、副本分配与集群状态
设置自定义排名规则时沿用旧语法 asc(price)/desc(price)，PUT /settings/ranking-rules 返回 HTTP 400 invalid_settings_ranking_rules。该语法自 v0.22 起废弃，现行写法为 属性名:asc / 属性名:desc；PUT 是全量覆盖，务必把默认规则一起带上。
search body 里的 locales 传了 chinese / cn 这类非法值，返回 400，错误码 invalid_search_locales。locales 只接受 ISO-639 取值，中文合法值是 zh / zho / cmn；且查询侧 locales 优先级高于索引侧 localizedAttributes，写错会覆盖索引设置。
embedder 的 documentTemplate 里用 {{doc.xxx}} 引用了文档中不存在的字段，索引任务整批失败报 template_rendering_error。解法：render-template 先预演、模板加 {% if %} 守卫或只引用真实字段。适用 Meilisearch v1.6+。
混合检索参数 hybrid 里 semanticRatio 超出 0.0-1.0 报 invalid_search_semantic_ratio；embedder 名与 settings 配置不一致报 invalid_search_embedder。二者都是 400。解法：semanticRatio 取 0.0-1.0，embedder 名与配置逐字一致。
userProvided embedder 模式下检索时，带了 vector 却没带 hybrid 参数报 missing_search_hybrid；hybrid 结构/键名写错报 invalid_search_hybrid_query。二者都是 400。解法：vector 与 hybrid 成对出现，hybrid.embedder 名字与 settings 里 embedder 名完全一致。
userProvided embedder 模式下，文档 _vectors 或检索 vector 的维度与 settings 里 embedders.dimensions 不一致，返回 400 invalid_vector_dimensions。常见于换了嵌入模型（如 bge-small 512 维换 bge-base 768 维）但配置没同步。解法：核对模型实际输出维度，同步改 embedder 配置、_vectors、查询向量三处，等设置任务完成后重建文档。
从 v1.15 之前升级上来、库里已有中文数据的索引，如果没重建索引，中文查询和文档会被忽略、搜不到。根因是 v1.15 更换了 Charabia 的中文分词策略，旧索引里的 token 还是老版本切出来的。触发一次 reindex 即可恢复；全新安装 v1.54.3 不受影响。
PUT dictionary、separatorTokens、nonSeparatorTokens、localizedAttributes 等分词设置后立即搜索行为不变，根因是这些都是索引侧设置，PUT 只返回 taskUid，实际是异步 settingsUpdate 任务并会重索引全部文档。任务没 succeeded 就搜索，用的还是旧配置。
