企业官网建设流程全解析

• 数据库
• 分布式数据库
• 后端

Apache Cassandra 的构建与测试既可以通过传统ant命令完成，也提供了一套更完整的辅助脚本体系（位于仓库根目录的 .build 目录下）。本篇技术指南以 .build/README.md 为核心，系统梳理这套脚本的用法：如何在 Docker 容器内外完成代码检查（Checkstyle 等 lint）、构建 tarball 与 Maven 产物、构建 Debian/RedHat 安装包、运行从单元测试到分布式 dtest 的全系列测试，以及如何接入 SonarQube 静态分析。读完本文，你将能够独立复现 Cassandra CI 流水线的核心步骤，并理解其中"同一份脚本、Docker 内外两种执行方式"的设计原理。

脚本体系总览：Docker 与非 Docker 双轨设计

.build目录下的辅助脚本遵循统一的设计约定：

• Docker 版本位于 .build/docker/，以docker run方式在容器内执行，是 CI（如 Jenkins）默认路径；
• 非 Docker 版本直接位于 .build/ 根目录，要求宿主机已安装ant、git、对应 JDK 等工具链；
• 所有脚本在首个参数为-h时都会打印帮助信息；
• 所有脚本的公共参数约定：
  • 可选的JDK 版本参数（如11、17），默认使用 build.xml 中java.default属性指定的版本；
  • 可选的build_dir环境变量，用于指定构建输出目录，从而支持"同一份源码并行发起多个构建"。

核心脚本与功能对照：

代码检查与 Lint：一键跑完静态检查

在 Docker 中运行代码检查：

.build/docker/check-code.sh

在宿主机直接运行（需本地具备ant）：

.build/check-code.sh

指定 JDK 版本（该约定适用于所有构建脚本）：

.build/docker/check-code.sh 11

指定独立构建路径（可用于同一源码路径并行构建，适用于所有构建脚本）：

build_dir=/tmp/cass_Mtu462n .build/docker/check-code.sh

实现原理：查看 .build/check-code.sh 可知，非 Docker 版本本质上执行的是ant -f "${CASSANDRA_DIR}/build.xml" check；脚本源码中保留了被注释的dependency-check目标，注释说明"dependency-check 现在需要先下载 NVD key"，即依赖漏洞检查（OWASP Dependency Check）默认被跳过。Docker 版本 .build/docker/check-code.sh 则会额外设置-Ddependency-check.home.base=/tmp，并委托 .build/docker/_docker_run.sh 在bullseye-build.docker镜像中执行。Checkstyle 相关规则集中在 .build/checkstyle.xml 与 .build/checkstyle_test.xml，抑制规则见 .build/checkstyle_suppressions.xml，OWASP 依赖检查的抑制清单见 .build/owasp/dependency-check-suppressions.xml。

构建发布产物：tarball 与 Maven 构件

构建 tarball 和 Maven 构件（产出位于build/目录）：

# Docker 方式 .build/docker/build-artifacts.sh # 非 Docker 方式（需 ant） .build/build-artifacts.sh # 指定 JDK .build/docker/build-artifacts.sh 11

实现原理：.build/build-artifacts.sh 实际执行ant -f build.xml artifacts -Dant.gen-doc.skip=true -Dcheck.skip=true，即在产出发布构件时跳过文档生成与代码检查以加速。Docker 包装脚本 .build/docker/build-artifacts.sh 通过 _docker_run.sh 在bullseye-build.docker镜像中运行。

构建 Debian 与 RedHat 软件包

打包脚本仅设计用于 Docker 环境（原因在于打包过程需要修改本地受版本控制的文件，隔离在容器中更安全）：

# Debian 包 .build/docker/build-debian.sh # RedHat 包（rpm） .build/docker/build-redhat.sh # 指定 JDK 版本 .build/docker/build-debian.sh 11 .build/docker/build-redhat.sh rpm 11

实现原理：.build/docker/build-debian.sh 会在执行前打印警告"此脚本会修改本地受版本控制的文件"，随后委托 _docker_run.sh 执行容器内的 .build/docker/_build-debian.sh。相关的打包模板与配置位于仓库的 debian/（如control、rules、cassandra.install）与 redhat/（如cassandra.spec、cassandra.in.sh）目录。

运行测试：从单元测试到分布式测试全覆盖

基础用法

Docker 方式运行单元测试：

.build/docker/run-tests.sh test

非 Docker 方式：

