Linux 安装 Docker Compose 教程

1.1 Docker Compose 是什么？

Docker Compose 是用于定义和运行多容器 Docker 应用的工具。它通过一个声明式的 YAML 文件（通常命名为 compose.yaml 或 docker-compose.yml），描述应用由哪些服务（services）、网络（networks）、卷（volumes）等组成，然后用一条命令即可创建、启动、停止或销毁整套环境。

它本身并不替代 Docker Engine，而是构建在 Docker Engine 之上，负责编排多个容器之间的依赖、网络连通性和生命周期管理。对于单机开发、测试和轻量运维场景，Compose 是最常见的多容器管理方式。

更完整的背景可参考官方文档：History and development of Docker Compose。

1.2 Docker、Docker CLI 与 Compose 的关系

理解这三个组件的分工，有助于判断“我到底缺什么”。

• Docker Engine：真正的容器运行时，负责创建、运行、管理容器和镜像。没有 Engine，容器无法运行。
• Docker CLI：命令行客户端（docker 命令），通过 API 与 Engine 通信。用户日常执行的 docker run、docker build 等都经由 CLI。
• Docker Compose：在 CLI 之上（或作为 CLI 插件）工作的编排工具。它读取 Compose 文件，把服务定义翻译成对 Docker Engine 的一系列操作。

简单来说：Engine 负责“跑”，CLI 负责“发指令”，Compose 负责“按文件批量发指令并管理依赖”。Compose 插件安装后，会以 docker compose 子命令的形式出现在 Docker CLI 中。

1.3 Compose V1、V2 与 V5 的区别

官方文档明确区分了 Compose CLI 的版本演进与 Compose 文件格式版本，二者不能混为一谈。

截至目前，官方支持的 Compose CLI 版本是 Compose v2 和 Compose v5，二者均基于 Compose Specification。

维度	Compose V1	Compose V2	Compose V5
产品形态	独立 Python 程序	用 Go 实现的 Docker CLI 插件	功能上与 V2 相同，新增官方 Go SDK
常用命令	docker-compose	docker compose	同样使用 docker compose
安装形式	独立二进制或包	通常作为 Docker CLI 插件安装	同样作为 CLI 插件（当前主流版本）
与 Docker CLI 的关系	独立程序，不集成到 docker 命令	作为插件深度集成	同 V2，并提供可嵌入应用的 SDK
文件格式处理	依赖文件中的 version 字段（2.x / 3.x）	忽略 version 字段，遵循 Compose Specification	同 V2
维护状态与建议	已停止更新（最终版本 1.29.2，2021 年），不推荐新部署使用	长期支持的现代实现	2025 年发布，功能与 V2 相同，当前主流版本线

关键说明：

• Compose V1：2014 年发布，Python 实现，命令带连字符（docker-compose）。从 2023 年中期起停止更新，且已不再出现在新版 Docker Desktop 中。旧项目若仍依赖它，应计划迁移，而不是继续扩大使用范围。
• Compose V2：2020 年宣布，Go 实现，命令改为空格形式（docker compose）。它忽略 Compose 文件中的顶层 version 字段，统一按 Compose Specification 解析。这是现代 Linux 环境的推荐基础。
• Compose V5：2025 年发布。官方明确指出它与 V2 功能相同，主要区别是引入了官方 Go SDK，方便在应用程序中直接嵌入 Compose 能力，而不必通过 CLI。版本号直接跳到 v5，是为了避免与旧版 Compose 文件格式（2.x / 3.x）混淆。因此，看到 docker compose version 输出 5.x 时，不必惊慌，它并非另一套编排系统。

注意：Compose 文件中的 version: “3.8” 这类字段，属于文件格式版本，与 CLI 的 V1/V2/V5 是不同概念。现代 Compose（V2/V5）已不再依赖该字段。

官方权威说明见：

• History and development of Docker Compose
• Frequently asked questions about Docker Compose

1.4 docker compose 与 docker-compose 有什么区别？

两者看起来相似，实际指向不同实现，检查结果也可能不同。

先执行下面两条命令，观察系统实际状态：

# 检查 Docker CLI 是否能识别 Compose 插件（推荐方式）
docker compose version

# 检查系统是否存在独立的 docker-compose 命令（旧式）
docker-compose --version

说明：

• docker compose version（无连字符）用于验证现代 Compose 插件是否已正确安装。如果输出类似 Docker Compose version v2.x.x 或 v5.x.x，说明插件可用。
• docker-compose –version（有连字符）检查的是独立可执行文件。即使该命令不存在，也不代表现代 Compose 插件未安装。
• 两者的版本号和实现可以完全不同。系统上可能同时存在旧式独立程序和现代插件，也可能只有其中一种。

推荐做法：新部署和日常操作优先使用 docker compose。旧项目或脚本仍在使用 docker-compose 时，应先确认当前实际安装形式，再决定是否添加兼容别名或修改脚本，而不是为了“让旧命令存在”去安装来源不明的旧版程序。

