Docker Compose Support

Docker Compose 是一项流行的技术，可用于定义和管理应用程序所需服务的多个容器。通常在您的应用程序旁边创建一个 `@`3 文件，用于定义和配置服务容器。

Docker Compose is a popular technology that can be used to define and manage multiple containers for services that your application needs. A compose.yml file is typically created next to your application which defines and configures service containers.

使用 Docker Compose 的典型工作流是运行 `@`4，使用它连接到已启动的服务，在完成后运行 `@`5。

A typical workflow with Docker Compose is to run docker compose up, work on your application with it connecting to started services, then run docker compose down when you are finished.

`@`6 模块可以包含在项目中，以提供使用 Docker Compose 处理容器的支持。将模块依赖项添加到您的构建中，如以下针对 Maven 和 Gradle 的清单中所示：

The spring-boot-docker-compose module can be included in a project to provide support for working with containers using Docker Compose. Add the module dependency to your build, as shown in the following listings for Maven and Gradle:

Maven
<dependencies>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-docker-compose</artifactId>
		<optional>true</optional>
	</dependency>
</dependencies>
Gradle
dependencies {
	developmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

当这个模块作为依赖项包含时，Spring Boot 将执行以下操作：

When this module is included as a dependency Spring Boot will do the following:

  • Search for a compose.yml and other common compose filenames in your application directory

  • Call docker compose up with the discovered compose.yml

  • Create service connection beans for each supported container

  • Call docker compose stop when the application is shutdown

如果在启动应用程序时 Docker Compose 服务已经运行，Spring Boot 将只为每个受支持的容器创建服务连接 bean。它不会再次调用 `@`11，也不会在应用程序关闭时调用 `@`12。

If the Docker Compose services are already running when starting the application, Spring Boot will only create the service connection beans for each supported container. It will not call docker compose up again and it will not call docker compose stop when the application is shutdown.

默认情况下，在运行测试时 Spring Boot 的 Docker Compose 支持被禁用。要启用它，请将 configprop:spring.docker.compose.skip.in-tests[] 设置为 `@`13。

By default, Spring Boot’s Docker Compose support is disabled when running tests. To enable it, set configprop:spring.docker.compose.skip.in-tests[] to false.

Prerequisites

您需要在路径上拥有 @`14 和 `@`15 (或 `@`16) CLI 应用程序。支持的最小 Docker Compose 版本为 2.2.0。

You need to have the docker and docker compose (or docker-compose) CLI applications on your path. The minimum supported Docker Compose version is 2.2.0.

Service Connections

服务连接是到任何远程服务的连接。Spring Boot 的自动配置可以获取服务连接的详细信息，并使用它们来建立与远程服务的连接。执行此操作时，连接详细信息优先于任何与连接相关的配置属性。

A service connection is a connection to any remote service. Spring Boot’s auto-configuration can consume the details of a service connection and use them to establish a connection to a remote service. When doing so, the connection details take precedence over any connection-related configuration properties.

使用 Spring Boot 的 Docker Compose 支持时，服务连接建立到容器映射的端口。

When using Spring Boot’s Docker Compose support, service connections are established to the port mapped by the container.

Docker Compose 通常以使容器内的端口映射到您计算机上的临时端口的方式使用。例如，Postgres 服务可以在容器内使用端口 5432 运行，但被映射到本地完全不同的端口。服务连接将始终发现并使用本地映射的端口。

Docker compose is usually used in such a way that the ports inside the container are mapped to ephemeral ports on your computer. For example, a Postgres server may run inside the container using port 5432 but be mapped to a totally different port locally. The service connection will always discover and use the locally mapped port.

通过使用容器的镜像名称来建立服务连接。当前支持以下服务连接：

Service connections are established by using the image name of the container. The following service connections are currently supported:

Connection Details Matched on

ActiveMQConnectionDetails

Containers named "symptoma/activemq" or "apache/activemq-classic"

ArtemisConnectionDetails

Containers named "apache/activemq-artemis"

CassandraConnectionDetails

Containers named "cassandra" or "bitnami/cassandra"

ElasticsearchConnectionDetails

Containers named "elasticsearch" or "bitnami/elasticsearch"

JdbcConnectionDetails

Containers named "gvenzl/oracle-free", "gvenzl/oracle-xe", "mariadb", "bitnami/mariadb", "mssql/server", "mysql", "bitnami/mysql", "postgres", or "bitnami/postgresql"

LdapConnectionDetails

Containers named "osixia/openldap"

MongoConnectionDetails

Containers named "mongo" or "bitnami/mongodb"

Neo4jConnectionDetails

Containers named "neo4j" or "bitnami/neo4j"

OtlpMetricsConnectionDetails

Containers named "otel/opentelemetry-collector-contrib"

OtlpTracingConnectionDetails

Containers named "otel/opentelemetry-collector-contrib"

PulsarConnectionDetails

Containers named "apachepulsar/pulsar"

R2dbcConnectionDetails

Containers named "gvenzl/oracle-free", "gvenzl/oracle-xe", "mariadb", "bitnami/mariadb", "mssql/server", "mysql", "bitnami/mysql", "postgres", or "bitnami/postgresql"

RabbitConnectionDetails

Containers named "rabbitmq" or "bitnami/rabbitmq"

RedisConnectionDetails

Containers named "redis" or "bitnami/redis"

ZipkinConnectionDetails

Containers named "openzipkin/zipkin".

Custom Images

有时你可能需要使用自己版本的映像来提供服务。只要行为与标准映像一致，你就可以使用任何自定义映像。具体而言，标准映像支持的任何环境变量也必须在你的自定义映像中使用。

Sometimes you may need to use your own version of an image to provide a service. You can use any custom image as long as it behaves in the same way as the standard image. Specifically, any environment variables that the standard image supports must also be used in your custom image.

如果你的映像使用不同的名称，则可以在你的 compose.yml 文件中使用标签，以便 Spring Boot 可以提供服务连接。使用名为 org.springframework.boot.service-connection 的标签来提供服务名称。

If your image uses a different name, you can use a label in your compose.yml file so that Spring Boot can provide a service connection. Use a label named org.springframework.boot.service-connection to provide the service name.

例如：

For example:

services:
  redis:
    image: 'mycompany/mycustomredis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.service-connection: redis

Skipping Specific Containers

如果你在 compose.yml 中定义了不想连接到你的应用程序的容器映像，则可以使用标签来忽略它。带有标签 org.springframework.boot.ignore 的任何容器都将被 Spring Boot 忽略。

If you have a container image defined in your compose.yml that you don’t want connected to your application you can use a label to ignore it. Any container with labeled with org.springframework.boot.ignore will be ignored by Spring Boot.

例如：

For example:

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.ignore: true

Using a Specific Compose File

如果你的 Compose 文件与你的应用程序不在同一个目录中，或名称不同，则可以在 application.properties 或 application.yaml 中使用 configprop:spring.docker.compose.file[] 指向不同的文件。属性可以定义为确切路径或相对于你的应用程序的路径。

If your compose file is not in the same directory as your application, or if it’s named differently, you can use configprop:spring.docker.compose.file[] in your application.properties or application.yaml to point to a different file. Properties can be defined as an exact path or a path that’s relative to your application.

例如：

For example:

spring:
  docker:
    compose:
      file: "../my-compose.yml"

Waiting for Container Readiness

由 Docker Compose 启动的容器可能需要一些时间才能完全就绪。检查就绪性的推荐方法是在你的 compose.yml 文件中的服务定义下添加一个 healthcheck 部分。

Containers started by Docker Compose may take some time to become fully ready. The recommended way of checking for readiness is to add a healthcheck section under the service definition in your compose.yml file.

因为 healthcheck 配置通常从 compose.yml 文件中省略，Spring Boot 也会直接检查服务就绪性。默认情况下，当可以建立到容器映射端口的 TCP/IP 连接时，容器被视为就绪。

Since it’s not uncommon for healthcheck configuration to be omitted from compose.yml files, Spring Boot also checks directly for service readiness. By default, a container is considered ready when a TCP/IP connection can be established to its mapped port.

你可以在 compose.yml 文件中添加 org.springframework.boot.readiness-check.tcp.disable 标签，为每个容器禁用此功能。

You can disable this on a per-container basis by adding a org.springframework.boot.readiness-check.tcp.disable label in your compose.yml file.

例如：

For example:

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.readiness-check.tcp.disable: true

你也可以在 application.properties 或 application.yaml 文件中更改超时值：

You can also change timeout values in your application.properties or application.yaml file:

spring:
  docker:
    compose:
      readiness:
        tcp:
          connect-timeout: 10s
          read-timeout: 5s

可以使用 configprop:spring.docker.compose.readiness.timeout[] 配置总体超时。

The overall timeout can be configured using configprop:spring.docker.compose.readiness.timeout[].

Controlling the Docker Compose Lifecycle

默认情况下，Spring Boot 在你的应用程序启动时调用 docker compose up，在应用程序关闭时调用 docker compose stop。如果你希望有不同的生命周期管理，可以使用 configprop:spring.docker.compose.lifecycle-management[] 属性。

By default Spring Boot calls docker compose up when your application starts and docker compose stop when it’s shut down. If you prefer to have different lifecycle management you can use the configprop:spring.docker.compose.lifecycle-management[] property.

支持以下值：

The following values are supported:

  • none - Do not start or stop Docker Compose

  • start-only - Start Docker Compose when the application starts and leave it running

  • start-and-stop - Start Docker Compose when the application starts and stop it when the JVM exits

此外，你可以使用 configprop:spring.docker.compose.start.command[] 属性来更改使用 docker compose up 还是 docker compose start。configprop:spring.docker.compose.stop.command[] 允许你配置使用 docker compose down 还是 docker compose stop。

In addition you can use the configprop:spring.docker.compose.start.command[] property to change whether docker compose up or docker compose start is used. The configprop:spring.docker.compose.stop.command[] allows you to configure if docker compose down or docker compose stop is used.

以下示例显示如何配置生命周期管理：

The following example shows how lifecycle management can be configured:

spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      start:
        command: start
      stop:
        command: down
        timeout: 1m

Activating Docker Compose Profiles

Docker Compose 配置与 Spring 配置类似，它们都允许你调整特定环境的 Docker Compose 配置。如果你想激活某个特定的 Docker Compose 配置，可以在 application.properties 或 application.yaml 文件中使用 configprop:spring.docker.compose.profiles.active[] 属性：

Docker Compose profiles are similar to Spring profiles in that they let you adjust your Docker Compose configuration for specific environments. If you want to activate a specific Docker Compose profile you can use the configprop:spring.docker.compose.profiles.active[] property in your application.properties or application.yaml file:

spring:
  docker:
    compose:
      profiles:
        active: "myprofile"