DM-ROW 接口文档

Appearance

Jenkins流水线配置 ​

**本文引用的文件** - [Jenkinsfile（lemes-web）](file://dm/lemes-web/Jenkinsfile) - [Jenkinsfile（docs前端）](file://docs/front end/dm/lemes-web/Jenkinsfile) - [JenkinsCommon.groovy](file://lemes-cloud/src/devops/JenkinsCommon.groovy) - [devops-ci.yml（lemes-cloud）](file://lemes-cloud/devops-ci.yml) - [devops-ci.yml（lemes-service-common）](file://lemes-cloud/lemes-service-common/devops-ci.yml) - [devops-ci.yml（lemes-web）](file://dm/lemes-web/devops-ci.yml) - [devops-ci.yml（docs前端）](file://docs/front end/dm/lemes-web/devops-ci.yml) - [Jenkinsfile（lemes-auth）](file://lemes-cloud/lemes-auth/Jenkinsfile) - [Jenkinsfile（lemes-gateway）](file://lemes-cloud/lemes-gateway/Jenkinsfile) - [Jenkinsfile（lemes-framework）](file://lemes-cloud/lemes-framework/Jenkinsfile) - [Jenkinsfile（lemes-service-dm-device）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/Jenkinsfile) - [Jenkinsfile（lemes-service-dm-store）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/Jenkinsfile) - [Jenkinsfile（lemes-service-dm-workflow）](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/Jenkinsfile)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本文件面向CI/CD工程师，系统性梳理DeviceMate项目的Jenkins流水线配置，重点解析Jenkinsfile的Declarative Pipeline结构、阶段划分、并行与串行组合、触发机制、参数化与环境变量、错误处理与恢复策略，并结合通用Groovy工具库JenkinsCommon.groovy，给出可复用、模块化的流水线设计建议与最佳实践。

项目结构 ​

DeviceMate项目由多模块构成，包含后端Spring Cloud微服务、前端Web应用以及若干公共框架与作业模块。Jenkins流水线在各模块的Jenkinsfile中统一委托给devops.JenkinsCommon工具类，通过传入config映射实现差异化行为（如部署目标、是否混淆、是否打包镜像、Sonar扫描等）。

图表来源

章节来源

核心组件 ​

  • Declarative Pipeline入口：各模块Jenkinsfile通过@Library引入通用库，并实例化devops.JenkinsCommon，传入config映射后调用executeCommon(config)。
  • 通用流水线工具：JenkinsCommon.groovy封装了代码拉取、构建（前端Webpack或后端Maven）、可选混淆、镜像构建与推送、Rancher部署、Sonar扫描、结果判定与异常处理。
  • 配置驱动：通过config映射控制willDeploy（部署目标）、submodule（子模块列表）、buildCommand（自定义构建命令）、confusion（混淆开关）、commonDockerfile（是否使用公共Dockerfile）、dockerBuild（是否打包镜像）、sonar（是否扫描）、jdk版本等。

章节来源

架构总览 ​

下图展示从Jenkinsfile到通用工具库的调用链路，以及关键阶段的职责分工。

图表来源

详细组件分析 ​

通用流水线工具：JenkinsCommon.groovy ​

  • 节点与工具初始化：声明JDK/Maven工具链，设置PATH与JAVA_HOME，打印版本信息。
  • 分支与镜像标签：基于BRANCH_NAME生成镜像tag，统一Harbor项目命名空间。
  • 子模块支持：根据config.submodule在Code Pull阶段对指定子模块进行切换与同步。
  • 构建阶段：
    • 前端：使用node镜像执行npm install与构建。
    • 后端：执行mvn clean deploy，跳过测试。
  • 可选混淆：下载混淆工具与配置，对后端产物进行混淆并归档。
  • 容器化与推送：根据commonDockerfile决定是否使用公共Dockerfile，按分支与模块生成镜像名并推送至Harbor。
  • Rancher部署：遍历willDeploy配置，调用升级接口逐环境逐Pod发布。
  • Sonar扫描：按需执行sonar:sonar，读取config.sonar.token。
  • 结果判定：若存在任一部署失败，标记为UNSTABLE；异常直接标记FAILURE。

图表来源

章节来源

前端模块流水线（lemes-web） ​

  • 关键特性：
    • willDeploy：定义不同分支的部署目标（如dms-sit、mx-uat、wh-uat等）。
    • submodule：按分支选择视图模块集合（如src/views/devicemate、src/views/dms等）。
    • commonDockerfile：关闭通用Dockerfile，采用项目内自定义构建逻辑。
  • 触发方式：通过Jenkins Job配置的SCM轮询/推送/Webhook触发。
  • 参数化：通过config映射注入部署目标与子模块列表。

章节来源

后端模块流水线（lemes-auth、lemes-gateway、lemes-framework、service-dm-*） ​

  • 共同点：
    • 统一委托JenkinsCommon.executeCommon(config)。
    • 可选confusion、sonar、jdk版本、dockerBuild等。
  • 差异点：
    • willDeploy：仅在特定分支配置部署目标。
    • jdk：部分模块指定amazon-corretto-17。
    • dockerBuild：framework模块显式禁用镜像构建。

章节来源

配置驱动与参数化 ​

  • config映射字段（示例）：
    • willDeploy：Map<分支, List<环境>>
    • submodule：Map<分支, Map{'modules':[...]}> 或 List
    • buildCommand：字符串或Map<分支, 字符串>
    • confusion：布尔
    • commonDockerfile：布尔
    • dockerBuild：布尔
    • sonar：Map
    • jdk：字符串（如amazon-corretto-17）
  • 环境变量：
    • Jenkins环境变量（如BRANCH_NAME）被JenkinsCommon读取用于镜像标签与分支判断。
    • Sonar扫描使用config.sonar.token或外部凭据。

章节来源

错误处理与恢复 ​

  • 失败重试：JenkinsCommon未内置自动重试，可在Jenkinsfile层为特定stage配置retry策略。
  • 跳过策略：当willDeploy为空或dockerBuild=false时，跳过对应阶段。
  • 中断处理：catch异常后将构建结果标记为FAILURE；部署阶段任一失败标记为UNSTABLE。
  • 建议：在Jenkinsfile中对关键stage增加post阶段与通知策略，结合节点标签与资源限制提升稳定性。

章节来源

触发机制 ​

  • 手动触发：Jenkins Job页面“立即构建”。
  • 定时触发：在Jenkins Job配置中添加定时触发器。
  • 代码推送触发：Jenkins Job绑定SCM，配置Webhook或轮询。
  • 分支合并触发：通过过滤分支或使用参数化选择分支，配合SCM触发。

章节来源

并行与串行组织 ​

  • JenkinsCommon内部按阶段顺序执行（Code Pull → App Build → Confusion → Docker → Rancher → Sonar），未见显式parallel块。
  • 若需并行：可在Jenkinsfile中对多个willDeploy环境或多个子模块构建进行并行化（需在Jenkinsfile层扩展）。

章节来源

依赖关系分析 ​

  • 模块到工具库：所有Jenkinsfile均依赖JenkinsCommon.groovy。
  • 工具库到外部系统：Harbor/Docker Registry、Rancher升级接口、SonarQube。
  • 配置耦合：willDeploy/submodule/buildCommand/confusion/dockerBuild/sonar/jdk等均通过config映射传递，降低Jenkinsfile重复。

图表来源

章节来源

性能考量 ​

  • 前端缓存与增量：JenkinsCommon中提供isNpmInstall判断逻辑（注释掉），可考虑启用以减少不必要的npm install。
  • 镜像构建优化：使用--no-cache与合适的build-arg，避免历史层影响。
  • Sonar扫描：仅在必要分支执行，减少构建时间。
  • 资源隔离：通过节点标签与容器资源限制，避免并发构建互相抢占。

章节来源

故障排查指南 ​

  • 构建失败定位：
    • 查看App Build阶段日志，确认前端npm安装或后端Maven打包是否报错。
    • 检查confusion阶段（后端）是否存在混淆工具下载或替换失败。
  • 镜像推送失败：
    • 核对Harbor凭据与网络连通性。
    • 检查commonDockerfile与JDK版本匹配。
  • Rancher部署失败：
    • 检查willDeploy配置与集群rancherName/instanceCode是否正确。
    • 关注升级接口返回码与异常堆栈。
  • Sonar扫描失败：
    • 确认token有效与网络可达。
  • 构建结果：
    • 任一部署失败标记为UNSTABLE；异常直接标记FAILURE。

章节来源

结论 ​

DeviceMate项目的Jenkins流水线通过JenkinsCommon.groovy实现了高度模块化与可配置化，前端与后端构建路径清晰，部署与扫描环节完善。建议在Jenkinsfile层补充重试、并行与通知策略，进一步提升稳定性与可观测性。

附录 ​

最佳实践清单 ​

  • 在Jenkinsfile中为关键stage配置retry与post通知。
  • 对willDeploy与submodule进行分环境分分支管理，避免误发布。
  • 统一JDK版本与工具链，减少环境差异。
  • 将Sonar扫描限定在必要分支，平衡质量与效率。
  • 对Dockerfile与镜像标签进行版本化管理，便于回滚。

示例参考路径 ​