📝 摘要：基于 Docker 部署 ClickHouse 25.4 单机实战：用临时容器拷出 config.xml 再改，重点配置 default_time_zone 为上海避免查询差 8 小时、开 Prometheus 指标端点、挂载 data/logs/config 三目录持久化并加 ulimit。含 Prometheus 采集与告警规则、Grafana 装 ClickHouse 数据源导入看板，10 分钟搭好部署加监控加可视化，适合本地开发与小规模 OLAP。

OLAP 界的性能怪兽 ClickHouse，用 Docker 部署其实很简单。本文带你从零开始，10 分钟搞定部署 + 监控 + 可视化。

前言

ClickHouse——一个让你体验「亿级数据秒级响应」的列式数据库。

想本地跑个 ClickHouse 玩玩？不想折腾繁琐的安装配置？Docker 一把梭，开箱即用。

本文基于 ClickHouse 25.4 官方镜像，一条龙搞定：

• 完整的部署流程（带时区配置，国内必备）
• Prometheus 监控集成 + 生产级告警规则
• Grafana 可视化看板配置

话不多说，直接开干。

---

一、部署流程

1.1 创建目录

mkdir -p /data/ck/{config,data,logs}

目录	用途
config	配置文件
data	数据持久化
logs	日志文件

1.2 获取默认配置

先启动一个临时容器，把默认配置文件 copy 出来：

# 启动临时容器
docker run -d \
  --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  -p 9009:9009 \
  -e CLICKHOUSE_USER=admin \
  -e CLICKHOUSE_PASSWORD=admin123 \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  -e TZ=Asia/Shanghai \
  clickhouse/clickhouse-server:25.4

# 复制配置文件到宿主机
docker cp clickhouse-server:/etc/clickhouse-server/config.xml /data/ck/config/config.xml

# 删除临时容器
docker rm -f clickhouse-server

为什么要这么折腾？因为 ClickHouse 的 config.xml 有上千行，手写容易出错，不如直接拿官方的改。

1.3 修改配置文件

编辑 /data/ck/config/config.xml，主要改两个地方：

1) 时区配置（重要）

找到 <timezone> 或添加以下配置：

<!-- 设置默认时区为上海，不设置的话时间会差 8 小时 -->
<default_time_zone>Asia/Shanghai</default_time_zone>

踩坑提醒：不配置时区，now() 函数返回的时间会是 UTC，查询结果和你预期的差 8 小时。问就是血泪教训。

2) Prometheus 监控端点

找到 <prometheus> 配置段，取消注释或添加：

<prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
    <status_info>true</status_info>
</prometheus>

1.4 正式启动

docker run -d \
  --name clickhouse-server \
  --ulimit nofile=262144:262144 \
  -p 8123:8123 \
  -p 9000:9000 \
  -p 9009:9009 \
  -p 9363:9363 \
  -v /data/ck/data:/var/lib/clickhouse \
  -v /data/ck/logs:/var/log/clickhouse-server \
  -v /data/ck/config/config.xml:/etc/clickhouse-server/config.xml \
  -e CLICKHOUSE_USER=admin \
  -e CLICKHOUSE_PASSWORD=admin123 \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  -e TZ=Asia/Shanghai \
  clickhouse/clickhouse-server:25.4

端口说明

端口	用途
8123	HTTP 接口，Web UI 和 HTTP 查询
9000	Native TCP 接口，客户端连接用
9009	集群间复制端口（单机可忽略）
9363	Prometheus 指标端口

1.5 验证部署

# 检查容器状态
docker ps | grep clickhouse

# 测试 HTTP 接口
curl http://localhost:8123

# 执行简单查询
curl "http://localhost:8123/?user=admin&password=admin123" -d "SELECT version()"

看到版本号输出，恭喜你，部署成功。

---

二、Prometheus 监控集成

2.1 验证指标端点

curl http://localhost:9363/metrics

应该能看到一堆 Prometheus 格式的指标，比如 ClickHouseMetrics_Query、ClickHouseProfileEvents_Query 等。

2.2 配置 Prometheus 采集

在 prometheus.yml 中添加：

