跳到主要内容
跳到主要内容

如何在 Linux 上构建 ClickHouse

你不必自己构建 ClickHouse!

你可以按照 快速开始 的说明安装预构建的 ClickHouse。

ClickHouse 可以在以下平台上构建:

  • x86_64
  • AArch64
  • PowerPC 64 LE (实验性)
  • s390/x (实验性)
  • RISC-V 64 (实验性)

假设

以下教程基于 Ubuntu Linux,但在其他 Linux 发行版上也应该适用,只需进行适当的更改。 建议用于开发的最低 Ubuntu 版本为 24.04 LTS。

本教程假定你在本地已检查出 ClickHouse 仓库及所有子模块。

安装前提条件

ClickHouse 使用 CMake 和 Ninja 进行构建。

你可以选择性安装 ccache,以便让构建重用已经编译的目标文件。

安装 Clang 编译器

要在 Ubuntu/Debian 上安装 Clang,请使用 LLVM 的自动安装脚本 从这里

对于其他 Linux 发行版,请检查是否可以安装 LLVM 的任何 预构建包

截至 2025 年 3 月,要求使用 Clang 19 或更高版本。 不支持 GCC 或其他编译器。

安装 Rust 编译器(可选)

备注

Rust 是 ClickHouse 的一个可选依赖项。 如果未安装 Rust,ClickHouse 的某些功能将在编译时被省略。

首先,按照官方 Rust 文档 中的步骤安装 rustup

与 C++ 依赖项一样,ClickHouse 使用 vendoring 来精确控制安装的内容,并避免依赖第三方服务(如 crates.io 注册表)。

虽然在发布模式下,任何现代 Rust 的 rustup 工具链版本都应该可以与这些依赖项一起使用,但如果你计划启用 sanitizers,必须使用与 CI 中使用的确切相同 std 的版本(我们为此 vendoring 了库):

构建 ClickHouse

我们建议在 ClickHouse 内部创建一个单独的目录 build 来存放所有构建产物:

你可以有多个不同的目录(例如 build_releasebuild_debug 等)用于不同的构建类型。

可选:如果你安装了多个编译器版本,可以可选地指定要使用的确切编译器。

出于开发目的,建议使用调试构建。 与发布构建相比,它们具有较低的编译器优化级别(-O),提供更好的调试体验。 此外,LOGICAL_ERROR 类型的内部异常会立即崩溃而不是优雅地失败。

运行 ninja 进行构建:

如果希望构建所有二进制文件(实用工具和测试),可以不带参数运行 ninja:

你可以使用参数 -j 控制并行构建的作业数量:

提示

CMake 提供了上述命令的快捷方式:

运行 ClickHouse 可执行文件

构建成功完成后,你可以在 ClickHouse/<build_dir>/programs/ 中找到可执行文件:

ClickHouse 服务器会尝试在当前目录中查找配置文件 config.xml。 你也可以通过 -C 在命令行上指定配置文件。

要使用 clickhouse-client 连接到 ClickHouse 服务器,请打开另一个终端,导航到 ClickHouse/build/programs/ 并运行 ./clickhouse client

如果在 macOS 或 FreeBSD 上收到 Connection refused 消息,请尝试指定主机地址 127.0.0.1:

高级选项

最小构建

如果你不需要第三方库提供的功能,可以进一步加快构建速度:

如果遇到问题,后果自负 ...

Rust 需要互联网连接。要禁用 Rust 支持:

运行 ClickHouse 可执行文件

你可以用编译后的 ClickHouse 二进制文件替换系统中已安装的生产版本 ClickHouse 二进制文件。 为此,请遵循官方网站的说明在你的机器上安装 ClickHouse。 接下来,运行:

请注意,clickhouse-clientclickhouse-server 和其他命令是指向常用的 clickhouse 二进制文件的符号链接。

你还可以使用系统中已安装的 ClickHouse 软件包中的配置文件来运行自定义构建的 ClickHouse 二进制文件:

在任意 Linux 上构建

在 OpenSUSE Tumbleweed 上安装前提条件:

在 Fedora Rawhide 上安装前提条件:

在 Docker 中构建

我们在 CI 中使用 clickhouse/binary-builder 的 Docker 镜像进行构建。 它包含构建二进制文件和包所需的一切。 有一个脚本 docker/packager/packager 来简化镜像使用: