📚 课程目录第1章 ClickHouse本地单机环境搭建与验证

1. ClickHouse本地单机环境搭建与验证

环境准备与安装路径选择

ClickHouse 单机环境有两种主流落地方式：Docker 容器适合快速验证、隔离干净；Linux 原生安装适合贴近生产、便于调优。两者最终都暴露三个关键端口：HTTP 接口 8123、TCP 原生协议 9000、以及可选的 MySQL 兼容端口 9004。本案例以 Docker 为主线，同时给出 Linux 原生安装命令，任选其一即可完成验证。

ClickHouse 官方镜像 clickhouse/clickhouse-server 默认以 default 用户运行，无密码。生产环境务必修改密码并限制网络访问，本案例仅用于本地验证。

Docker 方式：一条命令拉起服务

创建数据与配置的持久化目录，避免容器重建后数据丢失：

mkdir -p ~/ch/data ~/ch/conf
docker run -d --name ch-single \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 -p 9000:9000 \
  -v ~/ch/data:/var/lib/clickhouse \
  -v ~/ch/conf:/etc/clickhouse-server/conf.d \
  clickhouse/clickhouse-server:24.3

参数说明：--ulimit nofile 提高文件描述符上限，ClickHouse 打开分区文件较多，默认值容易触发 Too many open files；两个 -v 分别挂载数据目录和配置覆盖目录；24.3 为 LTS 版本标签，可替换为其他稳定版本。

Linux 原生方式（可选）

sudo apt-get install -y apt-transport-https ca-certificates
sudo apt-get install -y clickhouse-server clickhouse-client
sudo systemctl start clickhouse-server
sudo systemctl status clickhouse-server

启动状态与端口连通性检查

容器启动后先确认进程与端口是否就绪。ClickHouse 启动需要几秒加载元数据，立即连接可能失败，建议等待 3~5 秒后再验证。

docker ps --filter name=ch-single
docker logs --tail 20 ch-single
curl 'http://localhost:8123/ping'

/ping 返回 Ok. 表示 HTTP 接口已就绪。若返回连接拒绝，检查容器是否处于 Exited 状态，并用 docker logs 查看报错。

建库、建表并插入测试数据

进入客户端交互模式：

docker exec -it ch-single clickhouse-client

在客户端中依次执行以下语句。这里使用最基础的 MergeTree 引擎，不设分区键，仅用于验证读写链路：

CREATE DATABASE IF NOT EXISTS demo;

CREATE TABLE demo.hello_ch
(
    id        UInt32,
    name      String,
    created   DateTime DEFAULT now()
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO demo.hello_ch (id, name) VALUES (1, 'clickhouse');

SELECT * FROM demo.hello_ch;

预期返回一行：id=1、name=clickhouse、created 为插入时刻的时间戳。若 SELECT 能返回该行，说明写入、存储、查询全链路正常。

用 HTTP 接口做独立验证

不进入客户端，直接用 curl 验证 HTTP 通道，可排除客户端配置干扰：

curl 'http://localhost:8123/?query=SELECT%20count()%20FROM%20demo.hello_ch'

返回 1 即表示 HTTP 接口也能读到同一份数据，两条连接路径共享同一存储引擎。

验证清单

检查项	命令 / 语句	通过标准
容器运行	`docker ps --filter name=ch-single`	状态为 Up
HTTP 存活	`curl localhost:8123/ping`	返回 `Ok.`
TCP 连接	`clickhouse-client --query "SELECT 1"`	返回 `1`
建库建表	`SHOW TABLES FROM demo`	列出 `hello_ch`
数据写入	`SELECT count() FROM demo.hello_ch`	返回 `1`

若 docker logs 出现 Address already in use，说明宿主机 8123 或 9000 已被占用，改用 -p 18123:8123 -p 19000:9000 重新映射，并相应调整连接端口。若出现 Too many open files，确认启动时已加 --ulimit nofile=262144:262144。

清理与复用

验证完成后可停止容器保留数据，下次直接 docker start ch-single 即可恢复；若需彻底重置，执行 docker rm -f ch-single 并删除 ~/ch/data 目录。数据目录挂载在宿主机，容器删除不会自动清除，这是后续案例复用环境的基础。