GitLab Runner中Docker认证失败：如何替换auth.ipv6.docker.com为auth.ipv4.docker.com？

你遇到的是Docker Registry尝试通过IPv6地址连接授权服务器失败的问题，错误中的auth.ipv6.docker.com是Docker自动解析的IPv6授权端点，可以通过配置强制切换到IPv4的授权通道，具体方法如下：

方法1：通过hosts文件强制域名解析 #

编辑系统的/etc/hosts文件，添加auth.ipv6.docker.com和auth.docker.com的IPv4映射：

# 先通过dig命令获取auth.docker.com的IPv4地址，例如执行：dig auth.docker.com A +short
99.84.247.249 auth.docker.com auth.ipv6.docker.com

保存后重启Docker服务：

systemctl restart docker

方法2：禁用Docker的IPv6支持 #

编辑Docker守护进程配置文件/etc/docker/daemon.json（不存在则创建），添加以下内容：

{
  "ipv6": false,
  "fixed-cidr-v6": "",
  "dns": ["8.8.8.8", "8.8.4.4"]
}

重启Docker服务使配置生效：

systemctl restart docker

此方法会让Docker完全使用IPv4网络，从根源上避免IPv6连接问题。

方法3：GitLab Runner层面配置映射 #

如果仅需要在GitLab Runner的Docker executor中生效，可编辑Runner的config.toml文件，在[runners.docker]段添加extra_hosts配置：

[[runners]]
  # 保留原有配置...
  executor = "docker"
  [runners.docker]
    # 保留原有配置...
    extra_hosts = [
      "auth.ipv6.docker.com:99.84.247.249",
      "auth.docker.com:99.84.247.249"
    ]

重启GitLab Runner服务：

systemctl restart gitlab-runner

以上三种方法都能实现让Docker的授权请求走IPv4通道，解决你遇到的连接失败问题。

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