Rundeck 开源仓库构建与测试命令实战指南:从 Gradle 多模块构建到前后端测试

原创2026-10-05 21:53:011,952 阅读
文章标签:运维任务调度后端

Rundeck 开源仓库构建与测试命令实战指南:从 Gradle 多模块构建到前后端测试

本文基于 Rundeck OSS 仓库的开发者速查文档 build-commands.md 展开,系统讲解该仓库的 Gradle 多模块构建流程、后端/功能/前端三层测试体系以及常见构建故障的排查方法。读完本文,你将掌握如何在本仓库中完成完整构建、跳过测试的快速构建、单模块定向测试、Docker 容器化功能测试与 ui-trellis 前端单元测试,并能独立处理 Java 17 缺失、前端依赖损坏、Gradle Daemon 异常等高频问题。

仓库构建系统概览

Rundeck 是一个基于 Grails 7 + Spring Boot 3.5 + Groovy 4 + Java 17 构建的多模块 Gradle 项目。从 settings.gradle 可以看到,仓库将工程拆分为数十个模块,核心包括:

  • rundeckapp:主应用(Grails 应用),也是最终 WAR 包的产出模块;
  • rundeckapp:grails-spa:packages:ui-trellis:前端单页应用(Vue + TypeScript + Jest);
  • core、rundeck-authz、rundeck-storage、rundeck-repository、rundeck-data-models:后端核心与领域模型;
  • plugins:*:一系列内置插件(localexec、script、jsch、git、object-store 等);
  • functional-test:基于 Docker Compose 与 Spock 的功能测试模块。

顶层 gradle.properties 集中管理版本与构建行为,其中与本指南直接相关的关键项包括:

# 当前版本与框架基线
currentVersion = 6.3.0
grailsVersion=7.2.2
springBootVersion=3.5.16
groovyVersion=4.0.33

# Gradle 行为开关
org.gradle.daemon=true          # 启用 Gradle Daemon
org.gradle.parallel=true        # 启用并行构建
org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx4096M -XX:MaxMetaspaceSize=1024M -XX:+HeapDumpOnOutOfMemoryError

注意 org.gradle.jvmargs 中的 -Xmx4096M 与 -XX:MaxMetaspaceSize=1024M:这是为 Groovy 4 + Grails 7 编译预留的堆内存(注释注明从原来的 1024M 提升而来)。如果你的机器内存紧张或编译频繁 OOM,可优先从这里排查。

此外,模块的 Java 版本约束统一来自 gradle/java-version.gradle,它声明了 sourceCompatibility = JavaVersion.VERSION_17 与 targetCompatibility = JavaVersion.VERSION_17。这意味着本地开发必须安装 JDK 17,否则会直接触发后文“Cannot find Java 17”的构建失败。

常见构建任务详解

原文档给出的构建命令速查如下,我们逐条展开说明其适用场景:

# 完整构建(含测试与质量检查,耗时最长)
./gradlew build

# 跳过测试的构建
./gradlew build -x test

# 跳过测试与质量检查(最快,约 4-8 分钟)
./gradlew build -x check

# 开发模式启动应用
./gradlew bootRun

# 清理构建产物
./gradlew clean

# 代码格式化检查 / 自动修复
./gradlew spotlessCheck
./gradlew spotlessApply

完整构建 ./gradlew build:这是最保守的命令,会依次执行编译、单元测试、质量检查(详见下文“构建验证”一节)。由于 Rundeck 模块众多,全量测试套件可能耗时超过 1 小时,日常迭代中并不常用。

./gradlew build -x test:跳过测试,仅验证编译与产物打包。当你想快速确认改动能否编译通过、且不关心测试结果时使用。

./gradlew build -x check(最快):-x check 同时跳过了测试(test 属于 check 生命周期)以及 CodeNarc 等质量检查任务。原文档明确标注其耗时为 4-8 分钟,是本地快速验证构建的首选。它的语义是“只编译代码、产出构建产物,不跑测试套件、不跑代码质量检查”,完整测试留给 CI 执行。

./gradlew bootRun:以开发模式启动 Rundeck 应用。该命令在 rundeckapp/build.gradle 中定义,并且 bootRun 依赖 processResources 与 copyCompiledAssets(见 rundeckapp/build.gradle)——这是因为 bootRun 没有 WAR 根目录,前端编译产物必须通过类路径注入,这些任务会把已编译的资产复制到 classpath:/assets/ 下,保证开发模式下页面资源可访问。

./gradlew clean:清理所有模块的构建产物,用于解决增量编译脏数据、缓存不一致等问题。

