Docker Buildx 多平台构建失败问题排查实录

问题背景

在使用 Docker buildx 进行多平台镜像构建时，遇到了网络连接和构建器配置问题。本文记录了完整的排查过程和解决方案，希望能帮助遇到类似问题的开发者。

问题现象

初始错误

执行多平台构建命令时出现以下错误：

docker buildx build --platform linux/amd64,linux/arm64 \
  -t 内部仓库地址:node-18.20.8-alpine \
  --push --provenance=false .

错误信息：

ERROR: failed to solve: node:18.20.8-alpine: failed to resolve source metadata for docker.io/library/node:18.20.8-alpine: failed to authorize: failed to fetch oauth token: Post "https://auth.docker.io/token": proxyconnect tcp: dial tcp 127.0.0.1:7890: connect: connection refused

关键信息提取

从错误信息中可以看出几个关键点：

1. 🔍 代理连接被拒绝：dial tcp 127.0.0.1:7890: connect: connection refused
2. 🔍 认证失败：无法获取 Docker Hub 的 oauth token
3. 🔍 网络问题：无法连接到 Docker 认证服务器

排查过程

1. 检查 Docker 代理配置

首先检查 Docker 的代理设置：

docker system info | grep -i proxy

发现问题：

HTTP Proxy: http.docker.internal:3128
HTTPS Proxy: http.docker.internal:3128
No Proxy: hubproxy.docker.internal

Docker 配置了代理，但错误信息显示尝试连接 127.0.0.1:7890，存在配置冲突。

2. 测试网络连通性

# 测试到 Docker Hub 的连接
ping -c 3 docker.io

结果：

--- docker.io ping statistics ---
3 packets transmitted, 0 packets received, 100.0% packet loss

确认网络连接存在问题。

3. 尝试直接拉取镜像

有趣的是，直接拉取镜像却是成功的：

# ARM64 平台
docker pull --platform linux/arm64 node:18.20.8-alpine
# ✅ 成功：Status: Image is up to date

# AMD64 平台
docker pull --platform linux/amd64 node:18.20.8-alpine
# ✅ 成功：Status: Image is up to date

关键发现：单独拉取镜像成功，但 buildx 构建失败！

4. 检查 buildx 构建器状态

docker buildx ls

发现问题：

NAME/NODE                     DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
multi-platform-builder*       docker-container
 \_ multi-platform-builder0    \_ desktop-linux   running   v0.13.2    linux/amd64 (+2), linux/arm64...
default                                           error
Cannot load builder default: Cannot connect to the Docker daemon...

multi-platform-builder 构建器状态异常！

解决方案

1. 删除有问题的构建器：

docker buildx rm multi-platform-builder

2. 切换到稳定的构建器：

docker buildx use desktop-linux

3. 重新构建：

docker buildx build --platform linux/amd64,linux/arm64 \
  -t 内部仓库地址:node-18.20.8-alpine \
  --push --provenance=false .

结果：✅ 构建成功！

根本原因分析

为什么单独 pull 成功，但 buildx 失败？

1. 不同的网络路径：

   • docker pull 使用 Docker daemon 的直接连接
   • docker buildx 使用容器化的构建器，网络环境不同

2. 构建器配置问题：

   • multi-platform-builder 构建器内部网络配置异常
   • 代理设置在构建器容器中无法正常工作

3. 认证机制差异：

   • buildx 需要更复杂的认证流程
   • 构建器容器可能无法正确继承主机的认证信息

最佳实践建议

1. 构建器管理

# 定期检查构建器状态
docker buildx ls

# 清理异常构建器
docker buildx rm <builder-name>

# 使用稳定的构建器
docker buildx use desktop-linux

2. 网络配置

• 优先使用企业内部镜像仓库
• 配置可靠的镜像源作为备选
• 定期测试网络连通性

3. 调试技巧

# 逐步验证
docker pull <image>                    # 测试基础连通性
docker buildx build --platform linux/amd64  # 单平台测试
docker buildx build --platform linux/amd64,linux/arm64  # 多平台测试

# 详细日志
docker buildx build --progress=plain ...

总结

这次问题排查的关键收获：

1. 分层诊断：从网络、代理、构建器等多个维度排查
2. 对比测试：通过 docker pull 与 docker buildx 的对比发现关键线索
3. 构建器管理：Docker buildx 构建器需要定期维护
4. 备选方案：准备多种解决方案应对不同场景

最终结果：成功构建并推送多平台镜像到内部仓库

参考资源

• Docker Buildx 官方文档
• 多平台构建指南
• Docker 网络配置

---

本文记录了一次真实的 Docker buildx 问题排查过程，希望能为遇到类似问题的开发者提供参考。