跳转到主要内容
当你提交拉取请求时，ClickHouse 的持续集成 (CI) 系统会对你的代码运行一些自动化检查。 这会发生在仓库维护者 (ClickHouse 团队成员) 审查你的代码并为你的拉取请求添加 can be tested 标签之后。 如 GitHub checks 文档所述，这些检查结果会显示在 GitHub 拉取请求页面上。 如果某项检查失败，你可能需要修复它。 本页概述了你可能会遇到的检查，以及相应的处理方法。 如果看起来检查失败与你的更改无关，可能只是暂时性故障或基础设施问题。 向该拉取请求推送一个空提交，以重新启动 CI 检查： 
git commit --allow-empty
git push
如果你不确定该怎么做，请向维护者求助。

​
与 master 合并

验证该拉取请求能否合并到 master。 如果不能，此检查将失败，并显示消息 Cannot fetch mergecommit。 要修复此检查，请按 GitHub 文档 中的说明解决冲突，或者使用 git 将 master 分支合并到你的拉取请求分支。

​
文档检查

尝试构建 ClickHouse 文档网站。 如果你修改了文档中的某些内容，此检查可能会失败。 最可能的原因是文档中的某个交叉链接有误。 前往检查报告，查找 ERROR 和 WARNING 消息。

​
描述检查

检查你的拉取请求描述是否符合模板 PULL_REQUEST_TEMPLATE.md。 你必须为此次更改指定一个更新日志类别 (例如 Bug Fix) ，并为 CHANGELOG.md 编写一条面向用户的变更说明

​
Docker 镜像

构建 ClickHouse server 和 Keeper 的 Docker 镜像，以验证其能否正确构建。

​
官方 Docker 库测试

运行官方 Docker 库中的测试，以验证 clickhouse/clickhouse-server Docker 镜像 能否正常工作。 要添加新测试，请创建目录 ci/jobs/scripts/docker_server/tests/$test_name，并在其中创建 run.sh 脚本。 有关这些测试的更多信息，请参见 CI 作业脚本文档。

​
Marker 检查

此检查表示 CI 系统已开始处理该拉取请求。 当其状态为“pending”时，表示并非所有检查都已开始运行。 当所有检查都开始运行后，其状态会变为“success”。

​
风格检查

对代码库执行各种风格检查。 Style Check 作业中的基础检查：
cpp
使用 ci/jobs/scripts/check_style/check_cpp.sh 脚本 (也可在本地运行) 执行基于简单正则表达式的代码风格检查。 如果检查失败，请根据代码风格指南修复相应的风格问题。
codespell, aspell
检查语法和拼写错误。
mypy
对 Python 代码进行静态类型检查。

​
在本地运行样式检查作业

整个 风格检查 作业都可以通过以下方式在 Docker 容器中于本地运行： 
python -m ci.praktika run "Style check"
要运行某项特定检查 (例如 cpp 检查) ： 
python -m ci.praktika run "Style check" --test cpp
这些命令会拉取 clickhouse/style-test Docker 镜像，并在容器化环境中运行该作业。 除 Python 3 和 Docker 外，无需其他依赖。

​
运行无状态测试

本地安装并使用默认设置的 ClickHouse 可能适用于某些特定测试用例，但无法正确运行所有测试查询。在 CI 中，每个作业都会部署特定的 ClickHouse 配置 (例如 S3 存储、并行副本) ，手动复现这些配置可能相当繁琐。为避免这种情况，你可以在本地使用与 CI 相同的编排方式复现任何 CI 作业——无需手动配置。

​
前置条件

  • Python 3 (仅需标准库)
  • Docker
如有需要，请在 Ubuntu 上安装 Docker 并重新登录： 
sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker "$USER"
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "ip6tables": true
}
EOF
sudo systemctl restart docker

​
在本地运行 CI 作业

从 CI 报告中任选一个作业名称，然后在本地运行： 
python -m ci.praktika run "<JOB_NAME>"
  • 始终按 CI 报告中的显示结果原样引用作业名称 (其中可能包含空格和逗号) ，例如："Stateless tests (amd_debug, parallel)"。这样会使用与 CI 相同的 ClickHouse 配置，并运行相同的测试。
  • 作业名称中的架构和构建类型 (例如 amd_debug) 是 CI 专用标记。在本地运行时，它们不会产生任何影响——作业会使用你提供的二进制文件，以及你当前所在架构。作业名称只决定 ClickHouse 配置和测试集 (除非用 --test 覆盖) 。
  • 在 CI 中，功能测试会拆分成多个批次，以便更高效地利用资源。例如，"Stateless tests (amd_debug, parallel)" 和 "Stateless tests (amd_debug, sequential)" 合起来覆盖完整范围：可安全并行运行的测试会并发执行，其余测试则顺序执行。这种拆分通过尽可能提高并行度来缩短 CI 总耗时。若要在本地复现完整测试范围，请同时运行这两个批次。
  • 此外还有一个 "Fast test" CI 作业，它会运行一小部分功能测试，以验证 ClickHouse 的基础功能——它使用的是不包含全部可选模块的构建，也是发现回归问题最快的方法。你也可以用同样的方式在本地运行它。将你的 ClickHouse 二进制文件放到默认搜索路径之一 (./ci/tmp/clickhouse、./build/programs/clickhouse 或 ./clickhouse) ——否则该作业会先尝试构建 ClickHouse： 
    python -m ci.praktika run "Fast test"

