03. 部署失败自动回滚:Jenkins 编排引擎的异常处理实战

「Jenkins」系列已发布: 00. 一套 Jenkins 共享库,干掉 50 个项目的重复流水线配置 | 01. 一行闭包启动整条流水线:Jenkins Pipeline 入口设计揭秘 | 02. 730 行 Context 类:Jenkins Pipeline 的“全局黑板”怎么管配置 | 03. 部署失败自动回滚:Jenkins 编排引擎的异常处理实战(本文)

生产部署最怕半途崩。编排引擎的分级 ErrorHandler + 自动回滚 + 灰度策略,让一次失败部署变成用户无感知的小插曲。

1032 行代码如何优雅应对生产事故

详解 Jenkins 部署编排引擎的异常处理机制,掌握失败自动回滚与灰度发布的核心策略,让生产部署更加安全可靠。

一、编排引擎的职责边界

Stages.groovy是整个共享库中代码量最大的文件(1032 行),但它的职责其实非常单一:决定在什么时候、以什么顺序、在什么条件下、调用哪个执行器

它不构建 Docker 镜像——那是DockerImageManager的事。它不操作负载均衡——那是CLBManager/ALBManager的事。它甚至不决定部署策略——那是DeployStrategy的事。

这种"编排与执行分离"的设计,是这套系统最核心的架构决策。

graph TB subgraph 编排层 S --> EH[ErrorHandler] end subgraph 执行器层 DS --> SM[ServiceManager] DS --> CM[CLBManager] DS --> AM[ALBManager] DS --> SSH[SSHExecutor] DS --> HC[HealthChecker] DS --> VM[VersionManager] end subgraph 可观测层 S --> NF[Notify] EH --> NF end

1.1 Pipeline 阶段的生命周期

Stages 将一次完整的部署流水线划分为十个标准阶段,每个阶段都有明确的触发条件和后置处理:

stateDiagram-v2 [*] --> Init: sysPipeline 调用 PermissionCheck --> RollbackStage: 权限通过 && ENABLE_ROLLBACK? RollbackStage --> TagSelection: 非回滚模式 DeployNotify --> Build: 开始部署流程 Build --> ArtifactVerify: 构建完成 DeployConfirm --> NodeDeploy: 人工确认或 AUTO_DEPLOY=true NodeDeploy --> DeploySuccessNotify: 节点部署完成 Init --> Fail: 配置异常 PermissionCheck --> Fail: 权限拒绝 DeployConfirm --> Fail: 用户取消部署 NodeDeploy --> Fail: 节点部署异常

这十个阶段的实际执行顺序可能因配置不同而有所裁剪:如果开启了回滚模式,会跳过构建阶段;如果设置了skipStages,可以跳过指定阶段。

1.2 Gate 机制:进入条件的前置校验

每个 Stage 在执行前,Stages 会检查两个条件:

  1. 跳过标记:如果该 Stage 在当前执行路径上被跳过(如回滚模式下跳过构建阶段),直接跳过。
  2. 前置依赖:检查 Context 中该 Stage 所需的关键属性是否已就绪。例如 Build 阶段会检查ctx.imageFullName或ctx.jarPath是否存在。

如果任一条件不满足,Stages 会根据严重程度选择跳过该阶段、等待重试,或直接终止 Pipeline。

1.2.1 Post-Action 机制:不管成功失败都要做的事

每个 Stage 还有一个 post-action 钩子。典型的 post-action 包括:

  • 记录该阶段的耗时到日志
  • 将阶段执行结果追加到 AuditLogger
  • 清理临时文件

这保证了即使某个阶段执行失败,审计日志仍然是完整的——排查问题时,你能知道"在哪个阶段、花了多长时间、因为什么原因失败"。

二、三种发布策略:滚动、单节点、分批

Stages 支持三种发布策略,通过 Jenkins 参数DEPLOY_STRATEGY切换:

策略 行为 适用场景
rolling(滚动) 逐批部署,每批 N 台服务器,批次间串行 常规生产部署,保证服务可用性
single(单节点) 指定单个节点部署,弹出选择列表 故障机器单独修复
batch(分批) 按批次并行部署,每批 N 台同时执行 非关键服务或测试环境

2.1 滚动部署的详细流程

以 rolling 策略为例,Stages 对每个节点执行以下原子操作序列:

sequenceDiagram participant S as Stages.deployNode() participant VM as VersionManager
版本备份 participant CLB as CLBManager
CLB 摘流 participant SM as ServiceManager
停止服务 participant SM2 as ServiceManager
启动服务 participant HC as HealthChecker
健康检查 participant ALB2 as ALBManager
ALB 挂流 participant VM2 as VersionManager
清理旧版本 S->>VM: backupCurrentVersion() S->>ALB: setWeight(serverId, 0) S->>CLB: setWeight(serverId, 0) S->>SM: stopService() S->>SSH: scp 文件 + systemd 创建 S->>HC: check(healthPath) S->>CLB2: setWeight(serverId, 100) S->>ALB2: setWeight(serverId, 100) S->>VM2: cleanupOldVersions()

每一步都独立可观测
。如果"传输文件"失败,日志会明确指出是哪一步出了问题,而不像一行ssh deploy.sh那样,失败了也不知道卡在哪。

2.1.1 Docker Compose 部署路径

