迁移到 Compose V2

从 2023 年 7 月起，Compose V1 停止接收更新。它在新版本的 Docker Desktop 中也不再可用。

Compose V2 于 2020 年首次发布，包含在当前支持的所有 Docker Desktop 版本中。它提供了改进的 CLI 体验、改进的 BuildKit 构建性能以及持续的新功能开发。

如何切换到 Compose V2？

最简单且推荐的方法是确保您拥有最新版本的 Docker Desktop，它捆绑了 Docker 引擎和 Docker CLI 平台，包括 Compose V2。

借助 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命令行标志。

此更改允许您使用 root 命令上的所有共享标志docker。例如，docker --log-level=debug --tls compose up启用来自 Docker 引擎的调试日志记录并确保使用 TLS 进行连接。

提示

更新脚本以使用 Compose V2，方法是将连字符 ( -) 替换为空格，使用docker compose代替docker-compose。

服务容器名称

Compose 根据项目名称、服务名称和规模/副本计数生成容器名称。

在 Compose V1 中，使用下划线 ( _) 作为单词分隔符。在 Compose V2 中，连字符 ( -) 用作单词分隔符。

下划线不是 DNS 主机名中的有效字符。通过使用连字符，Compose V2 确保可以通过一致、可预测的主机名通过网络访问服务容器。

例如，运行 Compose 命令会生成一个以 Compose V1-p myproject up --scale=1 svc命名的容器和一个以 Compose V2 命名的容器。myproject_svc_1myproject-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 之间的以下行为有所不同：

撰写V1撰写V2
--compatibility已弃用。根据旧架构版本迁移 YAML 字段。用作_容器名称的单词分隔符，而不是-匹配 V1。
ps --filter KEY-VALUE无证。允许按任意服务属性进行过滤。只允许按特定属性进行过滤，例如--filter=status=running。

环境变量

Compose V1 中的环境变量行为没有正式记录，并且在某些边缘情况下表现不一致。

对于 Compose V2， 环境变量部分涵盖了 优先级和 .env文件插值，并包含许多涉及棘手情况的示例，例如转义嵌套引号。

检查是否：

  • 您的项目使用多个级别的环境变量覆盖，例如.env文件和--envCLI 标志。
  • 任何.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 中，在upCompose 项目上运行时，会根据需要重新创建服务容器，以达到所需状态，具体方法是将 Docker 引擎中的实际状态与已解析的项目配置（包括 Compose YAML、环境变量和命令行标志）进行比较。

由于 Compose V1 和 V2 名称服务容器不同，因此up在项目上首次使用 V2 运行且运行最初由 V1 启动的服务时，会导致使用更新的名称重新创建服务容器。

请注意，即使--compatibility使用 flag 来保留 V1 命名风格，Compose 仍然需要在 V2 第一次运行时重新创建最初由 V1 启动的服务容器up以迁移内部状态。

将 Compose V2 与 Docker-in-Docker 结合使用

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 日发布。此后，这些软件包尚未收到任何安全更新。使用风险自负。

其他资源