Jenkins Pipeline构建报错No such DSL method 'sshagent' 排查求助

问题背景 #

搭建Jenkins CI/CD流程实现项目自动化构建部署时，编写声明式Pipeline脚本，用于远程连接目标服务器依次执行docker-compose停机、代码拉取、镜像构建、服务启动操作，原脚本内容如下：

def secret = 'server'
def server = 'jenkins@103.171.85.155'
def directory = 'wayshub-frontend'
def branch = 'master'

pipeline{
    agent any
    stages{
        stage ('compose down and pull'){
            steps{
                sshagent([secret]) {
                    sh '''
                    ssh -o StrictHostkeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose down
                    docker system prune -f
                    git pull origin ${branch}
                    exit
                    EOF
                    '''
                }
            }
        }
        stage ('build images'){
            steps{
                sshagent([secret]) {
                    sh '''
                    ssh -o StrictHostkeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose build
                    exit
                    EOF
                    '''
                }
            }
        }
        stage ('deploy'){
            steps{
                sshagent([secret]) {
                    sh '''
                    ssh -o StrictHostkeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose up -d
                    exit
                    EOF
                    '''
                }
            }
        }
    }
}

构建执行时触发报错，核心错误信息如下：

java.lang.NoSuchMethodError: No such DSL method 'sshagent' found among steps [archive, bat, build, catchError, checkout, deleteDir, dir, dockerFingerprintFrom, dockerFingerprintRun, echo, emailext, emailextrecipients, envVarsForTool, error, fileExists, findBuildScans, getContext, git, input, isUnix, junit, library, libraryResource, load, mail, milestone, node, parallel, powershell, properties, publishChecks, publishHTML, pwd, pwsh, readFile, readTrusted, resolveScm, retry, script, sh, sleep, stage, stash, step, timeout, timestamps, tm, tool, unarchive, unstable, unstash, validateDeclarativePipeline, waitUntil, warnError, withChecks, withContext, withCredentials, withDockerContainer, withDockerRegistry, withDockerServer, withEnv, withGradle, wrap, writeFile, ws]

故障根因 #

1. 核心报错原因：Jenkins环境未安装SSH Agent插件。sshagent是该插件提供的专属Pipeline步骤，未安装插件时Jenkins无法识别该DSL方法，直接抛出找不到方法的错误。
2. 原脚本存在两处隐藏问题，即使安装插件后也会执行失败：
   • 所有sh步骤使用三单引号'''包裹shell命令，Groovy语法中单引号字符串不会执行变量插值，脚本顶部定义的server/directory/branch变量无法传入ssh命令，会导致远程执行时变量为空报错
   • SSH参数拼写错误：StrictHostkeyChecking中key首字母未大写，正确参数名为StrictHostKeyChecking

解决步骤 #

• 安装SSH Agent插件
  1. 进入Jenkins后台「系统管理」-「插件管理」页面
  2. 在可选插件列表搜索SSH Agent，勾选后执行安装，安装完成后重启Jenkins生效
  3. 提前在Jenkins「凭据管理」中添加ID为server的SSH私钥凭据，确保该私钥对目标部署服务器有免密登录权限
• 修复Pipeline脚本问题，修正后可正常执行的脚本如下：

def secret = 'server'
def server = 'jenkins@103.171.85.155'
def directory = 'wayshub-frontend'
def branch = 'master'

pipeline{
    agent any
    stages{
        stage ('compose down and pull'){
            steps{
                sshagent([secret]) {
                    // 替换为三双引号支持变量插值，修正SSH参数拼写
                    sh """
                    ssh -o StrictHostKeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose down
                    docker system prune -f
                    git pull origin ${branch}
                    exit
                    EOF
                    """
                }
            }
        }
        stage ('build images'){
            steps{
                sshagent([secret]) {
                    sh """
                    ssh -o StrictHostKeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose build
                    exit
                    EOF
                    """
                }
            }
        }
        stage ('deploy'){
            steps{
                sshagent([secret]) {
                    sh """
                    ssh -o StrictHostKeyChecking=no ${server} << EOF
                    cd ${directory}
                    docker-compose up -d
                    exit
                    EOF
                    """
                }
            }
        }
    }
}

内容的提问来源于stack exchange，提问作者Alfino Dwi Nugroho