Dev Services for Elasticsearch

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

If any Elasticsearch-related extension is present (e.g. quarkus-elasticsearch-rest-client or quarkus-hibernate-search-orm-elasticsearch), Dev Services for Elasticsearch automatically starts an Elasticsearch server in dev mode and when running tests. So, you don’t have to start a server manually. The application is configured automatically.

Enabling / Disabling Dev Services for Elasticsearch

开发服务 for Elasticsearch 自动启用，除非：

Dev Services for Elasticsearch is automatically enabled unless:

  • quarkus.devservices.enabled is set to false.

  • quarkus.elasticsearch.devservices.enabled is set to false

  • the hosts property is configured, depending on the extension used it can be:

  • quarkus.elasticsearch.hosts

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

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

Dev Services for Elasticsearch relies on Docker to start the server. If your environment does not support Docker, you will need to start the server manually, or connect to an already running server.

Shared Elasticsearch

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

Sometimes you need to share the server between applications. Dev Services for Elasticsearch implements a service discovery mechanism for your multiple Quarkus applications running in dev mode to share a single server.

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

Dev Services for Elasticsearch starts the container with the quarkus-dev-service-elasticsearch label which is used to identify the container.

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

If you need multiple (shared) servers, you can configure the quarkus.elasticsearch.devservices.service-name attribute and indicate the server name. It looks for a container with the same value, or starts a new one if none can be found. The default service name is elasticsearch.

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

Sharing is enabled by default in dev mode, but disabled in test mode. You can disable the sharing with quarkus.elasticsearch.devservices.shared=false.

Setting the port

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

By default, Dev Services for Elasticsearch picks a random port and configures the application. You can set the port by configuring the quarkus.elasticsearch.devservices.port property.

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

Note that the Elasticsearch hosts property is automatically configured with the chosen port.

Configuring the image

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

Dev Services for Elasticsearch support distributions based on both Elasticsearch and OpenSearch images.

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

When using Hibernate Search, Dev Services will default to Elasticsearch or OpenSearch based on Hibernate Search configuration.

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

Otherwise, Dev Services will default to Elasticsearch. To use OpenSearch, configure the distribution explicitly:

quarkus.elasticsearch.devservices.distribution=opensearch

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

If you need to use a different Elasticsearch or OpenSearch image than the default one you can configure it via:

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

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

For exotic image names, Quarkus might be unable to infer the distribution (elastic or opensearch). In these cases starting the Dev Services will fail, and you will need to configure the distribution explicitly:

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。

Within a dev mode session or test suite execution, Quarkus will always reuse Elasticsearch Dev Services as long as their configuration (username, password, environment, port bindings, …​) did not change.

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

When the configuration of Elasticsearch Dev Services changes, Quarkus will always restart the corresponding containers.

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

When a dev mode session or test suite execution ends, Quarkus will (by default) stop 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：

If you want to keep Dev Service containers running after a dev mode session or test suite execution to reuse them in the next dev mode session or test suite execution, this is possible as well. Just enable TestContainers reuse by inserting this line in one of your TestContainers configuration file (generally ~/.testcontainers.properties or C:/Users/myuser/.testcontainers.properties):

testcontainers.reuse.enable=true

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

Even with container reuse enabled, containers will only be reused if their startup command did not change: same environment variables (username/password in particular), same port bindings, …​

重用容器意味着重用它们的内部状态，包括 Elasticsearch 架构和索引内容。

Reusing containers implies reusing their internal state, including the Elasticsearch schema and the content of indexes.

如果这不是你想要的，而且如果你的测试写入索引（这可能不是你想要的），请考虑在应用程序启动时重新初始化架构和数据。如果你使用 Hibernate Search，Hibernate Search’s schema management可能对你有帮助。

If that’s not what you want — and if your tests write to the indexes, that’s probably not what you want — consider reinitializing your schema and data on application startup. If you use Hibernate Search, Hibernate Search’s schema management may help with that.

启用容器重用后，旧容器（尤其是那些配置已过时的容器）可能会无限期地运行，即使在启动新的 Quarkus 开发模式会话或测试套件执行之后也是如此。

With container reuse enabled, old containers (especially with obsolete configuration) might be left running indefinitely, even after starting a new Quarkus dev mode session or test suite execution.

在那种情况下，你需要手动停止并移除这些容器。

In that case, you will need to stop and remove these containers manually.

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

If you want to reuse containers for some Quarkus applications but not all of them, or some Dev Services but not all of them, you can disable this feature for a specific Dev Service by setting the configuration property quarkus.elasticsearch.devservices.reuse to false.

Current limitations

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

Currently, only the default backend for Hibernate Search Elasticsearch is supported, because Dev Services for Elasticsearch can only start one Elasticsearch container.

Configuration reference

Unresolved directive in elasticsearch-dev-services.adoc - include::{generated-dir}/config/quarkus-elasticsearch-rest-client_quarkus.elasticsearch.devservices.adoc[]