.build/run-tests.sh test

按分片（split）运行，支持并行

将单元测试均分为 64 份并只运行第 1 份：

.build/docker/run-tests.sh test 1/64

分片格式为K/N（N 份中的第 K 份），例如1/4、2/4。同时指定 JDK：

.build/docker/run-tests.sh test 1/64 11

实现原理：查看 .build/run-tests.sh 的_list_tests与_split_tests函数可知，脚本通过find test/<前缀> -name '*Test.java'枚举测试类，再用 GNUsplit -n r/K/N（macOS 上回退到gsplit）完成轮转分片；如果某个分片中没有测试类，脚本会"取第一个测试类"来运行，以保证生成 JUnit XML 报告。

按正则表达式筛选测试类

只运行名字匹配正则的单元测试：

.build/docker/run-tests.sh test VerifyTest 11 .build/docker/run-tests.sh test "Compaction*Test$" 11

实现原理：第二个参数若不是K/N分片格式，则被当作正则交给grep -e过滤测试类列表（见 .build/run-tests.sh 的_split_tests）。

支持的测试类型全集

对应命令示例（Docker 方式）：

.build/docker/run-tests.sh test .build/docker/run-tests.sh stress-test .build/docker/run-tests.sh fqltool-test .build/docker/run-tests.sh microbench .build/docker/run-tests.sh test-cdc .build/docker/run-tests.sh test-compression .build/docker/run-tests.sh test-oa .build/docker/run-tests.sh test-system-keyspace-directory .build/docker/run-tests.sh test-latest .build/docker/run-tests.sh test-burn .build/docker/run-tests.sh long-test .build/docker/run-tests.sh cqlsh-test .build/docker/run-tests.sh jvm-dtest .build/docker/run-tests.sh jvm-dtest-upgrade .build/docker/run-tests.sh dtest .build/docker/run-tests.sh dtest-novnode .build/docker/run-tests.sh dtest-latest .build/docker/run-tests.sh dtest-large .build/docker/run-tests.sh dtest-large-novnode .build/docker/run-tests.sh dtest-upgrade .build/docker/run-tests.sh dtest-upgrade-large

Python dtest 的非 Docker 运行

Python 分布式测试（dtest系列）在非 Docker 环境下使用独立的包装脚本 .build/run-python-dtests.sh：

# 运行 dtest .build/run-python-dtests.sh dtest # 运行 dtest-upgrade-large .build/run-python-dtests.sh dtest-upgrade-large

该脚本要求cassandra-dtest源码位于CASSANDRA_DIR/../cassandra-dtest（可用CASSANDRA_DTEST_DIR环境变量覆盖），并会设置一系列面向测试性能与稳定性的环境变量（如CCM_MAX_HEAP_SIZE=1024M、CASSANDRA_SKIP_SYNC=true、NUM_TOKENS=16等）。

其他 JVM 测试类型在非 Docker 下通过 .build/run-tests.sh 运行：

.build/run-tests.sh jvm-test

前置条件与关键约束

从 .build/run-tests.sh 的源码可以提炼出以下约束，值得在实际使用前注意：

• 必须先用ant jar构建项目，脚本会检查build/apache-cassandra-<版本>.jar是否存在；
• 存在build/dist目录时测试无法运行（该目录来自ant artifacts），需要先移除；
• 测试超时时间（test.timeout、test.burn.timeout、test.long.timeout、test.distributed.timeout）均从 build.xml 读取；
• jvm-dtest-upgrade不能使用与升级路径不重叠的 JDK（如仅支持 JDK11/17 混合升级场景）；
• 运行结束时脚本会调用ant generate-test-report合并所有 JUnit XML 并输出汇总数字。

Docker 执行机制的深入剖析

通用包装器 _docker_run.sh

所有 Docker 版本脚本（check-code、build-artifacts、build-debian/redhat）都委托给 .build/docker/_docker_run.sh，其关键机制包括：

• 镜像管理：镜像名形如apache/cassandra-bullseye-build:<tag>，其中 tag 是 Dockerfile 内容的 MD5 值；本地没有时先尝试docker pull，失败则docker build（带重试）；
• 目录挂载：将仓库源码挂到/home/build/cassandra、宿主 Maven 仓库挂到/home/build/.m2/repository/、build_dir挂到/dist；
• JDK 切换：容器内通过 .build/docker/_set_java.sh 调用update-java-alternatives（Debian/Ubuntu）或alternatives（其他发行版）切换java/javac，并导出正确的JAVA_HOME；
• 安全选项：以--security-opt seccomp=unconfined运行，避免默认 seccomp 配置干扰构建；
• Git worktree 支持：当仓库目录是一个 git worktree 时（.git为文件而非目录），会自动挂载其原始工作目录，保证 git 操作在容器内外一致。

