Mac下Jenkins流水线构建Docker镜像遇mkdir /.docker权限拒绝错误

问题背景 #

Mac系统通过Homebrew安装Jenkins，搭配Docker Desktop，流水线中使用docker:24.0.5镜像作为构建代理构建Python应用Docker镜像时，报错mkdir /.docker: permission denied。此前已解决docker command not found问题，且前序阶段可正常使用Docker容器。

核心原因 #

使用docker { image 'docker:24.0.5' }作为构建代理时，Jenkins会启动该镜像的容器：

1. 容器内默认非root用户无权限在根目录创建.docker目录（Docker客户端用于存储配置文件）；
2. 容器默认未连接宿主机Docker daemon，导致Docker客户端尝试创建本地配置目录时触发权限错误。

解决方案 #

方案1：调整Docker代理容器配置

修改Jenkinsfile的Build Docker Image阶段，指定以root用户运行代理容器，并挂载宿主机的Docker套接字和配置目录：

pipeline {
    agent none
    stages {
        // ...其他阶段
        stage("Build Docker Image") {
            agent {
                docker { 
                    image 'docker:24.0.5'
                    user 'root'  // 以root用户运行容器，获取目录写入权限
                    // 挂载宿主机Docker套接字（调用宿主机Docker服务）和配置目录（复用宿主机配置）
                    args '-v /var/run/docker.sock:/var/run/docker.sock -v $HOME/.docker:/root/.docker'
                }
            }
            steps {
               script {
                dockerImage = docker.build("<docker image name>:${env.BUILD_ID}")
               }
            }
        }
        // ...其他阶段
    }
}

方案2：直接使用宿主机Jenkins代理

如果前序阶段已验证宿主机Jenkins可正常调用Docker，可跳过Docker代理容器，直接使用宿主机作为构建环境：

pipeline {
    agent none
    stages {
        // ...其他阶段
        stage("Build Docker Image") {
            agent any  // 使用宿主机Jenkins代理（需确保宿主机已配置好Docker环境）
            steps {
               script {
                dockerImage = docker.build("<docker image name>:${env.BUILD_ID}")
               }
            }
        }
        // ...其他阶段
    }
}

补充验证

确保运行Jenkins的用户拥有Docker访问权限：

• 若Jenkins以jenkins用户运行，执行命令将其加入Docker用户组：

  sudo usermod -aG docker jenkins
  

• 在Docker Desktop的Settings > Security中，允许Jenkins进程访问Docker服务。

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