Jenkins Docker代理使用docker agent语法执行任务报错排查

环境配置 #

基于jenkins/inbound-agent:4.9-1-jdk11构建Jenkins代理容器，已安装Docker CLI，启动命令如下：

docker run --detach \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /root/.ssh/:/var/lib/jenkins/.ssh \
--restart always \
--init jenkins/inbound-agent:4.9-1-jdk11 \
-url https://jenkins.url \
secret_key_for_jenkins_agent \
dood

正常执行场景 #

• 在代理容器内手动启动新容器，无任何问题；
• 流水线中直接执行docker run命令正常：

stage('Run in Docker') {
    steps {
        sh 'docker run alpine:latest ls'
    }
}

异常场景与报错 #

使用docker阶段代理时出现执行失败：

stage('Run in Docker') {
    agent {
        docker {
            image 'alpine:latest'
            reuseNode true
        }
    }
    steps {
        sh "echo hello"
    }
}

报错信息：

$ docker run -t -d -u 0:0 -w /home/jenkins/workspace/Dockers -v /home/jenkins/workspace/Dockers:/home/jenkins/workspace/Dockers:rw,z -v /home/jenkins/workspace/Dockers@tmp:/home/jenkins/workspace/Dockers@tmp:rw,z -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** -e ******** alpine:latest cat
$ docker top 7a692e853148ab2ec522be205f493287ca58099fabfd9a3ebb890c29a82da1bf -eo pid,comm
[Pipeline] {
[Pipeline] sh
process apparently never started in home/jenkins/workspace/Dockers@tmp/durable-14231f71
(running Jenkins temporarily with -org.jenkinsci.plugins.durabletask.BourneShellScript.LAUNCH_DIAGNOSTICS=true might make the problem clearer)
[Pipeline] }
$ docker stop --time=1 7a692e853148ab2ec522be205f493287ca58099fabfd9a3ebb890c29a82da1bf
$ docker rm -f 7a692e853148ab2ec522be205f493287ca58099fabfd9a3ebb890c29a82da1bf

完整流水线代码 #

pipeline {
    agent { label 'dood' }

    stages {
        // Pre build cleanup
        stage('Pre-build Clean Workspace') {
            steps {
                cleanWs()
            }
        }

        // Cloning Latest Patchset - Job is Gerrit Triggered
        stage('Clone Latest Patchset') {
            steps {
                checkout([
                    $class: 'GitSCM',
                    branches: [[name: '$GERRIT_BRANCH']],
                    extensions: [
                        [
                            $class: 'SubmoduleOption',
                            disableSubmodules: false,
                            parentCredentials: true,
                            recursiveSubmodules: true,
                            reference: '',
                            trackingSubmodules: false
                            ],
                        [
                            $class: 'BuildChooserSetting',
                            buildChooser: [$class: 'GerritTriggerBuildChooser']
                            ],
                        [
                            $class: 'CleanBeforeCheckout',
                            deleteUntrackedNestedRepositories: true
                            ]
                    ],
                    userRemoteConfigs: [
                        [
                            credentialsId: 'xxxxxxx_SSH',
                            refspec: '$GERRIT_REFSPEC',
                            url: 'ssh://gerrit-ssh.xxxxxxxx.biz/xxxxxxxx/Dockers'
                            ]
                    ]
                ])
            }
        }

        stage('Run in Docker') {
            agent {
                docker {
                    image 'alpine:latest'
                    reuseNode true
                    alwaysPull true
                }
            }
            steps {
                sh "echo hello"
            }
        }

        // Post build cleanup
        stage('Post-build Clean Workspace') {
            steps {
                cleanWs()
            }
        }
    }
}

原因分析与解决方案 #

核心原因 #

1. 权限不匹配：Jenkins默认以root用户（-u 0:0）启动阶段代理容器，但主代理的workspace目录属于jenkins用户（UID/GID通常为1000），root用户在容器内无法读写该目录，导致durable task无法创建执行脚本的临时文件。
2. SELinux上下文限制：挂载目录时使用了:z标签，会修改文件的SELinux上下文，进一步限制了容器内用户的访问权限。
3. reuseNode参数冲突：reuseNode true让阶段代理共享主代理的workspace，加剧了权限不匹配的问题。

解决方案 #

• 方案1：移除reuseNode true
  让Jenkins为阶段代理创建独立的workspace，避免权限冲突：

  stage('Run in Docker') {
      agent {
          docker {
              image 'alpine:latest'
              alwaysPull true
          }
      }
      steps {
          sh "echo hello"
      }
  }
  

• 方案2：指定匹配的用户
  在docker代理配置中使用与主代理一致的用户（UID/GID为1000）：

  stage('Run in Docker') {
      agent {
          docker {
              image 'alpine:latest'
              reuseNode true
              alwaysPull true
              user '1000:1000'
          }
      }
      steps {
          sh "echo hello"
      }
  }
  

• 方案3：调整挂载权限或SELinux标签

  • 在主代理容器中执行chmod o+rw /home/jenkins/workspace/Dockers，让其他用户（包括root）有读写权限；
  • 若SELinux不是强制模式，可去掉挂载目录的:z标签（需修改Jenkins Docker插件的默认挂载配置，或通过args参数手动指定挂载选项）。

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