Docker Compose 完全指南 / 第 2 章 · 安装与配置:V2 vs V1、验证与排错
第 2 章 · 安装与配置
2.1 安装方式总览
Docker Compose V2 作为 Docker CLI 的插件分发,安装方式因平台而异:
| 平台 | 推荐方式 | 说明 |
|---|---|---|
| Linux (Ubuntu/Debian) | Docker Engine 仓库 | 最可靠,自动管理依赖 |
| Linux (CentOS/RHEL) | Docker Engine 仓库 | 同上 |
| macOS | Docker Desktop | 一站式,含 Compose |
| Windows | Docker 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):
- 访问 Docker Desktop for Mac
- 下载
.dmg文件并安装 - 启动 Docker Desktop
- 终端验证:
docker compose version
Windows:
- 确保已启用 WSL 2(Windows Subsystem for Linux)
- 下载 Docker Desktop for Windows
- 安装时勾选"Use WSL 2 instead of Hyper-V"
- 重启后验证
# 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-compose | V2 插件二进制 |
~/.docker/config.json | Docker 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 daemon | Docker 未启动 | 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 V1 | V2 是唯一推荐版本,命令为 docker compose(空格) |
| 插件位置 | ~/.docker/cli-plugins/docker-compose |
| 验证命令 | docker compose version |
| 别名过渡 | alias docker-compose='docker compose' |
扩展阅读
上一章:第 1 章 · 简介 ← | 下一章:第 3 章 · 基础语法 →