📚 课程目录第4章环境准备

4. 环境准备：Docker安装、Docker Compose配置、启动一个简单的ClickHouse服务

说实话，很多初学者在学OLAP时，第一步就卡在环境搭建上。

我记得几年前带一个新人，光是装ClickHouse就折腾了两天——依赖冲突、端口占用、配置写错……最后发现是系统里残留了旧版本。从那以后，我养成了一个习惯：所有实验环境都用Docker。

这一章，我们就用Docker和Docker Compose，把ClickHouse跑起来。你不需要懂Linux内核，也不需要编译源码。跟着我做，十分钟内就能看到一个活着的OLAP引擎。

4.1 为什么选择Docker？

Docker说白了就是一个“轻量级虚拟机”。但它比虚拟机快得多，启动一个容器只要几秒钟。

对于学习ClickHouse来说，Docker有三个好处：

隔离干净——不会搞乱你的宿主机环境
版本可控——想换版本就换镜像，不用卸载重装
一键复现——把配置分享给同事，他那边也能跑起来

我的习惯：每个项目都配一个 docker-compose.yml。这样不管换电脑还是换团队，环境都是一致的。你想想看，这能省多少“在我机器上能跑啊”的扯皮时间？

4.2 安装Docker

不同操作系统安装方式不太一样。我列个表，你对照自己的系统来：

操作系统	安装方式	验证命令
macOS	下载 Docker Desktop for Mac	`docker --version`
Windows	下载 Docker Desktop for Windows（需开启WSL2）	`docker --version`
Ubuntu/Debian	`sudo apt install docker.io`	`docker --version`
CentOS/RHEL	`sudo yum install docker`	`docker --version`

安装完成后，跑一下这个命令：

docker run hello-world

如果看到一段欢迎信息，说明Docker已经装好了。

我曾经踩过的坑：在Linux上装完Docker后，普通用户直接跑 docker 命令会报权限错误。解决方案是把当前用户加入 docker 组：sudo usermod -aG docker $USER，然后退出重新登录。

4.3 安装Docker Compose

Docker Compose 是一个“编排工具”。你可以把它理解成一个剧本——把多个容器怎么启动、怎么连接、用哪个镜像，都写在一个 YAML 文件里。

macOS 和 Windows 的 Docker Desktop 已经自带了 Compose。Linux 需要单独装：

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

验证一下：

docker-compose --version

看到版本号就对了。

4.4 编写 docker-compose.yml

现在我们来写一个最简单的 ClickHouse 服务配置。新建一个文件夹，比如叫 clickhouse-lab，在里面创建 docker-compose.yml：

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:23.8
    container_name: clickhouse-lab
    ports:
      - "8123:8123"   # HTTP 接口
      - "9000:9000"   # 原生 TCP 接口
    volumes:
      - ./data:/var/lib/clickhouse
      - ./logs:/var/log/clickhouse-server
    ulimits:
      nofile:
        soft: 262144
        hard: 262144

解释一下几个关键点：

image：我选了 23.8 版本，这是比较稳定的 LTS 版。你也可以换成 latest 或你需要的版本。
ports：8123 是 HTTP 端口，可以用浏览器访问；9000 是原生协议端口，给 clickhouse-client 用。
volumes：把容器里的数据目录映射到宿主机。这样就算容器删了，数据还在。
ulimits：ClickHouse 对文件句柄数要求比较高。不设这个限制，容器可能会报 "too many open files"。

  为什么选 23.8？ 我在生产环境用过 22.x 和 23.x，23.8 在查询性能和内存管理上都有明显改进。而且这个版本对新手很友好，默认配置就能跑起来，不需要调优。

4.5 启动ClickHouse

在 docker-compose.yml 所在目录下，执行：

docker-compose up -d

-d 表示后台运行。你会看到类似这样的输出：

Creating clickhouse-lab ... done

检查一下容器是否正常运行：

docker ps

应该能看到 clickhouse-lab 的状态是 Up。

然后试试用 HTTP 接口访问：

curl http://localhost:8123

如果返回 Ok.，说明 ClickHouse 已经活过来了。

验证小技巧：直接在浏览器打开 http://localhost:8123，看到 "Ok." 就算成功。我个人喜欢用 curl，因为后面写脚本时更方便。

4.6 连接ClickHouse并执行第一条SQL

有两种方式连接 ClickHouse：

方式一：使用 clickhouse-client（推荐）

进入容器内部：

docker exec -it clickhouse-lab clickhouse-client

你会看到这样的提示符：

clickhouse-lab :)

输入第一条SQL：

SELECT 'Hello, ClickHouse!' AS greeting;

结果：

┌─greeting──────────────┐
│ Hello, ClickHouse!    │
└───────────────────────┘

方式二：通过HTTP接口

curl -X POST 'http://localhost:8123/' --data-binary "SELECT 'Hello, ClickHouse!'"

Hello, ClickHouse!

注意：HTTP 接口默认没有认证。如果是在公网环境，一定要配置密码或限制IP。我在早期项目里吃过这个亏——忘了关公网端口，结果被人扫到，数据库被删了。从那以后，我所有实验环境都加上了 default 用户的密码。

4.7 本章知识体系

下面这张图概括了本章的核心逻辑：

4.8 常用管理命令

把下面几个命令记住，日常操作就够了：

操作	命令
启动服务	`docker-compose up -d`
停止服务	`docker-compose down`
查看日志	`docker-compose logs -f`
重启服务	`docker-compose restart`
进入容器	`docker exec -it clickhouse-lab bash`

我的习惯：每次修改配置后，先 docker-compose down 再 up -d，而不是直接 restart。因为 down 会清理网络和卷的残留状态，避免一些奇怪的问题。

4.9 常见问题排查

如果你启动时遇到问题，别慌。我列几个最常见的：

端口被占用：Error: listen tcp 0.0.0.0:8123: bind: address already in use。换个端口，比如把 8123:8123 改成 18123:8123。
权限不足：Linux 上 docker 命令需要 sudo，或者把用户加入 docker 组。
容器反复重启：用 docker logs clickhouse-lab 看日志，多半是配置文件语法错误。
数据目录权限：宿主机上的 ./data 目录如果权限不对，容器里的 clickhouse 用户写不进去。手动 chmod 777 ./data 可以临时解决。