更新到最新 Meilisearch 版本

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

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

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

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

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

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

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

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

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

首先，使用获取版本端点验证与您的数据库兼容的 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 或更高，你可以跳到 创建转储 部分。否则，请继续执行下一步。

在使用低于 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 和 GCP）配置为将转储存储在 /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

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

# 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