第2章 单机部署：环境准备与安装验证

单机部署是学习 ClickHouse 的第一步，也是后续搭建集群的基础。说实话，很多人一上来就搞集群，结果连单机都没跑明白，出了问题排查起来特别痛苦。我建议你先老老实实把单机环境搭一遍，踩踩坑，再考虑分布式的事。

2.1 环境准备

ClickHouse 对操作系统有一定要求。我个人习惯用 CentOS 7.9 或 Ubuntu 20.04 LTS，这两个版本我都生产验证过，稳定性没问题。

2.1.1 硬件要求

资源	最低配置	推荐配置	说明
CPU	2 核	8 核以上	ClickHouse 对多核利用极好，核越多越快
内存	4 GB	32 GB 以上	内存越大，查询缓存效果越好
磁盘	50 GB HDD	500 GB SSD/NVMe	强烈建议用 SSD，IOPS 是关键
网络	千兆	万兆	集群场景下网络延迟影响大

2.1.2 操作系统依赖

不管用 CentOS 还是 Ubuntu，先把基础依赖装上。嗯，这里有个小坑——很多人忘了装 tzdata，结果 ClickHouse 启动时报时区错误。

CentOS / RHEL 7/8：

yum install -y epel-release
yum install -y curl wget unzip tzdata
yum groupinstall -y "Development Tools"

Ubuntu 20.04 / 22.04：

apt-get update
apt-get install -y curl wget unzip tzdata build-essential

2.2 安装方式选择

ClickHouse 官方提供了三种安装方式：YUM/APT 仓库、TAR 包、Docker。生产环境我推荐用 YUM/APT，管理起来最省心。你想想看，后续升级、回滚都方便。

2.2.1 添加官方 YUM 仓库（CentOS）

cat <<EOF | tee /etc/yum.repos.d/clickhouse.repo
[clickhouse]
name=ClickHouse Repository
baseurl=https://packages.clickhouse.com/rpm/stable/
gpgcheck=1
gpgkey=https://packages.clickhouse.com/rpm/stable/repodata/repomd.xml.key
enabled=1
EOF

yum clean all
yum makecache

2.2.2 添加官方 APT 仓库（Ubuntu）

apt-get install -y apt-transport-https ca-certificates dirmngr
apt-key adv --keyserver keyserver.ubuntu.com --recv E0C56BD4

echo "deb https://packages.clickhouse.com/deb stable main" | tee /etc/apt/sources.list.d/clickhouse.list
apt-get update

2.2.3 执行安装

两种系统命令几乎一样：

# CentOS
yum install -y clickhouse-server clickhouse-client

# Ubuntu
apt-get install -y clickhouse-server clickhouse-client

安装过程中会提示你设置默认用户密码。我建议先留空，等配置阶段再统一设置。为什么？因为安装脚本生成的默认密码格式有时候跟配置文件对不上，我踩过这个坑。

2.3 配置文件详解

ClickHouse 的配置体系有点特别。它用 XML 格式，而且支持多文件覆盖。说白了，就是你可以把不同维度的配置拆到不同文件里，最后合并生效。

核心配置文件有两个：

文件	作用	修改频率
config.xml	主配置文件，定义服务端全局参数	低频
users.xml	用户、权限、配额配置	中频

2.3.1 config.xml 关键参数

打开 /etc/clickhouse-server/config.xml，我挑几个生产环境必须关注的参数说说：

<!-- 监听地址，默认只监听 127.0.0.1 -->
<listen_host>0.0.0.0</listen_host>

<!-- HTTP 端口，用于 HTTP 接口查询 -->
<http_port>8123</http_port>

<!-- 原生 TCP 端口，用于 clickhouse-client 连接 -->
<tcp_port>9000</tcp_port>

<!-- 数据存储路径，可以配多个 -->
<path>/var/lib/clickhouse/</path>

<!-- 日志级别，生产建议用 information -->
<logger>
    <level>information</level>
    <log>/var/log/clickhouse-server/clickhouse-server.log</log>
    <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
</logger>

<!-- 最大内存使用，单位字节 -->
<max_server_memory_usage>0</max_server_memory_usage>

2.3.2 users.xml 关键参数

默认用户是 default，密码为空。生产环境必须改：

<users>
    <default>
        <password>你的密码</password>
        <!-- 或者用 SHA256 加密 -->
        <password_sha256_hex>加密后的值</password_sha256_hex>

        <networks>
            <ip>127.0.0.1</ip>
            <ip>192.168.1.0/24</ip>
        </networks>

        <profile>default</profile>
        <quota>default</quota>
    </default>
</users>

2.4 启动与验证

配置改好了，该启动了。ClickHouse 的启动方式很灵活，我一般用 systemd 管理。

2.4.1 启动服务

# 启动
systemctl start clickhouse-server

# 设置开机自启
systemctl enable clickhouse-server

# 查看状态
systemctl status clickhouse-server

如果启动失败，先看日志：

tail -f /var/log/clickhouse-server/clickhouse-server.log
tail -f /var/log/clickhouse-server/clickhouse-server.err.log

2.4.2 客户端连接验证

用 clickhouse-client 连上去试试：

clickhouse-client --host 127.0.0.1 --port 9000 --user default --password

# 如果没设密码
clickhouse-client

连上后执行几个简单命令：

SELECT version();
SELECT 1 + 1;
SHOW databases;

看到类似下面的输出，说明安装成功：

┌─version()─┐
│ 24.3.3.102 │
└───────────┘

┌─plus(1, 1)─┐
│          2 │
└────────────┘

┌─name────┐
│ default │
│ system  │
└─────────┘

2.4.3 HTTP 接口验证

ClickHouse 还提供了 HTTP 接口，方便程序调用：

curl 'http://127.0.0.1:8123/?query=SELECT+version()'

返回结果：

24.3.3.102

2.5 本章知识体系

下面这张图把单机部署的核心流程串起来了，你可以对照着检查自己有没有遗漏：

2.6 常见问题与避坑

最后分享几个我实际遇到过的问题，你遇到了可以直接对照排查：

• 端口被占用：ClickHouse 默认用 8123 和 9000 端口。如果启动失败，先 netstat -tlnp | grep 8123 看看是不是被其他服务占了。
• 权限不足：数据目录 /var/lib/clickhouse 的所有者必须是 clickhouse 用户。我见过有人用 root 启动，结果数据目录权限乱了。
• 内存不足：如果服务器内存小于 4GB，启动时可能报 Cannot allocate memory。可以临时调小 max_server_memory_usage 试试。
• CPU 不支持：老 CPU 没有 SSE4.2 指令集，ClickHouse 直接拒绝启动。没别的办法，换机器吧。