ClickHouse 教程 / 安装与部署

安装与部署

1. 单机安装

1.1 使用官方安装脚本（推荐）

官方提供一键安装脚本，支持主流 Linux 发行版：

# 一键安装最新稳定版
curl https://clickhouse.com/ | sh

# 安装完成后启动服务
sudo clickhouse start

# 验证安装
clickhouse-client --query "SELECT version()"

1.2 RPM 安装（CentOS / RHEL / Fedora）

# 添加 ClickHouse 官方仓库
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://packages.clickhouse.com/rpm/clickhouse.repo

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

# 启动服务
sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server

1.3 DEB 安装（Ubuntu / Debian）

# 添加 GPG key
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 \
    --recv 8919F6BD2B48D754

# 添加仓库
echo "deb https://packages.clickhouse.com/deb stable main" | \
    sudo tee /etc/apt/sources.list.d/clickhouse.list

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

# 启动服务
sudo systemctl start clickhouse-server
sudo systemctl enable clickhouse-server

1.4 tgz 包手动安装

适用于无 root 权限或自定义安装路径的场景：

# 下载二进制包
wget https://builds.clickhouse.com/master/amd64/clickhouse-common-static-24.8.1.1.tgz
tar -xzf clickhouse-common-static-24.8.1.1.tgz
sudo ./clickhouse-common-static-*/install/doinst.sh

# 创建数据目录
mkdir -p /data/clickhouse
mkdir -p /var/log/clickhouse-server

⚠️ 注意：生产环境请使用 LTS（长期支持）版本，避免使用 nightly 或 testing 版本。

2. Docker 快速启动

2.1 最简单的启动方式

# 拉取最新镜像
docker pull clickhouse/clickhouse-server:latest

# 启动容器
docker run -d \
    --name clickhouse-server \
    -p 8123:8123 \
    -p 9000:9000 \
    -v /data/clickhouse:/var/lib/clickhouse \
    clickhouse/clickhouse-server:latest

# 连接测试
docker exec -it clickhouse-server clickhouse-client

2.2 使用 Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:24.8-lts
    container_name: clickhouse-server
    ports:
      - "8123:8123"   # HTTP 接口
      - "9000:9000"   # Native TCP 协议
      - "9009:9009"   # 集群内部通信
    volumes:
      - ./data/clickhouse:/var/lib/clickhouse
      - ./config/config.xml:/etc/clickhouse-server/config.xml
      - ./config/users.xml:/etc/clickhouse-server/users.xml
    environment:
      CLICKHOUSE_DB: mydb
      CLICKHOUSE_USER: default
      CLICKHOUSE_PASSWORD: ""
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    restart: unless-stopped

# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f clickhouse

# 进入交互式客户端
docker exec -it clickhouse-server clickhouse-client

2.3 多节点集群 Docker 部署

# docker-compose-cluster.yml
version: '3.8'

services:
  clickhouse-1:
    image: clickhouse/clickhouse-server:24.8-lts
    hostname: clickhouse-1
    ports:
      - "8123:8123"
      - "9000:9000"
    volumes:
      - ./config/cluster.xml:/etc/clickhouse-server/config.d/cluster.xml
      - ch1-data:/var/lib/clickhouse

  clickhouse-2:
    image: clickhouse/clickhouse-server:24.8-lts
    hostname: clickhouse-2
    ports:
      - "8124:8123"
      - "9001:9000"
    volumes:
      - ./config/cluster.xml:/etc/clickhouse-server/config.d/cluster.xml
      - ch2-data:/var/lib/clickhouse

  clickhouse-3:
    image: clickhouse/clickhouse-server:24.8-lts
    hostname: clickhouse-3
    ports:
      - "8125:8123"
      - "9002:9000"
    volumes:
      - ./config/cluster.xml:/etc/clickhouse-server/config.d/cluster.xml
      - ch3-data:/var/lib/clickhouse

volumes:
  ch1-data:
  ch2-data:
  ch3-data:

💡 提示：开发环境可以使用 ClickHouse 提供的 clickhouse/clickhouse-server 镜像内建的 clickhouse-keeper 替代 ZooKeeper。

3. 配置文件详解

3.1 配置文件路径