代码格式化:原文档记录的 spotlessCheck / spotlessApply 用于检查与自动修复代码格式。需要说明的是,从当前仓库根 build.gradle 的实际配置看,Groovy 代码质量检查集成的是 CodeNarc(规则文件见 config/codenarc/rules.groovy,复杂度报告可通过 ./gradlew codenarcComplexity 生成)。若你的分支上 Spotless 插件未启用,上述两条命令可能不可用,请以实际环境的任务列表为准。

后端测试:单元测试与定向执行

# 运行所有模块的全部测试
./gradlew test

# 只运行指定测试类(支持通配符)
./gradlew test --tests "com.example.MySpec"

# 只运行 rundeckapp 模块的测试
./gradlew :rundeckapp:test
  • ./gradlew test 会遍历所有 Java/Groovy 模块执行测试。Rundeck 的单元测试以 Spock 为主(仓库中大量 *Spec.groovy 测试类即 Spock 规范),测试框架版本由 gradle.properties 中的 spockVersion=2.3-groovy-4.0 管理。
  • --tests 支持精确类名或通配符(如 --tests "org.rundeck.*Spec"),适合调试单个失败用例,能显著缩短测试反馈周期。
  • :rundeckapp:test 是典型的按模块定向执行语法。Gradle 中模块路径由 settings.gradle 的 include 声明决定,rundeckapp 及 plugins:*、core、rundeck-authz:* 等均可按同样方式定向测试。只改动某个插件时,运行 ./gradlew :plugins:git-plugin:test 这类命令远比全量测试高效。

功能测试:Docker 容器化的 API 与 Selenium 测试

功能测试模块 functional-test 采用“Docker Compose 起一个真实的 Rundeck 容器,再用 Spock 写 API/Selenium 测试”的架构,其任务在 functional-test/build.gradle 中定义。原文档给出的命令为:

# API 功能测试
./gradlew :functional-test:apiTest

# Selenium 功能测试
./gradlew :functional-test:seleniumTest

注意任务名差异:当前仓库的 functional-test/build.gradle 中,Selenium 任务的实际名称为 seleniumCoreTest(文档中的 seleniumTest 属于历史/别名写法)。同时仓库还提供了 alphaUiSeleniumCoreTest(开启 alphaUi 特性标志)、pluginBlocklistTest、ldapTest、jdbcTest、apiTestNodeExecutorSecureInput 等专用任务,functional-test/readme.md 也确认当前有效任务为 apiTest、seleniumCoreTest、tomcatTest 等。因此 Selenium 测试实际应执行:

./gradlew :functional-test:seleniumCoreTest

功能测试默认针对 rundeck/rundeck:SNAPSHOT 镜像运行,可用的环境变量(详见 functional-test/readme.md)包括:

环境变量 默认值 作用
TEST_IMAGE rundeck/rundeck:SNAPSHOT 指定被测 Docker 镜像
TEST_RUNDECK_CONTAINER_SERVICE rundeck 要暴露的 Docker Compose 服务名
TEST_RUNDECK_CONTAINER_PORT 4440 宿主机暴露端口
TEST_RUNDECK_CONTAINER_CONTEXT 空 容器上下文路径(需以 / 开头)
TEST_RUNDECK_CONTAINER_TOKEN admintoken API 认证 Token
TEST_RUNDECK_GRAILS_URL http://localhost:4440 注入容器的 RUNDECK_GRAILS_URL
TEST_TARGET_PLATFORM linux/amd64 容器目标平台
TEST_WAR_FILE_LOCATION 空 指定 WAR 文件路径(tomcatTest 用)

此外还有两个实用开关:

  • USE_LOCAL_DOCKER_COMPOSE:默认使用本地 Docker 引擎与 docker compose 启动测试环境;设为 false 可回退到容器化 docker-compose(注意可能需要手动拉取部分镜像)。
  • TEST_SELENIUM_HEADLESS_MODE:Selenium 默认以 headless 模式运行(避免弹窗抢焦点);设为 false 可观察浏览器实际执行过程,便于调试 UI 测试。

如果不想自建 Docker 环境,也可以将功能测试指向一个外部已部署的 Rundeck 实例,只需设置 TEST_RUNDECK_URL(服务器基地址,不含 /api 路径)与 TEST_RUNDECK_TOKEN,并可选覆盖 RUNDECK_TEST_USER(默认 admin)与 RUNDECK_TEST_PASS(默认 admin123)。

从实现上看,apiTest 任务会注入 COMPOSE_PATH=docker/compose/oss/docker-compose.yml 与 Spock 配置 IncludeAPITestsConfig.groovy(按 @APITest 注解筛选用例),且 Grails 7 下强制 maxParallelForks = 1 顺序执行,以避免 Docker Compose 端口冲突(见 functional-test/build.gradle)。功能测试还支持通过 -PtestFiles=... 属性精确圈定要跑的测试类,便于 CI 失败后只重跑失败用例。

