Dev Services for Elasticsearch

如果存在任何 Elasticsearch 相关扩展(例如 quarkus-elasticsearch-rest-client`或 `quarkus-hibernate-search-orm-elasticsearch),开发服务 for Elasticsearch 会在开发模式下以及在运行测试时自动启动一个 Elasticsearch 服务器。因此,你不需要手动启动服务器。应用程序会自动进行配置。

Enabling / Disabling Dev Services for Elasticsearch

开发服务 for Elasticsearch 自动启用,除非:

  • quarkus.devservices.enabled`设为 `false

  • quarkus.elasticsearch.devservices.enabled`设为 `false

  • hosts 属性已被配置,具体取决于所用扩展,它可以是:

  • quarkus.elasticsearch.hosts

  • quarkus.hibernate-search-orm.elasticsearch.hosts

开发服务 for Elasticsearch 依赖于 Docker 来启动服务器。如果你的环境不支持 Docker,你需要手动启动服务器,或连接到一个已经运行的服务器上。

Shared Elasticsearch

有时你需要在应用程序之间共享服务器。开发服务 for Elasticsearch 为你的多个在 _dev_模式下运行的 Quarkus 应用程序实现了 _service discovery_机制,以共享一个单一的服务器。

开发服务 for Elasticsearch 使用 `quarkus-dev-service-elasticsearch`标签启动容器,该标签用于识别该容器。

如果你需要多个(共享)服务器,你可以配置 quarkus.elasticsearch.devservices.service-name`属性并指定服务器名称。它会寻找具有相同值的容器,或在找不到容器时启动一个新容器。默认服务名称为 `elasticsearch

在开发模式下默认启用共享,但在测试模式下禁用。你可以使用 `quarkus.elasticsearch.devservices.shared=false`禁用共享。

Setting the port

默认情况下,开发服务 for Elasticsearch 会选取一个随机端口并为应用程序进行配置。你可以通过配置 `quarkus.elasticsearch.devservices.port`属性来设置端口。

请注意,Elasticsearch hosts 属性会自动配置为已选端口。

Configuring the image

开发服务 for Elasticsearch 支持基于 Elasticsearch 和 OpenSearch 镜像的发行版。

当使用 Hibernate Search时,开发服务会根据 Hibernate Search 配置默认为 Elasticsearch 或 OpenSearch。

否则,Dev Services 将默认为 Elasticsearch。如需使用 OpenSearch,请显式配置发行版本:

quarkus.elasticsearch.devservices.distribution=opensearch

如果你需要使用不同于默认版本的 Elasticsearch 或 OpenSearch 映像,可以通过以下途径进行配置:

quarkus.elasticsearch.devservices.image-name={elasticsearch-image}

对于非常规映像名称,Quarkus 可能无法推断发行版本(elastic`或 `opensearch)。在这种情况下,启动 Dev Services 将失败,你需要显式配置发行版本:

quarkus.elasticsearch.devservices.image-name=my-custom-image-with-no-clue-about-the-distribution:1.0
quarkus.elasticsearch.devservices.distribution=elasticsearch

Reusing Dev Services

General case

在开发模式会话或测试套件执行过程中,只要配置(用户名、密码、环境、端口绑定等)没有更改,Quarkus 总是会重用 Elasticsearch Dev Services。

当 Elasticsearch Dev Services 的配置发生更改时,Quarkus 总是会重新启动相应的容器。

当开发模式会话或测试套件执行结束时,Quarkus 会(默认)停止 Elasticsearch Dev Services。

Reusing Dev Service containers across runs

如果你想让 Dev Service 容器继续运行 after a dev mode session or test suite execution,以便在下一次开发模式会话或测试套件执行中重用它们,也是可以的。只需在你的 TestContainers configuration file之一(通常是 ~/.testcontainers.properties`或 `C:/Users/myuser/.testcontainers.properties)中插入此行即可启用 TestContainers reuse

testcontainers.reuse.enable=true

即使启用了容器重用,只有当它们的启动命令没有更改时才重用容器:相同的环境变量(尤其是用户名/密码),相同的端口绑定等。

重用容器意味着重用它们的内部状态,包括 Elasticsearch 架构和索引内容。 如果这不是你想要的,而且如果你的测试写入索引(这可能不是你想要的),请考虑在应用程序启动时重新初始化架构和数据。如果你使用 Hibernate Search,Hibernate Search’s schema management可能对你有帮助。

启用容器重用后,旧容器(尤其是那些配置已过时的容器)可能会无限期地运行,即使在启动新的 Quarkus 开发模式会话或测试套件执行之后也是如此。 在那种情况下,你需要手动停止并移除这些容器。

如果你想要为某些 Quarkus 应用程序(但不是所有应用程序)或某些 Dev Services(但不是所有 Dev Services)重用容器,可以通过将配置属性 quarkus.elasticsearch.devservices.reuse设置为 `false`来禁用特定 Dev Service 的此功能。

Current limitations

目前,仅支持 Hibernate Search Elasticsearch 的默认后端,因为 Elasticsearch 的 Dev Services 只能启动一个 Elasticsearch 容器。

Configuration reference

Unresolved include directive in modules/ROOT/pages/elasticsearch-dev-services.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-elasticsearch-rest-client_quarkus.elasticsearch.devservices.adoc[]