Docker Compose 安装问题排查全记录（WSL2 Ubuntu 22.04 环境）

Docker Compose 安装问题排查全记录（WSL2 Ubuntu 22.04 环境）

一、核心问题

在 WSL2 下的 Ubuntu 22.04 系统中，始终无法通过 docker compose 命令调用 Docker Compose V2 插件，具体表现为：

1. 执行 docker compose version 报错 docker: unknown command: docker compose；
2. 安装 docker-compose-plugin 后，插件文件未被 Docker CLI 识别；
3. 执行 docker info | grep -i "plugin" 显示所有 Docker 插件（含 docker-compose）因 input/output error 失效；
4. 曾出现 /usr/bin/docker-compose: Input/output error 系统级 I/O 错误。

二、问题根源

最终定位为 WSL2 环境下 Docker 安装目录损坏 + 插件路径识别异常，具体原因：

1. WSL2 虚拟文件系统交互异常，导致 /usr/local/lib/docker/cli-plugins/ 等 Docker 插件目录损坏；
2. Docker CLI 插件自动发现机制受损坏目录影响，即使手动安装插件到正确路径也无法识别；
3. 排除物理磁盘故障（WSL2 虚拟磁盘不支持 SMART 检测，I/O 错误源于文件系统而非硬件）；
4. 排除 Docker 版本兼容问题（Docker Engine 29.0.3 完全支持 Compose V2）。

三、尝试的排查思路与解决手段（按时间线）

1. 初始安装流程（官方 apt 方式）

• 思路：按 Docker 官方文档通过 apt 仓库安装 Docker Engine + Compose 插件；
• 操作：更新系统包 → 安装依赖 → 导入 Docker GPG 密钥 → 添加官方源 → 安装 docker-ce 及 docker-compose-plugin；
• 结果：因 GPG 密钥未正确导入导致安装失败，提示 NO_PUBKEY 错误。

2. 修复 GPG 密钥与重新安装

• 思路：解决仓库签名验证问题，确保 apt 能正常拉取 Docker 包；
• 操作：删除无效密钥文件 → 重新导入 Docker 官方 GPG 密钥 → 更新 apt 缓存 → 再次安装；
• 结果：Docker Engine 安装成功（docker --version 正常输出），但 docker compose 仍报错，提示命令不存在。

3. 验证插件安装与路径

• 思路：排查 Compose 插件是否真的安装成功，以及 Docker CLI 是否能识别插件路径；
• 操作：
  1. 检查 docker-compose-plugin 安装状态（dpkg -l | grep docker-compose-plugin 显示已安装）；
  2. 查看插件目录 /usr/libexec/docker/cli-plugins/，发现无 docker-compose 文件（安装不完整）；
• 结果：确认插件未正确部署到目标路径，导致 Docker CLI 无法识别。

4. 手动安装 Compose 二进制文件（含 xget 加速）

• 思路：绕过 apt 安装，直接下载 Compose 二进制文件到 Docker 插件目录；
• 操作：
  1. 创建插件目录 /usr/libexec/docker/cli-plugins/；
  2. 用 xget 加速从 GitHub 下载 Compose 二进制文件（替换 GitHub 地址为 xget.xi-xu.me/gh 前缀）；
  3. 赋予文件执行权限（chmod +x）；
• 结果：插件文件成功安装，但 docker compose 仍报错，Docker CLI 未识别。

5. 深入排查插件识别机制

• 思路：验证插件文件本身是否正常，以及 Docker CLI 插件路径配置；
• 操作：
  1. 直接执行插件文件（/usr/libexec/docker/cli-plugins/docker-compose version），确认文件可正常运行；
  2. 查看 Docker 插件配置（docker info | grep -i "plugin"），发现所有插件因 I/O 错误失效；
  3. 手动指定插件路径环境变量（export DOCKER_CLI_PLUGINS_PATH=/usr/libexec/docker/cli-plugins）；
• 结果：临时指定环境变量后仍无效，确认损坏目录影响了 Docker CLI 插件扫描。

6. 彻底清理与重建 Docker 环境（最终有效方案）

• 思路：删除所有损坏的 Docker 相关目录和配置，在干净环境中重新安装；
• 操作：
  1. 彻底卸载 Docker 相关包（purge docker-ce docker-ce-cli containerd.io docker-compose-plugin）；
  2. 删除所有 Docker 目录（/var/lib/docker、/usr/local/lib/docker、/usr/libexec/docker 等）；
  3. 重启 WSL2（wsl --shutdown），刷新文件系统状态；
  4. 按官方文档重新安装 Docker Engine + Compose 插件；
• 结果：Docker 环境重建成功，docker compose version 正常输出版本号，hello-world 容器可正常运行。

7. 辅助排查：确认 WSL2 分发版名称与环境

• 思路：解决 WSL2 重启时的分发版名称识别问题；
• 操作：通过 PowerShell（wsl --list --verbose）或 Ubuntu 终端（cat /etc/os-release）获取分发版名称；
• 结果：成功关闭并重启 WSL2，确保清理操作生效。

四、最终解决方案

1. 卸载 Docker 所有组件及残留文件；
2. 重启 WSL2 刷新环境；
3. 按官方流程重新安装 Docker Engine 及 Compose 插件。