强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

Docker Compose 完全指南 / 第 2 章 · 安装与配置:V2 vs V1、验证与排错

第 2 章 · 安装与配置

2.1 安装方式总览

Docker Compose V2 作为 Docker CLI 的插件分发,安装方式因平台而异:

平台推荐方式说明
Linux (Ubuntu/Debian)Docker Engine 仓库最可靠,自动管理依赖
Linux (CentOS/RHEL)Docker Engine 仓库同上
macOSDocker Desktop一站式,含 Compose
WindowsDocker Desktop + WSL2必须通过 WSL2 运行
通用二进制手动下载插件适用于离线/受限环境

2.2 Linux 安装(推荐方式)

2.2.1 安装 Docker Engine(含 Compose 插件)

从 Docker 官方仓库安装,Compose V2 会作为 docker-compose-plugin 自动包含。

Ubuntu / Debian:

# 1. 卸载旧版本(如有)
sudo apt-get remove docker docker-engine docker.io containerd runc 2>/dev/null

# 2. 安装依赖
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 3. 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 4. 添加仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. 安装 Docker Engine + CLI + Compose 插件
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# 6. 将当前用户加入 docker 组(免 sudo)
sudo usermod -aG docker $USER
newgrp docker

CentOS / RHEL / Fedora:

# 1. 卸载旧版本
sudo yum remove docker docker-client docker-client-latest \
  docker-common docker-latest docker-latest-logrotate \
  docker-logrotate docker-engine 2>/dev/null

# 2. 安装 yum-utils
sudo yum install -y yum-utils

# 3. 添加仓库
sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

# 4. 安装
sudo yum install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# 5. 启动 Docker
sudo systemctl start docker
sudo systemctl enable docker

# 6. 免 sudo
sudo usermod -aG docker $USER
newgrp docker

2.2.2 验证安装

# 检查 Docker Engine
docker --version
# Docker version 27.x.x, build xxxxxxx

# 检查 Compose 插件(注意是空格,不是连字符)
docker compose version
# Docker Compose version v2.x.x

# 检查 Compose 版本详情
docker compose version --short
# 2.x.x

⚠️ 注意:如果输出 docker: 'compose' is not a docker command,说明 Compose 插件未正确安装。请确认安装了 docker-compose-plugin 包。


2.3 macOS / Windows 安装

Docker Desktop(推荐)

Docker Desktop 是 macOS 和 Windows 上最简单的安装方式,已内置 Compose。

macOS (Apple Silicon / Intel):

  1. 访问 Docker Desktop for Mac
  2. 下载 .dmg 文件并安装
  3. 启动 Docker Desktop
  4. 终端验证:
docker compose version

Windows:

  1. 确保已启用 WSL 2(Windows Subsystem for Linux)
  2. 下载 Docker Desktop for Windows
  3. 安装时勾选"Use WSL 2 instead of Hyper-V"
  4. 重启后验证
# PowerShell 或 CMD
docker compose version

💡 WSL2 性能提示:将项目文件放在 WSL2 文件系统内(如 \\wsl$\Ubuntu\home\user\project),而非 Windows 盘符(C:\),I/O 性能可提升 5-10 倍。


2.4 手动安装(二进制方式)

适用于无法使用包管理器的场景(离线环境、CI Runner 等)。

# 获取最新版本号(或手动指定)
COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest \
  | grep '"tag_name"' | sed -E 's/.*"v([^"]+)".*/\1/')

# 下载二进制(x86_64 架构)
mkdir -p ~/.docker/cli-plugins/
curl -SL "https://github.com/docker/compose/releases/download/v${COMPOSE_VERSION}/docker-compose-linux-x86_64" \
  -o ~/.docker/cli-plugins/docker-compose

# 赋予执行权限
chmod +x ~/.docker/cli-plugins/docker-compose

# 验证
docker compose version

ARM64 架构(如 Apple Silicon、AWS Graviton):

# 替换 URL 中的架构标识
curl -SL "https://github.com/docker/compose/releases/download/v${COMPOSE_VERSION}/docker-compose-linux-aarch64" \
  -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

2.5 V1 残留与清理

如果你的系统上还存在旧版 docker-compose(V1),建议清理。

检查是否有 V1 残留

# V1 使用连字符
docker-compose --version
# 如果输出版本号,说明有 V1 残留

# V2 使用空格
docker compose version

卸载 V1

# pip 安装的
pip uninstall docker-compose

# 二进制安装的
sudo rm /usr/local/bin/docker-compose

# apt 安装的
sudo apt-get remove docker-compose

V1 与 V2 兼容性

特性V1 → V2 兼容性
docker-compose.yml 文件✅ 完全兼容
version: "3.x" 字段✅ 兼容(但建议删除)
docker-compose 命令⚠️ 需改为 docker compose
v2 / v3 功能合并✅ V2 统一支持
extends 关键字✅ 支持
links 关键字⚠️ 仍支持但不推荐,用网络替代

