当前位置：
  1. 首页
  2. Linux
  3. 系统管理
  4. 正文

Linux 安装 Docker Compose v2 详细教程：在线安装与离线安装全方案

系统管理 0 0

装好 Docker 之后，部署多容器应用一般不会一个个 docker run 手敲，而是写一个 compose 文件，用 docker compose up -d 一把拉起来。很多离线部署脚本（比如 eda-license-manager 的 deploy.sh）第一步就是检查 docker compose 在不在——不在就直接报错退出。本文以 Docker Compose v2.24.6 为例，把在线安装、离线二进制安装、离线 RPM/DEB 包安装三种方法讲清楚，顺带把 v1 和 v2 的区别、插件查找路径和常见报错一次说透。

1. 先分清：v1 和 v2 是两个东西

项目Compose v1（已停止维护）Compose v2（当前主流）
命令docker-compose（带横杠，独立命令）docker compose（空格，docker 的子命令）
实现形式Python 写的独立程序Go 写的 docker CLI 插件
安装方式下载一个 docker-compose 二进制放进 PATH下载插件放进 cli-plugins 目录，或装 docker-compose-plugin 包
配置文件docker-compose.ymlcompose.yaml / compose.yml / docker-compose.yml 都认
状态2023 年 7 月已停止维护，不再发新版持续更新，Docker 官方唯一推荐的版本

记住一条就行：现在只装 v2。v1 早就停更了，新写的部署脚本用的都是 docker compose（空格）。如果你手头的老脚本还写着 docker-compose（横杠），第 9.4 节有兼容办法。

2. 版本选择

本文用 Compose v2.24.6，和 Docker 25.0.4 是同一时期发布的版本，搭配使用没问题。实测信息如下（2026-11-10 验证过下载链接有效）：

架构下载地址大小
x86_64https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-x86_6461,431,093 字节（约 58.6 MiB）
aarch64https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-aarch64约 60 MiB

想用更新的版本也行，下载地址里的 v2.24.6 换成新版本号即可，安装步骤完全一样。最新版本号去 https://github.com/docker/compose/releases 查看。Compose v2 对 Docker Engine 的要求不高，20.10 及以上就能用，搭配 Docker 25.0.4 完全没问题。

3. 方法一：在线安装（有外网的机器）

已经配好 Docker 官方软件源的机器，一条命令就装好，连带把插件放到正确位置：

# RHEL / CentOS / Rocky（需要先配好 Docker 官方 yum 源）
dnf install -y docker-compose-plugin

# Ubuntu / Debian（需要先配好 Docker 官方 apt 源）
apt-get update
apt-get install -y docker-compose-plugin

# 验证
docker compose version
# 输出：Docker Compose version v2.24.6

如果装 Docker 的时候已经勾上了 docker-compose-plugin，这一步就不用重复做，直接验证即可。离线环境走不了这条路，看下面两种方法。

4. 方法二：离线安装 standalone 二进制（推荐）

这是离线环境最省事的方法：就一个文件，下载、传过去、放进插件目录、加执行权限，四步完事。不挑发行版，RHEL、Ubuntu、Debian 通用。

4.1 在联网机上下载

# x86_64（绝大多数服务器）
curl -SL https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-x86_64 -o docker-compose

# aarch64（ARM 服务器）
curl -SL https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-aarch64 -o docker-compose

# 核对大小（x86_64 应为 61431093 字节）
ls -l docker-compose
# 有 sha256 校验需求的，可以顺带下载校验文件
curl -SL https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-x86_64.sha256 -o docker-compose.sha256
sha256sum -c docker-compose.sha256

注意用 -L 参数：GitHub 的 release 下载地址会 302 跳转到对象存储，不加 -L 下回来的会是个几 KB 的跳转页而不是真正的二进制。

4.2 传到目标机

scp docker-compose root@目标机IP:/root/
# 只能通过跳板机访问时加 -J
scp -J 跳板机用户@跳板机IP docker-compose root@目标机IP:/root/

4.3 放进插件目录并加执行权限

# 系统级插件目录（所有用户都能用 docker compose）
mkdir -p /usr/local/lib/docker/cli-plugins
cp docker-compose /usr/local/lib/docker/cli-plugins/docker-compose
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

# 只给当前用户用的话，放用户级目录也行（不用 sudo）
mkdir -p ~/.docker/cli-plugins
cp docker-compose ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

