ClickHouse 数据库

xuxiaowei · January 1, 2026, 5:11pm

文档

在 Debian/Ubuntu 上安装 ClickHouse

配置软件源

sudo apt update

# 安装先决条件软件包
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

# 下载 ClickHouse 的 GPG 密钥并将其存储到密钥环中
curl -fsSL 'https://packages.clickhouse.com/rpm/lts/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg

# lts 长期支持版
# 获取系统架构
ARCH=$(dpkg --print-architecture)

# 将 ClickHouse 仓库添加到 APT 软件源列表
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb lts main" | sudo tee /etc/apt/sources.list.d/clickhouse.list

# 更新 apt 软件包列表
sudo apt-get update

# stable 稳定版
# 获取系统架构
ARCH=$(dpkg --print-architecture)

# 将 ClickHouse 仓库添加到 APT 软件源列表
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg arch=${ARCH}] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list

# 更新 apt 软件包列表
sudo apt-get update

安装 ClickHouse 服务端和客户端

warning 警告

安装过程需要输入用户 default 密码

# 安装
sudo apt-get install -y clickhouse-server clickhouse-client

# 安装日志
root@localhost:~# sudo apt-get install -y clickhouse-server clickhouse-client
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  clickhouse-common-static
Suggested packages:
  clickhouse-common-static-dbg
The following NEW packages will be installed:
  clickhouse-client clickhouse-common-static clickhouse-server
0 upgraded, 3 newly installed, 0 to remove and 44 not upgraded.
Need to get 203 MB of archives.
After this operation, 706 MB of additional disk space will be used.
Get:1 https://packages.clickhouse.com/deb stable/main amd64 clickhouse-common-static amd64 25.11.2.24 [202 MB]
Get:2 https://packages.clickhouse.com/deb stable/main amd64 clickhouse-client amd64 25.11.2.24 [149 kB]                                                                
Get:3 https://packages.clickhouse.com/deb stable/main amd64 clickhouse-server amd64 25.11.2.24 [178 kB]                                                                
Fetched 203 MB in 39s (5133 kB/s)                                                                                                                                      
Selecting previously unselected package clickhouse-common-static.
(Reading database ... 75216 files and directories currently installed.)
Preparing to unpack .../clickhouse-common-static_25.11.2.24_amd64.deb ...
Unpacking clickhouse-common-static (25.11.2.24) ...
Selecting previously unselected package clickhouse-client.
Preparing to unpack .../clickhouse-client_25.11.2.24_amd64.deb ...
Unpacking clickhouse-client (25.11.2.24) ...
Selecting previously unselected package clickhouse-server.
Preparing to unpack .../clickhouse-server_25.11.2.24_amd64.deb ...
Unpacking clickhouse-server (25.11.2.24) ...
Setting up clickhouse-common-static (25.11.2.24) ...
Setting up clickhouse-server (25.11.2.24) ...
ClickHouse binary is already located at /usr/bin/clickhouse
Symlink /usr/bin/clickhouse-server already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-server to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-client already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-client to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-local already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-local to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-benchmark already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-benchmark to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-obfuscator already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-obfuscator to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-git-import to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-compressor already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-compressor to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-format already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-format to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-extract-from-config already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-extract-from-config to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-keeper already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-keeper to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-keeper-converter already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-keeper-converter to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-disks to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-chdig already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-chdig to /usr/bin/clickhouse.
Symlink /usr/bin/chdig already exists. Will keep it.
Symlink /usr/bin/ch already exists. Will keep it.
Symlink /usr/bin/chl already exists. Will keep it.
Symlink /usr/bin/chc already exists. Will keep it.
Creating clickhouse group if it does not exist.
 groupadd -r clickhouse
Creating clickhouse user if it does not exist.
 useradd -r --shell /bin/false --home-dir /nonexistent -g clickhouse clickhouse
Will set ulimits for clickhouse user in /etc/security/limits.d/clickhouse.conf.
Creating config directory /etc/clickhouse-server/config.d that is used for tweaks of main server configuration.
Creating config directory /etc/clickhouse-server/users.d that is used for tweaks of users configuration.
Config file /etc/clickhouse-server/config.xml already exists, will keep it and extract path info from it.
/etc/clickhouse-server/config.xml has /var/lib/clickhouse/ as data path.
/etc/clickhouse-server/config.xml has /var/log/clickhouse-server/ as log path.
Users config file /etc/clickhouse-server/users.xml already exists, will keep it and extract users info from it.
Creating log directory /var/log/clickhouse-server/.
Creating data directory /var/lib/clickhouse/.
Creating pid directory /var/run/clickhouse-server.
 chown -R clickhouse:clickhouse '/var/log/clickhouse-server/'
 chown -R clickhouse:clickhouse '/var/run/clickhouse-server'
 chown  clickhouse:clickhouse '/var/lib/clickhouse/'