官方 FAQ 对此有清晰说明：What is the difference between docker compose and docker-compose。

1.5 我是否需要单独安装 Docker Compose？

根据当前环境判断即可，不必盲目安装。

当前环境	是否需要单独安装 Compose	建议操作
已安装 Docker Desktop	通常不需要	Desktop 已包含 Engine、CLI 和 Compose。可用 docker compose version 确认
已安装 Docker Engine + Docker CLI	先检查，再决定	执行 docker compose version。若提示找不到命令，再按官方方式安装 Compose 插件
只安装了 Docker CLI	需要确认完整环境	CLI 本身不能运行容器。需确认能连上可用的 Engine，并安装 Compose 插件
尚未安装 Docker	需要完整安装	优先按发行版安装 Docker Engine、CLI 和 Compose 插件（后续章节详述）
无法使用官方软件仓库	可手动安装插件	可下载 CLI 插件二进制，但需自行管理升级与校验，维护成本更高

核心提醒：

• Docker CLI、Docker Engine、Compose 插件是不同组件。仅安装 CLI 并不等于具备完整运行环境。
• Docker Desktop 是“全家桶”方案，适合桌面和开发机；服务器环境更常见的是单独安装 Engine + CLI + Compose 插件。
• 官方推荐的安装入口见：Overview of installing Docker Compose 和 Install the Docker Compose plugin。

Linux 安装 Docker Compose 插件

本章适用于已安装 Docker Engine 与 Docker CLI 的 AlmaLinux 9 系统，目标是安装官方 Docker Compose CLI 插件，使 docker compose 命令可用。不涉及重新安装 Docker，也不以旧版独立命令 docker-compose 为目标。

3.1 检查现有环境

先确认 Docker CLI 是否可用，以及 Compose 插件是否已经存在。

docker --version

正常输出会显示 Docker 版本号，说明 Docker CLI 已安装。如果 Docker 尚未安装，则应先按照对应发行版的官方文档配置 Docker 仓库，并安装 Engine、CLI 和 Compose 插件。

3.2 安装 Docker Compose plgin

Docker Compose plgin包来自 Docker 官方仓库。若系统尚未配置该仓库，需要先添加；若已配置，可直接安装。

Debian / Ubuntu：安装 Compose 插件

如果已经正确配置 Docker 官方 APT 仓库：

sudo apt update
sudo apt install docker-compose-plugin

该命令仅安装 docker-compose-plugin 包，不会重新安装 Docker Engine 或 Docker CLI。安装完成后无需重启系统。

AlmaLinux / RHEL：安装 Compose 插件

如果已经配置 Docker 官方 RPM 仓库：

sudo dnf install docker-compose-plugin

该命令仅安装 docker-compose-plugin 包，不会重新安装 Docker Engine 或 Docker CLI。安装完成后无需重启系统。

3.3 验证安装结果

检查版本：

docker compose version

成功时会显示 Compose 版本号（当前常见为 v2.x 或 v5.x）。只要命令能正常输出版本信息，即可确认插件已正确安装。

3.4 常见问题速查

1. docker compose 提示无法识别 compose 子命令

原因：插件未安装，或 Docker CLI 未找到插件。

排查：

docker compose version
rpm -q docker-compose-plugin

若未安装，按 3.2 节安装；若已安装但仍失败，检查插件是否位于 Docker CLI 的插件搜索路径中。

2. DNF 找不到 docker-compose-plugin 软件包

原因：Docker 官方仓库未配置，或仓库未启用。

排查：

dnf repolist | grep docker
sudo dnf clean all
sudo dnf makecache

确认仓库出现后，再执行 sudo dnf install docker-compose-plugin。若仓库地址有误，重新按 3.2 节添加官方 repo。

3. Docker 官方 RPM 仓库未配置或无法访问

原因：网络限制、仓库文件缺失或 GPG 问题。

排查：

ls /etc/yum.repos.d/docker-ce.repo
curl -I https://download.docker.com/linux/rhel/docker-ce.repo

若网络不通，可考虑手动下载 RPM 包安装（见官方 Install from a package），但需自行管理升级。

4. docker compose version 成功，但执行项目时提示无法连接 Docker daemon

原因：这是 Docker 守护进程问题，与 Compose 插件本身无关。

排查：

sudo systemctl status docker
sudo systemctl start docker

确认 dockerd 正在运行，且当前用户有权限连接 Docker 套接字。

5. 普通用户遇到权限错误

原因：用户未加入 docker 组，或会话未刷新。

排查与处理：

groups
sudo usermod -aG docker $USER

执行后需重新登录或使用 newgrp docker 使组权限生效。加入 docker 组相当于获得较高权限，仅添加受信任用户。

安装完成后，即可使用 docker compose 管理多容器应用。