解决Jenkins主节点Pipeline中'docker: command not found'报错

问题描述 #

运行Jenkins Pipeline执行Docker相关命令（如docker build .）时，系统返回报错：docker: command not found。

示例Pipeline代码片段：

steps {
  sh "docker build ." // 示例命令
}

当前环境与配置 #

• 使用Jenkins主节点，已安装Docker Pipeline Plugin和Docker Plugin
• Pipeline用于构建Golang应用镜像、健康检查、打标签并推送至DockerHub，完整代码如下：

// Pipeline that Builds / Tests / Deploys the new Version of the Image.
pipeline {

    agent { dockerfile {filename "Dockerfile" dir "."}}
    environment {
        DOCKERHUB_CREDENTIALS=credentials("DockerHub")
    }
    stages {

        stage("build"){
            steps{
                sh "echo 'Running Build Pipeline...'"
                sh "docker build . --name=new_versioned_image"
                sleep 10 
                sh "echo 'Docker Built Image Successfully! And Initial Tests Has been Passed. Going to the Testing Stage..'"
            }
        }

        stage("test"){
            steps{
                // checking for application health..
                load "./version_env.groovy"

                sh "echo 'Running Test Pipeline'"
                sh "echo 'Running Healtcheck Test...'"
                sh "Sleeping until the Application will be fully ready..."
                sleep 10    

                script {
                    final String url = "http://${env.APPLICATION_HOST}:${APPLICATION_PORT}"
                    final def (String response, int code) =
                    sh(script: "curl -X GET -f $url", returnStdout: true).trim().tokenize("\n")
            
                    if (code == 200) {sh "echo Application health State Is Okay... Running Deployment Stage.."}else{
                        echo "Application Responded with Failure."
                        error "Health Check Stage Failure."
                    }
                }
            }
        }

        stage("deployment"){

            steps {  
                load "./version_env.groovy"
                load "./JenkinsCredentials.groovy" // Create A File Called `JenkinsCredentials` and Put There Credentials for `withCredentials` Statement.
                
                sh "echo 'Running Deployment Pipeline Stage...'"
                sh "echo 'Tagging new Image Version'"

                withCredentials([
                    credentialsId: "DockerHub",
                    usernameVariable: "DOCKERHUB_CREDENTIALS_USR", 
                    passwordVariable: "DOCKERHUB_CREDENTIALS_PSW", 
                ]){
                    sh "docker login -u ${DOCKERHUB_CREDENTIALS_USR} -p ${DOCKERHUB_CREDENTIALS_PSW}"
                    sh "Logged In.. Into Docker."

                    sh "echo 'Tagging An Image'"
                    sh "docker tag new_versioned_image ${env.DOCKERHUB_REPOSITORY_LINK}:latest"
                    sh "echo 'Tagged... Pushing onto docker repo.'"

                    sh "docker push ${env.DOCKERHUB_REPOSITORY_LINK}:latest"

                    sh "docker tag new_store_application_image ${env.DOCKERHUB_REPOSITORY_NAME}:latest"
                    sh "echo 'Tagged Successfully.. Pushing Image On Docker Hub..'"
                    sh "echo 'Image has been Pushed Successfully! Pipeline Finished.'"
                }
            }
        }
        
        post {
            always {
                sh "Logging Out From Dockerhub..."
                sh "docker logout"
            }
        }
    }
}

核心需求 #

倾向于通过配置主节点PATH指定Docker安装目录解决问题，同时需要更多可行的解决方案建议。

解决方案建议 #

1. 修正Pipeline Agent配置（关键问题） #

当前Pipeline使用agent { dockerfile { ... }}，会基于指定Dockerfile创建新容器运行Pipeline，但容器内部默认没有安装Docker，这是导致docker: command not found的核心原因。有两种修正方式：

方式一：挂载宿主机Docker资源到Agent容器

修改agent配置，将宿主机的Docker socket和可执行文件挂载到容器中，让容器可以直接使用宿主机的Docker：

agent {
    dockerfile {
        filename "Dockerfile"
        dir "."
        args "-v /var/run/docker.sock:/var/run/docker.sock -v /usr/bin/docker:/usr/bin/docker"
    }
}

注意：需确保宿主机上Docker的安装路径为/usr/bin/docker，可通过在Jenkins主节点执行which docker确认实际路径。

方式二：直接使用Jenkins主节点作为Agent

将agent改为使用主节点运行Pipeline，避免在容器内执行Docker命令：

agent { label 'master' }
// 或简化为 agent any（当只有主节点时）

2. 配置Jenkins主节点PATH环境变量 #

如果选择使用主节点作为Agent，需确保Jenkins进程能找到Docker命令：

1. 登录Jenkins管理界面，进入「系统管理」→「系统配置」
2. 找到「全局属性」，勾选「环境变量」
3. 添加环境变量：
   • 变量名：PATH
   • 变量值：$PATH:/usr/bin（替换为which docker输出的目录，比如/usr/bin）
4. 保存配置后重启Jenkins服务

3. 确保Jenkins用户拥有Docker权限 #

在Jenkins主节点服务器上执行以下操作：

1. 切换到root用户，将Jenkins用户加入docker组：

   sudo usermod -aG docker jenkins
   

2. 重启Jenkins服务：

   sudo systemctl restart jenkins
   

3. 验证：切换到jenkins用户执行docker --version，确认命令可正常运行

4. 修正Pipeline代码中的语法错误 #

• envinronment拼写错误，应改为environment
• withCredentials块内语法错误，修正为：

  withCredentials([
      usernamePassword(
          credentialsId: "DockerHub",
          usernameVariable: "DOCKERHUB_CREDENTIALS_USR",
          passwordVariable: "DOCKERHUB_CREDENTIALS_PSW"
      )
  ]){
      // 后续登录命令使用正确的变量
      sh "docker login -u ${DOCKERHUB_CREDENTIALS_USR} -p ${DOCKERHUB_CREDENTIALS_PSW}"
  }
  

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