​
在 CI 作业中运行指定测试

使用 --test 时，该作业会准备一套与 CI 中使用的完全相同的 ClickHouse 配置，但只运行选定的测试： 
python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1
  • 你可以传入多个测试名称： 
    python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting
  • 提示：如果任意 ClickHouse 配置都可以，只是需要运行特定测试，请使用别名 functional，而不是完整的 job 名称： 
    python -m ci.praktika run functional --test 00001_select1

​
其他自定义选项

  • --path PATH — ClickHouse 二进制文件的自定义路径。默认情况下，运行器会按顺序在以下位置查找：./ci/tmp/clickhouse、./build/programs/clickhouse、./clickhouse。
  • --count N — 将每个测试重复执行 N 次。
  • --workers N — 覆盖根据机器容量自动计算出的并行工作线程数。

​
构建检查

以多种配置构建 ClickHouse，供后续步骤使用。

​
在本地运行构建

可以通过以下方式，在类似 CI 的环境中于本地运行该构建： 
python -m ci.praktika run "<BUILD_JOB_NAME>"
除 Python 3 和 Docker 之外，无需其他依赖。

​
可用的构建作业

构建作业名称与 CI Report 中显示的名称完全一致： AMD64 构建：
  • Build (amd_debug) - 带符号的调试构建
  • Build (amd_release) - 优化后的发布构建
  • Build (amd_asan) - Address Sanitizer 构建
  • Build (amd_tsan) - Thread Sanitizer 构建
  • Build (amd_msan) - Memory Sanitizer 构建
  • Build (amd_ubsan) - Undefined Behavior Sanitizer 构建
  • Build (amd_binary) - 不使用 Thin LTO 的快速发布构建
  • Build (amd_compat) - 适用于旧系统的兼容性构建
  • Build (amd_musl) - 使用 musl libc 的构建
  • Build (amd_darwin) - macOS 构建
  • Build (amd_freebsd) - FreeBSD 构建
ARM64 构建：
  • Build (arm_release) - ARM64 优化后的发布构建
  • Build (arm_asan) - ARM64 Address Sanitizer 构建
  • Build (arm_coverage) - 带覆盖率插桩的 ARM64 构建
  • Build (arm_binary) - 不使用 Thin LTO 的 ARM64 快速发布构建
  • Build (arm_darwin) - macOS ARM64 构建
  • Build (arm_v80compat) - ARMv8.0 兼容性构建
其他架构：
  • Build (ppc64le) - PowerPC 64 位小端
  • Build (riscv64) - RISC-V 64 位
  • Build (s390x) - IBM System/390 64 位
  • Build (loongarch64) - LoongArch 64 位
如果作业成功，构建结果将位于 <repo_root>/ci/tmp/build 目录下。 注意： 对于不属于“其他架构”类别的构建 (“其他架构”类别使用交叉编译) ，你的本地机器架构必须与构建类型一致，才能按 BUILD_JOB_NAME 的要求生成相应构建。

​
示例

要运行本地调试版本： 
python -m ci.praktika run "Build (amd_debug)"
如果上述方法不适合你，请使用构建日志中的 cmake 选项，并遵循通用构建流程。

​
无状态功能测试

运行针对以不同配置构建的 ClickHouse 二进制文件的无状态功能测试，包括 release、debug、启用 sanitizers 等。 查看报告，确认哪些测试失败，然后按此处的说明在本地复现。 请注意，复现时必须使用正确的构建配置——某项测试可能在 AddressSanitizer 下失败，但在 Debug 下通过。 从 CI build checks page 下载二进制文件，或在本地自行构建。

​
集成测试

运行集成测试。

​
Bugfix validate 检查

检查是否新增了测试 (功能测试或集成测试) ，或者是否有修改过的测试在基于 master 分支构建的 二进制文件 上运行失败。 当拉取请求带有 “pr-bugfix” 标签时，会触发此检查。

​
压力测试

从多个客户端并发运行无状态功能测试，以发现并发相关的错误。如果失败：
  • 请先修复所有其他测试失败；
    • 查看报告，找到服务器日志，并检查其中可能的错误原因。

​
兼容性检查

检查 clickhouse 二进制文件能否在使用旧版 libc 的发行版上运行。 如果失败，请向维护者寻求帮助。

​
AST fuzzer

运行随机生成的查询，用于捕获程序错误。 如果运行失败，请向维护者寻求帮助。

​
性能测试

用于衡量查询性能的变化。 这是耗时最长的一项检查，运行时间接近 6 小时。 有关性能测试报告的详细说明，请参见此处。
最后修改于 2026年6月10日