测试专用包装器 docker/run-tests.sh

测试专用包装器 .build/docker/run-tests.sh 的用法与参数：

Usage: run-tests.sh test_type [split_chunk|test_regexp] [java_version] 默认 split_chunk 为 1/1 默认 java_version 为 build.xml 中 java.default 指定的版本

其额外能力包括：

• 使用ubuntu2004_test.docker构建测试镜像，并对不同测试类型施加差异化内存约束：
  • test、test-cdc、test-oa、jvm-dtest等要求约 6 GiB/执行器；
  • microbench、test-burn、long-test、cqlsh-test要求约 6 GiB/执行器并限制 CPU；
  • simulator-dtest与全部dtest*系列要求约 16 GiB/执行器；
• 若在 Jenkins 环境（检测到JENKINS_URL与NODE_NAME），会通过 REST API 获取执行器数量以按机器算力切分资源；
• 支持环境变量定制：build_dir（构建目录）、m2_dir（Maven 仓库）、python_version（Python 版本）、cython=yes（仅 cqlsh-test 可用）、DEBUG=1；
• dtest 相关目标会额外挂载cassandra_dtest_dir，并设置testtag.extra以区分测试聚合标签；dtest-upgrade还会预先填充 ccm 仓库目录（见 .build/docker/_copy_ccm_repositories.sh）；
• 测试日志写入build/test/logs/docker_attach_<容器名>.log并自动以xz压缩，失败时输出docker inspect、docker logs等信息辅助排查。

接入 SonarQube 静态分析（实验性）

使用现有 SonarQube 服务器

如果已有可用的 SonarQube 服务器，设置以下环境变量后直接分析：

SONAR_HOST_URL=http://sonar.example.com SONAR_CASSANDRA_TOKEN=cassandra-project-analysis-token SONAR_PROJECT_KEY=<key of the Cassandra project in SonarQube> ant sonar

一键启动本地 SonarQube（Docker）

无需外部服务器时，可在本地 Docker 容器中启动 SonarQube：

ant sonar-create-server

服务器将运行在http://localhost:9000，管理员账号为admin/password，容器名为sonarqube。使用本地实例时无需配置上述三个环境变量——脚本会读取 .build/sonar/sonar-quality-profile.xml 与 .build/sonar/sonar-quality-gate.json 自动完成项目创建、质量配置文件（Quality Profile）与质量门禁（Quality Gate）的初始化，随后直接执行：

ant sonar

分析完成后服务器保持运行，可在浏览器中查看结果。

停止、重启与清理本地服务器

# 停止容器（不删除，便于下次继续查看历史分析结果） ant sonar-stop-server # 稍后重新启动并访问之前的分析结果 docker container start sonarqube # 彻底删除容器 docker container rm sonarqube

自定义质量配置文件

如需使用自定义质量配置：先用ant sonar-create-server启动服务器，在 Web 界面手工创建项目并配置质量配置文件，再为项目生成分析 token，导出以下环境变量后运行ant sonar：

SONAR_HOST_URL="http://127.0.0.1:9000" SONAR_CASSANDRA_TOKEN="<token>" SONAR_PROJECT_KEY="<key of the Cassandra project in SonarQube>"

Sonar 相关的辅助脚本还包括 .build/sonar/sonar-report.sh 与 .build/sonar/sonar-setup-local.sh，可用于生成报告与本地环境初始化。

小结

Apache Cassandra 的 .build 脚本体系把构建、检查、打包与测试封装成了统一、可参数化、可并行化的命令入口：Docker 版本保证了 CI 环境的一致性（镜像按 Dockerfile 内容哈希缓存、JDK 通过 alternatives 切换、资源按测试类型差异化分配），非 Docker 版本则方便本地快速验证（但需要ant、git与对应 JDK）。结合 build.xml 中定义的目标与超时参数，这套脚本完整覆盖了从check、artifacts、build-debian/redhat到test、stress-test、dtest、microbench的发布与测试流水线，是理解 Cassandra 持续集成流程的最佳入口。

• 数据库
• 分布式数据库
• 后端