1. 为什么需要Publish over SSH插件？
在持续集成和持续部署(CI/CD)的实践中，Jenkins作为最流行的自动化服务器之一，经常需要将构建产物部署到远程服务器。传统的手动上传方式效率低下且容易出错，而Publish over SSH插件正是解决这一痛点的利器。
这个插件的工作原理是通过SSH协议（默认端口22）建立安全连接，使用SFTP（SSH File Transfer Protocol）进行文件传输。与FTP相比，SFTP的主要优势在于：
- 所有传输数据都经过加密
- 使用与SSH相同的认证机制
- 可以复用已有的SSH密钥体系
- 支持断点续传和文件权限保留
提示：虽然插件名称是"Publish over SSH"，但实际使用的是SFTP协议而非原始的SCP协议，这带来了更好的文件传输可靠性。
2. 环境准备与插件安装
2.1 服务器端配置
在目标服务器上需要确保：
- SSH服务已安装并运行（通常是openssh-server）
- 防火墙开放了SSH端口（默认22）
- 准备好具有适当权限的用户账号
验证SSH服务是否正常：
bash复制systemctl status sshd
如果使用密钥认证（推荐），需要在服务器上配置公钥：
bash复制# 在~/.ssh/authorized_keys中添加Jenkins服务器的公钥
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo "你的公钥内容" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
2.2 Jenkins端安装插件
在Jenkins管理界面：
- 进入"Manage Jenkins" > "Manage Plugins"
- 在"Available"标签页搜索"Publish Over SSH"
- 勾选安装并重启Jenkins
安装后验证：
bash复制# 检查插件是否加载成功
ls $JENKINS_HOME/plugins/publish-over-ssh*
3. 全局SSH服务器配置
3.1 基础配置路径
进入"Manage Jenkins" > "Configure System"，向下滚动到"Publish over SSH"部分。这里可以配置多个SSH服务器，供不同项目复用。
关键配置项说明：
| 配置项 | 说明 | 推荐值 |
|---|---|---|
| Name | 服务器别名 | 建议使用"环境-用途"命名，如"prod-web" |
| Hostname | 服务器IP或域名 | 确保DNS可解析 |
| Username | SSH登录用户名 | 避免使用root |
| Remote Directory | 远程基础目录 | 如"/opt/deploy" |
| Port | SSH端口 | 非标准端口时修改 |
| Timeout (ms) | 连接超时 | 建议30000(30秒) |
3.2 认证方式选择
插件支持两种认证方式：
-
密码认证：
- 直接填写Password字段
- 适合临时测试，不推荐生产环境使用
-
密钥认证（推荐）：
- 需要将Jenkins用户的私钥添加到配置中
- 私钥路径通常为
~/.ssh/id_rsa - 如果密钥有密码，需要在"Passphrase"字段填写
生成专用部署密钥对：
bash复制ssh-keygen -t rsa -b 4096 -C "jenkins-deploy" -f ~/.ssh/jenkins_deploy
3.3 高级配置技巧
-
跳板机配置：
如果需要通过跳板机访问目标服务器，可以：bash复制
ssh -J jump_user@jump_host target_user@target_host -
代理设置：
如果Jenkins需要通过代理访问外网，在/etc/default/jenkins中添加：bash复制JAVA_OPTS="-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8080" -
连接测试：
配置完成后点击"Test Configuration"按钮验证连接：- 成功：显示"Success"
- 失败：检查SSH服务、防火墙、密钥权限等
4. 项目中的SSH部署配置
4.1 基本文件传输
在Jenkins项目的配置页面，添加"Send files or execute commands over SSH"构建后步骤：
关键参数解析：
- Source files：要传输的文件路径，支持Ant风格模式
- 例如：
target/*.jar传输target目录下所有jar文件
- 例如：
- Remove prefix：移除源路径前缀
- 如源为
target/app.jar，前缀填target/，远程得到app.jar
- 如源为
- Remote directory：相对于全局配置中Remote Directory的路径
- Exec command：传输完成后执行的命令
- 如：
systemctl restart myapp
- 如：
典型配置示例：
code复制Source files: target/*.war
Remove prefix: target/
Remote directory: webapps/
Exec command:
chmod 755 /opt/webapps/*.war
/opt/tomcat/bin/shutdown.sh
/opt/tomcat/bin/startup.sh
4.2 高级传输模式
-
目录结构保留：
使用**/*模式传输完整目录结构：code复制Source files: build/dist/** Remove prefix: build/dist -
文件排除：
在"Advanced"选项中设置Excludes：code复制**/*.tmp, **/.gitignore -
传输前清理：
在Exec command中添加清理命令：bash复制rm -rf /opt/deploy/*
4.3 多服务器部署
对于需要同时部署到多台服务器的情况：
- 在全局配置中添加多个SSH Server
- 在项目配置中添加多个"Send files over SSH"步骤
- 或者使用"SSH Publishers"一次发送到多个服务器
多环境部署示例流程：
code复制1. 测试环境验证
- Server: test-web
- Command: test-specific commands
2. 生产环境部署
- Server: prod-web1,prod-web2
- Command:
/opt/scripts/rolling-deploy.sh
health-check.sh
5. 实战中的问题排查
5.1 常见错误与解决方案
| 错误现象 | 可能原因 | 解决方案 |
|---|---|---|
| Connection refused | SSH服务未运行/防火墙阻止 | 检查sshd状态和防火墙规则 |
| Authentication failed | 密钥错误/权限问题 | 检查密钥对和~/.ssh权限 |
| No such file or directory | 远程目录不存在 | 创建目录或调整路径 |
| Permission denied | 用户权限不足 | 调整目录权限或使用sudo |
| Timeout | 网络问题/负载高 | 增加超时时间或检查网络 |
5.2 日志分析技巧
-
启用SSH调试：
在Exec command前添加：bash复制export SSH_DEBUG_OPTS="-vvv" -
查看Jenkins控制台输出：
- 注意"SSH: Transferred"行确认传输文件
- 检查退出码（0表示成功）
-
服务器端日志：
bash复制journalctl -u sshd --since "1 hour ago"
5.3 性能优化
-
并行传输：
对于多台服务器，使用"Parallel transfer"选项 -
增量部署：
只传输变更文件：bash复制
rsync -avz -e ssh /local/path/ user@host:/remote/path/ -
压缩传输：
在Exec command中添加：bash复制tar -xzf package.tgz && rm package.tgz
6. 安全最佳实践
6.1 权限控制
-
最小权限原则：
- 创建专用部署用户
- 限制sudo权限到必要命令
bash复制
deployuser ALL=(ALL) NOPASSWD: /usr/bin/systemctl restart myapp -
目录隔离：
bash复制chown -R deployuser:deploygroup /opt/deploy chmod -R 750 /opt/deploy
6.2 密钥管理
-
密钥轮换：
- 定期更换部署密钥（建议每3-6个月）
- 旧密钥加入
revoked_keys文件
-
密钥存储：
- 使用Jenkins Credentials管理密钥
- 避免硬编码在项目中
6.3 审计与监控
-
记录部署操作：
bash复制echo "$(date) - Deployed by $USER" >> /var/log/deploy.log -
SSH登录监控：
bash复制grep 'sshd.*Accepted' /var/log/auth.log -
文件完整性检查：
bash复制find /opt/deploy -type f -exec md5sum {} \; > checksums.txt
7. 与其他工具的集成
7.1 与Docker集成
在Exec command中操作Docker：
bash复制docker stop myapp || true
docker rm myapp || true
docker run -d --name myapp -p 8080:8080 myimage:latest
7.2 与Kubernetes集成
使用kubectl滚动更新：
bash复制kubectl set image deployment/myapp myapp=myregistry/myapp:$BUILD_NUMBER
7.3 与配置管理工具结合
-
Ansible：
bash复制
ansible-playbook -i inventory deploy.yml -
Chef：
bash复制knife ssh 'name:web-*' 'sudo chef-client'
7.4 与监控系统联动
部署后触发健康检查：
bash复制curl -X POST "http://monitor/api/check?app=myapp&env=prod"
8. 实际案例：Spring Boot应用部署
8.1 项目结构假设
code复制myapp/
├── src/
├── target/
│ ├── myapp-1.0.0.jar
│ ├── application-prod.yml
│ └── lib/
├── Jenkinsfile
└── deploy.sh
8.2 Jenkins配置示例
-
Source files：
code复制target/myapp-*.jar, target/application-*.yml, target/lib/** -
Remove prefix：
code复制target/ -
Remote directory：
code复制/opt/myapp/ -
Exec command：
bash复制chmod 755 /opt/myapp/myapp-*.jar ln -sf /opt/myapp/myapp-1.0.0.jar /opt/myapp/current.jar sudo systemctl restart myapp
8.3 systemd服务文件
/etc/systemd/system/myapp.service：
ini复制[Unit]
Description=MyApp Service
After=network.target
[Service]
User=appuser
WorkingDirectory=/opt/myapp
ExecStart=/usr/bin/java -jar /opt/myapp/current.jar
Restart=always
[Install]
WantedBy=multi-user.target
8.4 部署后验证
在Exec command中添加：
bash复制sleep 10 # 等待应用启动
curl -sf http://localhost:8080/health || exit 1
9. 进阶技巧与自动化
9.1 参数化部署
在Jenkins项目中定义参数：
- DEPLOY_ENV：prod/stage/test
- RESTART_SERVICE：true/false
在Exec command中使用：
bash复制if [ "$RESTART_SERVICE" = "true" ]; then
sudo systemctl restart myapp-$DEPLOY_ENV
fi
9.2 版本回滚机制
-
保留历史版本：
bash复制cp /opt/myapp/myapp.jar /opt/myapp/backups/myapp-$(date +%Y%m%d%H%M).jar -
回滚脚本：
bash复制ln -sf /opt/myapp/backups/myapp-202306011200.jar /opt/myapp/current.jar
9.3 自动化测试集成
部署前后运行测试：
bash复制# 部署前测试
npm run test
# 部署后冒烟测试
curl -sf http://$HOST:8080/api/health | grep -q '"status":"UP"'
9.4 通知机制
部署结果通知到Slack：
bash复制curl -X POST -H 'Content-type: application/json' \
--data '{"text":"Deployment of $JOB_NAME ($BUILD_NUMBER) to $ENV completed"}' \
$SLACK_WEBHOOK
10. 维护与监控
10.1 插件更新策略
-
定期检查插件更新：
bash复制
jenkins-plugin-cli --list --available -
测试环境先验证：
bash复制cp $JENKINS_HOME/plugins/publish-over-ssh.jpi /tmp/backup/
10.2 连接池配置
在$JENKINS_HOME/config.xml中调整：
xml复制<sshConnector>
<connectionTimeout>30000</connectionTimeout>
<maxConnections>10</maxConnections>
</sshConnector>
10.3 资源监控
-
SSH连接数：
bash复制netstat -an | grep :22 | wc -l -
传输速度监控：
bash复制grep "SSH: Transferred" $JENKINS_HOME/jobs/*/builds/*/log | awk '{print $6}' -
磁盘空间检查：
bash复制df -h /opt/deploy
11. 替代方案比较
11.1 与Ansible比较
| 特性 | Publish over SSH | Ansible |
|---|---|---|
| 学习曲线 | 低 | 中 |
| 配置复杂度 | 简单 | 中等 |
| 扩展性 | 有限 | 强 |
| 适合场景 | 简单文件传输 | 复杂配置管理 |
11.2 与Rsync比较
bash复制rsync -avz -e ssh --delete /local/path/ user@host:/remote/path/
优势：
- 增量传输更高效
- 支持删除远程多余文件
- 更详细的进度显示
劣势：
- 需要额外安装rsync
- Jenkins集成度不如原生插件
11.3 与Docker/K8s部署比较
容器化部署更适合：
- 微服务架构
- 需要环境一致性
- 快速扩展的场景
SSH部署更适合：
- 传统应用
- 服务器数量少
- 简单直接的部署需求
12. 个人实战经验分享
在实际使用Publish over SSH插件多年后，我总结了以下经验教训：
-
密钥管理：
- 为每个环境使用独立密钥对
- 密钥加密存储，仅在部署时解密
- 使用Jenkins Credentials绑定密钥
-
目录结构设计：
bash复制
/opt/ ├── apps/ │ ├── myapp/ │ │ ├── releases/ │ │ │ ├── 1.0.0/ │ │ │ └── 1.0.1/ │ │ └── current -> releases/1.0.1/ ├── scripts/ └── logs/ -
部署脚本优化：
- 添加前置检查（磁盘空间、依赖版本等）
- 实现原子化部署（要么完全成功，要么完全回滚）
- 记录详细的部署日志
-
网络不稳定处理：
bash复制max_retries=3 retry_delay=5 for i in $(seq 1 $max_retries); do rsync -avz ... && break || sleep $retry_delay done -
权限控制技巧：
bash复制# 允许部署用户重启服务但限制其他操作 Cmnd_Alias DEPLOY_CMDS = /bin/systemctl restart myapp deployuser ALL=(ALL) NOPASSWD: DEPLOY_CMDS -
监控集成：
- 部署后自动触发监控系统基线更新
- 关键指标（部署时长、成功率）上报到Prometheus
- 失败部署自动创建工单
-
文档自动化：
bash复制# 生成部署报告 echo "Deployment Report" > report.txt echo "App: $JOB_NAME" >> report.txt echo "Version: $GIT_COMMIT" >> report.txt ssh user@host "cat >> /opt/deploy/logs/history.log" < report.txt -
多环境处理：
- 使用Jenkins的Environment Injector插件管理不同环境变量
- 部署脚本中根据环境加载不同配置
bash复制source /opt/configs/${DEPLOY_ENV}.env -
回滚机制：
- 保留最近5个版本
- 自动化健康检查失败时自动回滚
- 回滚操作需要与正常部署相同的审批流程
-
团队协作：
- 在部署日志中记录操作人（通过Jenkins的Build User Vars插件）
- 重要的生产部署需要多人确认
- 部署日历可视化展示各环境的变更情况