本地Docker环境Jenkins Agent启动失败：Docker权限问题

问题场景 #

通过Docker部署Jenkins控制器和自定义Agent，Agent启动时出现permission denied while trying to connect to the Docker daemon socket错误，尽管已在Agent的Dockerfile中执行usermod -aG docker jenkins，权限问题仍未解决。

核心原因 #

宿主机/var/run/docker.sock的所属组GID，与Agent容器内docker组的GID不一致。仅将jenkins用户加入容器内的docker组，无法匹配宿主机socket的权限要求。

解决思路 #

1. 对齐容器与宿主机的Docker组GID #

• 先在宿主机执行以下命令，获取docker组的实际GID：

  getent group docker | cut -d: -f3
  

  示例输出可能为999（不同环境GID可能不同）。
• 修改Agent的Dockerfile，将容器内docker组的GID改为宿主机的对应值：

  FROM jenkins/agent
  USER root
  RUN apt update && curl -fsSL https://get.docker.com | sh
  # 替换下方的999为宿主机获取到的docker组GID
  RUN groupmod -g 999 docker || groupadd -g 999 docker
  RUN usermod -aG docker jenkins
  USER jenkins
  

• 重新构建Agent镜像：

  docker build . -t jenkinsagent
  

2. 启动Agent时动态传递宿主机Docker组权限 #

无需修改Dockerfile，直接在启动Agent的命令中，将容器内用户加入宿主机docker组的GID：

docker run -i --rm --name agent -v /var/run/docker.sock:/var/run/docker.sock --group-add $(getent group docker | cut -d: -f3) --init jenkinsagent java -jar /usr/share/jenkins/agent.jar

该命令会自动获取宿主机docker组的GID，并临时将Agent容器内的jenkins用户加入对应组，匹配socket权限。

3. 验证控制器容器权限（可选） #

若Agent启动命令是在Jenkins控制器容器内执行，需确保控制器内的jenkins用户同样有权限访问docker.sock：

• 进入控制器容器：

  docker exec -it <jenkins-controller-container-id> bash
  

• 切换到jenkins用户并测试：

  su jenkins
  docker ps
  

  若仍有权限问题，需按步骤1的方法调整控制器容器内的docker组GID。

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