合并 Compose 文件
Docker Compose 允许您将一组 Compose 文件合并和覆盖在一起,以创建一个组合的 Compose 文件。
默认情况下,Compose 读取两个文件,compose.yml
和一个可选的 compose.override.yml
文件。按照惯例,compose.yml
包含您的基本配置。覆盖文件可以包含对现有服务的配置覆盖或全新的服务。
如果服务在两个文件中都定义,Compose 会使用下面描述的规则和 Compose 规范 中的规则合并配置。
如何合并多个 Compose 文件
要使用多个覆盖文件,或使用不同名称的覆盖文件,您可以使用预定义的 COMPOSE_FILE 环境变量,或使用 -f
选项指定文件列表。
Compose 以命令行上指定的顺序合并文件。后续文件可能会合并、覆盖或添加到其前身。
例如
$ docker compose -f compose.yml -f compose.admin.yml run backup_db
compose.yml
文件可能指定 webapp
服务。
webapp:
image: examples/web
ports:
- "8000:8000"
volumes:
- "/data"
compose.admin.yml
也可能指定此相同的服务
webapp:
environment:
- DEBUG=1
任何匹配的字段都会覆盖之前文件。新值会添加到 webapp
服务配置中
webapp:
image: examples/web
ports:
- "8000:8000"
volumes:
- "/data"
environment:
- DEBUG=1
- ANOTHER_VARIABLE=value
重要
当您使用多个 Compose 文件时,您必须确保文件中的所有路径都相对于基本 Compose 文件(使用
-f
指定的第一个 Compose 文件)。这是必需的,因为覆盖文件不必是有效的 Compose 文件。覆盖文件可以包含少量配置片段。跟踪服务中哪个片段相对于哪个路径很困难而且令人困惑,因此为了使路径更容易理解,所有路径都必须相对于基本文件定义。
其他信息
使用
-f
是可选的。如果没有提供,Compose 会在工作目录及其父目录中搜索compose.yml
和compose.override.yml
文件。您必须至少提供compose.yml
文件。如果两个文件存在于同一目录级别,Compose 会将它们组合成一个配置。当您使用多个 Compose 文件时,文件中的所有路径都相对于使用
-f
指定的第一个配置文件。您可以使用--project-directory
选项覆盖此基本路径。您可以将
-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.yml
文件。您可以使用类似 docker compose pull 的命令从任何地方获取db
服务的 postgres 镜像,方法是使用-f
标志,如下所示:docker compose -f ~/sandbox/rails/compose.yml pull db
以下是如何完成的示例
$ docker compose -f ~/sandbox/rails/compose.yml 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 将原始服务中的配置复制到本地服务中。如果原始服务和本地服务中都定义了配置选项,则本地值会替换或扩展原始值。
对于 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 规范中的 合并和覆盖。
示例
使用多个文件的一个常见用例是更改开发 Compose 应用程序以适应类似生产环境(可能是生产、预发布或 CI)。为了支持这些差异,您可以将 Compose 配置拆分成几个不同的文件
从定义服务的规范配置的基本文件开始。
compose.yml
services:
web:
image: example/my_web_app:latest
depends_on:
- db
- cache
db:
image: postgres:latest
cache:
image: redis:latest
在此示例中,开发配置将一些端口公开到主机,将我们的代码作为卷挂载,并构建 Web 镜像。
compose.override.yml
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.yml
services:
web:
ports:
- 80:80
environment:
PRODUCTION: 'true'
cache:
environment:
TTL: '500'
要使用此生产 Compose 文件进行部署,您可以运行
$ docker compose -f compose.yml -f compose.prod.yml up -d
这将使用 compose.yml
和 compose.prod.yml
中的配置部署所有三个服务,但不会使用 compose.override.yml
中的开发配置。
有关更多信息,请参阅 在生产环境中使用 Compose。
局限性
Docker Compose 支持为应用程序模型中要包含的许多资源指定相对路径:服务镜像的构建上下文、定义环境变量的文件位置、绑定挂载卷中使用的本地目录的路径。在这样的约束下,在 monorepo 中的代码组织可能变得困难,因为自然的选择是为每个团队或组件创建专用文件夹,但这样一来,Compose 文件的相对路径就变得无关紧要了。