无法推送Docker多平台镜像至Docker Hub，求排查方案

可能的原因 #

• 多平台镜像体积大、推送时间长，网络不稳定导致连接中断
• Docker Hub的速率限制触发：单平台推送未达阈值，但多平台推送的分层数量触发了限制
• Buildx构建器的缓存或网络配置异常
• 本地防火墙、代理或杀毒软件拦截了长连接推送

排查与解决步骤 #

1. 验证网络稳定性 #

• 优先使用有线网络，避免无线信号波动影响长连接
• 执行持续网络测试，确认连接是否稳定：

  ping registry-1.docker.io -t  # Windows
  ping registry-1.docker.io -i 1  # Linux/macOS
  

• 尝试上传大文件到其他云服务，确认是否是本地网络的问题

2. 调整Buildx推送参数 #

• 限制推送并发数，避免因一次性推送过多分层触发限流或断连：

  docker buildx build --push --push-parallelism 2 -t myusername/timescale-ha-db --platform linux/amd64,linux/arm64 -f Dockerfile-postgres .
  

• 改用分步推送方式（先推单平台镜像，再合并manifest）：
  1. 分别构建并导出单平台镜像到本地：

     docker buildx build --load -t myusername/timescale-ha-db:amd64 --platform linux/amd64 -f Dockerfile-postgres .
     docker buildx build --load -t myusername/timescale-ha-db:arm64 --platform linux/arm64 -f Dockerfile-postgres .
     

  2. 推送单平台镜像：

     docker push myusername/timescale-ha-db:amd64
     docker push myusername/timescale-ha-db:arm64
     

  3. 创建并推送多平台manifest列表：

     docker manifest create myusername/timescale-ha-db:latest myusername/timescale-ha-db:amd64 myusername/timescale-ha-db:arm64
     docker manifest push myusername/timescale-ha-db:latest
     

3. 检查Docker Hub速率配额 #

• 查询当前剩余推送配额：

  curl -u "你的Docker Hub用户名:密码" https://hub.docker.com/v2/users/rate_limit_status/
  

• 如果配额不足，等待6小时自动重置，或升级到Docker Hub Pro/Team账号提升限额

4. 重置Buildx构建器 #

• 删除现有构建器并重新创建，清除可能的配置异常：

  docker buildx rm builder
  docker buildx create --use
  

5. 排除本地网络拦截 #

• 暂时关闭本地防火墙、杀毒软件，测试推送是否正常
• 若使用代理，检查代理配置是否支持长连接，尝试关闭代理直接推送

内容的提问来源于stack exchange，提问作者Nikos