合并 Compose 文件

Docker Compose 允许您合并和覆盖一组 Compose 文件以创建复合 Compose 文件。

默认情况下，Compose 读取两个文件，一个 compose.yaml 和一个可选的 compose.override.yaml 文件。按照惯例，compose.yaml 包含您的基本配置。覆盖文件可以包含现有服务的配置覆盖或全新的服务。

如果一个服务在两个文件中都定义了，Compose 会使用下面描述的规则和 Compose 规范 中的规则合并配置。

如何合并多个 Compose 文件

要使用多个覆盖文件，或使用不同名称的覆盖文件，您可以使用预定义的 COMPOSE_FILE 环境变量，或使用 -f 选项指定文件列表。

Compose 按照命令行中指定的顺序合并文件。后续文件可能会合并、覆盖或添加到其前身。

例如：

$ docker compose -f compose.yaml -f compose.admin.yaml run backup_db

compose.yaml 文件可能指定一个 webapp 服务。

webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"

compose.admin.yaml 也可能指定相同的服务。

webapp:
  environment:
    - DEBUG=1

任何匹配的字段都会覆盖前一个文件。新值会添加到 webapp 服务配置中。

webapp:
  image: examples/web
  ports:
    - "8000:8000"
  volumes:
    - "/data"
  environment:
    - DEBUG=1

合并规则

• 路径是相对于基础文件评估的。当您使用多个 Compose 文件时，必须确保所有文件中的路径都相对于基础 Compose 文件（使用 -f 指定的第一个 Compose 文件）。这是必需的，因为覆盖文件不必是有效的 Compose 文件。覆盖文件可以包含配置的小片段。跟踪服务的哪个片段相对于哪个路径是困难和令人困惑的，因此为了使路径更容易理解，所有路径都必须相对于基础文件定义。

  提示

  您可以使用 docker compose config 来查看合并后的配置并避免与路径相关的问题。

• Compose 将原始服务的配置复制到本地服务。如果配置选项在原始服务和本地服务中都定义了，则本地值将替换或扩展原始值。

  • 对于 image、command 或 mem_limit 等单值选项，新值会替换旧值。

    原始服务

    services:
      myservice:
        # ...
        command: python app.py

    本地服务

    services:
      myservice:
        # ...
        command: python otherapp.py

    结果

    services:
      myservice:
        # ...
        command: python otherapp.py

  • 对于多值选项 ports、expose、external_links、dns、dns_search 和 tmpfs，Compose 会连接两组值。

    原始服务

    services:
      myservice:
        # ...
        expose:
          - "3000"

    本地服务

    services:
      myservice:
        # ...
        expose:
          - "4000"
          - "5000"

    结果

    services:
      myservice:
        # ...
        expose:
          - "3000"
          - "4000"
          - "5000"

  • 在 environment、labels、volumes 和 devices 的情况下，Compose 将条目与本地定义的值合并在一起，本地定义的值优先。对于 environment 和 labels，环境变量或标签名称决定使用哪个值。

    原始服务

    services:
      myservice:
        # ...
        environment:
          - FOO=original
          - BAR=original

    本地服务

    services:
      myservice:
        # ...
        environment:
          - BAR=local
          - BAZ=local

    结果

    services:
      myservice:
        # ...
        environment:
          - FOO=original
          - BAR=local
          - BAZ=local

  • volumes 和 devices 的条目使用容器中的挂载路径合并。

    原始服务

    services:
      myservice:
        # ...
        volumes:
          - ./original:/foo
          - ./original:/bar

    本地服务

    services:
      myservice:
        # ...
        volumes:
          - ./local:/bar
          - ./local:/baz

    结果

    services:
      myservice:
        # ...
        volumes:
          - ./original:/foo
          - ./local:/bar
          - ./local:/baz

有关更多合并规则，请参阅 Compose 规范中的 合并和覆盖。

附加信息

• 使用 -f 是可选的。如果未提供，Compose 会在工作目录及其父目录中搜索 compose.yaml 和 compose.override.yaml 文件。您必须至少提供 compose.yaml 文件。如果两个文件位于同一目录级别，Compose 会将它们组合成一个配置。

• 您可以使用 -f 和 -（破折号）作为文件名从 stdin 读取配置。例如：

  $ docker compose -f - <<EOF
    webapp:
      image: examples/web
      ports:
       - "8000:8000"
      volumes:
       - "/data"
      environment:
       - DEBUG=1
    EOF
  

  当使用 stdin 时，配置中的所有路径都相对于当前工作目录。

• 您可以使用 -f 标志指定不在当前目录中的 Compose 文件的路径，无论是从命令行还是通过在您的 shell 或环境文件中设置 COMPOSE_FILE 环境变量。

  例如，如果您正在运行 Compose Rails 示例，并且在名为 sandbox/rails 的目录中有一个 compose.yaml 文件。您可以使用类似 docker compose pull 的命令通过以下方式使用 -f 标志从任何地方获取 db 服务的 postgres 镜像：docker compose -f ~/sandbox/rails/compose.yaml pull db

  这是完整的示例：

  $ docker compose -f ~/sandbox/rails/compose.yaml pull db
  Pulling db (postgres:latest)...
  latest: Pulling from library/postgres
  ef0380f84d05: Pull complete
  50cf91dc1db8: Pull complete
  d3add4cd115c: Pull complete
  467830d8a616: Pull complete
  089b9db7dc57: Pull complete
  6fba0a36935c: Pull complete
  81ef0e73c953: Pull complete
  338a6c4894dc: Pull complete
  15853f32f67c: Pull complete
  044c83d92898: Pull complete
  17301519f133: Pull complete
  dcca70822752: Pull complete
  cecf11b8ccf3: Pull complete
  Digest: sha256:1364924c753d5ff7e2260cd34dc4ba05ebd40ee8193391220be0f9901d4e1651
  Status: Downloaded newer image for postgres:latest
  

示例

多文件的一个常见用例是将开发 Compose 应用程序更改为生产环境（可以是生产、staging 或 CI）。为了支持这些差异，您可以将 Compose 配置拆分为几个不同的文件。

从定义服务规范配置的基础文件开始。

compose.yaml

services:
  web:
    image: example/my_web_app:latest
    depends_on:
      - db
      - cache

  db:
    image: postgres:latest

  cache:
    image: redis:latest

在此示例中，开发配置将某些端口公开给主机，将我们的代码挂载为卷，并构建 web 镜像。

compose.override.yaml

services:
  web:
    build: .
    volumes:
      - '.:/code'
    ports:
      - 8883:80
    environment:
      DEBUG: 'true'

  db:
    command: '-d'
    ports:
     - 5432:5432

  cache:
    ports:
      - 6379:6379

当您运行 docker compose up 时，它会自动读取覆盖。

要在生产环境中使用此 Compose 应用程序，需要创建另一个覆盖文件，该文件可能存储在不同的 git 存储库中或由不同的团队管理。

compose.prod.yaml

services:
  web:
    ports:
      - 80:80
    environment:
      PRODUCTION: 'true'

  cache:
    environment:
      TTL: '500'

要使用此生产 Compose 文件进行部署，您可以运行：

$ docker compose -f compose.yaml -f compose.prod.yaml up -d

这会使用 compose.yaml 和 compose.prod.yaml 中的配置部署所有三个服务，但不使用 compose.override.yaml 中的开发配置。

有关更多信息，请参阅 在生产中使用 Compose。

限制

Docker Compose 支持应用程序模型中包含的许多资源的相对路径：服务镜像的构建上下文、定义环境变量的文件位置、用于绑定挂载卷的本地目录路径。有了这样的约束，单体仓库中的代码组织会变得很困难，因为自然的C选择是为每个团队或组件设置专用文件夹，但这样 Compose 文件的相对路径就变得不相关了。

参考信息

• 合并规则