夜雨聆风
PublishOverSSH 插件使用指南:实现 Jenkins 到远程服务器的安全文件传输与命令执行
PublishOverSSH 插件使用指南：实现 Jenkins 到远程服务器的安全文件传输与命令执行
实际应用场景背景
在企业级 DevOps 实践中，经常需要将构建好的应用程序安全地部署到远程服务器，同时执行必要的运维命令。Publish Over SSH 插件提供了一种简单可靠的方式来实现 Jenkins 与远程服务器之间的安全连接，支持文件传输和命令执行，广泛应用于应用部署、配置管理和系统维护等场景。
概述
Publish Over SSH 是 Jenkins 的一款强大插件，允许在构建过程中通过 SSH 协议安全地连接到远程服务器，执行文件传输和命令执行操作。该插件简化了远程部署流程，提高了部署的可靠性与安全性，是现代 CI/CD 流水线中的重要组件。
安装与配置
重要提醒：备份 Jenkins
在安装任何插件之前，强烈建议备份 Jenkins 配置，以防插件安装导致 Jenkins 出现问题。由于安装插件后需要重启 Jenkins，因此备份是防止数据丢失的关键步骤。
备份方法：
-
1. 备份 Jenkins 主目录（通常是 /var/lib/jenkins 或 /root/.jenkins） -
2. 或者使用 Jenkins 的备份插件进行系统备份
1. 插件安装
在 Jenkins 中安装 Publish Over SSH 插件：
方式一：在线安装
-
1. 进入 “Manage Jenkins” → “Manage Plugins” -
2. 在 “Available” 标签页搜索 “Publish Over SSH” -
3. 选择插件并点击 “Install without restart”
方式二：离线安装（推荐）
如果在线无法找到插件，可以使用张师傅提供的插件文件进行离线安装：
-
1. 下载插件文件：publish-over-ssh.hpi -
2. 进入 “Manage Jenkins” → “Manage Plugins” → “Advanced” 标签页 -
3. 在 “Upload Plugin” 部分，点击 “Choose File” 选择下载的 .hpi 文件 -
4. 点击 “Upload” 完成上传安装 -
5. 安装完成后，重启 Jenkins 服务
注意：很多情况下在线可能查询不到此插件，张师傅提供了此插件的备份文件，确保您可以顺利完成安装。
2. 服务器配置
-
1. 进入 “Manage Jenkins” → “Configure System” -
2. 找到 “Publish over SSH” 部分 -
3. 配置 SSH 服务器信息：
SSH Servers:
Name:remote-server-name
Hostname:your-server-ip
Username:username
Remote Directory:/path/to/remote/directory
Advanced Settings:
-Usepasswordauthentication,or use a different key: [勾选]
-Passphrase / Password: [输入密码或密钥]
-Port:22(默认)
-Timeout (ms):300000
-TCP No Delay:true
配置参数详解
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Jenkinsfile 编写实践
基础用法示例
pipeline {
agent any
stages {
stage('远程操作') {
steps {
script {
sshPublisher(
publishers: [
sshPublisherDesc(
configName:'remote-server-name', // 对应配置的服务器名称
transfers: [
sshTransfer(
cleanRemote:false, // 是否清理远程目录
excludes:'', // 排除的文件模式
execCommand:'''
# 在远程服务器执行的命令
pwd
ls -la
date
''',
execTimeout:120000, // 命令执行超时(毫秒)
flatten:false, // 是否扁平化目录结构
makeEmptyDirs:false, // 是否创建空目录
noDefaultExcludes:false, // 是否排除默认模式
patternSeparator:'[, ]+', // 模式分隔符
remoteDirectory:'/tmp', // 远程目标目录
remoteDirectorySDF:false, // 目录是否使用日期格式
removePrefix:"", // 移除的路径前缀
sourceFiles:"dist/**"// 要传输的源文件
)
],
usePromotionTimestamp:false, // 是否使用推广时间戳
useWorkspaceInPromotion:false, // 推广时是否使用工作区
verbose:true// 详细输出
)
]
)
}
}
}
}
}实际部署示例
以下是一个通用的部署场景的 Jenkinsfile 示例，展示了如何使用 Publish Over SSH 进行远程部署：
pipeline {
agent any
stages {
stage('远程部署') {
steps {
script {
sshPublisher(
publishers: [
sshPublisherDesc(
configName:'remote-server-name', // 必须与Jenkins系统配置中的服务器名称一致
transfers: [
sshTransfer(
cleanRemote:false, // 是否在传输前清空远程目录
excludes:'', // 排除的文件模式，如'.git,**/*.log'
execCommand:"""
# execCommand 参数详解：
# - 作用：在文件传输完成后，在远程服务器上执行指定的命令
# - 使用场景：启动应用、重启服务、执行部署脚本等
# - 格式：可以是单行或多行命令，多行命令使用三重引号包围
# - 注意：命令会在 remoteDirectory 目录下执行
cd ${env.remoteDirectory} && \\
export APP_IMAGE=${env.APP_IMAGE} && \\
docker-compose -f docker-compose.yaml -p my-project up -d --force-recreate my-app
""",
execTimeout:120000, // 命令执行超时时间（毫秒）
flatten:false, // 是否扁平化目录结构
makeEmptyDirs:false, // 是否创建空目录
noDefaultExcludes:false, // 是否排除默认模式
patternSeparator:'[, ]+', // 模式分隔符，用于分隔 sourceFiles 或 excludes 中的多个模式
remoteDirectory:"$env.remoteDirectory", // 传输到远程服务器的目标目录
remoteDirectorySDF:false, // 目录是否使用日期格式
removePrefix:"", // 移除的路径前缀
sourceFiles:"target/*.jar,dist/**"// 要传输的源文件，支持Ant风格通配符
)
],
usePromotionTimestamp:false, // 是否使用推广时间戳
useWorkspaceInPromotion:false, // 推广时是否使用工作区
verbose:true// 详细输出，便于调试
)
]
)
}
}
}
}
}参数详细说明
以下是 Publish Over SSH 插件中各个参数的详细解释：
1. configName
-
• 含义: 对应在 Jenkins 系统配置中定义的 SSH 服务器名称 -
• 作用: 用于指定要连接的远程服务器配置，必须与系统配置中的服务器名称完全匹配 -
• 示例: ‘remote-server-name’
2. cleanRemote
-
• 含义: 是否在传输前清空远程目录 -
• 可选值: true/false -
• 作用: 当设置为 true 时，在文件传输前会先清空远程目标目录 -
• 注意: 使用时需谨慎，避免意外删除重要文件
3. execCommand
-
• 含义: 在远程服务器上执行的命令 -
• 作用: 允许在文件传输完成后执行一系列命令，如启动服务、重启进程等 -
• 格式: 可以是单行或多行命令，多行命令建议使用三重引号包围 -
• 示例:
execCommand: '''
cd /app
echo "Starting application..."
systemctl restart myapp
'''4. execTimeout
-
• 含义: 命令执行的超时时间 -
• 单位: 毫秒 -
• 作用: 控制远程命令执行的最大等待时间，超过此时间将终止命令执行 -
• 推荐值: 根据命令复杂度设置，一般为 60000-300000（1-5分钟）
5. remoteDirectory
-
• 含义: 文件传输的目标远程目录 -
• 作用: 指定文件传输到远程服务器的具体路径 -
• 特点: 相对于服务器配置中设定的远程目录
6. sourceFiles
-
• 含义: 要传输的源文件路径模式 -
• 作用: 定义哪些文件需要传输到远程服务器 -
• 格式: 支持 Ant 风格的通配符模式 -
• 示例: ‘dist/**’, ‘target/.jar’, ‘config/‘
7. excludes
-
• 含义: 排除的文件模式 -
• 作用: 指定不需要传输的文件或目录 -
• 格式: 逗号分隔的多个排除模式 -
• 示例: ‘.git,/*.log,/temp/*’
8. flatten
-
• 含义: 是否扁平化目录结构 -
• 可选值: true/false -
• 作用: 当设置为 true 时，忽略源文件的目录结构，将所有文件传输到同一目录
9. makeEmptyDirs
-
• 含义: 是否创建空目录 -
• 可选值: true/false -
• 作用: 当设置为 true 时，即使目录为空也会被创建
10. noDefaultExcludes
-
• 含义: 是否排除默认模式 -
• 可选值: true/false -
• 作用: 控制是否应用默认的排除规则（如 .gitignore 文件中的规则）
11. patternSeparator
-
• 含义: 模式分隔符 -
• 作用: 定义多个文件模式之间的分隔符 -
• 默认值: ‘[, ]+’（支持逗号和空格分隔） -
• 说明: 这个参数控制 sourceFiles、excludes 等多个模式值之间的分隔符。例如，当有多个源文件模式如 ‘src/, lib/, config/**’ 时，使用 patternSeparator 来识别各模式的边界
12. remoteDirectorySDF
-
• 含义: 目录是否使用日期格式 -
• 可选值: true/false -
• 作用: 当设置为 true 时，remoteDirectory 支持日期格式化
13. removePrefix
-
• 含义: 移除的路径前缀 -
• 作用: 在传输文件时移除指定的路径前缀 -
• 示例: 如果源文件路径为 ‘dist/app/main.js’，removePrefix 设置为 ‘dist/’，则文件会被传输到 remoteDirectory/app/main.js
14. usePromotionTimestamp
-
• 含义: 是否使用推广时间戳 -
• 可选值: true/false -
• 作用: 在推广构建时是否使用时间戳创建子目录
15. useWorkspaceInPromotion
-
• 含义: 推广时是否使用工作区 -
• 可选值: true/false -
• 作用: 控制推广构建时的行为
16. verbose
-
• 含义: 详细输出 -
• 可选值: true/false -
• 作用: 当设置为 true 时，输出更详细的传输日志，便于调试
最佳实践建议
1. 安全性考虑
-
• 使用 SSH 密钥而非密码进行认证 -
• 限制远程用户权限，遵循最小权限原则 -
• 定期更换认证凭据
2. 错误处理
-
• 设置合理的超时时间 -
• 在远程命令中添加错误检查逻辑 -
• 使用 verbose 模式进行调试
3. 性能优化
-
• 合理设置文件传输过滤规则 -
• 避免不必要的文件传输 -
• 使用适当的并发连接数
常见问题及解决方案
问题1: 连接超时
解决方案:
-
• 检查网络连通性 -
• 增加超时时间设置 -
• 确认防火墙规则
问题2: 权限不足
解决方案:
-
• 验证 SSH 用户权限 -
• 检查目标目录权限 -
• 确认 SELinux/AppArmor 配置
问题3: 文件传输失败
解决方案:
-
• 检查磁盘空间 -
• 验证路径是否存在 -
• 调整传输参数
与其他工具对比
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SEO 关键词融入
Publish Over SSH、Jenkins 远程部署、SSH 自动化、Jenkins CI/CD、远程服务器管理、自动化部署、SSH 文件传输、Jenkins 插件、DevOps 自动化、安全部署
总结
Publish Over SSH 插件是 Jenkins 生态系统中不可或缺的组件，为 CI/CD 流水线提供了可靠的远程操作能力。通过合理配置和使用，可以实现高效、安全的应用部署和系统管理。掌握该插件的使用方法对于 DevOps 工程师来说至关重要，能够显著提升部署效率和系统可靠性。
参考文档
-
• Jenkins Publish Over SSH Plugin 官方文档 -
• SSH 协议规范 -
• Jenkins Pipeline 语法指南 -
• DevOps 最佳实践指南
温馨提示
由于网络环境或文件存储等因素，若相关文件或图片链接暂时无法访问，您也可以通过访问张师傅的好来斯技术博客获取更多相关资源和最新信息。
本篇文章原始链接：
https://www.howlaisi.com/categories/jenkins/publishoverssh-cha-jian-shi-yong-zhi-nan