Meilisearch 知识 - Weadb Notes

Meilisearch 是一个开源的、基于 Rust 编写的高性能轻量级搜索引擎。相比于 Elasticsearch，它的特点是开箱即用、配置简单，并且对中文支持友好，非常适合中小型项目、电商网站或文档系统的搜索场景。

以下是关于 Meilisearch 的安装、基础配置和日常使用方法的详细说明。

一、安装 Meilisearch

Meilisearch 提供了多种安装方式，其中 Docker 是最推荐、也是最方便的部署手段。

1. 使用 Docker 安装（推荐）

你可以通过一行命令直接启动一个实例：

docker run -itd \
  -p 7700:7700 \
  -v $(pwd)/meili_data:/meili_data \
  getmeili/meilisearch:v1.6 \
  meilisearch --master-key="YOUR_MASTER_KEY_HERE"

参数说明：

-p 7700:7700: 映射服务端口（默认 7700）。
-v $(pwd)/meili_data:/meili_data: 将数据持久化到宿主机的当前目录下。
--master-key: 设置主密钥（Master Key），用于后续 API 调用的安全验证（建议长度不低于 16 字节）。

2. 本地直接运行（以 macOS/Linux 为例）

如果不想使用 Docker，也可以直接下载编译好的二进制文件：

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

# 启动并设置密钥
./meilisearch --master-key="YOUR_MASTER_KEY_HERE"

启动成功后，在浏览器访问 http://localhost:7700，会进入 Meilisearch 自带的 Web 控制台，输入刚才设置的 Master Key 即可进入管理页面。

二、核心概念

在使用之前，需要了解 Meilisearch 的几个核心术语：

Host: 服务地址（如 http://localhost:7700）。
Index（索引）: 相当于数据库中的“表”。用来存放相似类型的数据。
Document（文档）: 相当于表中的“行”，格式为 JSON。每个 Document 必须包含一个主键（通常为 id）。

三、基础使用（基于 REST API）

Meilisearch 的设计完全是 API 驱动的。我们可以直接使用 curl 命令，或者任何 HTTP 工具（如 Postman）来与其交互。

1. 创建索引并导入数据

向指定的 Index 导入数据时，如果该 Index 不存在，Meilisearch 会自动创建它。

我们向名为 books 的索引中添加两条数据：

curl \
  -X POST 'http://localhost:7700/indexes/books/documents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY_HERE' \
  --data-binary '[
    { "id": 1, "title": "三体", "author": "刘慈欣", "genre": "科幻" },
    { "id": 2, "title": "流浪地球", "author": "刘慈欣", "genre": "科幻" },
    { "id": 3, "title": "活着", "author": "余华", "genre": "文学" }
  ]'

注意： 写入操作是异步的。执行上述命令后，API 会立即返回一个 taskUid（任务ID），你可以通过 GET /tasks/<taskUid> 接口查询该任务的执行状态是否为 succeeded。

2. 搜索数据 (Search)

这是最常用的功能。你可以通过 POST 请求向 /indexes/{index_uid}/search 发送检索词：

curl \
  -X POST 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY_HERE' \
  --data-binary '{ "q": "三体" }'

返回结果类似如下格式：

{
  "hits": [
    { "id": 1, "title": "三体", "author": "刘慈欣", "genre": "科幻" }
  ],
  "query": "三体",
  "processingTimeMs": 1,
  "limit": 20,
  "offset": 0,
  "estimatedTotalHits": 1
}

四、进阶配置：过滤、排序与设置

在实际业务中，我们往往需要实现“按分类筛选”或“按时间排序”的功能。默认情况下，Meilisearch 不允许对所有字段进行过滤和排序，你必须显式地进行设置。

1. 配置过滤与排序属性 (Filterable & Sortable)

向 /settings 接口发送配置请求：

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY_HERE' \
  --data-binary '{
    "filterableAttributes": ["genre", "author"],
    "sortableAttributes": ["id"]
  }'

2. 进行带条件和排序的搜索

配置完成后，即可在搜索请求中加入 filter 和 sort 参数：

curl \
  -X POST 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_MASTER_KEY_HERE' \
  --data-binary '{
    "q": "刘慈欣",
    "filter": "genre = 科幻",
    "sort": ["id:desc"]
  }'

五、 SDK 接入（以 JavaScript / Node.js 为例）

在实际业务开发中，我们通常不需要自己拼装 curl 请求，而是使用官方提供的 SDK。

首先安装依赖：

npm install meilisearch

在代码中调用：

import { MeiliSearch } from 'meilisearch';

// 初始化客户端
const client = new MeiliSearch({
  host: 'http://localhost:7700',
  apiKey: 'YOUR_MASTER_KEY_HERE',
});

async function main() {
  const index = client.index('books');

  // 1. 添加文档
  await index.addDocuments([
    { id: 4, title: "白夜行", author: "东野圭吾", genre: "推理" }
  ]);

  // 2. 搜索
  const searchResults = await index.search('东野', {
    limit: 10,
  });

  console.log(searchResults.hits);
}

main();

六、生产环境部署建议

安全权限分级：在实际的前端页面（如网站搜索框）中，绝对不要泄露你的 Master Key。你可以使用 Master Key 请求 /keys 接口，生成一个只读权限的 Default Search API Key 部署在前端。
内存与磁盘占用： Meilisearch 采用 LMDB 键值数据库存储数据，会把文件映射到内存中。建议为服务器保留足够的剩余内存，内存越大，搜索性能越稳定。
备份与恢复：
- Dump: 可以通过 POST /dumps 创建一个与版本无关的数据包，用于数据库版本升级或备份。
- Snapshot: 可以定时生成快照，用于故障快速恢复。

一、 安装 Meilisearch