Set up the password for the default user: 
Password for the default user is saved in file /etc/clickhouse-server/users.d/default-password.xml.
Setting capabilities for clickhouse binary. This is optional.
 chown -R clickhouse:clickhouse '/etc/clickhouse-server'

ClickHouse has been successfully installed.

Start clickhouse-server with:
 sudo clickhouse start

Start clickhouse-client with:
 clickhouse-client --password

Synchronizing state of clickhouse-server.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing: /usr/lib/systemd/systemd-sysv-install enable clickhouse-server
Created symlink '/etc/systemd/system/multi-user.target.wants/clickhouse-server.service' → '/usr/lib/systemd/system/clickhouse-server.service'.
Setting up clickhouse-client (25.11.2.24) ...
root@localhost:~#

# 查看版本
clickhouse-server --version

# 查看版本结果
root@172:~# clickhouse-server --version
ClickHouse server version 25.11.2.24 (official build).
root@172:~#

在 Redhat/CentOS 上安装 ClickHouse

配置软件源

# yum
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo

# openSUSE、SLES：zypper
sudo zypper addrepo -r https://packages.clickhouse.com/rpm/clickhouse.repo -g
sudo zypper --gpg-auto-import-keys refresh clickhouse-stable

安装 ClickHouse 服务端和客户端

# 安装
sudo yum install -y clickhouse-server clickhouse-client

# 安装日志
[root@anlois-8-8 ~]# sudo yum install -y clickhouse-server clickhouse-client
Failed to set locale, defaulting to C.UTF-8
Last metadata expiration check: 0:00:22 ago on Wed Dec 10 15:35:34 2025.
Dependencies resolved.
========================================================================================================================================================================
 Package                                          Architecture                   Version                                Repository                                 Size
========================================================================================================================================================================
Installing:
 clickhouse-client                                x86_64                         25.11.2.24-1                           clickhouse-stable                         148 k
 clickhouse-server                                x86_64                         25.11.2.24-1                           clickhouse-stable                         178 k
Installing dependencies:
 clickhouse-common-static                         x86_64                         25.11.2.24-1                           clickhouse-stable                         193 M

Transaction Summary
========================================================================================================================================================================
Install  3 Packages

Total download size: 193 M
Installed size: 673 M
Downloading Packages:
(1/3): clickhouse-client-25.11.2.24.x86_64.rpm                                                                                          116 kB/s | 148 kB     00:01    
(2/3): clickhouse-server-25.11.2.24.x86_64.rpm                                                                                          104 kB/s | 178 kB     00:01    
(3/3): clickhouse-common-static-25.11.2.24.x86_64.rpm                                                                                   7.0 MB/s | 193 MB     00:27    
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Total                                                                                                                                   7.0 MB/s | 193 MB     00:27     
Running transaction check
Transaction check succeeded.
Running transaction test
Transaction test succeeded.
Running transaction
  Preparing        :                                                                                                                                                1/1 
  Installing       : clickhouse-common-static-25.11.2.24-1.x86_64                                                                                                   1/3 
  Installing       : clickhouse-client-25.11.2.24-1.x86_64                                                                                                          2/3 
  Installing       : clickhouse-server-25.11.2.24-1.x86_64                                                                                                          3/3 
  Running scriptlet: clickhouse-server-25.11.2.24-1.x86_64                                                                                                          3/3 
ClickHouse binary is already located at /usr/bin/clickhouse
Symlink /usr/bin/clickhouse-server already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-server to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-client already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-client to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-local already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-local to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-benchmark already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-benchmark to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-obfuscator already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-obfuscator to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-git-import to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-compressor already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-compressor to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-format already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-format to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-extract-from-config already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-extract-from-config to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-keeper already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-keeper to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-keeper-converter already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-keeper-converter to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-disks to /usr/bin/clickhouse.
Symlink /usr/bin/clickhouse-chdig already exists but it points to /clickhouse. Will replace the old symlink to /usr/bin/clickhouse.
Creating symlink /usr/bin/clickhouse-chdig to /usr/bin/clickhouse.
Symlink /usr/bin/chdig already exists. Will keep it.
Symlink /usr/bin/ch already exists. Will keep it.
Symlink /usr/bin/chl already exists. Will keep it.
Symlink /usr/bin/chc already exists. Will keep it.
Creating clickhouse group if it does not exist.
 groupadd -r clickhouse