scrape_configs:
  - job_name: 'clickhouse'
    static_configs:
      - targets: ['<ClickHouse-IP>:9363']
    metrics_path: '/metrics'

重启 Prometheus 后，在 Targets 页面应该能看到 clickhouse 处于 UP 状态。

2.3 配置 Prometheus 告警规则

创建 clickhouse-rules.yml，覆盖 ClickHouse 核心监控场景：

groups:
  # ==================== 服务级告警 ====================
  - name: clickhouse-service-alerts
    rules:
      # 服务不可用 - 最高优先级
      - alert: ClickHouse服务不可用
        expr: up{job="clickhouse"} == 0
        for: 1m
        labels:
          severity: critical
          group: clickhouse
        annotations:
          summary: "ClickHouse 服务不可用"
          description: "实例 {{ $labels.instance }} 已停止响应"

      # 连接数过高
      - alert: ClickHouse连接数过高
        expr: ClickHouseMetrics_TCPConnection > 100
        for: 5m
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 连接数过高"
          description: "当前 TCP 连接数: {{ $value }}，阈值: 100"

      # 并发查询过多
      - alert: ClickHouse并发查询过多
        expr: ClickHouseMetrics_Query > 50
        for: 5m
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 并发查询过多"
          description: "当前并发查询数: {{ $value }}，阈值: 50"

  # ==================== 查询级告警 ====================
  - name: clickhouse-query-alerts
    rules:
      # 慢查询增多
      - alert: ClickHouse慢查询增多
        expr: increase(ClickHouseProfileEvents_SlowRead[5m]) > 10
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 慢查询增多"
          description: "过去 5 分钟慢读取次数: {{ $value }}"

      # 插入失败
      - alert: ClickHouse插入失败
        expr: increase(ClickHouseProfileEvents_FailedInsertQuery[5m]) > 0
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 插入失败"
          description: "过去 5 分钟插入失败次数: {{ $value }}"

      # 查询失败
      - alert: ClickHouse查询失败
        expr: increase(ClickHouseProfileEvents_FailedSelectQuery[5m]) > 0
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 查询失败"
          description: "过去 5 分钟查询失败次数: {{ $value }}"

  # ==================== 资源级告警 ====================
  - name: clickhouse-resource-alerts
    rules:
      # 内存使用过高
      - alert: ClickHouse内存使用过高
        expr: ClickHouseAsyncMetrics_MemoryResident > 25 * 1024 * 1024 * 1024
        for: 5m
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 内存使用过高"
          description: "常驻内存: {{ $value | humanize }}，请关注内存压力"

      # 待合并数据块过多（影响查询性能）
      - alert: ClickHouse待合并块过多
        expr: ClickHouseMetrics_MaxPartCountForPartition > 100
        for: 10m
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 待合并数据块过多"
          description: "单分区最大 Part 数: {{ $value }}，可能影响查询性能，考虑优化写入频率"

      # 磁盘空间不足
      - alert: ClickHouse磁盘空间不足
        expr: ClickHouseAsyncMetrics_DiskAvailable_default < 10 * 1024 * 1024 * 1024
        for: 5m
        labels:
          severity: critical
          group: clickhouse
        annotations:
          summary: "ClickHouse 磁盘空间不足"
          description: "可用磁盘空间: {{ $value | humanize }}，请及时清理或扩容"

  # ==================== 集群级告警（可选，单机可删除）====================
  - name: clickhouse-cluster-alerts
    rules:
      # 副本延迟（仅集群环境有效）
      - alert: ClickHouse副本延迟
        expr: ClickHouseAsyncMetrics_ReplicasMaxAbsoluteDelay > 300
        for: 5m
        labels:
          severity: warning
          group: clickhouse
        annotations:
          summary: "ClickHouse 副本延迟过高"
          description: "副本延迟: {{ $value }} 秒，请检查网络或负载"

      # ZooKeeper 连接异常（仅使用 ZK 的集群有效）
      - alert: ClickHouse ZK连接异常
        expr: ClickHouseMetrics_ZooKeeperSession == 0
        for: 2m
        labels:
          severity: critical
          group: clickhouse
        annotations:
          summary: "ClickHouse ZooKeeper 连接断开"
          description: "ZooKeeper 会话数为 0，集群协调功能受影响"

