Ubuntu24 单节点ClickHouse二进制包部署

1. 背景

业务项目引入ClickHouse作为高性能数据分析、海量数据存储查询组件，需完成服务器单节点离线部署。本文档完整记录Ubuntu24系统下tgz二进制包部署全流程，标准化实操步骤，可为后续同环境、同版本集群/单节点部署提供复用指导。

2. 环境信息

本次部署硬件、软件环境固定参数如下：

|--------------|------------|
| 配置项 | 配置参数 |
| 服务器操作系统 | Ubuntu 24 |
| Clickhouse版本 | 25.3.2.39 |
| Java版本 | OpenJDK 21 |
| 系统总内存 | 125G |
| CPU核数 | 72核 |

3. 下载安装包

Ubuntu系统部署Clickhouse采用tgz二进制包方式，需依次下载以下四个安装包：

bash 复制代码

clickhouse-common-static-25.3.2.39-amd64.tgz  --（核心运行依赖包）
clickhouse-common-static-dbg-25.3.2.39-amd64.tgz --（调试日志依赖包）
clickhouse-server-25.3.2.39-amd64.tgz --（服务端主程序包）
clickhouse-client-25.3.2.39-amd64.tgz --（本地命令行客户端包）

复制代码

4. 安装与启动

4.1 解压安装包

将四个安装包依次解压至指定目录/usr/local，执行全局解压命令：

bash 复制代码

sudo tar -xvf clickhouse-common-static-25.3.2.39-amd64.tgz -C /usr/local
sudo tar -xvf clickhouse-common-static-dbg-25.3.2.39-amd64.tgz -C /usr/local
sudo tar -xvf clickhouse-server-25.3.2.39-amd64.tgz -C /usr/local
sudo tar -xvf clickhouse-client-25.3.2.39-amd64.tgz -C /usr/local

4.2 执行安装操作

进入各解压后的目录，依次执行安装脚本，命令如下：

bash 复制代码

cd /usr/local/clickhouse-common-static-25.3.2.39 && sudo ./install/doinst.sh
cd /usr/local/clickhouse-common-static-dbg-25.3.2.39 && sudo ./install/doinst.sh
cd /usr/local/clickhouse-server-25.3.2.39 && sudo ./install/doinst.sh
cd /usr/local/clickhouse-client-25.3.2.39 && sudo ./install/doinst.sh

4.3 启动ClickHouse服务

安装脚本已自动注册systemd系统服务，直接执行命令启停服务：

bash 复制代码

sudo systemctl start clickhouse-server

5. 常见问题与解决办法

5.1 目录找不到或权限访问失败

问题现象：服务启动报错，提示

/var/lib/clickhouse/、/var/log/clickhouse-server/ 目录不存在、用户无读写权限。

问题根因：安装脚本自动创建系统clickhouse运行用户，但Ubuntu24默认目录权限收紧，内置脚本无法自动创建数据、日志目录，目录初始化失败。

解决方案：手动创建目录、归属修改为clickhouse用户组、赋权读写权限，执行以下命令：

bash 复制代码

sudo mkdir -p /var/lib/ clickhousesudo 
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse
sudo chmod -R 777 /var/lib/clickhouse

5.2 启动报错"Failed to find user name for 750"

问题现象：服务启动失败，日志抛出：Failed to find user name for 750

问题根因：ClickHouse服务配置默认运行UID为750，当前系统clickhouse用户UID与750不匹配，服务无法识别运行用户。

解决方案：修改系统clickhouse用户UID为标准750，适配服务配置：

复制代码

sudo usermod -u 750 clickhouse

6. 部署验证

6.1 验证服务端状态

通过systemctl查看服务常驻状态，确认服务正常运行

复制代码

sudo systemctl status clickhouse-server

通过systemctl查看服务常驻状态，确认服务正常运行

6.2 验证Clickhouse-client功能

调用内置clickhouse-client进入交互式命令行，执行建表、查询基础SQL，校验读写语法、本地连通性：

复制代码

clickhouse-client

6.3 校验业务C++客户端连通能力

业务说明：业务底层通过C++客户端SDK对接ClickHouse写入业务数据，需提前部署C++依赖库、编译客户端组件，保障业务程序正常连通写入，完整适配步骤如下：

部署clickhouse-cpp客户端库

源码地址：GitHub - ClickHouse/clickhouse-cpp: C++ client library for ClickHouse下载clickhouse-cpp-master源码包解压后，执行编译安装命令：

bash 复制代码

# 生成Release编译配置
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
# 编译并安装组件
make --build build --target install

部署abseil-cpp依赖库

Github下载abseil-cpp-master源码包，进入目录执行编译安装：

bash 复制代码

mkdir build && cd build
cmake ..
make --build build --target install

适配系统zstd开发依赖包

系统内置libzstd 1.5.5运行库，需配套安装开发包：离线安装包：libzstd-dev_1.5.5+dfsg2-2build1.1_amd64.deb

编译运行业务C++读写示例代码

验证远端读写、连接鉴权全部功能正常。