路径	用途
`/etc/clickhouse-server/config.xml`	主配置文件
`/etc/clickhouse-server/users.xml`	用户与权限配置
`/etc/clickhouse-server/config.d/*.xml`	配置片段（覆盖主配置）
`/etc/clickhouse-server/users.d/*.xml`	用户配置片段

3.2 config.xml 关键配置

<clickhouse>
    <!-- 服务端口配置 -->
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    <interserver_http_port>9009</interserver_http_port>

    <!-- 数据存储目录 -->
    <path>/var/lib/clickhouse/</path>
    <tmp_path>/var/lib/clickhouse/tmp/</tmp_path>
    <user_files_path>/var/lib/clickhouse/user_files/</user_files_path>

    <!-- 日志配置 -->
    <logger>
        <level>information</level>
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
        <errorlog>/var/log/clickhouse-server/clickhouse-server.err.log</errorlog>
        <size>500M</size>
        <count>5</count>
    </logger>

    <!-- 监听地址（0.0.0.0 允许远程连接） -->
    <listen_host>0.0.0.0</listen_host>

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

    <!-- ZooKeeper 配置（集群部署时需要） -->
    <zookeeper>
        <node>
            <host>zookeeper1</host>
            <port>2181</port>
        </node>
        <node>
            <host>zookeeper2</host>
            <port>2181</port>
        </node>
    </zookeeper>

    <!-- 集群宏定义 -->
    <macros>
        <cluster>production</cluster>
        <shard>01</shard>
        <replica>replica01</replica>
    </macros>
</clickhouse>

3.3 users.xml 用户配置

<clickhouse>
    <users>
        <default>
            <password></password>
            <networks>
                <ip>::/0</ip>
            </networks>
            <profile>default</profile>
            <quota>default</quota>
            <access_management>1</access_management>
        </default>

        <analyst>
            <password_sha256_hex>5e884898da28047151d0e56f8dc...</password_sha256_hex>
            <networks>
                <ip>10.0.0.0/8</ip>
            </networks>
            <profile>readonly</profile>
            <quota>default</quota>
        </analyst>
    </users>

    <profiles>
        <default>
            <max_threads>8</max_threads>
            <max_memory_usage>10000000000</max_memory_usage>
            <max_execution_time>60</max_execution_time>
        </default>
        <readonly>
            <readonly>1</readonly>
        </readonly>
    </profiles>

    <quotas>
        <default>
            <interval>
                <duration>3600</duration>
                <queries>1000</queries>
                <result_rows>1000000000</result_rows>
                <read_rows>10000000000</read_rows>
            </interval>
        </default>
    </quotas>
</clickhouse>

⚠️ 注意：生产环境必须修改默认用户密码，并限制 listen_host 范围。默认用户无密码且允许任何 IP 连接，存在严重安全风险！

4. 数据目录结构

/var/lib/clickhouse/
├── data/                          # 数据库数据
│   ├── default/                   # default 数据库
│   │   └── my_table/             # 表数据目录
│   │       ├── detached/         # 分离的数据部分
│   │       └── all_1_1_0/        # 数据部分（part）
│   │           ├── columns.txt   # 列定义
│   │           ├── data.bin      # 列数据文件
│   │           ├── primary.idx   # 主键索引
│   │           ├── count.txt     # 行数
│   │           └── checksums.txt # 校验和
│   └── system/                    # 系统表
├── metadata/                      # 表元数据（DDL）
│   ├── default.sql
│   └── default/
│       └── my_table.sql
├── preprocessed_configs/          # 预处理后的配置
├── tmp/                           # 临时文件
└── access/                        # 用户权限信息

-- 查看数据部分信息
SELECT
    database,
    table,
    partition,
    name AS part_name,
    rows,
    formatReadableSize(bytes_on_disk) AS size,
    modification_time
FROM system.parts
WHERE table = 'my_table'
  AND active = 1
ORDER BY modification_time DESC;

5. 客户端工具

5.1 clickhouse-client（命令行）

# 基本连接
clickhouse-client

# 指定主机和端口
clickhouse-client --host 192.168.1.100 --port 9000

# 执行单条查询
clickhouse-client --query "SELECT 1"

# 从文件执行查询
clickhouse-client --queries-file query.sql

# 格式化输出
clickhouse-client --query "SELECT * FROM system.tables LIMIT 5" \
    --format PrettyCompact

# 批量插入数据
clickhouse-client --query "INSERT INTO my_table FORMAT CSV" < data.csv

