01-Windows+DockerDesktop部署ClickHouse

概述

一个"新手但很重要的 ClickHouse 心法"

ClickHouse不是 "约束驱动型数据库"， 而是 "写入 + 合并 + 查询驱动型数据库"。

Windows+DockerDesktop快速部署使用（测试）

容器编排

首先，依据以下的 docker-compose.yml 文件来启动用于测试的ClickHouse容器。

yaml 复制代码

version: "3.9"
# docker-compose 文件版本
# 3.9 是目前较新的版本，兼容 Docker Desktop + WSL2

services:
  clickhouse:
    # image: clickhouse/clickhouse-server:23.3.11.5
    # image: clickhouse/clickhouse-server:24.8
    image: clickhouse/clickhouse-server:23.8 # 此版本目前较为稳定
    container_name: clickhouse-test
    restart: unless-stopped
    ports:
      - "8123:8123"   # HTTP API 端口（REST、浏览器、BI 工具）
      - "9000:9000"   # Native TCP 端口（clickhouse-client / JDBC）
    # ulimit 设置（非常重要）
    # ClickHouse 会同时打开大量文件（每个 part / 每个 column）
    # 如果不调大，数据量稍大就会报：Too many open files
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      # 用户文件存放目录，
      # CH建议用户交互的文件（如导入）存放在此目录，因此测试截断将此目录与宿主机进行映射，便于操作
      - ./vl-clickhouse/user_files:/var/lib/clickhouse/user_files

      # ClickHouse 的核心数据目录
      # 表数据、分区、part、列文件都在这里
      # 后续迁移到 WSL2 / Linux 时，这个目录结构是完全一致的
      # 因为Docker-Desktop的文件系统机制，会导致权限问题非常复杂，因此此目录在测试截断不做映射
      # - ./vl-clickhouse/data:/var/lib/clickhouse

      # ClickHouse server 的运行日志
      # 包括：启动日志、查询异常、Merge 异常等
      - ./vl-clickhouse/logs:/var/log/clickhouse-server

      # 配置目录
      # config.d：服务级配置（内存、线程、merge、日志级别等）
      - ./vl-clickhouse/config/config.d:/etc/clickhouse-server/config.d 
      # users.d ：用户、权限、配额、profile 配置
      - ./vl-clickhouse/config/users.d:/etc/clickhouse-server/users.d
    environment:
      # 初始化参数，容器首次启动时生效（仅第一次）
      # 默认创建的数据库
      CLICKHOUSE_DB: test
      # 默认用户（非 default）
      CLICKHOUSE_USER: test
      # 用户密码
      CLICKHOUSE_PASSWORD: test123
      # 启用访问控制（用户 / 权限 / 角色），如果不开启，用户管理功能会受限
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
    healthcheck:
      # 容器健康检查
      # Docker 会周期性执行该命令
      # 返回 0 表示健康，非 0 表示异常
      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
      interval: 10s   # 每 10 秒检查一次
      timeout: 3s     # 单次检查超时时间
      retries: 3      # 连续失败 3 次标记为 unhealthy

执行docker-compose up -d启动。

使用DBeaver连接失败

上面其实有一个坑，当我们启动完容器后使用数据库管理工具如Dbeaver连接本地部署的ClickHouse时，会提示如下错误：

yaml 复制代码

