迁移到 Compose V2
自 2023 年 7 月起,Compose V1 已停止接收更新。在新的 Docker Desktop 版本中也不再可用。
Compose V2 于 2020 年首次发布,已包含在所有当前支持的 Docker Desktop 版本中。它提供了改进的 CLI 体验、使用 BuildKit 改进的构建性能以及持续的新功能开发。
如何切换到 Compose V2?
最简单且推荐的方式是确保您拥有最新版本的 Docker Desktop,它捆绑了 Docker Engine 和包括 Compose V2 在内的 Docker CLI 平台。
使用 Docker Desktop,Compose V2 始终可以通过 docker compose
访问。此外,默认情况下会开启 使用 Compose V2 设置,该设置提供了从 docker-compose
的别名。
对于 Linux 上的手动安装,您可以通过以下方式获取 Compose V2:
Compose V1 和 Compose V2 之间有什么区别?
docker-compose
与 docker compose
与 Compose V1 不同,Compose V2 集成到 Docker CLI 平台中,推荐的命令行语法是 docker compose
。
Docker CLI 平台提供了一组一致且可预测的选项和标志,例如 DOCKER_HOST
环境变量或 --context
命令行标志。
此更改允许您在根 docker
命令上使用所有共享标志。例如,docker --log-level=debug --tls compose up
启用来自 Docker Engine 的调试日志记录,并确保连接使用 TLS。
提示
更新脚本以使用 Compose V2,将连字符 (
-
) 替换为空格,即使用docker compose
而不是docker-compose
。
服务容器名称
Compose 根据项目名称、服务名称和扩展/副本计数生成容器名称。
在 Compose V1 中,下划线 (_
) 用作单词分隔符。在 Compose V2 中,连字符 (-
) 用作单词分隔符。
下划线不是 DNS 主机名中的有效字符。通过使用连字符代替,Compose V2 确保可以通过一致、可预测的主机名在网络上访问服务容器。
例如,运行 Compose 命令 -p myproject up --scale=1 svc
,Compose V1 会生成名为 myproject_svc_1
的容器,而 Compose V2 会生成名为 myproject-svc-1
的容器。
提示
在 Compose V2 中,全局
--compatibility
标志或COMPOSE_COMPATIBILITY
环境变量保留了 Compose V1 使用下划线 (_
) 作为单词分隔符的行为。由于此选项必须为每个运行的 Compose V2 命令指定,因此建议您仅将其用作过渡到 Compose V2 时的临时措施。
命令行标志和子命令
Compose V2 支持几乎所有 Compose V1 的标志和子命令,因此在大多数情况下,它可以在脚本中直接替换使用。
V2 中不支持
以下内容在 Compose V1 中已弃用,且在 Compose V2 中不受支持
docker-compose scale
。请改用docker compose up --scale
。docker-compose rm --all
V2 中不同
以下内容在 Compose V1 和 V2 之间的行为不同
Compose V1 | Compose V2 | |
---|---|---|
| 已弃用。根据旧版 schema 版本迁移 YAML 字段。 | 使用 _ 作为容器名称的单词分隔符,而不是 - ,以匹配 V1。 |
| 未文档化。允许按任意服务属性进行过滤。 | 仅允许按特定属性进行过滤,例如 --filter=status=running 。 |
环境变量
Compose V1 中的环境变量行为并未正式文档化,并且在某些边缘情况下表现不一致。
对于 Compose V2,环境变量 部分涵盖了 优先级 以及 .env
文件插值,并包含许多涵盖复杂情况(如转义嵌套引号)的示例。
检查是否
- 您的项目使用了多层环境变量覆盖,例如
.env
文件和--env
CLI 标志。 - 任何
.env
文件值包含转义序列或嵌套引号。 - 任何
.env
文件值包含字面量$
符号。这在 PHP 项目中很常见。 - 任何变量值使用高级扩展语法,例如
${VAR:?error}
。
提示
在项目上运行
docker compose config
,以预览 Compose V2 执行插值后的配置,验证值是否如预期所示。与 Compose V1 保持向后兼容通常可以通过确保字面量值(无插值)使用单引号,而应应用插值的值使用双引号来实现。
这对使用 Compose V1 的项目意味着什么?
对于大多数项目而言,切换到 Compose V2 无需更改 Compose YAML 文件或您的开发工作流程。
建议您适应运行 Compose V2 的新首选方式,即使用 docker compose
而不是 docker-compose
。这提供了额外的灵活性,并消除了对 docker-compose
兼容性别名的需求。
但是,Docker Desktop 继续支持 docker-compose
别名,以将命令重定向到 docker compose
,从而方便使用并提高与第三方工具和脚本的兼容性。
在切换之前我还需要知道什么?
迁移正在运行的项目
在 V1 和 V2 中,对 Compose 项目运行 up
会根据 Docker Engine 中的实际状态与解析的项目配置(包括 Compose YAML、环境变量和命令行标志)进行比较,按需重新创建服务容器以达到所需状态。
由于 Compose V1 和 V2 命名服务容器的方式不同,在首次使用 V2 运行由 V1 启动的正在运行服务的项目时,运行 up
会导致服务容器以更新的名称重新创建。
请注意,即使使用 --compatibility
标志保留 V1 的命名风格,Compose 在首次由 V2 运行 up
时,仍然需要重新创建由 V1 启动的服务容器,以便迁移内部状态。
在 Docker-in-Docker 中使用 Compose V2
Compose V2 现已包含在 Docker Hub 上的 Docker 官方镜像中。
此外,一个新的 Docker Hub 上的 docker/compose-bin 镜像 打包了最新版本的 Compose V2,可用于多阶段构建。
如果我愿意,还可以继续使用 Compose V1 吗?
是的。您仍然可以下载和安装 Compose V1 包,但如果出现问题,Docker 将不提供支持。
警告
Compose V1 的最终版本 1.29.2 发布于 2021 年 5 月 10 日。此后这些包没有收到任何安全更新。请自行承担风险使用。