Docker 连接错误：Error while fetching server API version

问题概述

在使用 docker-compose build 命令时，可能会遇到以下错误：

docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

这个错误表明 Docker 客户端无法连接到 Docker 守护进程，通常是由于 Docker 服务未运行、权限问题或配置错误导致的。

常见原因与解决方案

1. Docker 服务未运行

确保 Docker 守护进程正在运行：

# 检查 Docker 服务状态
sudo systemctl status docker

# 启动 Docker 服务
sudo systemctl start docker

# 或者使用 service 命令（适用于旧系统）
sudo service docker start

TIP

如果使用 systemctl 时遇到 "System has not been booted with systemd" 错误，说明您的系统没有使用 systemd，请使用 service 命令代替。

2. 用户权限问题

Docker 默认要求用户具有相应权限才能访问 Docker socket：

# 将当前用户添加到 docker 组
sudo usermod -aG docker ${USER}

# 重新登录使更改生效
su - ${USER}

# 或者直接修改 socket 权限（不推荐长期使用）
sudo chmod 666 /var/run/docker.sock

WARNING

修改 socket 权限为 666 会降低系统安全性，建议仅作为临时解决方案。

3. Docker Compose 版本问题

从 Docker Compose V1 迁移到 V2：

# 安装 Docker Compose V2 插件
mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.3.3/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose

# 或者使用包管理器安装
sudo apt install docker-compose-v2

# 验证安装
docker compose version

安装后使用新语法：

# 代替 docker-compose up -d
docker compose up -d

# 代替 docker-compose build
docker compose build

4. WSL 集成问题（Windows 用户）

确保在 Docker Desktop 中启用 WSL 集成：

1. 打开 Docker Desktop
2. 进入 Settings → Resources → WSL Integration
3. 启用对您的 WSL 发行版的支持
4. 重启 Docker

5. Python 依赖冲突

某些版本的 requests 或 urllib3 库可能与 Docker SDK 冲突：

# 降级 requests 库
pip3 install requests==2.31.0

# 或者限制 urllib3 版本
pip install 'urllib3<2'

6. Docker Desktop 配置（macOS 用户）

在 Docker Desktop 中启用默认 socket：

1. 打开 Docker Desktop
2. 进入 Settings → Advanced
3. 启用 "Allow the default Docker socket to be used"

7. 环境变量和上下文检查

检查 Docker 环境变量和上下文配置：

# 检查 DOCKER_HOST 环境变量
echo $DOCKER_HOST

# 检查当前 Docker 上下文
docker context ls

# 确保所选上下文的端点与您的环境匹配

8. iptables 配置（Linux 用户）

某些系统可能需要切换 iptables 版本：

sudo update-alternatives --config iptables

选择 legacy 版本（选项 1）后启动 Docker 服务：

sudo service docker start

解决方案流程图

预防措施

1. 定期更新 Docker：保持 Docker 和 Docker Compose 为最新版本
2. 使用官方安装方法：避免使用过时的包管理器版本
3. 检查系统要求：确保您的操作系统与 Docker 版本兼容
4. 备份重要数据：定期备份 Docker 容器和镜像

INFO

对于 Ubuntu 24.04 用户，建议从 Docker 官方源安装而不是使用 Ubuntu 自带的软件包，以获得更好的兼容性。

总结

"DockerException: Error while fetching server API version" 错误通常与 Docker 守护进程的连接问题有关。通过检查服务状态、用户权限、版本兼容性和系统配置，大多数情况下可以快速解决这个问题。如果问题仍然存在，考虑查看 Docker 日志获取更详细的错误信息：

# 查看 Docker 服务日志
sudo journalctl -u docker.service

# 或直接查看 Docker 守护进程日志
docker info