Unexpected end of file from server, server ClickHouseNode [uri=http://127.0.0.1:8123/test, options={use_server_time_zone=false,use_time_zone=false}]@1266016401
  Unexpected end of file from server
  Unexpected end of file from server

其原因是ClickHouse没有配置哪些IP可以连接**，**或者说是其监听哪些主机。

调整ClickHouse的主机监听设置

与PostgreSQL类似，ClickHouse也需要通过其配置文件来定义允许连接到数据库的主机列表。该配置信息位于/etc/clickhouse-server/config.xml文件中。为了便于对配置进行修改和研究，建议将此配置文件从运行中的容器复制到宿主机上。为此，在启动容器之后，请执行以下命令：

bash 复制代码

# 拷贝config.xml
docker cp clickhouse-test:/etc/clickhouse-server/config.xml vl-clickhouse/config

# 拷贝users.xml
docker cp clickhouse-test:/etc/clickhouse-server/users.xml vl-clickhouse/config

然后docker-compose down停止容器，将这两个配置进行挂载映射：

yaml 复制代码

volumes:
  # ...
  - ./vl-clickhouse/config/config.xml:/etc/clickhouse-server/config.xml
  - ./vl-clickhouse/config/users.xml:/etc/clickhouse-server/users.xml

修改./vl-clickhouse/config/config.yml，将listen_host主机监听地址改为0.0.0.0（按需修改）：

然后docker-compose up -d重新启动容器，回到Dbeaver测试连接：

完整的容器编排配置

yaml 复制代码

version: "3.9"
# docker-compose 文件版本
# 3.9 是目前较新的版本，兼容 Docker Desktop + WSL2

services:
  clickhouse:
    # image: clickhouse/clickhouse-server:23.3.11.5
    # image: clickhouse/clickhouse-server:24.8
    image: clickhouse/clickhouse-server:23.8 # 此版本目前较为稳定
    container_name: clickhouse-test
    restart: unless-stopped
    ports:
      - "8123:8123"   # HTTP API 端口（REST、浏览器、BI 工具）
      - "9000:9000"   # Native TCP 端口（clickhouse-client / JDBC）
    # ulimit 设置（非常重要）
    # ClickHouse 会同时打开大量文件（每个 part / 每个 column）
    # 如果不调大，数据量稍大就会报：Too many open files
    ulimits:
      nofile:
        soft: 262144
        hard: 262144
    volumes:
      # 用户文件存放目录，
      # CH建议用户交互的文件（如导入）存放在此目录，因此测试截断将此目录与宿主机进行映射，便于操作
      - ./vl-clickhouse/user_files:/var/lib/clickhouse/user_files

      # ClickHouse 的核心数据目录
      # 表数据、分区、part、列文件都在这里
      # 后续迁移到 WSL2 / Linux 时，这个目录结构是完全一致的
      # 因为Docker-Desktop的文件系统机制，会导致权限问题非常复杂，因此此目录在测试截断不做映射
      # - ./vl-clickhouse/data:/var/lib/clickhouse

      # ClickHouse server 的运行日志
      # 包括：启动日志、查询异常、Merge 异常等
      - ./vl-clickhouse/logs:/var/log/clickhouse-server

      # 配置目录
      # config.d：服务级配置（内存、线程、merge、日志级别等）
      - ./vl-clickhouse/config/config.d:/etc/clickhouse-server/config.d 
      # users.d ：用户、权限、配额、profile 配置
      - ./vl-clickhouse/config/users.d:/etc/clickhouse-server/users.d
      # 先拷贝由映射的两个配置文件
      # docker cp clickhouse-test:/etc/clickhouse-server/config.xml vl-clickhouse/config
      # docker cp clickhouse-test:/etc/clickhouse-server/users.xml vl-clickhouse/config
      - ./vl-clickhouse/config/config.xml:/etc/clickhouse-server/config.xml
      - ./vl-clickhouse/config/users.xml:/etc/clickhouse-server/users.xml
    environment:
      # 初始化参数，容器首次启动时生效（仅第一次）
      # 默认创建的数据库
      CLICKHOUSE_DB: test
      # 默认用户（非 default）
      CLICKHOUSE_USER: test
      # 用户密码
      CLICKHOUSE_PASSWORD: test123
      # 启用访问控制（用户 / 权限 / 角色），如果不开启，用户管理功能会受限
      CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
    healthcheck:
      # 容器健康检查
      # Docker 会周期性执行该命令
      # 返回 0 表示健康，非 0 表示异常
      test: ["CMD", "clickhouse-client", "--query", "SELECT 1"]
      interval: 10s   # 每 10 秒检查一次
      timeout: 3s     # 单次检查超时时间
      retries: 3      # 连续失败 3 次标记为 unhealthy