ClickHouse 学习笔记：单例模式安装部署实战指南

ClickHouse 是由俄罗斯「Yandex」公司开源的列式存储数据库，专门用于 OLAP（在线分析处理）场景。本笔记记录了 ClickHouse 单例模式的完整安装部署流程，帮助开发者快速搭建分析型数据库环境。

📋 目录

环境准备
安装方式选择
[RPM/DEB 包安装（推荐）](#RPM/DEB 包安装（推荐）)
[Docker 容器安装](#Docker 容器安装)
源码编译安装
基础配置优化
服务启动与验证
常用管理命令
性能调优建议
常见问题排查

环境准备

系统要求

项目	最低要求	推荐配置
CPU	2 核	4 核以上
内存	4 GB	8 GB 以上
磁盘	20 GB	100 GB 以上 SSD
操作系统	CentOS 7+ / Ubuntu 18.04+	CentOS 8 / Ubuntu 20.04+

关闭防火墙（测试环境）

bash 复制代码

# CentOS/RHEL
sudo systemctl stop firewalld
sudo systemctl disable firewalld

# Ubuntu
sudo ufw disable

关闭 SELinux

bash 复制代码

# 编辑配置文件
sudo vim /etc/selinux/config

# 设置 SELINUX=disabled
SELINUX=disabled

# 重启系统或执行
sudo setenforce 0

安装方式选择

ClickHouse 提供多种安装方式，适用于不同场景：

安装方式	适用场景	优点	缺点
RPM/DEB 包	生产环境	管理便捷，易于升级	需手动解决依赖
Docker	开发测试	快速部署，环境隔离	性能有损耗
源码编译	定制化需求	灵活配置	编译耗时较长

💡 推荐：生产环境使用 RPM/DEB 包，开发测试环境使用 Docker

RPM/DEB 包安装（推荐）

CentOS/RHEL 系统

1. 添加 YUM 仓库

bash 复制代码

# CentOS 8 / RHEL 8
sudo yum install -y yum-utils
sudo rpm --import https://repo.clickhouse.com/CLICKHOUSE-KEY.GPG
sudo yum-config-manager --add-repo https://repo.clickhouse.com/rpm/clickhouse.repo

# CentOS 7 / RHEL 7
sudo yum install -y yum-utils
sudo rpm --import https://repo.clickhouse.com/CLICKHOUSE-KEY.GPG
sudo yum-config-manager --add-repo https://repo.clickhouse.com/rpm/clickhouse.repo

2. 安装 ClickHouse

bash 复制代码

# 安装服务器和客户端
sudo yum install -y clickhouse-server clickhouse-client

# 或者仅安装服务器（无客户端）
sudo yum install -y clickhouse-server

3. 启动服务

bash 复制代码

# 启动服务
sudo systemctl start clickhouse-server

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

# 查看服务状态
sudo systemctl status clickhouse-server

Ubuntu/Debian 系统

1. 添加 APT 仓库

bash 复制代码

# 添加 GPG 密钥
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv E0C56BDD

# 添加仓库
sudo add-apt-repository "deb https://repo.clickhouse.com/deb stable main"

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

2. 安装 ClickHouse

bash 复制代码

# 安装服务器和客户端
sudo apt-get install -y clickhouse-server clickhouse-client

# 或者仅安装服务器
sudo apt-get install -y clickhouse-server

3. 启动服务

bash 复制代码

# 启动服务
sudo systemctl start clickhouse-server

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

# 查看服务状态
sudo systemctl status clickhouse-server

Docker 容器安装

1. 拉取镜像

bash 复制代码

# 拉取最新稳定版
docker pull clickhouse/clickhouse-server:latest

# 或者指定版本
docker pull clickhouse/clickhouse-server:23.8

2. 运行容器

bash 复制代码

# 基本运行命令
docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  clickhouse/clickhouse-server:latest

# 带数据持久化的运行命令
docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  -v clickhouse_data:/var/lib/clickhouse \
  -v clickhouse_logs:/var/log/clickhouse-server \
  clickhouse/clickhouse-server:latest

3. 参数说明

参数	说明
`-d`	后台运行
`--name`	容器名称
`-p 8123:8123`	HTTP 接口端口（用于 Web UI 和 HTTP API）
`-p 9000:9000`	Native 接口端口（用于 ClickHouse 客户端）
`-v`	数据卷挂载

源码编译安装

⚠️ 注意：源码编译耗时较长（约 30-60 分钟），仅在需要定制化功能时使用

环境准备

bash 复制代码

# 安装依赖（CentOS 7）
sudo yum groupinstall -y "Development Tools"
sudo yum install -y cmake ninja-build python3

# 安装依赖（Ubuntu）
sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build python3

编译步骤

bash 复制代码

# 1. 克隆源码
git clone --recursive https://github.com/ClickHouse/ClickHouse.git
cd ClickHouse

# 2. 创建构建目录
mkdir build
cd build

# 3. 配置编译选项
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/clickhouse ..

# 4. 编译（使用多核加速）
ninja -j $(nproc)

# 5. 安装
sudo ninja install

# 6. 创建符号链接
sudo ln -s /usr/local/clickhouse/bin/* /usr/bin/

基础配置优化

配置文件位置

ClickHouse 主要配置文件位于 /etc/clickhouse-server/ 目录：

复制代码

/etc/clickhouse-server/
├── config.xml          # 主配置文件
├── users.xml           # 用户配置
└── config.d/           # 自定义配置目录

关键配置项优化

1. 内存配置

编辑 config.xml：

xml 复制代码

<!-- 设置最大内存使用量（默认内存的 80%） -->
<max_server_memory_usage_to_ram_ratio>0.8</max_server_memory_usage_to_ram_ratio>

<!-- 单查询最大内存限制 -->
<max_memory_usage>10000000000</max_memory_usage>  <!-- 约 10GB -->

<!-- 聚合查询内存限制 -->
<max_bytes_before_external_group_by>5000000000</max_bytes_before_external_group_by>  <!-- 5GB -->

2. 并发配置

xml 复制代码

<!-- 最大并发查询数 -->
<max_concurrent_queries>100</max_concurrent_queries>

<!-- 线程池大小 -->
<background_thread_pool_threads>16</background_thread_pool_threads>

3. 日志配置

xml 复制代码

<!-- 日志级别 -->
<level>information</level>

<!-- 日志文件路径 -->
<log>/var/log/clickhouse-server/clickhouse-server.log</log>

<!-- 错误日志路径 -->
<errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>

<!-- 日志滚动配置 -->
<size>1000M</size>
<count>10</count>

4. 网络配置

xml 复制代码

<!-- HTTP 监听端口 -->
<http_port>8123</http_port>

<!-- Native 客户端端口 -->
<tcp_port>9000</tcp_port>

<!-- 绑定 IP（0.0.0.0 表示监听所有网卡） -->
<listen_host>0.0.0.0</listen_host>

生产环境推荐配置

创建 /etc/clickhouse-server/config.d/custom-config.xml：

xml 复制代码

<clickhouse>
    <remote_servers>
        <!-- 集群配置（如有需要） -->
    </remote_servers>

    <!-- Zookeeper 配置（用于复制表） -->
    <zookeeper>
        <node>
            <host>zk1.example.com</host>
            <port>2181</port>
        </node>
    </zookeeper>

    <!-- 压缩配置 -->
    <compression>
        <case>
            <method>lz4</method>
        </case>
    </compression>

    <!-- 墨认数据库路径 -->
    <path>/var/lib/clickhouse/</path>
    <tmp_path>/var/lib/clickhouse/tmp/</tmp_path>
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>
</clickhouse>

服务启动与验证

使用 systemd 管理服务

bash 复制代码

# 启动服务
sudo systemctl start clickhouse-server

# 停止服务
sudo systemctl stop clickhouse-server

# 重启服务
sudo systemctl restart clickhouse-server

# 查看服务状态
sudo systemctl status clickhouse-server

# 查看实时日志
sudo journalctl -u clickhouse-server -f

连接验证

方法一：使用 clickhouse-client

bash 复制代码

# 本地连接
clickhouse-client

# 指定主机连接
clickhouse-client --host=127.0.0.1 --port=9000

# 执行测试查询
clickhouse-client --query="SELECT 1"

方法二：使用 HTTP 接口

bash 复制代码

# 安装 curl（如果未安装）
sudo yum install -y curl  # CentOS
# sudo apt-get install -y curl  # Ubuntu

# 测试 HTTP 接口
curl http://localhost:8123

# 执行查询
curl http://localhost:8123?query=SELECT%201

方法三：Web UI

在浏览器中访问：http://服务器IP:8123

📝 说明：ClickHouse 的 Web UI 较为简洁，主要用于查询执行和系统监控

功能验证测试

sql 复制代码

-- 1. 查看 ClickHouse 版本
SELECT version();

-- 2. 查看数据库列表
SHOW DATABASES;

-- 3. 创建测试数据库
CREATE DATABASE IF NOT EXISTS test;

-- 4. 创建测试表
CREATE TABLE test.sample_table (
    id UInt32,
    name String,
    created_date Date
) ENGINE = Memory;

-- 5. 插入测试数据
INSERT INTO test.sample_table VALUES
    (1, 'Alice', '2024-01-01'),
    (2, 'Bob', '2024-01-02'),
    (3, 'Charlie', '2024-01-03');

-- 6. 查询验证
SELECT * FROM test.sample_table;

-- 7. 查看表结构
DESCRIBE test.sample_table;

-- 8. 查看系统信息
SELECT
    name,
    value
FROM system.settings
WHERE name IN ('max_memory_usage', 'max_concurrent_queries')
LIMIT 10;

预期输出示例：

复制代码

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

┌─id─┬─name────┬─created_date─┐
│  1 │ Alice   │   2024-01-01 │
│  2 │ Bob     │   2024-01-02 │
│  3 │ Charlie │   2024-01-03 │
└────┴─────────┴──────────────┘

常用管理命令

clickhouse-client 常用参数

bash 复制代码

# 连接参数
--host, -h          # 服务器地址（默认 localhost）
--port              # 端口（默认 9000）
--user, -u          # 用户名（默认 default）
--password          # 密码
--database, -d      # 默认数据库
--queries-file      # 从文件执行 SQL

# 输出参数
--format, -f        # 输出格式（JSON, CSV, XML 等）
--progress          # 显示进度
--time, -t          # 显示执行时间
--stacktrace        # 显示堆栈跟踪

# 使用示例
clickhouse-client -h 192.168.1.100 -u admin --password 123456 -d mydb

数据目录管理

bash 复制代码

# 查看数据目录大小
sudo du -sh /var/lib/clickhouse/

# 查看临时目录
sudo ls -la /var/lib/clickhouse/tmp/

# 查看日志文件
sudo tail -f /var/log/clickhouse-server/clickhouse-server.log

配置文件检查

bash 复制代码

# 检查配置文件语法
clickhouse-server --config-file=/etc/clickhouse-server/config.xml --help

# 查看有效配置
clickhouse-client --query="SHOW SETTINGS"

性能调优建议

1. 硬件优化

CPU：支持 AVX2 指令集的处理器
内存：足够的 RAM（至少 8GB，推荐 16GB+）
磁盘：使用 SSD，启用 RAID 0
网络：千兆或万兆以太网

2. 关键配置调优

内存优化

xml 复制代码

<!-- /etc/clickhouse-server/config.d/memory.xml -->
<clickhouse>
    <!-- 聚合查询外部化（内存不足时启用） -->
    <max_bytes_before_external_group_by>5000000000</max_bytes_before_external_group_by>
    <max_bytes_before_external_sort>5000000000</max_bytes_before_external_sort>

    <!-- 查询内存限制 -->
    <max_memory_usage>16000000000</max_memory_usage>  <!-- 16GB -->

    <!-- 线程池设置 -->
    <background_thread_pool_threads>32</background_thread_pool_threads>
</clickhouse>

I/O 优化

xml 复制代码

<!-- /etc/clickhouse-server/config.d/io.xml -->
<clickhouse>
    <!-- 读取线程数 -->
    <read_backoff_for_threading_monotonic_blocks>1</read_backoff_for_threading_monotonic_blocks>

    <!-- 最大并发读取数 -->
    <max_concurrent_reads>32</max_concurrent_reads>

    <!-- 压缩块大小 -->
    <max_compress_block_size>1048576</max_compress_block_size>  <!-- 1MB -->
</clickhouse>

3. 查询优化建议

sql 复制代码

-- 使用 PREWHERE 优化查询（ClickHouse 特性）
SELECT id, name FROM large_table PREWHERE id > 1000;

-- 使用抽样查询大数据集
SELECT count() FROM table SAMPLE 1000000;

-- 使用 LIMIT 限制结果集
SELECT * FROM large_table ORDER BY timestamp DESC LIMIT 100;

-- 使用projection加速聚合查询

常见问题排查

问题 1：服务无法启动

现象：

bash 复制代码

sudo systemctl status clickhouse-server
# 显示 Failed to start ClickHouse server

排查步骤：

bash 复制代码

# 1. 查看详细错误日志
sudo journalctl -u clickhouse-server -n 100 --no-pager

# 2. 检查配置文件语法
clickhouse-server --config-file=/etc/clickhouse-server/config.xml --help

# 3. 检查端口占用
sudo netstat -tulpn | grep 9000
sudo netstat -tulpn | grep 8123

# 4. 检查目录权限
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse/
sudo chown -R clickhouse:clickhouse /var/log/clickhouse-server/

解决方案：

bash 复制代码

# 修复权限
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse/
sudo chown -R clickhouse:clickhouse /var/log/clickhouse-server/
sudo chmod 755 /var/lib/clickhouse/
sudo chmod 755 /var/log/clickhouse-server/

# 删除锁文件
sudo rm -f /var/lib/clickhouse/lock

# 重新启动
sudo systemctl restart clickhouse-server

问题 2：内存不足错误

现象：

复制代码

Memory limit (for query) exceeded: would use 12.00 GiB...

解决方案：

xml 复制代码

<!-- 临时解决方案：增加内存限制 -->
<max_memory_usage>20000000000</max_memory_usage>  <!-- 20GB -->

<!-- 长期解决方案：使用外部聚合 -->
<max_bytes_before_external_group_by>10000000000</max_bytes_before_external_group_by>
<max_bytes_before_external_sort>10000000000</max_bytes_before_external_sort>

问题 3：Too many parts

现象：

复制代码

Too many parts (300). Merging of 5 parts should be initiated

解决方案：

xml 复制代码

<!-- 调整合并参数 -->
<merge_tree>
    <max_scheduled_merge_density>200</max_scheduled_merge_density>
    <number_of_free_entries_in_pool_to_lower_max_size_of_merge>8</number_of_free_entries_in_pool_to_lower_max_size_of_merge>
</merge_tree>

<!-- 手动触发合并 -->
OPTIMIZE TABLE your_table FINAL;

问题 4：连接被拒绝

现象：

复制代码

Connection refused: connect(127.0.0.1:9000)

排查步骤：

bash 复制代码

# 1. 检查服务是否运行
sudo systemctl status clickhouse-server

# 2. 检查端口监听
sudo netstat -tulpn | grep clickhouse

# 3. 检查防火墙
sudo firewall-cmd --list-all  # CentOS
sudo ufw status               # Ubuntu

# 4. 测试本地连接
clickhouse-client --host=127.0.0.1 --port=9000

解决方案：

bash 复制代码

# 允许端口通过防火墙
sudo firewall-cmd --permanent --add-port=9000/tcp
sudo firewall-cmd --reload

问题 5：数据目录磁盘空间不足

现象：

复制代码

Cannot write to file /var/lib/clickhouse/... No space left on device

解决方案：

bash 复制代码

# 1. 查看磁盘使用情况
df -h

# 2. 清理旧数据
sudo find /var/lib/clickhouse/clickhouse/ -name "*.bin" -mtime +30 -delete

# 3. 移动数据到其他磁盘
sudo systemctl stop clickhouse-server
sudo mv /var/lib/clickhouse /data/clickhouse
sudo ln -s /data/clickhouse /var/lib/clickhouse
sudo systemctl start clickhouse-server

总结

本文详细介绍了 ClickHouse 单例模式的安装部署流程，包括：

✅ 多种安装方式 ：RPM/DEB 包（生产）、Docker（开发）、源码编译（定制）

✅ 完整配置优化 ：内存、并发、日志、网络等关键参数

✅ 验证测试方法 ：客户端连接、HTTP 接口、Web UI

✅ 性能调优建议 ：硬件选择和参数优化

✅ 常见问题排查：启动失败、内存不足、连接问题等

ClickHouse 作为高性能列式数据库，在 OLAP 场景下表现优异。通过合理的安装部署和配置优化，可以充分发挥其性能优势。