业务里要做「模糊搜 + 秒回」,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
2
3
4
5
6
7
8
9
10
11
12
13
# docker-compose.yml
services:
meilisearch:
image: getmeili/meilisearch:v1.10
ports:
- "127.0.0.1:7700:7700" # 只给本机,不直接对外
environment:
MEILI_MASTER_KEY: ${MEILI_MASTER_KEY}
MEILI_ENV: production
MEILI_NO_ANALYTICS: "true"
volumes:
- ./data/meili:/meili_data
restart: unless-stopped

两个「必须」:

  1. 端口绑 127.0.0.1,外面套 Nginx 反代,别裸奔 7700
  2. MEILI_ENV=production 时没配 master key 会拒绝启动

四、Spring Boot 接入

pom.xml:

1
2
3
4
5
<dependency>
<groupId>com.meilisearch.sdk</groupId>
<artifactId>meilisearch-java</artifactId>
<version>0.11.6</version>
</dependency>

配置:

1
2
3
4
meili:
host: http://127.0.0.1:7700
api-key: ${MEILI_MASTER_KEY}
index: article
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Configuration
public class MeiliConfig {

@Bean
public Client meiliClient(@Value("${meili.host}") String host,
@Value("${meili.api-key}") String key) {
return new Client(new Config(host, key));
}

@Bean
public Index articleIndex(Client client, @Value("${meili.index}") String name) throws Exception {
try {
return client.getIndex(name);
} catch (MeiliSearchApiException e) {
// 索引不存在时先建,再配可检索字段
Index index = client.index(name);
index.updateSearchableAttributesSettings(
new Settings().setSearchableAttributes(
new String[]{"title", "summary", "content"}));
return index;
}
}
}

写入文档:

1
2
3
4
5
6
7
8
9
10
public void upsert(Article a) throws Exception {
Map<String, Object> doc = Map.of(
"id", a.getId(),
"title", a.getTitle(),
"summary", a.getSummary(),
"content", a.getContent(),
"createdAt", a.getCreatedAt().toEpochMilli()
);
index.addDocuments(new Gson().toJson(new Object[]{doc}), "id");
}

搜索:

1
2
3
4
5
6
7
8
9
10
public List<Article> search(String kw, int page, int size) throws Exception {
SearchRequest req = SearchRequest.builder()
.q(kw)
.limit(size)
.offset(page * size)
.attributesToHighlight(new String[]{"title", "summary"})
.build();
SearchResult<Article> r = index.search(req, Article.class);
return r.getHits();
}

五、中文分词

Meilisearch 自带的是按空格切词,中文整段会被当成一个词。两个可选方案:

  1. 用 charabia 的 CJK 支持(新版本默认已含,效果一般但够用)
  2. 自己在入库前做二元切分,把「微信支付」写成「微信 信支 支付」塞进一个 contentTokenized 字段专门给搜索用

我选的是第二种,简单可靠:

1
2
3
4
5
6
7
String tokenize(String s) {
StringBuilder sb = new StringBuilder();
for (int i = 0; i < s.length() - 1; i++) {
sb.append(s, i, i + 2).append(' ');
}
return sb.toString();
}

六、踩坑清单

现象 原因 处理
启动报 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
2
TaskInfo info = index.addDocuments(json, "id");
client.waitForTask(info.getTaskUid(), 5_000, 50); // 最多 5 秒,50ms 一查

七、数据同步策略

不要每次搜索都查库,也不要指望实时一致:

  • 写库时发消息(MQ / Spring Event),消费者更新 Meilisearch
  • 失败补偿:定时任务扫 sync_failed 表重推
  • 全量重建:提供 /admin/index/rebuild 接口,先建临时索引再 swap,保证线上不空窗

小结

  • Windows 调试记得 --db-path,Linux 用 compose + 127.0.0.1 绑定
  • master key ≥ 16 字节,生产环境必配
  • 中文要么二元切分,要么靠 charabia,别指望默认
  • 索引是异步的,写完要等 task
  • 同步走消息 + 补偿任务,别做成强一致

写完这篇,站内搜索从「查不到」变成「查得快」,也算值了。