Spring Boot 集成 Meilisearch:Windows 与 Linux 两套环境实录
业务里要做「模糊搜 + 秒回」,MySQL 的 LIKE %x% 顶不住了,上了 Meilisearch。这篇记录 Windows 本地调试和 Linux 服务器部署两套环境,以及接入 Spring Boot 时踩的坑。

一、它是什么、适合什么
Meilisearch 是 Rust 写的轻量搜索引擎,特点:
- 开箱即用,单二进制,内存占用小(几百 MB 能跑)
- 默认就带拼写容错和前缀搜索,中文需要额外配分词
- 不支持复杂的聚合分析(那是 ES 的活)
适合:站内搜索、后台列表检索、商品名模糊匹配。
不适合:日志分析、需要复杂 query DSL 的场景。
二、Windows 本地
直接下 zip,解压运行:
1 | .\meilisearch.exe --master-key "dev_master_key_123456" --db-path "D:\data\meili" --http-addr 127.0.0.1:7700 |
持久化一定加 --db-path,否则重启数据全丢。--master-key 少于 16 字节会直接拒绝启动,这是硬性要求。
验证:
1 | curl -H "Authorization: Bearer dev_master_key_123456" http://127.0.0.1:7700/health |
三、Linux / Docker
1 | # docker-compose.yml |
两个「必须」:
- 端口绑
127.0.0.1,外面套 Nginx 反代,别裸奔 7700 MEILI_ENV=production时没配 master key 会拒绝启动
四、Spring Boot 接入
pom.xml:
1 | <dependency> |
配置:
1 | meili: |
1 |
|
写入文档:
1 | public void upsert(Article a) throws Exception { |
搜索:
1 | public List<Article> search(String kw, int page, int size) throws Exception { |
五、中文分词
Meilisearch 自带的是按空格切词,中文整段会被当成一个词。两个可选方案:
- 用
charabia的 CJK 支持(新版本默认已含,效果一般但够用) - 自己在入库前做二元切分,把「微信支付」写成「微信 信支 支付」塞进一个
contentTokenized字段专门给搜索用
我选的是第二种,简单可靠:
1 | String tokenize(String s) { |
六、踩坑清单
| 现象 | 原因 | 处理 |
|---|---|---|
| 启动报 master key 太短 | key < 16 字节 | 换长的 |
| 重启后索引没了 | 没挂 --db-path / volume |
持久化目录 |
| 401 unauthorized | header 少了 Bearer 前缀 |
检查 Authorization |
| 搜索结果总是空 | 字段没加进 searchableAttributes | 更新 settings |
| 中文搜不到 | 没做分词 | 二元切分或 charabia |
| 写入后立刻搜不到 | 索引是异步的 | 查 updateSettings 返回的 task,或前端加 100ms 缓冲 |
最后一条最坑:addDocuments 返回 TaskInfo,任务状态 enqueued → processing → succeeded。想在源码里「写完立刻查」就得轮询 task:
1 | TaskInfo info = index.addDocuments(json, "id"); |
七、数据同步策略
不要每次搜索都查库,也不要指望实时一致:
- 写库时发消息(MQ / Spring Event),消费者更新 Meilisearch
- 失败补偿:定时任务扫
sync_failed表重推 - 全量重建:提供
/admin/index/rebuild接口,先建临时索引再 swap,保证线上不空窗
小结
- Windows 调试记得
--db-path,Linux 用 compose +127.0.0.1绑定 - master key ≥ 16 字节,生产环境必配
- 中文要么二元切分,要么靠 charabia,别指望默认
- 索引是异步的,写完要等 task
- 同步走消息 + 补偿任务,别做成强一致
写完这篇,站内搜索从「查不到」变成「查得快」,也算值了。
本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 Woals'Blog!



