> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 持续集成系统概览

# 持续集成（CI）

当你提交拉取请求时，ClickHouse 的[持续集成 (CI) 系统](/zh/resources/develop-contribute/contribute/tests#test-automation)会对你的代码运行一些自动化检查。
这会发生在仓库维护者 (ClickHouse 团队成员) 审查你的代码并为你的拉取请求添加 `can be tested` 标签之后。
如 [GitHub checks 文档](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks)所述，这些检查结果会显示在 GitHub 拉取请求页面上。
如果某项检查失败，你可能需要修复它。
本页概述了你可能会遇到的检查，以及相应的处理方法。

如果看起来检查失败与你的更改无关，可能只是暂时性故障或基础设施问题。
向该拉取请求推送一个空提交，以重新启动 CI 检查：

```shell theme={null}
git commit --allow-empty
git push
```

如果你不确定该怎么做，请向维护者求助。

<div id="merge-with-master">
  ## 与 master 合并
</div>

验证该拉取请求能否合并到 master。
如果不能，此检查将失败，并显示消息 `Cannot fetch mergecommit`。
要修复此检查，请按 [GitHub 文档](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github) 中的说明解决冲突，或者使用 git 将 `master` 分支合并到你的拉取请求分支。

<div id="docs-check">
  ## 文档检查
</div>

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

<div id="description-check">
  ## 描述检查
</div>

检查你的拉取请求描述是否符合模板 [PULL\_REQUEST\_TEMPLATE.md](https://github.com/ClickHouse/ClickHouse/blob/master/.github/PULL_REQUEST_TEMPLATE.md)。
你必须为此次更改指定一个更新日志类别 (例如 Bug Fix) ，并为 [CHANGELOG.md](/zh/resources/changelogs/oss/2026) 编写一条面向用户的变更说明

<div id="docker-image">
  ## Docker 镜像
</div>

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

<div id="official-docker-library-tests">
  ### 官方 Docker 库测试
</div>

运行[官方 Docker 库](https://github.com/docker-library/official-images/tree/master/test#alternate-config-files)中的测试，以验证 `clickhouse/clickhouse-server` Docker 镜像 能否正常工作。

要添加新测试，请创建目录 `ci/jobs/scripts/docker_server/tests/$test_name`，并在其中创建 `run.sh` 脚本。

有关这些测试的更多信息，请参见 [CI 作业脚本文档](https://github.com/ClickHouse/ClickHouse/tree/master/ci/jobs/scripts/docker_server)。

<div id="marker-check">
  ## Marker 检查
</div>

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

<div id="style-check">
  ## 风格检查
</div>

对代码库执行各种风格检查。

Style Check 作业中的基础检查：

<div id="cpp">
  ##### cpp
</div>

使用 [`ci/jobs/scripts/check_style/check_cpp.sh`](https://github.com/ClickHouse/ClickHouse/blob/master/ci/jobs/scripts/check_style/check_cpp.sh) 脚本 (也可在本地运行) 执行基于简单正则表达式的代码风格检查。
如果检查失败，请根据[代码风格指南](/zh/resources/develop-contribute/contribute/style)修复相应的风格问题。

<div id="codespell">
  ##### codespell, aspell
</div>

检查语法和拼写错误。

<div id="mypy">
  ##### mypy
</div>

对 Python 代码进行静态类型检查。

<div id="running-style-check-locally">
  ### 在本地运行样式检查作业
</div>

整个 *风格检查* 作业都可以通过以下方式在 Docker 容器中于本地运行：

```sh theme={null}
python -m ci.praktika run "Style check"
```

要运行某项特定检查 (例如 *cpp* 检查) ：

```sh theme={null}
python -m ci.praktika run "Style check" --test cpp
```

这些命令会拉取 `clickhouse/style-test` Docker 镜像，并在容器化环境中运行该作业。
除 Python 3 和 Docker 外，无需其他依赖。

<div id="running-stateless-tests">
  ## 运行无状态测试
</div>

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

<div id="ci-prerequisites">
  #### 前置条件
</div>

* Python 3 (仅需标准库)
* Docker

如有需要，请在 Ubuntu 上安装 Docker 并重新登录：

```sh theme={null}
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
```

<div id="run-ci-job-locally">
  #### 在本地运行 CI 作业
</div>

从 CI 报告中任选一个作业名称，然后在本地运行：

```bash theme={null}
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：
  ```bash theme={null}
  python -m ci.praktika run "Fast test"
  ```

<div id="run-specific-tests-within-ci-job">
  #### 在 CI 作业中运行指定测试
</div>

使用 `--test` 时，该作业会准备一套与 CI 中使用的完全相同的 ClickHouse 配置，但只运行选定的测试：

```bash theme={null}
python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1
```

* 你可以传入多个测试名称：
  ```bash theme={null}
  python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
    --test 00001_select1 00002_log_and_exception_messages_formatting
  ```
* 提示：如果任意 ClickHouse 配置都可以，只是需要运行特定测试，请使用别名 `functional`，而不是完整的 job 名称：
  ```bash theme={null}
  python -m ci.praktika run functional --test 00001_select1
  ```

<div id="additional-customization-options">
  #### 其他自定义选项
</div>

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

<div id="build-check">
  ## 构建检查
</div>

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

<div id="running-builds-locally">
  ### 在本地运行构建
</div>

可以通过以下方式，在类似 CI 的环境中于本地运行该构建：

```bash theme={null}
python -m ci.praktika run "<BUILD_JOB_NAME>"
```

除 Python 3 和 Docker 之外，无需其他依赖。

<div id="available-build-jobs">
  #### 可用的构建作业
</div>

构建作业名称与 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` 的要求生成相应构建。

<div id="example-run-local">
  #### 示例
</div>

要运行本地调试版本：

```bash theme={null}
python -m ci.praktika run "Build (amd_debug)"
```

如果上述方法不适合你，请使用构建日志中的 cmake 选项，并遵循[通用构建流程](/zh/resources/develop-contribute/build/build)。

<div id="functional-stateless-tests">
  ## 无状态功能测试
</div>

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

<div id="integration-tests">
  ## 集成测试
</div>

运行[集成测试](/zh/resources/develop-contribute/contribute/tests#integration-tests)。

<div id="bugfix-validate-check">
  ## Bugfix validate 检查
</div>

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

<div id="stress-test">
  ## 压力测试
</div>

从多个客户端并发运行无状态功能测试，以发现并发相关的错误。如果失败：

* 请先修复所有其他测试失败；
  * 查看报告，找到服务器日志，并检查其中可能的错误原因。

<div id="compatibility-check">
  ## 兼容性检查
</div>

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

<div id="ast-fuzzer">
  ## AST fuzzer
</div>

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

<div id="performance-tests">
  ## 性能测试
</div>

用于衡量查询性能的变化。
这是耗时最长的一项检查，运行时间接近 6 小时。
有关性能测试报告的详细说明，请参见[此处](https://github.com/ClickHouse/ClickHouse/blob/master/tests/performance/scripts/README.md#how-to-read-the-report)。