升级到最新版 Meilisearch

目前，Meilisearch 数据库仅兼容创建它们时使用的 Meilisearch 版本。以下指南将引导您使用 dump（数据转储） 将现有数据库从旧版 Meilisearch 迁移至最新版本。

如果您在 DigitalOcean 或 AWS 等云平台上更新 Meilisearch 实例，请确保可以通过 SSH 连接到您的云实例。根据您连接的用户身份（root、admin 等），可能需要在某些命令前添加 sudo 前缀。

如果迁移到最新版 Meilisearch 需要跳过多个版本，这可能需要修改您的代码库。请参阅我们的版本特定更新警告以获取更多细节。

​

更新 Meilisearch Cloud

登录您的 Meilisearch Cloud 账户并导航至需要更新的项目。

点击目标项目，在页面顶部找到”General settings（常规设置）“部分。

当有新版本 Meilisearch 可用时，您会在”Meilisearch version（版本）“字段旁看到更新按钮。

要更新至最新版本，点击”Update to v.X.Y.Z（更新至 v.X.Y.Z）“按钮。

这将打开包含更新过程详细信息的弹窗。阅读后点击”Update（更新）“，项目”Status（状态）“将从”running（运行中）“变为”updating（更新中）”。

成功更新后，您将收到确认邮件，同时”Status（状态）“会恢复为”running（运行中）“。

​

更新自托管 Meilisearch 实例

您可以通过两种方式更新自托管实例：使用转储文件或不使用转储文件。

​

无转储升级 experimental

当从 Meilisearch >=v1.12 升级到 Meilisearch >=v1.13 时，可以使用无转储升级功能。

​

第一步：创建备份

无转储升级是实验性功能。因此，在极少数情况下可能会部分失败并导致数据库损坏。为防止数据丢失，请创建实例的快照：

curl \
  -X POST 'MEILISEARCH_URL/snapshots'

Meilisearch 将返回一个部分任务对象。使用其 taskUid 监控快照创建状态。任务完成后，继续下一步。

​

第二步：停止 Meilisearch 实例

接下来，停止您的 Meilisearch 实例。

​

第三步：安装新的 Meilisearch 二进制文件

使用以下命令安装最新版本的 Meilisearch：

为 Meilisearch 二进制文件赋予可执行权限:

chmod +x meilisearch

对于云平台，将新的 Meilisearch 二进制文件移动到 /usr/bin 目录:

mv meilisearch /usr/bin/meilisearch

​

步骤 4: 重新启动 Meilisearch

执行以下命令在启动时导入数据转储:

Meilisearch 应该会正常启动并立即创建一个新的 UpgradeDatabase 任务。该任务会被立即处理且无法取消。您可以通过使用 GET /tasks?types=UpgradeDatabase 端点获取其 taskUid，然后查询 GET /tasks/TASK_UID 来跟踪其进度。

在任务处理期间，您可以继续执行搜索查询。您也可以将新任务加入队列。Meilisearch 只会在 UpgradeDatabase 完成后才会处理新任务。

​

回滚更新

如果升级过程耗时过长，或者升级完成后任务状态显示为 failed，您可以取消升级任务。

取消更新任务会自动将数据库回滚至升级开始前的状态。

在使用 --experimental-dumpless-upgrade 参数启动 Meilisearch 后：

1. 取消 databaseUpgrade 任务
2. 如果在任务失败前取消更新，直接跳至下一步。如果更新已失败，请使用目标升级版本的二进制文件重新启动 Meilisearch
3. 等待 Meilisearch 处理您的取消请求
4. 用旧版本的二进制文件替换新版本
5. 重新启动 Meilisearch

如果您要升级到 Meilisearch <= v1.14 版本，则必须从快照重启实例（快照应在步骤1中生成）。之后您可以重试升级，或使用 dump 文件进行升级。您也可以在 Meilisearch 代码库提交 issue。

​

使用 dump 文件升级

​

第一步：导出数据

验证数据库版本

首先通过版本查询接口确认与您数据库兼容的 Meilisearch 版本：

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'Authorization: Bearer API_KEY'

响应示例如下：

{
  "commitSha": "字母数字组合字符串",
  "commitDate": "YYYY-MM-DD时间戳",
  "pkgVersion": "x.y.z"
}

curl \
  -X GET 'http://<your-domain-name>/version' \
  -H 'X-Meili-API-Key: API_KEY'

如果 pkgVersion 为 0.21 或更高版本，可直接跳转至创建 dump 文件。否则请继续下一步。

将所有字段设为可显示属性

当使用低于 v0.21 版本的 Meilisearch 创建 dump 时，所有字段必须被设为可显示才能保存在 dump 中。

首先验证所有属性是否已包含在可显示属性列表中：

# 当你看到 {index_uid} 时，请替换为你索引的唯一 ID
curl \
  -X GET 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'

如果所有索引的响应都是 {'displayedAttributes': '["*"]'}，你可以继续下一步。

如果响应结果不同，请将当前的可显示属性列表保存到文本文件中，然后将可显示属性列表重置为默认值 (["*"])：

