迁移到 Compose V2

目录

从 2023 年 7 月开始，Compose V1 停止接收更新。它也不再包含在 Docker Desktop 的新版本中。

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

如何切换到 Compose V2？

最简单且推荐的方式是确保您拥有最新版本的 Docker Desktop，它捆绑了 Docker Engine 和 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 命令行标志。

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

提示

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

服务容器名称

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 V1 迁移到 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 V1Compose V2
--compatibility已弃用。根据旧版架构版本迁移 YAML 字段。使用 _ 作为容器名称的词语分隔符，而不是 -，以匹配 V1。
ps --filter KEY-VALUE未记录。允许按任意服务属性进行过滤。仅允许按特定属性进行过滤，例如 --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 以不同的方式命名服务容器，因此在最初由 V1 启动的服务项目上第一次使用 V2 运行 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 日。从那时起，这些软件包没有收到任何安全更新。使用风险自负。

其他资源