WSL2 Ubuntu环境下Docker无法推送镜像至仓库如何排查

该问题是WSL2环境安装原生Docker的高频问题，拉取、构建、运行容器正常但推送挂死无报错，90%以上是网络配置冲突/不匹配导致，按以下步骤逐一排查即可：

• 首先开启Docker debug模式定位卡点
  编辑/etc/docker/daemon.json添加调试配置：

  {
    "debug": true,
    "log-level": "debug"
  }
  

  执行sudo systemctl restart docker重启服务，再运行推送命令，同时开另一个终端执行journalctl -u docker -f跟踪实时日志：

  • 如果日志卡在blob上传阶段、没有报错直接停住，优先排查MTU问题
  • 如果日志卡在鉴权完成、开始建立上传连接阶段，优先排查iptables兼容/规则残留问题

• 修复MTU不匹配问题（最高发原因）
  WSL2虚拟网卡的MTU和Docker默认网桥MTU不一致时，上传阶段的大包会被静默丢弃，表现就是无报错挂死：

  1. 执行ip link show eth0查看WSL2网卡的MTU值，输出中mtu后面的数字就是实际值，常见为1380、1420
  2. 在/etc/docker/daemon.json中添加MTU配置，和eth0数值保持一致：

     {
       "mtu": 你查到的实际MTU值
     }
     

  3. 执行sudo systemctl restart docker重启服务后重新测试推送

• 修复iptables/nftables兼容问题
  Ubuntu 22.04及以上版本默认使用nftables，和Docker默认依赖的iptables规则体系存在兼容问题，会导致长连接上传流量被丢弃：

  1. 切换iptables到legacy版本：

     sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
     sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
     

  2. 清空残留规则后重启Docker重新生成规则：

     sudo iptables -F
     sudo iptables -t nat -F
     sudo systemctl restart docker
     

  3. 测试推送是否恢复正常

• 清理Docker Desktop残留配置
  此前安装过Docker Desktop，卸载后残留的虚拟网桥、转发规则会和原生Docker的网络配置冲突：

  1. 清理无用Docker网络：sudo docker network prune -f
  2. 删除残留虚拟网桥：

     sudo ip link delete docker0
     sudo ip link show | grep br- | awk '{print $2}' | tr -d ':' | xargs -I {} sudo ip link delete {}
     

  3. 重启Docker服务重新生成默认网络配置后测试

• 快速定位问题范围
  如果以上步骤操作后仍未解决，可以先执行下面的命令快速判断问题层面：

  docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --network host docker:latest push 你的镜像标签
  

  如果host网络模式下推送正常，说明问题完全出在Docker网桥的配置层面，回到前面的MTU、iptables步骤重新核对参数即可。

附问题相关截图：

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