Jenkins使用DIND镜像执行docker命令报permission denied问题求助

问题背景 #

Windows通过Docker Desktop部署Jenkins主节点，VMware Ubuntu虚拟机作为Jenkins永久代理（SSH方式启动），Ubuntu上配置了Docker Engine+sysbox-runc用于DIND。Pipeline使用自定义DIND镜像作为agent，前序编译、打包步骤正常，但执行docker build时报错：

ERROR: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/_ping": dial unix /var/run/docker.sock: connect: permission denied

已将Jenkins SSH用户加入docker组，但仅把docker.sock设为777时才能正常运行，而在Ubuntu终端直接启动该DIND镜像执行docker命令无权限问题。

核心原因 #

Jenkins代理通过SSH启动Docker agent容器时，容器内的默认用户（比如镜像内置的jenkins或root用户）并不具备宿主机docker.sock的访问权限。虽然宿主机的Jenkins SSH用户已在docker组，但容器内的用户与宿主机用户的组ID（GID）不匹配，无法继承宿主机的docker组权限。

解决步骤 #

1. 获取宿主机docker组的GID
   在Ubuntu终端执行命令：

   getent group docker
   

   输出类似docker:x:999:，其中999就是docker组的GID。

2. 修改Pipeline的Docker Agent配置，添加组权限
   在JenkinsFile的args中加入--group-add <docker组GID>，让容器内用户加入对应权限组：

   pipeline {
     agent { docker {
         image 'custom dind image with java and maven'
         registryCredentialsId 'credential'
         args '-v /var/run/docker.sock:/var/run/docker.sock --group-add 999'
      } }
     stages {
         // 其他阶段...
         stage('docker build') {
             steps {
                 sh 'docker build -t img/img .'
             }
         }
     }
   }
   

3. 验证权限配置（可选）
   可以在docker build阶段前添加调试步骤，确认容器内权限是否正确：

   stage('debug permissions') {
       steps {
           sh 'id' // 查看当前用户所属组
           sh 'ls -l /var/run/docker.sock' // 查看socket文件的权限信息
       }
   }
   

   确保输出中用户组包含docker组的GID，且docker.sock的组权限为rw。

4. 确认Jenkins SSH用户的组权限生效
   添加用户到docker组后，需要重新登录SSH会话或重启Jenkins代理服务才能生效。可以在Ubuntu终端执行：

   su - <jenkins-ssh-username>
   docker ps
   

   确认该用户能正常执行docker命令，确保组权限已生效。

注意事项 #

• 不要将docker.sock设置为777权限，这会带来严重的安全风险，任何用户都能访问Docker daemon。
• 如果自定义DIND镜像有固定的用户，可以在镜像中创建一个GID与宿主机docker组一致的用户，这样无需每次在Pipeline中添加--group-add参数，但这种方式灵活性较差，适合固定环境。

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