Creating clickhouse user if it does not exist.
 useradd -r --shell /bin/false --home-dir /nonexistent -g clickhouse clickhouse
Will set ulimits for clickhouse user in /etc/security/limits.d/clickhouse.conf.
Creating config directory /etc/clickhouse-server/config.d that is used for tweaks of main server configuration.
Creating config directory /etc/clickhouse-server/users.d that is used for tweaks of users configuration.
Config file /etc/clickhouse-server/config.xml already exists, will keep it and extract path info from it.
/etc/clickhouse-server/config.xml has /var/lib/clickhouse/ as data path.
/etc/clickhouse-server/config.xml has /var/log/clickhouse-server/ as log path.
Users config file /etc/clickhouse-server/users.xml already exists, will keep it and extract users info from it.
Creating log directory /var/log/clickhouse-server/.
Creating data directory /var/lib/clickhouse/.
Creating pid directory /var/run/clickhouse-server.
 chown -R clickhouse:clickhouse '/var/log/clickhouse-server/'
 chown -R clickhouse:clickhouse '/var/run/clickhouse-server'
 chown  clickhouse:clickhouse '/var/lib/clickhouse/'
Password for the default user is an empty string. See /etc/clickhouse-server/users.xml and /etc/clickhouse-server/users.d to change it.
Setting capabilities for clickhouse binary. This is optional.
 chown -R clickhouse:clickhouse '/etc/clickhouse-server'

ClickHouse has been successfully installed.

Start clickhouse-server with:
 sudo clickhouse start

Start clickhouse-client with:
 clickhouse-client

Synchronizing state of clickhouse-server.service with SysV service script with /usr/lib/systemd/systemd-sysv-install.
Executing: /usr/lib/systemd/systemd-sysv-install enable clickhouse-server
Created symlink /etc/systemd/system/multi-user.target.wants/clickhouse-server.service → /usr/lib/systemd/system/clickhouse-server.service.

  Verifying        : clickhouse-client-25.11.2.24-1.x86_64                                                                                                          1/3 
  Verifying        : clickhouse-common-static-25.11.2.24-1.x86_64                                                                                                   2/3 
  Verifying        : clickhouse-server-25.11.2.24-1.x86_64                                                                                                          3/3 

Installed:
  clickhouse-client-25.11.2.24-1.x86_64                clickhouse-common-static-25.11.2.24-1.x86_64                clickhouse-server-25.11.2.24-1.x86_64               

Complete!
[root@anlois-8-8 ~]#

配置 ClickHouse `default` 用户密码

warning 警告

yum 安装过程没有配置用户 default 密码，需要 手动配置 default 密码

# 生成随机密码，密码使用 sha256 摘要
# 第一行输出随机密码
# 第二行输出密码的 sha256 摘要
PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'

# echo -n "xuxiaowei.com.cn" | sha256sum | tr -d '-'
# 0205a37be5d80e2358bd4241ce42f8fbb572a35c13eb41246551792ff76a5aae

# 生成随机密码，密码使用 sha256 摘要示例
# 第一行输出随机密码
# 第二行输出密码的 sha256 摘要
[root@anlois-8-8 ~]# PASSWORD=$(base64 < /dev/urandom | head -c8); echo "$PASSWORD"; echo -n "$PASSWORD" | sha256sum | tr -d '-'
5Ofv9Tg3
2c1a7fbb48f55b8bfb62a2a68116854792d7784b35042cf95f10fcc168df6bf0
[root@anlois-8-8 ~]#

# 使用管理员权限修改
sudo vim /etc/clickhouse-server/users.xml

# 配置密码

<clickhouse>
    <users>
        <default>
            <!-- 
                /etc/clickhouse-server/config.xml 中配置了密码模式：
                <default_password_type>sha256_password</default_password_type>
             -->
            <!-- password、password_sha256_hex 不能同时出现 -->
            <!-- <password></password> -->
            <password_sha256_hex>填写上面生成密码的 sha256 摘要</password_sha256_hex>
        </default>
    </users>
</clickhouse>

# 强制保存后退出
:wq!

使用 Docker 安装 ClickHouse

docker container

export CLICKHOUSE_HOME=${CLICKHOUSE_HOME:-$(pwd)}