# 多行模式（交互式）
clickhouse-client --multiline

💡 提示：交互式客户端中按 Tab 可以自动补全关键字，按 Ctrl+D 退出。

5.2 DBeaver（GUI 工具）

DBeaver 是免费开源的数据库管理工具：

下载安装 DBeaver
新建连接 → 选择 ClickHouse
填写连接信息：
- Host: localhost
- Port: 8123（HTTP）或 9000（Native）
- Database: default
驱动会自动下载

5.3 DataGrip（JetBrains）

DataGrip 是 JetBrains 出品的专业 SQL IDE：

File → New → Data Source → ClickHouse
配置 JDBC URL: jdbc:clickhouse://localhost:8123/default
自动下载 JDBC 驱动

5.4 Python / Go / Java 客户端

# Python: clickhouse-connect
import clickhouse_connect

client = clickhouse_connect.get_client(host='localhost', port=8123)
result = client.query('SELECT * FROM my_table LIMIT 10')
print(result.result_rows)

6. Web 界面 Play UI

ClickHouse 内置了一个轻量级 Web 查询界面：

访问地址: http://localhost:8123/play

功能特性：

在线 SQL 编辑器
查询结果表格展示
查询执行计划可视化
查询历史记录

💡 提示：Play UI 适合快速测试和调试，不需要安装任何客户端工具。

7. 常用系统命令

命令	用途	示例
`clickhouse-server`	启动服务端	`clickhouse-server --config-file /etc/clickhouse-server/config.xml`
`clickhouse-client`	命令行客户端	`clickhouse-client --query "SELECT 1"`
`clickhouse-benchmark`	性能测试工具	`clickhouse-benchmark --concurrency 10 -i 100 -q "SELECT count() FROM my_table"`
`clickhouse-copier`	集群数据复制	用于跨集群数据迁移
`clickhouse-local`	本地文件查询	`clickhouse-local --query "SELECT * FROM file('data.csv', 'CSV', 'id UInt32, name String')"`
`clickhouse-compressor`	数据压缩工具	`clickhouse-compressor --decompress < data.bin > data.tsv`
`clickhouse-format`	SQL 格式化	`clickhouse-format --query "select 1 from t"`

# 使用 clickhouse-benchmark 测试查询性能
clickhouse-benchmark \
    --concurrency 5 \
    --iterations 100 \
    --query "SELECT count() FROM hits WHERE EventTime > now() - INTERVAL 1 DAY"

# 使用 clickhouse-local 查询本地文件
clickhouse-local \
    --query "SELECT avg(price), max(price) FROM file('products.csv', 'CSV', 'name String, price Float64')"

8. 生产部署建议

8.1 硬件配置建议

资源	最低要求	推荐配置
CPU	4 核	16+ 核（ClickHouse 多线程并行）
内存	8 GB	64+ GB（数据缓存在内存中）
磁盘	SSD	NVMe SSD（I/O 密集型）
网络	1 Gbps	10 Gbps（集群间数据传输）

8.2 系统参数调优

# /etc/security/limits.conf
clickhouse soft nofile 262144
clickhouse hard nofile 262144

# /etc/sysctl.conf
vm.max_map_count = 262144
net.core.somaxconn = 4096

# 禁用 swap（强烈推荐）
swapoff -a

8.3 部署检查清单

检查项	说明
✅ 使用 SSD 磁盘	MergeTree 合并是 I/O 密集操作
✅ 禁用 Swap	内存不足时 Swap 会导致性能骤降
✅ 配置 ZooKeeper	单副本也需要（部分引擎依赖）
✅ 设置用户密码	禁止无密码 default 用户暴露在公网
✅ 配置日志轮转	避免日志撑满磁盘
✅ 监控磁盘空间	Merge 临时空间 = 数据量的 2 倍
✅ 配置备份策略	使用 `clickhouse-backup` 工具

# 使用 clickhouse-backup 进行备份
# 安装
sudo apt-get install -y clickhouse-backup

# 创建备份
clickhouse-backup create my_backup_20260511

# 查看备份列表
clickhouse-backup list

# 恢复备份
clickhouse-backup restore my_backup_20260511

⚠️ 注意：生产环境务必定期备份。ClickHouse 的 DROP TABLE 默认会删除所有数据文件，无回收站机制！