Meilisearch：轻量极速全文搜索引擎自托管部署与使用指南

Meilisearch 是一款用 Rust 编写的开源搜索引擎，主打「闪电般」的搜索体验：输入即得（search-as-you-type）、默认在 50 毫秒内返回结果，并自带容错纠错、分词、过滤、分面与地理位置搜索等能力。它以单二进制或 Docker 镜像分发，一条命令即可跑起来，非常适合给自己的网站、应用或内部系统补上一个 relevance 很高的站内搜索框。

一、项目官方信息

Meilisearch 同时提供托管版 Meilisearch Cloud 与自托管版，二者使用同一套引擎和同一套 RESTful API，可以先在本地跑通，再平滑迁移到云端。本文聚焦社区版的自托管部署。

二、官方图片

下面是 Meilisearch 官方仓库 README 中的 Logo 与生态、演示截图。

Meilisearch 官方对接了几乎所有主流语言与框架的 SDK（React、Rails、Go、Rust、PHP 等）：

官方在线演示（电影检索 where2watch）的实时搜索效果：

三、环境要求

• 操作系统：Linux（x86_64 / ARM64）、macOS、Windows 均可；生产推荐 64 位 Linux。
• 运行方式二选一：
• Docker：安装 Docker Engine（任意较新稳定版即可），能拉取 getmeili/meilisearch 镜像；
• 原生二进制：通过官方一键脚本下载，无需额外依赖。
• 资源：单二进制内存占用极低，日常测试与中小数据集 1 核 512MB 起步即可；生产按数据规模扩容。
• 网络：服务器需放行 TCP 7700 端口（若仅本机调用可不对外暴露）。
• 数据持久化：务必挂载数据目录，否则容器删除后数据丢失。

四、完整部署步骤

方式 A：Docker 一键启动（推荐）

官方 README 给出的最小启动命令如下，映射本机 7700 端口，并把当前目录下的 meili_data 挂载进容器用于持久化数据：

docker run -it --rm \
  -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest

逐行说明：

• -it：以交互模式前台运行，便于直接看到启动日志；
• --rm：容器停止后自动清理（生产环境一般去掉它，改为 -d 后台常驻）；
• -p 7700:7700：把容器的 7700 端口映射到宿主机 7700；
• -v $(pwd)/meili_data:/meili_data：把宿主机当前目录的 meili_data 挂载到容器内数据目录，保证索引数据落盘；
• getmeili/meilisearch:latest：官方镜像。

生产后台常驻版本（去掉 --rm，加 -d，并设置主密钥保护接口）：

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:latest \
  meilisearch --master-key="请改成一串足够随机的长密钥"

加了 --master-key 后，所有写操作与敏感读操作都需要携带 API Key 才能访问；若不设置 master key，实例以「开发模式」运行，接口完全开放，仅适合本机测试。

方式 B：原生二进制安装

官方提供一键安装脚本，会自动识别平台并下载对应版本：

curl -L https://install.meilisearch.com | sh

脚本执行完成后，当前目录会出现可执行文件 meilisearch，直接运行即可启动默认实例：

./meilisearch

启动后控制台会打印类似 Server is listening on http://127.0.0.1:7700 的信息。指定端口与数据目录的常见启动参数：

./meilisearch --http-port=7700 --db-path=./meili_data --master-key="请改成随机长密钥"

验证服务是否就绪

启动成功后，用 curl 访问健康检查接口：

curl http://127.0.0.1:7700/health

正常会返回：

{"status":"available"}

五、使用方法

1. 创建索引并写入文档

Meilisearch 以「索引（index）」组织数据，下面向名为 movies 的索引批量写入三条电影文档（对应官方 README 示例）：

curl -X POST "http://127.0.0.1:7700/indexes/movies/documents" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer 你的APIKey" \
  --data-binary '[
    { "id": 1, "title": "Carol", "genres": ["Romance", "Drama"] },
    { "id": 2, "title": "Wonder Woman", "genres": ["Action", "Adventure"] },
    { "id": 3, "title": "Life of Pi", "genres": ["Adventure", "Drama"] }
  ]'

说明：如果你设置了 --master-key，请求头必须带 Authorization: Bearer <API Key>；开发模式（未设 master key）可省略。Meilisearch 的写入是异步的，接口会立刻返回一个任务 uid，需要稍等片刻索引完成后才能搜到。

2. 执行搜索（含容错纠错）

curl -X POST "http://127.0.0.1:7700/indexes/movies/search" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer 你的APIKey" \
  --data-binary '{ "q": "wondre woman" }'

注意查询词里故意把 Wonder 拼错成了 wondre，Meilisearch 依然能正确返回《Wonder Woman》——这就是它内置的 typo tolerance（容错）能力。如果搜索结果为空，多半是索引还没建完，稍等几秒重试即可。

3. 拿到 API Key

设置了 master key 后，可通过密钥管理接口查看可用的 API Key（生产环境建议区分「可搜索只读 key」与「管理 key」）：

curl http://127.0.0.1:7700/keys -H "Authorization: Bearer 你的master-key"

4. 接入应用

官方为 JavaScript、Python、PHP、Ruby、Go、Rust、React 等都提供了 SDK 与现成的前端搜索框组件 Instant Meilisearch，安装对应 SDK 后用上面的 URL 与 API Key 初始化客户端即可，不必手写 HTTP 调用。

六、常见问题 FAQ

Q1：为什么刚写入文档立刻搜索，结果是空的？ Meilisearch 的索引是异步构建的。写入接口会返回一个任务（task）对象，你需要轮询任务状态（GET /tasks/{uid}）或稍等几秒，待任务完成后再搜索。

Q2：启动后接口不需要密码就能访问，正常吗？ 如果你没有传 --master-key，实例默认以开发模式运行，7700 端口对任何人开放。生产环境务必通过 --master-key 或环境变量 MEILI_MASTER_KEY 设置主密钥，并在防火墙/反代层只放行可信来源。

Q3：容器重启后数据没了？ 说明没有正确挂载数据目录。请确认 -v 挂载把宿主机目录映射到了容器内的 /meili_data，且宿主机目录有读写权限。

Q4：和 Elasticsearch / Algolia / Typesense 比有什么区别？ Meilisearch 单二进制、开箱即用，默认相关性就很强，运维成本远低于 Elasticsearch；它面向「快速上线一个好用的搜索框」场景，而非海量数据的复杂分析检索。官方文档提供了与 Algolia、Elasticsearch、Typesense、Pinecone 等的逐项对比。

Q5：能不能部署在欧盟 / 自己的服务器上？ 可以自托管在任意位置；官方托管版 Meilisearch Cloud 还提供法兰克福、巴黎等 EU 区域。自托管社区版完全在你自己的基础设施上运行。

Q6：Meilisearch 能配合 AI 代理 / RAG 使用吗？ 可以。它支持混合搜索与语义搜索、对话式搜索，内置原生 MCP server（/mcp 路由，实验性），并可作为 LangChain 的向量存储。

七、跳转链接

• GitHub 仓库：https://github.com/meilisearch/meilisearch
• 官方网站与文档：https://www.meilisearch.com/docs
• 发布版本与二进制：https://github.com/meilisearch/meilisearch/releases