curl \
  -X DELETE 'http://<your-domain-name>/indexes/{index_uid}/settings/displayed-attributes' \
  -H 'X-Meili-API-Key: API_KEY'

此命令会返回一个 updateId。使用获取更新状态的接口来跟踪操作进度：

 # 将 {indexUid} 替换为你的索引 uid，{updateId} 替换为上一步请求返回的 updateId
  curl \
    -X GET 'http://<your-domain-name>/indexes/{indexUid}/updates/{updateId}'
    -H 'X-Meili-API-Key: API_KEY'

当状态变为 processed 后，操作即完成。对所有索引重复此过程后，即可继续创建 dump。

创建 dump

在创建 dump 之前，请确保你的dump 目录位于可访问的位置。默认情况下，dump 会被创建在 Meilisearch 根目录下名为 dumps 的文件夹中。

像 DigitalOcean 和 AWS 这样的云平台默认配置将转储文件存储在 /var/opt/meilisearch/dumps 目录中。

如果不确定 Meilisearch 目录的位置，可以尝试以下方法：

接下来可以创建数据库转储：

curl \
  -X POST 'http://<your-domain-name>/dumps' \
  -H 'Authorization: Bearer API_KEY'

# 对于 v0.24 或更早版本使用 -H 'X-Meili-API-Key: API_KEY'

服务器将返回类似以下的响应：

{
  "taskUid": 1,
  "indexUid": null,
  "status": "enqueued",
  "type": "dumpCreation",
  "enqueuedAt": "2022-06-21T16:10:29.217688Z"
}

使用 taskUid 来跟踪转储状态。请注意，此过程可能需要一些时间才能完成。

  curl \
    -X GET 'http://<your-domain-name>/dumps/:dump_uid/status'
    -H 'Authorization: Bearer API_KEY'
  # v0.24 或以下版本使用 -H 'X-Meili-API-Key: API_KEY'

当 dumpCreation 任务显示 "status": "succeeded" 时，即可进行后续操作。

​

步骤 2: 准备迁移

停止 Meilisearch 实例

停止正在运行的 Meilisearch 实例。

创建备份

建议先创建 data.ms 的备份以防万一，而不是直接删除。除非你选择了其他位置，否则 data.ms 应位于 Meilisearch 二进制文件的根目录下。

在云平台上，data.ms 文件夹通常位于 /var/lib/meilisearch/data.ms。

将当前 Meilisearch 安装的二进制文件和数据库移动到 /tmp 文件夹：

安装所需版本的 Meilisearch

使用以下命令安装最新版本的 Meilisearch：

为 Meilisearch 二进制文件添加执行权限：

chmod +x meilisearch

对于云平台，将新的 Meilisearch 二进制文件移动到 /usr/bin 目录：

mv meilisearch /usr/bin/meilisearch

​

步骤 3：导入数据

启动 Meilisearch 并导入数据转储

执行以下命令在启动时导入转储文件：

导入转储文件需要索引其中包含的所有文档。根据数据集的大小，此过程可能需要很长时间并导致内存使用量激增。

以服务形式重启 Meilisearch

如果您运行的是云实例，在数据转储文件成功导入后，请按下 Ctrl+C 停止 Meilisearch。接着执行以下命令运行配置脚本，将 Meilisearch 以服务形式重启：

meilisearch-setup

如有需要，可以使用更新展示属性端点将 displayedAttributes 恢复为之前的值。

​

完成迁移

现在您的 Meilisearch 实例已更新并正常运行，请验证数据转储导入是否成功且没有数据丢失。

如果一切正常，那么恭喜您！您已成功将数据库迁移至最新版本的 Meilisearch。别忘了查看更新日志。

如果出现问题，您可以随时回退到之前的版本。若问题持续存在，欢迎寻求帮助。如果您成功迁移了数据库但代码库出现问题，请务必查看我们的版本特定警告。

​

删除备份文件或回滚（可选）

删除之前步骤创建的 Meilisearch 二进制文件和 data.ms 文件夹。然后使用以下命令将备份文件移回原位置：

对于云平台，请在 Meilisearch 目录根目录运行配置脚本：

meilisearch-setup

如果一切顺利，可以使用以下命令删除备份文件：

rm -r /tmp/meilisearch
rm -r /tmp/data.ms

如果需要，也可以删除 dump 文件：

​

版本特定警告

迁移到最新版本的 Meilisearch 后，您的代码库可能需要一些更改。本节包含一些影响较大的版本特定变更警告。完整的变更日志请查看 GitHub 上的发布页面。

• 如果您是从 v0.25 或更低版本 升级，请注意：
  • private 和 public 密钥已被弃用，取而代之的是两个具有相似权限的默认 API 密钥：Default Admin API Key 和 Default Search API Key。
  • updates API 已被 tasks API 取代。
• 如果您是 从 v0.27 或更低版本升级，现有密钥的 key 和 uid 字段将被重新生成。
• 如果您是 在云平台上从 v0.30 或更低版本升级到 v1.0 或更高版本，请在以下文件中将 --dumps-dir 替换为 --dump-dir：
  • /etc/systemd/system/meilisearch.service
  • /var/opt/meilisearch/scripts/first-login/001-setup-prod.sh