💡 兼容别名:如果习惯 V1 命令格式,可设置 shell 别名过渡:

# ~/.bashrc 或 ~/.zshrc
alias docker-compose='docker compose'

2.6 安装 Docker Compose 独立 V2(不依赖 Docker CLI)

某些 CI 环境可能需要独立的 docker-compose 二进制(兼容 V1 命令格式):

# Docker 官方提供了兼容 V1 语法的 V2 独立二进制
# 文件名仍为 docker-compose,但内核是 V2 (Go)

# 下载
COMPOSE_VERSION="v2.29.1"  # 替换为实际版本
sudo curl -SL \
  "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-x86_64" \
  -o /usr/local/bin/docker-compose

sudo chmod +x /usr/local/bin/docker-compose

# 验证
docker-compose --version

2.7 Shell 自动补全

Bash

# 下载补全脚本
sudo curl -L https://raw.githubusercontent.com/docker/compose/v2/contrib/completion/bash/docker-compose \
  -o /etc/bash_completion.d/docker-compose

# 重新加载
source /etc/bash_completion.d/docker-compose

Zsh

# 下载补全脚本
mkdir -p ~/.zsh/completion
curl -L https://raw.githubusercontent.com/docker/compose/v2/contrib/completion/zsh/_docker-compose \
  -o ~/.zsh/completion/_docker-compose

# ~/.zshrc 中添加
fpath=(~/.zsh/completion $fpath)
autoload -Uz compinit && compinit

Fish

# 下载补全脚本
mkdir -p ~/.config/fish/completions
curl -L https://raw.githubusercontent.com/docker/compose/v2/contrib/completion/fish/docker-compose.fish \
  -o ~/.config/fish/completions/docker-compose.fish

2.8 配置文件位置

Docker Compose 使用以下配置路径:

文件/目录用途
~/.docker/cli-plugins/docker-composeV2 插件二进制
~/.docker/config.jsonDocker CLI 配置(含 Compose 相关)
compose.yaml / docker-compose.yml项目级 Compose 配置
.env项目级环境变量文件

自定义 Compose 配置目录

# 查看 Docker 配置目录
docker info --format '{{.DockerRootDir}}'
# /var/lib/docker

# Compose 临时文件位置
ls /tmp/compose-*

2.9 验证安装:完整检查清单

运行以下脚本,确认环境就绪:

#!/bin/bash
echo "=== Docker Compose 环境检查 ==="

# 1. Docker Engine
echo -n "Docker Engine: "
docker --version 2>/dev/null || echo "❌ 未安装"

# 2. Docker 守护进程
echo -n "Docker Daemon: "
docker info >/dev/null 2>&1 && echo "✅ 运行中" || echo "❌ 未运行"

# 3. Compose V2
echo -n "Compose V2: "
docker compose version >/dev/null 2>&1 && echo "✅ $(docker compose version --short)" || echo "❌ 未安装"

# 4. 旧版 V1
echo -n "Compose V1: "
docker-compose --version 2>/dev/null && echo "⚠️ 建议卸载" || echo "✅ 未安装(或已是V2别名)"

# 5. Buildx
echo -n "Buildx: "
docker buildx version >/dev/null 2>&1 && echo "✅ $(docker buildx version --short)" || echo "⚠️ 未安装(可选)"

# 6. Shell 补全
echo -n "Shell 补全: "
type _docker_compose >/dev/null 2>&1 && echo "✅ 已配置" || echo "⚠️ 未配置(可选)"

echo ""
echo "=== 快速功能测试 ==="

# 7. Compose 功能测试
cd /tmp && mkdir -p compose-test && cd compose-test
cat > compose.yaml << 'EOF'
services:
  hello:
    image: hello-world
EOF

docker compose up 2>/dev/null
if [ $? -eq 0 ]; then
  echo "✅ Compose 功能正常"
else
  echo "❌ Compose 功能异常"
fi

cd /tmp && rm -rf compose-test

2.10 常见安装问题

问题原因解决方案
docker: 'compose' is not a docker command插件未安装安装 docker-compose-plugin
permission denied用户不在 docker 组sudo usermod -aG docker $USER
Cannot connect to the Docker daemonDocker 未启动sudo systemctl start docker
下载速度慢网络问题使用国内镜像或代理
Apple Silicon 兼容问题架构不匹配下载 aarch64 版本

国内镜像配置

# Docker daemon 镜像加速(/etc/docker/daemon.json)
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://docker.1panel.live"
  ]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

2.11 小结

要点说明
推荐安装方式Linux: 官方仓库;macOS/Windows: Docker Desktop
V2 vs V1V2 是唯一推荐版本,命令为 docker compose(空格)
插件位置~/.docker/cli-plugins/docker-compose
验证命令docker compose version
别名过渡alias docker-compose='docker compose'

扩展阅读


上一章:第 1 章 · 简介 ← | 下一章:第 3 章 · 基础语法 →