跳到主要内容
跳到主要内容
编辑此页

如何在 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,以便构建重用已编译的目标文件。

sudo apt-get update
sudo apt-get install git cmake ccache python3 ninja-build nasm yasm gawk lsb-release wget software-properties-common gnupg

安装 Clang 编译器

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

sudo bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"

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

截至 2025 年 1 月,需要 Clang 18 或更高版本。 不支持 GCC 或其他编译器。

安装 Rust 编译器(可选)

注意

Rust 是 ClickHouse 的可选依赖项。 如果未安装 Rust,则 ClickHouse 的某些功能将从编译中省略。

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

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

虽然在发布模式下,任何 rust 现代 rustup 工具链版本都应该适用于这些依赖项,但如果你计划启用 sanitizers,则必须使用与 CI 中使用的 std 完全相同的版本(为此我们 vendor 这些 crates)。

rustup toolchain install nightly-2024-12-01
rustup default nightly-2024-12-01
rustup component add rust-src

构建 ClickHouse

我们建议在 ClickHouse 内部创建一个单独的目录 build,其中包含所有构建工件

mkdir build
cd build

你可以为不同的构建类型创建几个不同的目录(例如 build_releasebuild_debug 等)。

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

export CC=clang-19
export CXX=clang++-19

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

cmake -D CMAKE_BUILD_TYPE=Debug ..

运行 ninja 进行构建

ninja clickhouse-server clickhouse-client

如果你想构建所有二进制文件(实用程序和测试),请运行不带参数的 ninja

ninja

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

ninja -j 1 clickhouse-server clickhouse-client
提示

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

cmake -S . -B build  # configure build, run from repository top-level directory
cmake --build build # compile

运行 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

clickhouse client --host 127.0.0.1

高级选项

最小化构建

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

cmake -DENABLE_LIBRARIES=OFF

如果遇到问题,你只能靠自己了...

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

cmake -DENABLE_RUST=OFF

运行 ClickHouse 可执行文件

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

sudo service clickhouse-server stop
sudo cp ClickHouse/build/programs/clickhouse /usr/bin/
sudo service clickhouse-server start

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

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

sudo service clickhouse-server stop
sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml

在任何 Linux 上构建

在 OpenSUSE Tumbleweed 上安装前提条件

sudo zypper install git cmake ninja clang-c++ python lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build

在 Fedora Rawhide 上安装前提条件

sudo yum update
sudo yum --nogpg install git cmake make clang python3 ccache lld nasm yasm gawk
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
mkdir build
cmake -S . -B build
cmake --build build

在 docker 中构建

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

# define a directory for the output artifacts
output_dir="build_results"
# a simplest build
./docker/packager/packager --package-type=binary --output-dir "$output_dir"
# build debian packages
./docker/packager/packager --package-type=deb --output-dir "$output_dir"
# by default, debian packages use thin LTO, so we can override it to speed up the build
CMAKE_FLAGS='-DENABLE_THINLTO=' ./docker/packager/packager --package-type=deb --output-dir "./$(git rev-parse --show-cdup)/build_results"