ClickHouse Server Docker 镜像文档

一、镜像概述和主要用途

yandex/clickhouse-server 是由 Yandex 官方维护的 Docker 镜像，用于快速部署和运行 ClickHouse 列式数据库管理系统（Columnar Database Management System, CDMS）。ClickHouse 专为高性能实时数据分析设计，该镜像提供了预配置的运行环境，支持一键启动 ClickHouse 服务实例，适用于开发、测试及生产环境的数据库部署。

二、核心功能和特性

2.1 核心功能

• 列式存储引擎：按列存储数据，显著提升查询性能（尤其是聚合查询）和数据压缩率。
• 完整 SQL 支持：兼容 SQL 标准，支持复杂查询、子查询、JOIN、窗口函数等。
• 实时数据处理：数据写入后立即可查，支持毫秒级响应的实时分析场景。
• 分布式架构：原生支持数据分片和分布式查询，可横向扩展至 PB 级数据量。

2.2 关键特性

• 高性能：单服务器每秒可处理数十亿行数据查询，万亿行数据聚合查询秒级响应。
• 高压缩率：内置多种压缩算法（如 LZ4、ZSTD），数据压缩比可达 10:1 至 50:1。
• 多存储引擎：支持 MergeTree（默认）、Log、TinyLog、Memory 等多种表引擎，适配不同场景。
• 数据可靠性：支持数据副本（Replication）和自动故障转移，保障数据不丢失。
• 生态兼容性：提供 HTTP、TCP 接口，支持 JDBC/ODBC 驱动，可集成 Grafana、Superset 等工具。

三、使用场景和适用范围

3.1 典型场景

• 日志/埋点分析：存储和查询应用日志、用户行为埋点数据（如 PV/UV、转化漏斗）。
• 监控数据存储：收集服务器、网络设备监控指标（如 CPU、内存、流量），支持实时告警。
• 实时报表系统：生成业务实时报表（如订单量、销售额、库存变化）。
• 物联网（IoT）数据处理：存储传感器采集的时序数据，支持快速聚合查询。
• 广告/营销分析：分析广告投放效果、用户画像、转化率等营销数据。

3.2 适用范围

• 数据规模：中小型（GB 级）至大型（PB 级）数据集。
• 用户类型：企业级数据分析平台、开发者测试环境、SaaS 服务后端数据库。
• 部署环境：单机部署（开发/测试）、分布式集群（生产环境）。

四、使用方法和配置说明

4.1 镜像拉取

docker pull yandex/clickhouse-server:latest  # 拉取最新版
# 或指定版本（如 23.8）
docker pull yandex/clickhouse-server:23.8

4.2 基本运行（docker run）

4.2.1 最简启动（测试用）

docker run -d --name clickhouse-server \
  -p 8123:8123  # HTTP 接口端口（用于 SQL 查询） \
  -p 9000:9000  # TCP 接口端口（用于 clickhouse-client 连接） \
  yandex/clickhouse-server:latest

4.2.2 生产级启动（持久化存储+自定义配置）

docker run -d --name clickhouse-server \
  --ulimit nofile=262144:262144  # 调整文件描述符限制（ClickHouse 建议） \
  -p 8123:8123 \
  -p 9000:9000 \
  -v /path/on/host/data:/var/lib/clickhouse  # 数据持久化目录 \
  -v /path/on/host/logs:/var/log/clickhouse-server  # 日志目录 \
  -v /path/on/host/config:/etc/clickhouse-server/config.d  # 自定义配置文件目录 \
  -e CLICKHOUSE_PASSWORD=StrongPassword123  # 设置默认用户密码 \
  yandex/clickhouse-server:latest

4.3 Docker Compose 配置

创建 docker-compose.yml：

version: '3'
services:
  clickhouse-server:
    image: yandex/clickhouse-server:latest
    container_name: clickhouse-server
    restart: always  # 自动重启
    ports:
      - "8123:8123"   # HTTP 接口
      - "9000:9000"   # TCP 接口
    volumes:
      - ./data:/var/lib/clickhouse  # 数据持久化
      - ./logs:/var/log/clickhouse-server  # 日志
      - ./config:/etc/clickhouse-server/config.d  # 自定义配置
    environment:
      - CLICKHOUSE_USER=default  # 默认用户名（不可删除）
      - CLICKHOUSE_PASSWORD=StrongPassword123  # 默认用户密码
      - TZ=Asia/Shanghai  # 时区设置
    ulimits:
      nofile:
        soft: 262144
        hard: 262144

启动服务：

docker-compose up -d

4.4 核心配置参数

4.4.1 环境变量

4.4.2 端口映射

4.5 常用操作

4.5.1 连接数据库

通过 clickhouse-client（需先安装客户端，或进入容器执行）：

# 宿主机连接（需安装 clickhouse-client）
clickhouse-client --host 127.0.0.1 --port 9000 --user default --password StrongPassword123

# 或进入容器执行
docker exec -it clickhouse-server clickhouse-client --password StrongPassword123

通过 HTTP 接口（curl 或浏览器）：

curl "[***]" -d "SELECT 1"

4.5.2 查看日志

docker logs -f clickhouse-server  # 实时查看日志

4.5.3 数据持久化

通过 -v 挂载宿主机目录至容器内 /var/lib/clickhouse（数据目录）和 /var/log/clickhouse-server（日志目录），确保容器重启后数据不丢失。

4.6 自定义配置

如需修改 ClickHouse 配置（如内存限制、连接数、集群配置），可通过以下方式：

1. 宿主机创建配置文件（如 custom_config.xml），内容示例：

   <yandex>
     <max_connections>1000</max_connections>  <!-- 最大连接数 -->
     <max_memory_usage>10G</max_memory_usage>  <!-- 单查询最大内存限制 -->
   </yandex>
   

2. 启动时挂载配置文件至容器 /etc/clickhouse-server/config.d/ 目录：

   docker run -d --name clickhouse-server \
     -v /path/on/host/custom_config.xml:/etc/clickhouse-server/config.d/custom_config.xml \
     ...（其他参数）
   

配置文件将与默认配置合并生效。

五、注意事项

1. 性能优化：生产环境建议调整宿主机内核参数（如 vm.max_map_count=262144），并确保磁盘 IO 性能（推荐 SSD）。
2. 安全加固：非信任网络中需禁用无密码登录，通过 CLICKHOUSE_PASSWORD 设置强密码，并限制端口访问（如仅允许内网 IP 连接 9000 端口）。
3. 版本兼容性：不同版本镜像配置文件可能存在差异，升级前建议备份数据和配置。
4. 分布式部署：多节点集群需配置 remote_servers 参数（通过自定义配置文件），并确保节点间网络互通。