Rundeck 开源仓库构建与测试命令实战指南:从 Gradle 多模块构建到前后端测试
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 参数控制测试与检查的取舍,模块路径实现定向执行。日常开发最实用的三条路径是:
- 快速验证编译:
./gradlew build -x check(4-8 分钟); - 定向回归后端:
./gradlew :rundeckapp:test --tests "目标Spec"; - 容器化端到端验证:
./gradlew :functional-test:apiTest/:functional-test:seleniumCoreTest。
前端则以 npm run --prefix rundeckapp/grails-spa/packages/ui-trellis 独立驱动 Jest。掌握这些命令组合,即可在 Rundeck 庞大的多模块仓库中高效地完成从编译、单测到容器化功能测试的完整开发闭环。更多任务细节可查阅 functional-test/readme.md 与各模块的 build.gradle。