WSL2环境下Jenkins连接Docker Engine构建镜像失败求助

环境配置：

• Windows 11 + WSL2 作为 Docker 引擎（Docker 版本 1.47.0）
• Spring Boot 项目，使用 Maven 3.9.8 管理依赖，搭配 fabric8io Docker Maven Plugin
• Git、Jenkins 均运行在本地 Docker 容器中

已做操作与遇到的问题：

• 已在 Docker Desktop 开启「Expose daemon on tcp://localhost:2375 without TLS」
• IDEA 本地环境下，pom.xml 配置 dockerHost 为 tcp://localhost:2375 可正常构建镜像
• Jenkins 流水线执行时，构建 Docker 镜像环节报错：Cannot create docker access object
• 尝试过 host.docker.internal:2375、不配置 dockerHost、http://127.0.0.1:2375 等多种配置，均无法解决问题

需求：在 WSL2 运行 Docker 容器（含 Git、Jenkins）的环境下，实现 Jenkins 成功连接 Docker 服务并构建镜像

方法一：挂载 Docker 套接字到 Jenkins 容器（推荐，无安全风险） #

这是最直接可靠的方式，无需暴露 TCP 端口：

1. 启动 Jenkins 容器时添加挂载参数，将 WSL2 中的 Docker 套接字映射到容器内：

   docker run -d \
     -p 8080:8080 \
     -p 50000:50000 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v jenkins_home:/var/jenkins_home \
     jenkins/jenkins:lts
   

   若用 Docker Compose，在 services.jenkins.volumes 中添加：- /var/run/docker.sock:/var/run/docker.sock
2. 给 Jenkins 容器内的 jenkins 用户添加 Docker 权限：
   • 进入容器：docker exec -it <jenkins容器ID> bash
   • 执行命令：usermod -aG docker jenkins
   • 重启容器：docker restart <jenkins容器ID>
3. 修改 pom.xml 的 dockerHost 配置为 Unix 套接字路径：

   <configuration>
     <dockerHost>unix:///var/run/docker.sock</dockerHost>
     <!-- 其他原有配置 -->
   </configuration>
   

方法二：正确配置 TCP 连接地址（适配 WSL2 网络特性） #

如果坚持使用 TCP 连接，需要注意 WSL2 的网络隔离特性：

1. 获取 WSL2 的主机 IP：在 Windows 命令行执行 wsl hostname -I，得到类似 172.17.0.1 的地址
2. 修改 Docker Desktop 的 Docker Engine 配置：
   • 打开 Docker Desktop 设置 -> Docker Engine，修改 hosts 字段：

     {
       "hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"]
     }
     

   • 重启 Docker Desktop 生效
3. 在 pom.xml 或 Jenkins 流水线中配置 dockerHost 为 WSL2 IP:2375：

   <configuration>
     <dockerHost>tcp://172.17.0.1:2375</dockerHost>
     <!-- 其他原有配置 -->
   </configuration>
   

   注意：WSL2 的 IP 可能随重启变化，可通过脚本动态获取，或在 Windows 上给 WSL2 设置静态 IP

方法三：通过 Jenkins Docker 插件实现连接 #

1. 在 Jenkins 插件市场安装 Docker Pipeline 和 Docker Commons 插件
2. 进入 Jenkins 全局配置，添加 Docker 云配置：
   • 选择「Docker」云，配置 Docker 主机 URL 为 tcp://host.docker.internal:2375
   • 勾选「Enable Docker」，点击测试连接确认可用
3. 在 Jenkins 流水线中使用插件语法构建镜像，替代 fabric8io 插件：

   pipeline {
     agent any
     stages {
       stage('Build Docker Image') {
         steps {
           script {
             docker.build('my-spring-boot-image:latest')
           }
         }
       }
     }
   }
   

注意事项 #

• 关闭 TLS 暴露 Docker 2375 端口存在安全风险，生产环境建议配置 TLS 认证
• WSL2 环境下 host.docker.internal 可能无法直接映射 Windows localhost，需提前测试网络连通性
• 可在 Jenkins 容器内执行 docker info 命令，验证是否能正常连接 Docker 服务

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