关键点就两个：文件名必须是 docker-compose（docker CLI 靠这个名字识别插件），必须有执行权限（没 chmod +x 的话 docker 会直接说找不到这个命令）。

4.4 验证

docker compose version
# 输出：Docker Compose version v2.24.6

# 不依赖 daemon 也能验证（version 是纯客户端命令）
# 想进一步验证它能正常干活：
docker compose config --help | head -5

5. 方法三：离线安装 docker-compose-plugin 包

如果你更习惯用包管理器管理（以后升级、卸载都走 dnf/apt），可以把插件包也离线下载下来装。包的名字就叫 docker-compose-plugin：

# === 联网机上（RHEL 系示例）===
mkdir -p ~/compose-rpm && cd ~/compose-rpm
dnf download --resolve docker-compose-plugin
# 产物：docker-compose-plugin-2.24.6-1.el9.x86_64.rpm（以实际版本为准）

# === 联网机上（Ubuntu/Debian 示例）===
mkdir -p ~/compose-deb && cd ~/compose-deb
apt-get download docker-compose-plugin
# 产物：docker-compose-plugin_2.24.6-1~ubuntu.22.04~jammy_amd64.deb

# === 目标机上 ===
scp -r ~/compose-rpm root@目标机IP:/root/     # 或 compose-deb
cd /root/compose-rpm
dnf install -y ./*.rpm                          # RHEL 系
# dpkg -i *.deb                                  # Ubuntu/Debian 系

docker compose version

包安装方式会把插件放到 /usr/libexec/docker/cli-plugins/docker-compose，和手动放 /usr/local/lib/docker/cli-plugins/ 效果一样。两种方法不要混着装——装了包又手动放一个同名插件，docker 会按查找顺序用第一个找到的，版本容易对不上。

6. 插件查找路径详解

很多人装完报“找不到 compose 命令”，其实是放错了地方。docker CLI 启动时按顺序在这些目录里找名叫 docker-compose 的可执行文件：

顺序目录说明
1~/.docker/cli-plugins/用户级，只对当前用户生效
2/usr/local/lib/docker/cli-plugins/系统级，手动安装推荐放这里
3/usr/lib/docker/cli-plugins/系统级，部分发行版的包放这里
4/usr/libexec/docker/cli-plugins/系统级，dnf/apt 装的 docker-compose-plugin 放这里
# 快速定位插件到底在哪（或到底有没有）
ls -la ~/.docker/cli-plugins/ /usr/local/lib/docker/cli-plugins/ \
  /usr/lib/docker/cli-plugins/ /usr/libexec/docker/cli-plugins/ 2>&1 | grep -i compose

# 让 docker 自己告诉你它找到了哪些插件
docker info 2>/dev/null | grep -i -A5 'Plugins'
# 或
docker system info --format '{{json .ClientInfo.Plugins}}' | python3 -m json.tool 2>/dev/null

7. 验证与常用命令

装完先验证版本，再拿一个最小的 compose 文件做一次端到端测试，确认 up、ps、down 整条链路都通：

# 1. 版本
docker compose version

# 2. 最小测试（需要一个能用的镜像；离线机先 docker load 导入镜像）
mkdir -p /tmp/compose-test && cd /tmp/compose-test
cat > compose.yaml <<'EOF'
services:
  web:
    image: nginx:1.25.4
    ports:
      - "18080:80"
EOF
docker compose up -d
docker compose ps
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:18080   # 应输出 200
docker compose down
cd /tmp && rm -rf /tmp/compose-test
命令作用
docker compose up -d按 compose 文件后台启动全部服务
docker compose ps查看这个项目下的容器状态
docker compose logs -f跟踪全部服务的日志
docker compose config校验并输出解析后的 compose 配置（排错神器）
docker compose down停止并删除容器和网络（默认不删卷）
docker compose down -v连同匿名卷一起删除
docker compose pull拉取 compose 文件里引用的全部镜像
docker compose restart重启项目下的全部服务

8. 离线环境用 Compose 的注意事项

  • 镜像要先备好：离线机上 docker compose up 遇到本地没有的镜像会尝试联网拉取，必然失败。先在联网机上 docker pull 再 docker save 打包，传到目标机 docker load 导入，或者直接把 pull_policy: never 写进 compose 文件，强制只用本地镜像。
  • compose 文件里的 version 字段会报 obsolete：v2 会忽略顶层的 version: '3.8' 并打印警告，不影响运行。新写的 compose 文件直接去掉 version 这一行。
  • 注意文件名：v2 默认按顺序找 compose.yaml、compose.yml、docker-compose.yaml、docker-compose.yml，四个都认；不在当前目录时用 -f 指定，如 docker compose -f /opt/offline-package/compose.offline.yaml up -d。
  • 项目名决定容器名前缀：默认取 compose 文件所在目录名，同一目录下两个项目会串。部署脚本一般用 -p 项目名 显式指定，避免和别的项目冲突。

9. 常见问题排查

9.1 docker compose: 'compose' is not a docker command

最常见的报错，意思是 docker CLI 没找到 compose 插件。按顺序查：

# 1. 插件文件在不在第 6 节说的四个目录里
ls -la /usr/local/lib/docker/cli-plugins/docker-compose
# 2. 有没有执行权限（没有就补）
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
# 3. 文件名对不对（必须是 docker-compose，不能是 docker-compose-linux-x86_64）
# 4. 是不是下错了架构
file /usr/local/lib/docker/cli-plugins/docker-compose
# 应显示 ELF 64-bit LSB executable, x86-64；显示 ARM aarch64 就是下错了，重新下 x86_64 的

9.2 下回来的文件只有几 KB，执行报 Exec format error

下载时没加 -L，下回来的是 GitHub 的 302 跳转页（HTML 文本），不是二进制。检查文件类型：

file docker-compose
# 正常：ELF 64-bit LSB executable, x86-64
# 异常：HTML document text 或 ASCII text，说明下载错了，重新用 curl -SL 下
head -c 200 docker-compose   # 看到 <html> 之类的内容就是下错了

9.3 部署脚本用的是 docker-compose（老式横杠命令）

有些老部署脚本里写的是 docker-compose up -d，装了 v2 插件也没用，因为 v2 只认 docker compose（空格）。两个办法：改脚本里的命令（推荐，一劳永逸），或者建一个兼容软链应急：

# 应急兼容：让 docker-compose 这个命令转发给 docker compose
cat > /usr/local/bin/docker-compose <<'EOF'
#!/bin/sh
exec docker compose "$@"
EOF
chmod +x /usr/local/bin/docker-compose
docker-compose version   # 应输出和 docker compose version 一样的版本号

9.4 sudo 下用不了，但 root / 普通用户下能用

插件放在用户级目录（~/.docker/cli-plugins/）时，sudo ./deploy.sh 会以 root 身份运行，root 的 ~/.docker/ 里没有插件，自然找不到。部署脚本如果用 sudo 跑，插件必须放在系统级目录（/usr/local/lib/docker/cli-plugins/），不要放用户级目录。

9.5 compose up 报拉取镜像失败（离线机）

# 先确认镜像在本地
docker images | grep -E '镜像名'
# 不在就先 docker load 导入，再 up；或在 compose 文件里加 pull_policy: never
# services:
#   web:
#     image: nginx:1.25.4
#     pull_policy: never

10. 卸载

# 手动二进制安装的卸载：删插件文件即可
rm -f /usr/local/lib/docker/cli-plugins/docker-compose
rm -f ~/.docker/cli-plugins/docker-compose
rm -f /usr/local/bin/docker-compose   # 如果建过 9.3 节的兼容软链

# 包安装的卸载
dnf remove -y docker-compose-plugin
# 或 apt-get purge -y docker-compose-plugin

docker compose version   # 应报 'compose' is not a docker command，说明卸干净了

11. 附录：速查表

项目内容
当前版本v2.24.6（与 Docker 25.0.4 同期）
下载地址https://github.com/docker/compose/releases/download/v2.24.6/docker-compose-linux-x86_64
系统级插件目录/usr/local/lib/docker/cli-plugins/docker-compose
用户级插件目录~/.docker/cli-plugins/docker-compose
包名docker-compose-plugin（dnf/apt）
验证命令docker compose version
常用命令up -d / ps / logs -f / config / down / pull

离线装 Compose 就记住一条主线：一个二进制文件 + 一个插件目录 + 一个执行权限。在线环境直接装 docker-compose-plugin 包最省事，离线环境下载 standalone 二进制最通用。装完先跑 docker compose version，再拿最小 compose 文件做一次 up / down 闭环验证——部署脚本里 docker compose 能跑通，后面的部署才不会卡在第一步。

上一篇 Linux 离线安装 Docker 25.0.4 详细教程：静态二进制与 RPM/DEB 离线包全方案

相关文章

发表回复

后才能评论