CI/CD / 系统课时
用 SSH 私钥执行远程操作
用 SSH 私钥执行远程操作
Jenkins 经常需要通过 SSH 在目标服务器执行部署命令。私钥不应提交到仓库,也不应复制到工作区长期保存。可以把 SSH 私钥交给 Jenkins Credentials 管理,在部署步骤中生成临时密钥文件,使用结束后由凭据绑定机制清理。
学习目标
- 使用
sshUserPrivateKey临时加载 Jenkins 中的 SSH 私钥 - 配合已维护的
known_hosts校验远程服务器身份 - 避免私钥写入仓库、工作区或流水线日志
准备 SSH 凭据
先在 Jenkins Credentials 中保存 SSH Username with private key 类型凭据,例如 ID 为 deploy-ssh。私钥内容由 Jenkins 管理,Jenkinsfile 只引用凭据 ID。
远程主机身份也需要验证。示例额外准备一个 Secret file 类型凭据 production-known-hosts,其文件内容来自经过可信渠道确认的目标主机 known_hosts 记录。不要为了省事长期使用 StrictHostKeyChecking=no,否则会削弱 SSH 对服务器身份的校验。
临时绑定私钥并执行命令
sshUserPrivateKey 可以把私钥绑定为临时文件,并把文件路径写入指定环境变量。再用 file 绑定 known_hosts 文件,就能让 SSH 同时完成客户端认证和服务器身份校验。

下面假设目标主机通过参数 DEPLOY_HOST 提供。实际执行时把 <HOST> 替换成真实主机名或地址。
pipeline {
agent any
parameters {
string(name: 'DEPLOY_HOST', defaultValue: '<HOST>', description: 'Deployment host')
}
stages {
stage('Remote Deploy') {
steps {
withCredentials([
sshUserPrivateKey(
credentialsId: 'deploy-ssh',
keyFileVariable: 'SSH_KEY',
usernameVariable: 'SSH_USER'
),
file(
credentialsId: 'production-known-hosts',
variable: 'KNOWN_HOSTS'
)
]) {
sh '''
ssh \
-i "$SSH_KEY" \
-o IdentitiesOnly=yes \
-o UserKnownHostsFile="$KNOWN_HOSTS" \
-o StrictHostKeyChecking=yes \
"$SSH_USER@$DEPLOY_HOST" \
'printf "%s\\n" "remote deployment command executed"'
'''
}
}
}
}
}预期输出
remote deployment command executed<HOST> 是动态占位符,实际值由部署环境决定。真实部署时可以把最后的远程命令替换成目标服务器已有的部署脚本,例如启动服务或切换版本,但不要把私钥内容作为命令参数传递。
理解临时文件的边界
SSH_KEY 保存的是 Jenkins 为当前凭据绑定提供的私钥文件路径,不是私钥文本本身。SSH 使用 -i "$SSH_KEY" 读取该文件;KNOWN_HOSTS 同理指向临时绑定的主机记录文件。
还应避免把密钥文件路径保存到后续阶段作为长期依赖。需要再次连接时,在新的最小作用域中重新使用 withCredentials 获取凭据。
连接失败时按认证链排查
出现 Permission denied (publickey) 时,先确认 credentialsId 对应的用户名和私钥是否匹配目标服务器授权配置,再检查目标服务器是否允许该用户使用公钥认证。出现主机密钥校验失败时,则应核对 known_hosts 中的主机名和公钥指纹,而不是直接关闭校验。
远程部署的安全边界可以归纳为两部分:Jenkins 私钥证明“客户端是谁”,known_hosts 证明“服务器是谁”。两者都通过临时凭据绑定进入部署步骤,才能在不把私钥写进仓库或长期工作区的前提下完成可审计的 SSH 操作。