Jenkins容器主节点调用Docker云代理执行Docker命令超时问题

错误信息 #

执行Docker镜像构建时出现如下超时错误：

Post "http://172.23.0.2:2375/v1.24/build?buildargs=%7B%7D&cachefrom=%5B%5D&cgroupparent=&cpuperiod=0&cpuquota=0&cpusetcpus=&cpusetmems=&cpushares=0&dockerfile=Dockerfile&labels=%7B%7D&memory=0&memswap=0&networkmode=default&rm=1&shmsize=0&t=test-image&target=&ulimits=null&version=1": dial tcp 172.23.0.2:2375: i/o timeout

环境配置步骤 #

• 构建Jenkins主节点镜像，Dockerfile内容：

  FROM jenkins/jenkins:2.414.3-jdk17
  USER root
  RUN apt-get update && apt-get install -y lsb-release
  RUN curl -fsSLo /usr/share/keyrings/docker-archive-keyring.asc \
    https://download.docker.com/linux/debian/gpg
  RUN echo "deb [arch=$(dpkg --print-architecture) \
    signed-by=/usr/share/keyrings/docker-archive-keyring.asc] \
    https://download.docker.com/linux/debian \
    $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list
  RUN apt-get update && apt-get install -y docker-ce-cli
  USER jenkins
  RUN jenkins-plugin-cli --plugins "blueocean docker-workflow"
  

• 创建Docker网络：

  docker network create jenkins
  

• 运行Jenkins主节点容器：

  docker run --name jenkins-blueocean --restart=on-failure --detach `
    --network jenkins --env DOCKER_HOST=tcp://docker:2376 `
    --env DOCKER_CERT_PATH=/certs/client --env DOCKER_TLS_VERIFY=1 `
    --volume jenkins-data:/var/jenkins_home `
    --volume jenkins-docker-certs:/certs/client:ro `
    --publish 8080:8080 --publish 50000:50000 myjenkins-blueocean
  

• 运行alpine socat容器：

  docker run -d --restart=always -p 127.0.0.1:2376:2375 --network jenkins `
  -v /var/run/docker.sock:/var/run/docker.sock alpine/socat tcp-listen:2375,fork,reuseaddr unix-connect:/var/run/docker.sock
  

• Jenkins云配置：
  • 在「Cloud docker Configuration」中配置Docker Host URI为socat容器IP，勾选「Enabled」和「Expose DOCKER_HOST」
  • 添加使用jenkins/jnlp-agent-docker镜像的Docker代理模板
• 流水线Jenkinsfile：

  pipeline {
    agent {
      node {
        label 'docker-agent'
      }
    }
    stages {
      stage('Build') {
        steps {
          script {
            echo "Bulding docker images"
            dockerImage = docker.build("test-image", "./WebApiTest")
          }
        }
      }    
    }
  }
  

问题原因分析 #

1. 网络隔离问题：socat容器绑定了127.0.0.1:2376，仅允许Windows本地主机访问，而Jenkins代理容器处于jenkins专属网络内，无法通过回环地址访问socat服务。
2. IP依赖不稳定：手动指定socat容器IP，容器重启后IP可能变化，导致代理节点无法持续连通。
3. 环境变量传递不匹配：Jenkins主节点配置的DOCKER_HOST指向tcp://docker:2376，但代理节点实际需要访问的是socat容器的服务端口，两者不匹配。

解决方案 #

1. 重新配置socat容器网络 #

删除现有socat容器，重新运行时取消本地端口绑定，让容器在jenkins网络内直接暴露服务：

# 清理旧容器
docker stop $(docker ps -q --filter "name=socat")
docker rm $(docker ps -aq --filter "name=socat")

# 重新启动socat容器，指定容器名便于网络解析
docker run -d --restart=always --name jenkins-socat --network jenkins `
-v /var/run/docker.sock:/var/run/docker.sock alpine/socat tcp-listen:2375,fork,reuseaddr unix-connect:/var/run/docker.sock

2. 更新Jenkins云配置 #

在Jenkins「Cloud docker Configuration」中，将Docker Host URI改为容器名+端口（同网络内可通过容器名直接解析）：

tcp://jenkins-socat:2375

无需手动维护IP，容器名解析更稳定。

3. 验证网络连通性 #

进入Jenkins代理容器，测试与socat容器的连通性：

# 获取代理容器ID
docker ps | grep jenkins/jnlp-agent-docker | awk '{print $1}'

# 进入代理容器
docker exec -it <代理容器ID> sh

# 测试telnet连接
telnet jenkins-socat 2375

若能成功建立连接，说明网络配置正常。

4. 优化流水线环境变量（可选） #

在Jenkinsfile中显式指定DOCKER_HOST，确保代理节点使用正确的服务地址：

pipeline {
  agent {
    node {
      label 'docker-agent'
    }
  }
  environment {
    DOCKER_HOST = 'tcp://jenkins-socat:2375'
  }
  stages {
    stage('Build') {
      steps {
        script {
          echo "Building docker images"
          dockerImage = docker.build("test-image", "./WebApiTest")
        }
      }
    }    
  }
}

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