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

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

如果迁移到最新版 Meilisearch 会导致您跳过多个版本，这可能需要更改您的代码库。有关更多详细信息，请参阅我们的特定版本更新警告。

如果您正在使用 v0.22 或更高版本，并将 Meilisearch 作为 systemctl 服务运行，请尝试使用我们的迁移脚本。

​
更新 Meilisearch Cloud

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

点击您要更新的项目。在页面顶部查找“通用设置”部分。

每当有新版本 Meilisearch 可用时，您将在“Meilisearch 版本”字段旁边看到一个更新按钮。

要更新到最新版 Meilisearch，请点击“更新到 v.X.Y.Z”按钮。

这将打开一个弹出窗口，其中包含有关更新过程的更多信息。阅读后，点击“更新”。您项目的“状态”将从“运行中”变为“更新中”。

项目成功更新后，您将收到一封确认更新的电子邮件，并且“状态”将变回“运行中”。

​
更新自托管 Meilisearch 实例

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

本指南仅适用于 v0.15 及更高版本。如果您使用的是旧版 Meilisearch，请联系支持以获取更多信息。

​
无转储升级 实验性

无转储升级适用于从 Meilisearch >=v1.12 升级到 Meilisearch >=v1.13 的情况

​
步骤 1：创建备份

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

curl \
  -X POST 'MEILISEARCH_URL/snapshots'

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

​
步骤 2：停止 Meilisearch 实例

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

​
步骤 3：安装新的 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 中生成的快照恢复您的实例。然后您可以重试升级，或者使用转储进行升级。也欢迎您在Meilisearch 仓库中提出问题。

​
使用转储

​
步骤 1：导出数据

验证您的数据库版本

首先，使用获取版本端点验证与您的数据库兼容的 Meilisearch 版本

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

响应应类似于这样

{
  "commitSha": "stringOfLettersAndNumbers",
  "commitDate": "YYYY-MM-DDTimestamp",
  "pkgVersion": "x.y.z"
}

如果您收到 missing_authorization_header 错误，您可能正在使用 v0.24 或更低版本。对于每个命令，请将 Authorization: Bearer 头替换为 X-Meili-API-Key: API_KEY 头

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

如果您的 pkgVersion 是 0.21 或更高版本，您可以直接跳到创建转储。如果不是，请继续下一步。

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

如果您的转储是在 Meilisearch v0.21 或更高版本中创建的，请跳过此步骤。

当使用低于 v0.21 的 Meilisearch 版本创建转储时，所有字段都必须是显示的，才能保存到转储中。

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

# whenever you see {index_uid}, replace it with your index's unique 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。使用获取更新端点来跟踪操作状态

# replace {indexUid} with the uid of your index and {updateId} with the updateId returned by the previous request
  curl \
    -X GET 'http://<your-domain-name>/indexes/{indexUid}/updates/{updateId}'
    -H 'X-Meili-API-Key: API_KEY'

一旦状态为 processed，您就可以继续了。对所有索引重复此过程，然后继续创建转储。

创建转储

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

DigitalOcean 和 AWS 等云平台配置为将转储文件存储在 /var/opt/meilisearch/dumps 目录中。

如果您不确定 Meilisearch 目录的位置，请尝试以下操作

由于 Meilisearch v0.27、v0.28 和 v0.29 中允许畸形 _geo 字段的错误，您可能无法导入转储。在创建转储之前，请确保 _geo 字段遵循正确格式。

然后您可以创建数据库转储

curl \
  -X POST 'http://<your-domain-name>/dumps' \
  -H 'Authorization: Bearer API_KEY'
# -H 'X-Meili-API-Key: API_KEY' for v0.24 or below

服务器应返回如下响应

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

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

对于 v0.27 及以下版本，您的请求响应会返回一个转储 uid。使用它与 `/dumps/:dump_uid/status` 路由一起跟踪请求状态

curl \
    -X GET 'http://<your-domain-name>/dumps/:dump_uid/status'
    -H 'Authorization: Bearer API_KEY'
  # -H 'X-Meili-API-Key: API_KEY' for v0.24 or below

一旦 dumpCreation 任务显示 "status": "succeeded"，您就可以继续了。

​
步骤 2：准备迁移

停止 Meilisearch 实例

停止您的 Meilisearch 实例。

创建备份

我们建议您不要删除 data.ms，而是创建一个备份以防万一。data.ms 应该位于 Meilisearch 二进制文件的根目录，除非您选择了其他位置。

在云平台上，您会在 /var/lib/meilisearch/data.ms 找到 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

如果需要，您也可以删除转储文件

​
特定版本警告

迁移到最新版 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