前端测试:ui-trellis 单元测试

前端(SPA)位于 rundeckapp/grails-spa/packages/ui-trellis,基于 Vue + TypeScript + Jest。原文档的命令如下:

UI=rundeckapp/grails-spa/packages/ui-trellis
npm run --prefix "$UI" ci:test:unit           # 运行前端单元测试
npm run --prefix "$UI" dev:test:watch         # 监听模式(改代码自动重跑)

在 rundeckapp/grails-spa/packages/ui-trellis/package.json 中可以找到这两个脚本的实际定义:

  • ci:test:unit:执行 npm ci && npm run test:unit,先基于 package-lock.json 做可复现的干净安装再跑 Jest,适合 CI 环境;
  • dev:test:watch:执行 npm install && jest --silent --watch,进入监听模式,本地迭代开发时改一行代码即自动回归。

--prefix 是 npm 的相对路径参数,使命令可以在仓库根目录直接对子包执行,无需 cd 切换目录。前端测试与后端测试相互独立,UI 改动建议先跑 dev:test:watch 快速验证,再回归后端。

构建验证:build -x check 的含义

原文档特别强调 ./gradlew build -x check 是“快速构建验证”手段:

# 快速构建验证(约 4-8 分钟)
./gradlew build -x check
  • 它会编译代码并产出构建产物(含 rundeckapp 的 WAR 包);
  • 但不执行测试套件(全量测试可达 1 小时以上);
  • 也不执行代码质量检查(CodeNarc、格式检查等)。

其隐含契约是:CI 会运行完整测试套件,因此本地提交前用 build -x check 快速确认“能编译、能出包”即可;安全性与回归由 CI 的完整流水线兜底。若你的改动涉及核心逻辑,建议本地至少补跑 ./gradlew :rundeckapp:test 或相关模块的定向测试。

故障排查

构建报错 “Cannot find Java 17”

由于全部模块要求 Java 17(见 gradle/java-version.gradle),当环境默认 JDK 不是 17 时构建会直接失败。在 macOS 上可显式指定 JDK 17 后重试:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)
./gradlew build -x check

Linux 环境下等价做法是:

export JAVA_HOME=/path/to/jdk-17
export PATH="$JAVA_HOME/bin:$PATH"
./gradlew build -x check

前端构建失败

node_modules 或 package-lock.json 损坏、与 lockfile 不一致,是前端构建失败最常见的诱因。原文档给出的修复方式是彻底重装依赖:

rm -rf node_modules package-lock.json
npm install

执行后建议先跑 npm run --prefix "$UI" ci:test:unit 验证依赖环境恢复正常。由于 ui-trellis 是独立 npm 包,重装不会影响后端构建;反之,若后端 bootRun 后页面资源缺失,也应检查 copyCompiledAssets 所依赖的前端编译产物是否生成。

Gradle Daemon 问题

gradle.properties 中 org.gradle.daemon=true 表明仓库默认开启常驻构建进程。当 Daemon 内存占用异常、JVM 参数变更不生效或出现诡异的构建失败时,先停掉 Daemon 再清理缓存:

./gradlew --stop
rm -rf ~/.gradle/caches

--stop 会终止所有常驻 Gradle Daemon;清除 ~/.gradle/caches 则会删除本地依赖与任务缓存,下次构建将从零下载/重算,耗时更长但能解决多数缓存脏数据问题。若问题与堆内存相关,可结合前文提到的 org.gradle.jvmargs 中 -Xmx4096M 与 -XX:MaxMetaspaceSize=1024M 设置一并排查。

小结

Rundeck 开源仓库的构建体系可以用一句话概括:顶层 ./gradlew 负责一切,-x 参数控制测试与检查的取舍,模块路径实现定向执行。日常开发最实用的三条路径是:

  1. 快速验证编译:./gradlew build -x check(4-8 分钟);
  2. 定向回归后端:./gradlew :rundeckapp:test --tests "目标Spec";
  3. 容器化端到端验证:./gradlew :functional-test:apiTest / :functional-test:seleniumCoreTest。

前端则以 npm run --prefix rundeckapp/grails-spa/packages/ui-trellis 独立驱动 Jest。掌握这些命令组合,即可在 Rundeck 庞大的多模块仓库中高效地完成从编译、单测到容器化功能测试的完整开发闭环。更多任务细节可查阅 functional-test/readme.md 与各模块的 build.gradle。

登录后查看全文
rundeck