如何将 Ruby 应用程序从 OpenSearch 迁移到 Elasticsearch

亲身体验 Elasticsearch：深入了解我们的示例笔记本，开始免费云服务试用，或立即在您的本地计算机上试用 Elastic。

OpenSearch Ruby 客户端是从版本7.x 的 Elasticsearch Ruby 客户端分叉而来，因此代码库相对相似。这意味着在将 Ruby 代码库从 OpenSearch 迁移到 Elasticsearch 时，各客户端库中的代码看起来会非常熟悉。在这篇博文中，我将展示一个使用 OpenSearch 的 Ruby 应用程序示例，以及将代码迁移到 Elasticsearch 的步骤。

这两个客户端都是根据流行的 Apache License 2.0 发布的，因此都是开源和免费软件。Elasticsearch 的许可证最近进行了更新，自 8.16 版起，Elasticsearch 和 Kibana 的核心内容均根据 OSI 批准的开源许可证 AGPL 发布。

迁移 Ruby 应用程序时考虑 Elasticsearch 版本

迁移时的一个考虑因素是将使用哪个版本的 Elasticsearch。我们建议使用最新的稳定版本，即8.17.0 。Elasticsearch Ruby 客户端的次版本与 Elasticsearch 的次版本一致。因此，对于 Elasticsearch8.17.x ，可以使用版本为8.17.x 的 Ruby gem。

OpenSearch 源自 Elasticsearch 7.10.2。因此，应用程序接口可能已经发生了变化，不同的功能可以在其中任何一个上使用。但这不在本篇文章的讨论范围内，我只想在一个示例应用程序中了解最常见的操作。

对于 Ruby on Rails，可以使用官方 Elasticsearch 客户端或Rails 集成库。我们建议分别迁移到 Elasticsearch 和客户端的最新稳定版本。elasticsearch-rails gem 版本8.0.0 支持 Rails6.1 、7.0 和7.1 以及 Elasticsearch8.x 。

代码

在本例中，我按照步骤从 tar 包中安装 OpenSearch。下载并解压 tar 包后，我需要设置一个初始管理员密码，稍后将使用该密码实例化客户端。

我创建了一个带有Gemfile 的目录，看起来像这样：

运行bundle install 后，我的项目安装了 gem。这就安装了3.4.0 版本的 opensearch-ruby，而我运行的 OpenSearch 版本是2.18.0 。我在同一目录下的example_code.rb 文件中编写了代码。该文件中的初始代码是 OpenSearch 客户端的实例化：

传输选项ssl: { verify: false} 参数是根据用户指南传递的，以便于测试。在生产中，应根据 OpenSearch 的部署情况进行设置。

自 OpenSearch 2.12.0 版起，在运行安装脚本时，必须将OPENSEARCH_INITIAL_ADMIN_PASSWORD 环境变量设置为强密码。按照从压缩包中安装 OpenSearch 的步骤，我在控制台中导出了变量，现在我的 Ruby 脚本可以使用它了。

使用cluster.health API 是确保客户端连接 OpenSearch 的一个简单 API：

它确实有效：

我测试了 Elasticsearch Ruby 客户端文档中的一些常见示例，它们都能按预期运行：

将 Ruby 应用程序迁移到 Elasticsearch

第一步是在 Gemfile 中添加elasticsearch-ruby 。运行bundle install 后，Elasticsearch Ruby 客户端 gem 将被安装。如果想在完全迁移前测试代码，可以先保留opensearch-ruby gem。

下一个重要步骤是客户端实例化。这取决于你运行 Elasticsearch 的方式。为了在这些示例中保持相似的方法，我按照下载 Elasticsearch并在本地运行的步骤进行操作。

运行bin/elasticsearch 时，Elasticsearch 会自动配置安全功能。确保复制了弹性用户的密码（但可以通过运行bin/elasticsearch-reset-password -u elastic 重置）。如果您遵循这个示例，请确保在启动 Elasticsearch 之前停止 OpenSearch，因为它们运行在同一个端口上。

在example_code.rb 的开头，我注释掉了 OpenSearch 客户端的实例化，并添加了 Elasticsearch 客户端的实例化：

正如您所看到的，在这个测试场景中，代码几乎完全相同。它将根据 Elasticsearch 的部署以及您决定与之连接和验证的方式而有所不同。这里与 OpenSearch 的安全问题相同，不验证 ssl 的选项仅用于测试目的，不应在生产中使用。

设置好客户端后，我再次运行代码，使用：bundle exec ruby example_code.rb.一切都很顺利！

调试迁移问题

根据您的应用程序使用的 API，如果 OpenSearch 的 API 与 Elasticsearch 的不同，您在针对 Elasticsearch 运行代码时可能会收到错误信息。REST API 文档是了解如何使用 API 的详细信息的重要参考资料。请务必查看您正在使用的 Elasticsearch 版本的文档。您也可以参阅Elasticsearch::API 参考资料。

您可能会从 Elasticsearch 中遇到以下错误：

• ArgumentError: Required argument '<ARGUMENT>' missing - 这是客户端错误，当请求缺少一个必填参数时就会出现。
• Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... 该错误来自 Elasticsearch，这意味着客户端代码使用了 Elasticsearch 无法识别的 API 参数。

Elasticsearch 客户端会从 Elasticsearch 引发错误，并附带服务器发送的详细错误信息。因此，即使是不支持的参数或端点，错误也会告诉你有什么不同。

结论

正如我们在本示例代码中演示的那样，从 Ruby 端将 Ruby 应用程序从 OpenSearch 迁移到 Elasticsearch 并不复杂。您需要了解搜索引擎之间的版本和任何潜在的不同应用程序接口。但就最常见的操作而言，迁移客户端时的主要变化在于实例化。它们在这方面都很相似，但主机和凭证的定义方式因堆栈的部署方式而异。一旦设置好客户端，并验证它连接到 Elasticsearch，就可以用 Elasticsearch 客户端无缝替换 OpenSearch 客户端。