说明：集群级告警（副本延迟、ZK 连接）仅在集群部署时生效，单机环境可删除该分组。

规则加载后，在 Prometheus 的 Alerts 页搜 click 就能看到这套 clickhouse-alerts——服务不可用、连接数 / 并发过高、慢查询、插入 / 查询失败、待合并块过多、副本延迟、ZK 会话异常一条不落，平时是绿色（INACTIVE），触发才变红：

---

三、Grafana 可视化

光有指标不够，还得有个漂亮的看板。

3.1 安装 ClickHouse 数据源插件

# 进入 Grafana 容器
docker exec -it grafana bash

# 安装插件
grafana cli plugins install vertamedia-clickhouse-datasource

# 退出并重启容器
exit
docker restart grafana

3.2 添加数据源

1. 打开 Grafana → Configuration → Data Sources
2. 点击 Add data source
3. 搜索并选择 ClickHouse
4. 配置连接信息：
   • URL: http://<ClickHouse-IP>:8123
   • User: admin
   • Password: admin123
5. 点击 Save & Test

3.3 导入仪表盘

1. 打开 Grafana → Dashboards → Import
2. 输入仪表盘 ID，点击 Load
3. 选择数据源，点击 Import

推荐仪表盘：

ID	名称	说明
882	ClickHouse 官方	基础监控，指标全面
13606	社区增强版	可视化更丰富，推荐

导入后就是这么一张 ClickHouse 性能大盘——查询耗时、内存用量、写入 / 合并速率、HTTP / TCP 连接数一屏尽收：

---

四、常见问题

Q1: 时间查询结果差 8 小时？

检查 config.xml 中是否配置了 <default_time_zone>Asia/Shanghai</default_time_zone>。

Q2: 连接被拒绝？

检查防火墙是否开放了 8123、9000 端口。Docker 部署记得加 -p 端口映射。

Q3: 数据丢失？

确保挂载了数据目录：-v /data/ck/data:/var/lib/clickhouse。不挂载的话，容器删除数据就没了。

Q4: ulimit 报错？

ClickHouse 需要大量文件句柄，启动时必须加 --ulimit nofile=262144:262144。

---

五、快速命令参考

# 进入 ClickHouse 客户端
docker exec -it clickhouse-server clickhouse-client -u admin --password admin123

# 查看数据库列表
docker exec -it clickhouse-server clickhouse-client -u admin --password admin123 -q "SHOW DATABASES"

# 查看表大小
docker exec -it clickhouse-server clickhouse-client -u admin --password admin123 -q "SELECT database, table, formatReadableSize(sum(bytes)) as size FROM system.parts GROUP BY database, table ORDER BY sum(bytes) DESC"

# 查看当前查询
docker exec -it clickhouse-server clickhouse-client -u admin --password admin123 -q "SELECT * FROM system.processes"

---

总结

Docker 部署 ClickHouse 的核心步骤：

1. 获取配置 → 临时容器 copy 出 config.xml
2. 改时区 → default_time_zone 设为 Asia/Shanghai
3. 开监控 → 配置 prometheus 端点
4. 挂目录 → 数据、日志、配置都要持久化

适用场景：本地开发、数据分析、小规模 OLAP 查询。

生产环境建议上集群，毕竟单节点扛不住大流量。但作为入门和测试，这套配置完全够用。

---

如果这篇文章对你有帮助，欢迎点赞收藏。有问题评论区见。

延伸阅读

• ClickHouse + DolphinScheduler：两个组件搞定轻量离线数仓，谁还堆 Hadoop 全家桶？ —— CK 部署好之后，接着用它搭一套轻量离线数仓。
• ClickHouse + Flink + DolphinScheduler：中小厂三件套搞定离线+实时数仓，告别 Hadoop 全家桶 —— 再加一个 Flink CDC，把离线数仓升级成离线+实时。
• ClickHouse 内存只涨不降之谜：MemoryTracking 20G 但 MemoryResident 才 2.5G，内存到底跑哪去了？ —— 部署上线后大概率会撞上的内存监控与运维难题。

---

🏷️ 标签：ClickHouse Docker Prometheus Grafana 时区配置 监控告警