第 02 章：环境搭建

zjc 于 2026-01-02 发布

这是《ClickHouse 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 ClickHouse 的环境搭建并不复杂，难的是把开发、测试、生产三种环境的资源边界和配置差异想清楚。本章从单机版开始，再到 Docker 和多节点集群，并给出常用配置与验证方法。

2.1 版本选择

ClickHouse 版本迭代较快，建议选择当前官方推荐的稳定版本，并在生产环境固定版本。不要把长期未升级的集群直接跨大版本升级。

查看版本：

SELECT version();

版本选择建议：

环境	建议
本地学习	官方稳定版或 Docker 最新稳定镜像
功能验证	与生产同一大版本
生产	固定版本、灰度升级、回滚方案完备

生产升级前至少确认：

兼容性列表；
表引擎和 SQL 行为差异；
元数据存储格式变化；
Keeper 或 ZooKeeper 版本；
客户端和 JDBC、ODBC 驱动版本。

2.2 使用 Docker 启动单节点

适合学习和快速验证：

docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  -e ULIMIT_NOFILE=262144:262144 \
  clickhouse/clickhouse-server:24.8

进入容器：

docker exec -it clickhouse-server clickhouse-client

HTTP 验证：

curl 'http://127.0.0.1:8123/?query=SELECT%201'

常见端口：

端口	协议	用途
8123	HTTP	HTTP API、健康检查
9000	Native	clickhouse-client、高吞吐写入
9440	Native TLS	加密原生协议
8443	HTTP TLS	加密 HTTP
9181	Keeper	Raft 通信，集群使用

2.3 Linux 单机安装

以 Debian、Ubuntu 系为例，官方文档提供安装脚本。生产环境建议使用内部制品库或镜像源，避免构建机直接依赖外网。

安装后确认服务：

sudo systemctl status clickhouse-server
sudo systemctl enable clickhouse-server

启动和停止：

sudo systemctl start clickhouse-server
sudo systemctl stop clickhouse-server

连接：

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

2.4 目录结构

默认目录可能因安装方式不同而变化，常见位置如下：

/etc/clickhouse-server/config.xml        服务配置
/etc/clickhouse-server/users.xml          用户配置
/var/lib/clickhouse/                      数据目录
/var/log/clickhouse-server/               日志目录

生产环境必须独立规划数据盘：

/data01/clickhouse/
/data02/clickhouse/
/data03/clickhouse/

多磁盘配置要结合存储策略使用，不要只是简单挂载后不声明策略。

2.5 核心配置

服务主配置通常是 config.xml，用户相关配置在 users.xml 或用户目录中。推荐使用独立配置文件减少主文件冲突，例如：

/etc/clickhouse-server/config.d/logging.xml
/etc/clickhouse-server/config.d/storage.xml
/etc/clickhouse-server/users.d/app_user.xml

资源限制示例：

<clickhouse>
    <max_server_memory_usage>0</max_server_memory_usage>
    <max_thread_pool_size>10000</max_thread_pool_size>
</clickhouse>

用户配额示例：

<clickhouse>
    <profiles>
        <app_profile>
            <max_memory_usage>4294967296</max_memory_usage>
            <max_execution_time>60</max_execution_time>
        </app_profile>
    </profiles>
</clickhouse>

更推荐使用 SQL 方式创建用户和角色：

CREATE ROLE app_reader;
GRANT SELECT ON analytics.* TO app_reader;

CREATE USER app_user IDENTIFIED BY 'strong-password'
SETTINGS PROFILE app_profile;
GRANT app_reader TO app_user;

2.6 命令行客户端

执行 SQL 文件：

clickhouse-client --multiquery < schema.sql

指定格式输出：

clickhouse-client --query "SELECT number FROM system.numbers LIMIT 3 FORMAT PrettyCompact"

常用格式：

格式	场景
PrettyCompact	人工查看
TabSeparated	管道处理
CSV / CSVWithNames	表格交换
JSONEachRow	应用写入
Parquet	外部数据交换

写入数据：

clickhouse-client --query "
INSERT INTO target_table FORMAT CSVWithNames
" < data.csv

2.7 搭建三节点测试集群

测试集群至少包含：

2 个 ClickHouse 分片副本混合部署，或 2 个 ClickHouse 节点
3 个 ClickHouse Keeper 节点

Keeper 负责副本元数据和分布式 DDL 协调。生产通常使用 3 个或 5 个节点，保证奇数多数派。

config.xml 中的远程服务器示例：

<clickhouse>
    <remote_servers>
        <analytics_cluster>
            <shard>
                <replica>
                    <host>ch-01.internal</host>
                    <port>9000</port>
                </replica>
                <replica>
                    <host>ch-02.internal</host>
                    <port>9000</port>
                </replica>
            </shard>
        </analytics_cluster>
    </remote_servers>
</clickhouse>

查看集群：

SELECT * FROM system.clusters;

确认 Keeper：

echo ruok | nc keeper-01 9181

ClickHouse Keeper 使用四字命令时要以 telnet 或 TCP 工具发送，命令支持程度与版本有关。

2.8 数据库和表初始化

CREATE DATABASE IF NOT EXISTS analytics;

CREATE TABLE analytics.events_local
(
    event_date Date,
    event_time DateTime,
    event_id String,
    user_id UInt64,
    event_type LowCardinality(String),
    city_id UInt32,
    amount Decimal64(2)
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(event_date)
ORDER BY (event_date, event_type, city_id, user_id);

插入测试数据：

INSERT INTO analytics.events_local
SELECT
    today() AS event_date,
    now() AS event_time,
    toString(number) AS event_id,
    number % 10000 AS user_id,
    if(number % 3 = 0, 'view', 'pay') AS event_type,
    number % 100 AS city_id,
    toDecimal64(number % 500, 2) AS amount
FROM system.numbers
LIMIT 100000;

验证：

SELECT event_type, count(), round(sum(amount), 2)
FROM analytics.events_local
GROUP BY event_type;

2.9 常见安装问题

连接被拒绝

排查顺序：

systemctl status clickhouse-server
ss -lntp | grep -E '8123|9000'
docker port clickhouse-server

常见原因：

服务未启动；
监听地址只绑定 127.0.0.1；
安全组或防火墙未放行；
客户端使用错协议端口；
TLS 配置不匹配。

认证失败

确认用户名、密码和网络来源：

SELECT name, networks, auth_type
FROM system.users;

磁盘空间不足

SELECT
    name,
    path,
    free_space,
    total_space
FROM system.disks
ORDER BY free_space;

本章小结

单机环境适合学习 SQL 和 MergeTree；测试和生产环境要提前规划版本、端口、数据目录、用户权限、Keeper 集群和资源限制。ClickHouse 的性能高度依赖机器资源和配置边界，环境搭建阶段就应该把可观测性和回滚方案一并纳入。

思考题

HTTP 端口和 Native 端口分别适合什么访问方式？
为什么生产环境要独立规划 ClickHouse 数据目录？
Keeper 在集群中承担哪些职责？
如何避免用户执行无限制的大查询？
如果服务启动失败，你会按什么顺序排查？