從 Docker Compose v1 遷移到 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 訪問。

對於 Linux 上的手動安裝，您可以透過以下方式獲取 Compose v2：

Compose v1 和 Compose v2 之間有什麼區別？

docker-compose vs 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 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 日釋出。此後這些軟體包未收到任何安全更新。使用風險自負。

其他資源