配置GitLab Runner的extra hosts域名与IP后流水线报443端口超时错误

API 探路者

2026-8-24

GitLab Runner配置extra_hosts后流水线443超时的解决方法

常见原因及排查步骤

检查extra_hosts格式与配置位置
确保配置放在[[runners]]下的[runners.docker]区块内，格式严格为extra_hosts = ["域名:IP地址"]，示例：
```
[[runners]]
  name = "Docker Runner"
  executor = "docker"
  [runners.docker]
    image = "ubuntu:22.04"
    extra_hosts = ["gitlab.example.com:192.168.3.10"]
```
注意不要遗漏引号、冒号，也不要将配置放在全局区域。
验证映射IP的可达性
在Runner所在主机上执行以下命令，确认目标IP的443端口可访问：
```
telnet 192.168.3.10 443
# 或者用nc
nc -zv 192.168.3.10 443
```
如果主机都无法连接，说明目标IP的端口未开放，或者存在防火墙/安全组拦截，先解决主机层面的网络问题。
检查Runner网络模式冲突
如果Docker executor使用了network_mode = "host"，extra_hosts的配置可能不生效，此时需要直接在主机的/etc/hosts中添加域名映射，或者调整网络模式为默认的bridge。
重启Runner并清理旧容器
修改config.toml后必须重启Runner服务才能生效：
```
sudo gitlab-runner restart
```
同时清理Docker残留的旧容器和网络，避免缓存影响：
```
docker system prune -f
```
排查容器内的DNS解析
可以在流水线中添加临时步骤，验证容器内的域名解析是否正确：
```
job1:
  script:
    - cat /etc/hosts
    - nslookup gitlab.example.com
    - curl -v https://gitlab.example.com
```
查看/etc/hosts中是否存在配置的域名映射，以及nslookup的结果是否符合预期。