更新到最新的 Meilisearch 版本

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

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

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

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

单击您要更新的项目。在页面顶部查找“常规设置”部分。

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

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

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

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

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

当从 Meilisearch >=v1.12 升级到 Meilisearch >=v1.13 时，可以使用无 dump 升级

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

curl \
  -X POST 'MEILISEARCH_URL/snapshots'

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

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

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

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

授予 Meilisearch 二进制文件执行权限

chmod +x meilisearch

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

mv meilisearch /usr/bin/meilisearch

执行以下命令以在启动时导入 dump

./meilisearch --experimental-dumpless-upgrade 

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

在任务处理期间，您可以继续进行搜索查询。您也可以将新任务排队。Meilisearch 仅在 UpgradeDatabase 完成后处理新任务。

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

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

响应应如下所示

{
  "commitSha": "stringOfLettersAndNumbers",
  "commitDate": "YYYY-MM-DDTimestamp",
  "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 版本创建 dumps 时，所有字段都必须显示，以便保存在 dump 中。

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

# 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。使用 get update 端点来跟踪操作状态

 # 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，您就可以继续了。为所有索引重复此过程，然后继续创建您的 dump。

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

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

如果您不确定 Meilisearch 目录位于何处，请尝试此操作

which meilisearch

/absolute/path/to/your/meilisearch/directory

然后您可以创建数据库的快照

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 来跟踪您的数据库快照状态。请记住，此过程可能需要一些时间才能完成。

  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"，您就可以继续下一步了。

停止您的 Meilisearch 实例。

我们建议您创建 data.ms 的备份，以防出现问题，而不是直接删除它。data.ms 应该位于 Meilisearch 二进制文件的根目录，除非您选择了其他位置。

在**云平台**上，您可以在 `/var/lib/meilisearch/data.ms` 找到 data.ms 文件夹。

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

mv /path/to/your/meilisearch/directory/meilisearch/data.ms /tmp/
mv /path/to/your/meilisearch/directory/meilisearch /tmp/

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

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

授予 Meilisearch 二进制文件执行权限

chmod +x meilisearch

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

mv meilisearch /usr/bin/meilisearch

执行以下命令以在启动时导入 dump

# replace {dump_uid.dump} with the name of your dump file
./meilisearch --import-dump dumps/{dump_uid.dump} --master-key="MASTER_KEY"
# Or, if you chose another location for data files and dumps before the update, also add the same parameters
./meilisearch --import-dump dumps/{dump_uid.dump} --master-key="MASTER_KEY" --db-path PATH_TO_DB_DIR/data.ms --dump-dir PATH_TO_DUMP_DIR/dumps

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

如果您运行的是**云实例**，请在数据库快照正确导入后按 Ctrl+C 停止 Meilisearch。接下来，执行以下命令来运行脚本以配置 Meilisearch 并将其作为服务重启

meilisearch-setup

如果需要，使用更新可显示属性端点将 displayedAttributes 设置回其先前的值。

现在您的更新后的 Meilisearch 实例已启动并运行，请验证数据库快照导入是否成功，并且没有数据丢失。

如果一切看起来都很好，那么恭喜！您已成功将数据库迁移到最新版本的 Meilisearch。请务必查看更新日志。

如果出现问题，您可以随时回滚到之前的版本。如果问题仍然存在，请随时寻求帮助。如果您已成功迁移数据库，但在代码库方面遇到问题，请务必查看我们的版本特定警告。

删除先前步骤创建的 Meilisearch 二进制文件和 data.ms 文件夹。接下来，使用以下命令将备份文件移回其先前的位置

mv /tmp/meilisearch /path/to/your/meilisearch/directory/meilisearch
mv /tmp/data.ms /path/to/your/meilisearch/directory/meilisearch/data.ms

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

meilisearch-setup

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

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

如果需要，您也可以删除数据库快照文件

rm /path/to/your/meilisearch/directory/meilisearch/dumps/{dump_uid.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