Docker构建阶段执行pip install出现域名解析临时失败问题求助

问题场景 #

在Debian 11家用服务器上通过Docker Compose部署项目，Dockerfile中执行pip install -r requirements.txt时持续出现域名解析失败，错误日志如下：

#0 21.27 WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7efff0d95750>: Failed to establish a new connection: [Errno -3] Temporary failure in name resolution')': /simple/asgiref/
#0 41.79 WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7efff0ca6190>: Failed to establish a new connection: [Errno -3] Temporary failure in name resolution')': /simple/asgiref/
#0 62.82 WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7efff0cbd9d0>: Failed to establish a new connection: [Errno -3] Temporary failure in name resolution')': /simple/asgiref/
#0 84.84 WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7efff0d95b90>: Failed to establish a new connection: [Errno -3] Temporary failure in name resolution')': /simple/asgiref/
#0 108.9 WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError('<pip._vendor.urllib3.connection.HTTPSConnection object at 0x7efff0d96410>: Failed to establish a new connection: [Errno -3] Temporary failure in name resolution')': /simple/asgiref/
#0 128.9 ERROR: Could not find a version that satisfies the requirement asgiref==3.5.2 (from versions: none)
#0 128.9 ERROR: No matching distribution found for asgiref==3.5.2

服务器运行Pi-hole作为DNS服务器，宿主机/etc/resolv.conf已配置Pi-hole为域名服务器，且宿主机手动执行pip install或ping任意网站均正常，Pi-hole也未拦截服务器请求。将宿主机/etc/resolv.conf改为nameserver 127.0.0.1后，Docker内pip安装依赖的问题解决，但不清楚原因。

原因分析 #

1. Docker构建网络隔离限制：Docker构建阶段默认使用独立的网络环境，若宿主机/etc/resolv.conf配置的是Pi-hole容器的具体IP（而非127.0.0.1），构建容器无法直接访问该容器IP——因为构建环境的127.0.0.1指向自身，而非宿主机，导致无法连接到Pi-hole进行域名解析。
2. 宿主机DNS转发逻辑：当宿主机/etc/resolv.conf设为nameserver 127.0.0.1时，Pi-hole通常已映射宿主机的53端口，此时Docker构建容器会将DNS请求发送到宿主机的127.0.0.1:53，实际转发到Pi-hole容器，从而完成正常解析。

解决方法 #

方法1：保持宿主机DNS配置为127.0.0.1 #

确保Pi-hole容器已映射宿主机的53端口（包括127.0.0.1接口），这样宿主机和Docker构建环境的DNS请求都会通过宿主机本地端口转发到Pi-hole，无需额外修改Docker配置。

方法2：在Docker Compose中指定构建阶段的DNS #

在docker-compose.yml中为构建服务指定DNS服务器，直接指向宿主机IP或Pi-hole容器IP：

services:
  your-service-name:
    build:
      context: .
      dns:
        - 127.0.0.1  # 或宿主机的局域网IP，确保构建容器能访问

方法3：使用国内PyPI源规避解析问题 #

临时在Dockerfile中替换PyPI源，减少DNS解析依赖：

RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

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