docker run -itd \
  --name clickhouse-server \
  --restart always \
  --env CLICKHOUSE_USER=xuxiaowei \
  --env CLICKHOUSE_PASSWORD=xuxiaowei.com.cn \
  --env CLICKHOUSE_DB=xuxiaowei \
  --publish 8123:8123 \
  --volume $CLICKHOUSE_HOME/data:/var/lib/clickhouse \
  --volume $CLICKHOUSE_HOME/log:/var/log/clickhouse-server \
  --ulimit nofile=262144:262144 \
  registry.cn-qingdao.aliyuncs.com/xuxiaoweicomcn/clickhouse-server:25.3.10

docker compose

#
# export CLICKHOUSE_HOME=/mnt/pve/ST8000/srv/clickhouse && docker compose up -d
# export CLICKHOUSE_HOME=`pwd` && echo $CLICKHOUSE_HOME && docker compose up -d
#
services:
  clickhouse-server:
    container_name: clickhouse-server
    # image: 'clickhouse/clickhouse-server:25.3.10'
    image: 'registry.cn-qingdao.aliyuncs.com/xuxiaoweicomcn/clickhouse-server:25.3.10'
    restart: always
    environment:
      # 用户名
      CLICKHOUSE_USER: xuxiaowei
      # 密码
      CLICKHOUSE_PASSWORD: xuxiaowei.com.cn
      # 数据库
      CLICKHOUSE_DB: xuxiaowei
    ports:
      - '8123:8123'
      # - '8443:8443'
      # - '9000:9000'
      # - '9004:9004'
      # - '9005:9005'
      # - '9009:9009'
      # - '9010:9010'
      # - '9011:9011'
      # - '9100:9100'
      # - '9181:9181'
    volumes:
      # 数据路径：/var/lib/clickhouse
      # container_name=clickhouse-server
      # vim $(docker inspect $container_name --format='{{.GraphDriver.Data.MergedDir}}')/etc/clickhouse-server/config.xml
      # vim $(docker inspect $container_name --format='{{.GraphDriver.Data.MergedDir}}')/etc/clickhouse-server/users.xml
      # vim $(docker inspect $container_name --format='{{.GraphDriver.Data.MergedDir}}')/etc/clickhouse-server/users.d/default-user.xml
      - '$CLICKHOUSE_HOME/data:/var/lib/clickhouse'
      # 日志路径：/var/log/clickhouse-server
      - '$CLICKHOUSE_HOME/log:/var/log/clickhouse-server'
    ulimits:
      nofile:
        soft: 262144
        hard: 262144

启动 clickhouse 服务

systemctl start clickhouse-server.service

命令	介绍
`systemctl status clickhouse-server.service`	查看 clickhouse 状态
`systemctl start clickhouse-server.service`	启动 clickhouse
`systemctl stop clickhouse-server.service`	停止 clickhouse
`systemctl restart clickhouse-server.service`	重启 clickhouse
`systemctl is-enabled clickhouse-server.service`	查看 clickhouse 开启自启状态
`systemctl enable clickhouse-server.service`	打开 clickhouse 开启自启
`systemctl disable clickhouse-server.service`	关闭 clickhouse 开启自启

配置

路径	说明
`/etc/clickhouse-server`	`clickhouse 服务` 配置文件夹
`/etc/clickhouse-server/config.xml`	`clickhouse 服务` 配置文件
`/etc/clickhouse-server/users.d/default-password.xml`	`clickhouse 服务` `default` 用户密码，使用 `sha256` 摘要
`/etc/clickhouse-client`	`clickhouse 客户` 配置文件夹
`/etc/clickhouse-keeper`	`clickhouse 分布式协调服务` 配置文件夹
`/var/lib/clickhouse`	`clickhouse 服务` 数据储存文件夹
`/var/lib/clickhouse/metadata`	`clickhouse 服务` 数据库表结构元数据文件夹
`/var/lib/clickhouse/store`	`clickhouse 服务` 数据库表文件夹
`/var/lib/clickhouse/tmp`	`clickhouse 服务` 数据库临时文件

允许远程连接

# 使用管理员权限修改
sudo vim /etc/clickhouse-server/config.xml

# 允许所有地址连接
<listen_host>0.0.0.0</listen_host>

# 强制保存后退出
:wq!

# 重启后生效
sudo systemctl restart clickhouse-server

ClickHouse 数据库

文档

在 Debian/Ubuntu 上安装 ClickHouse

配置软件源

安装 ClickHouse 服务端和客户端

在 Redhat/CentOS 上安装 ClickHouse

配置软件源

安装 ClickHouse 服务端和客户端

配置 ClickHouse default 用户密码

使用 Docker 安装 ClickHouse

docker container

docker compose

启动 clickhouse 服务

配置

允许远程连接

配置 ClickHouse `default` 用户密码