当服务配置了cfg.docker.composeServiceName时,Stages 走另一条部署路径:

  1. 版本备份 → 2. ALB/CLB 摘流 → 3. 传输 compose 文件 → 4. 停止服务 → 5. 拉取新镜像 → 6. 启动服务 → 7. 健康检查 → 8. 流量恢复 → 9. 清理旧镜像

这条路径的核心区别在于:文件传输由DockerComposeManager.transferComposeFile()完成,它会读取本地的docker-compose.yml模板,替换${APP_ENV}、${IMAGE_TAG}、${SERVICE_PORT}等占位符后再传输到远程服务器。

三、异常处理的四级模型

ErrorHandler.groovy(327 行)定义了生产环境中最关键的能力:错误分级处理

3.1 四级错误模型

graph TD E[异常发生] --> C{分类判断} C -->|WARNING| W[警告,继续执行] C -->|ERROR| R[尝试自动恢复] R -->|恢复成功| OK[继续执行] R -->|恢复失败| G C -->|CRITICAL| G[紧急告警 + 尝试恢复] G -->|恢复成功| OK G -->|恢复失败| F C -->|FATAL| F[立即终止 Pipeline] F --> STOP[终止 Pipeline]
级别 典型场景 处理策略 示例
WARNING 非关键问题 记录警告,继续执行 旧镜像清理失败
ERROR 可恢复错误 尝试执行恢复策略 服务启动失败,尝试重启
CRITICAL 严重错误 紧急告警 + 尝试恢复 SSH 连接中断
FATAL 致命错误 立即终止 Pipeline 健康检查超时

3.1.1 部署阶段的特殊异常分类

Stages 在deployNodes()方法中实现了更精细的异常分类:

  • TrafficSwitchException:流量切换失败(摘流或挂流失败)。此时服务仍在运行(旧版本),不需要回滚,只需告警并终止。
  • ServiceStopException:停止服务失败。此时流量已摘除,旧服务仍在运行,不需要回滚。
  • 其他 Exception:部署过程中的其他失败。触发自动回滚(如果autoRollback开启),将节点恢复到上一个备份版本。

这种分类让每个异常都有明确的处置策略,避免了"一刀切"的粗暴处理方式。

3.1.2 黄金三秒:异常发生后的自动上下文采集

当 FATAL 级别的异常发生时,ErrorHandler 在终止 Pipeline 之前会触发完整的环境快照。这个快照包含:

  • 当前阶段名称和执行进度
  • Context 中的关键属性(服务名、版本、环境、节点列表)
  • 最近 100 行 Jenkins 控制台日志
  • 异常堆栈

然后这个快照会通过 Notify 发送到企业微信群。收到告警的工程师不需要登录 Jenkins 就能判断问题大概出在哪里——这在凌晨三点被 On-Call 叫醒时尤其有价值。

四、通知系统:不只是"成功/失败"

Notify.groovy(412 行)不是简单的"发送一条消息"那么简单。它实现了

  • 多渠道支持:企业微信 Markdown 消息 + 钉钉 Webhook,根据环境自动选择 webhook
  • 多事件类型:部署开始、部署成功、部署失败、部署中断、手动回滚、回滚成功——每种事件使用不同的消息模板
  • 环境隔离:test 环境用测试 webhook,pre 环境用预发 webhook,prod 环境用生产 webhook,互不干扰

通知内容包含服务名、版本号、环境、操作人、构建号等关键信息,让团队成员一目了然。

五、设计启示

从编排引擎和异常处理的设计中,我们可以提炼出几条工程原则:

  1. 编排与执行分离:编排者不做事,执行者不决策。这避免了"上帝对象"。
  2. 异常分类优于异常统一处理:不是所有错误都应该终止流水线,也不是所有错误都值得重试。按场景分类处理,每个异常都有最合适的处置策略。
  3. 失败时的上下文比成功时的日志更重要:好的异常处理系统在失败时能提供完整的现场快照。
  4. 通知即可观测性:把通知当成第一等公民来设计,而不是事后补上的功能。

下一篇:04 混合负载均衡:CLB+ALB 流量调度 —— 如何在同一套流水线中无缝管理传统型和应用型两种负载均衡器?

📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货,微信搜索“运维知识点滴”或扫下方二维码关注,更新不迷路。

微信公众号【运维知识点滴】 微信小程序【A5单据合并&大试卷拆分转A4打印】
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费
运维实战干货 · 关注追更 Word 转 PDF · 试卷/发票打印神器 · 免费

💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的? 一个 Word 转 PDF 的打印神器,专治“文档版式和打印机对不上”:

  • A3 试卷打不出来? 学校发的电子版试卷多是 A3,家用打印机只吃 A4——上传 Word 一键转换:可缩到一页 A4(页数不变),也可对半拆成两张 A4(1:1 原大、字更清晰),两种模式自选;
  • 版式不乱:真实渲染引擎原样转换、绝不重排内容,转出的 PDF 和原 Word 排版一致,公式/表格/图片不跑版;
  • 两张 A5 单据拼一张 A4:出租车票、火车票等报销凭证拼版后,一次打印、整齐粘贴;
  • 隐私省心:无需注册,转换结果留存 5 天、最多下载 5 次即自动删除,不留任何历史记录;
  • 微信扫码即用,免费、免安装,支持 doc / docx(≤50MB)。

上一篇:02. 730 行 Context 类:Jenkins Pipeline 的“全局黑板”怎么管配置