跳至正文

ClickHouse 分布式集群架构(K8S)

ClickHouse 分布式集群架构、端口协议与全链路鉴权指南

本文档基于 ClickHouse 25.8 LTS(2 分片 × 3 副本) + 独立 ClickHouse Keeper(3 节点) 架构,详细梳理外部访问入口、内部通信协议、数据流向分类及多层鉴权机制。


一、 全景架构与数据流向图

+---------------------------------------------------------------------------------------------------+

|                                      外部客户端 / 业务接入层                                        |
|                                                                                                   |
|      [ Vector 日志采集端 ]                                        [ Grafana / 运维客户端 ]          |
+----------------+-----------------------------------------------------------+----------------------+

                 |                                                           |
                 | ① 写入业务数据 (JSON/原生块)                                | ② 查询请求 & 聚合结果
                 |    端口: 8123 (HTTP)                                      |    端口: 8123 (HTTP) / 9000 (TCP)
                 |    鉴权: users.xml (default 写账号)                        |    鉴权: users.xml (readuser 只读账号)
                 v                                                           v
+---------------------------------------------------------------------------------------------------+

|                              Kubernetes Service 统一入口 (负载均衡)                                 |
|                     clickhouse.test-clickhouse (Headless / ClusterIP / NodePort)                  |
+----------------+-----------------------------------------------------------+----------------------+

                 |                                                           |
                 +-----------------------------+-----------------------------+
                                               |
                                               v
+---------------------------------------------------------------------------------------------------+

|                                   ClickHouse Server 计算与存储层                                    |
|                                                                                                   |
|  +---------------------------------------------+   +-------------------------------------------+  |
|  |              Shard 00 (分片 1)              |   |             Shard 01 (分片 2)             |  |
|  |                                             |   |                                           |  |
|  |  +---------------------------------------+  |   |  +-------------------------------------+  |  |
|  |  |           clickhouse-00-0             |  |   |  |           clickhouse-01-0           |  |  |
|  |  +---+-------------------------------+---+  |   |  +--+------------------------------+--+  |  |
|  |      |                               |      |   |     |                              |     |  |
|  |      | ④ 集群同步数据:                |      |   |     | ④ 集群同步数据:             |     |  |
|  |      |    数据块 Parts 副本拉取        |      |   |     |    数据块 Parts 副本拉取     |     |  |
|  |      |    端口: 9009 (Interserver)   |      |   |     |    端口: 9009 (Interserver)|     |  |
|  |      |    鉴权: 默认免密 (内网直连)    |      |   |     |    鉴权: 默认免密 (内网直连) |     |  |
|  |      v                               v      |   |     v                              v     |  |
|  |  +---------------+       +---------------+  |   |  +--------------+      +--------------+  |  |
|  |  |clickhouse-00-1| <---> |clickhouse-00-2|  |   |  |clickhouse-01-1| <--> |clickhouse-01-2|  |  |
|  |  +---------------+       +---------------+  |   |  +--------------+      +--------------+  |  |
|  +----------------------+----------------------+   +---------------------+---------------------+  |
|                         ^                                                ^                        |
|                         |           ③ 跨分片内部业务数据转发/聚合          |                        |
|                         |              端口: 9000 (Native TCP)           |                        |
|                         +---- 鉴权: remote_servers.xml 节点间账密 ---------+                        |
+-------------------------+------------------------------------------------+------------------------+

                          |                                                |
                          | ⑤ 集群协调与元数据同步 (DDL队列 / 选主状态 / Parts位置)
                          |    端口: 9181 (ZooKeeper TCP 协议)
                          |    鉴权: K8s 命名空间内网网络隔离信任 (默认无密码 ACL)
                          v                                                v
+---------------------------------------------------------------------------------------------------+

|                                 ClickHouse Keeper 独立协调控制层                                    |
|                                                                                                   |
|      +-----------------------+   ⑥ 集群内部同步数据:   +-----------------------+                    |
|      |  clickhouse-keeper-0  | <---------------------> |  clickhouse-keeper-1  |                    |
|      |       (Leader)        |   Raft 选主与日志复制   |      (Follower)       |                    |
|      +-----------+-----------+   端口: 9444 (NuRaft)   +-----------+-----------+                    |
|                  ^               鉴权: 内网端口隔离                 ^                                |
|                  |                                                 |                                |
|                  +-------------------> +-----------------------+ <-+                                |
|                                        |  clickhouse-keeper-2  |                                    |
|                                        |      (Follower)       |                                    |
|                                        +-----------------------+                                    |
+---------------------------------------------------------------------------------------------------+

二、 外部访问入口设计

外部系统严禁直连单个 Pod IP(防止节点重启引发连接中断),统一通过 Kubernetes Service 接入:

  1. 集群内部接入(Vector、同集群应用)
    • 入口地址:clickhouse.test-clickhouse.svc.cluster.local(端口 8123 或 9000)。
    • 负载均衡机制:当前配置为 Headless Service(clusterIP: None),DNS 解析会返回全部 6 个健康 Pod 的 IP,客户端驱动会自动轮询分发流量。
  2. 集群外部接入(外部 Grafana、本地开发机)
    • 入口方式:需额外创建一个 NodePort 或 LoadBalancer 类型的 Service 指向 app: clickhouse 标签,将 8123(HTTP)和 9000(TCP)暴露给外部网络。

三、 核心端口、协议与数据分类矩阵

端口 所属组件 通信协议 数据分类 传输内容与流向 鉴权机制
8123 ClickHouse Server HTTP / HTTPS 外部业务数据 外部 ➔ Server。Vector 批量写入日志、Grafana 查询图表、JDBC 连接。 users.xml 校验账号、密码及来源 IP 网段。
9000 ClickHouse Server Native TCP 外部业务数据
跨分片内部数据
1. 外部 clickhouse-client 连接。
2. 分片间分布式表(Distributed)数据转发与查询聚合。
1. 外部走 users.xml。
2. 节点间走 remote_servers.xml 配置的账密。
9009 ClickHouse Server Interserver HTTP/TCP 集群同步数据 同分片内 Server ➔ Server。副本之间后台拉取合并后的数据块(Parts)。 默认免密(依靠内网隔离,也可在配置中开启副本间独立密码)。
9181 ClickHouse Keeper ZooKeeper TCP 集群协调元数据 Server ➔ Keeper。同步分布式建表队列(DDL)、表结构变更、副本选主状态。 内网隔离信任(默认未开启 ZK ACL 密码认证,严禁对外暴露)。
9444 ClickHouse Keeper NuRaft 内部协议 集群同步数据 Keeper ➔ Keeper。3 个 Keeper 节点之间的 Raft 心跳、选主投票与状态日志复制。 内网隔离信任(仅限 Keeper 节点间互连,严禁对外暴露)。

四、 全链路三层鉴权机制解析

一条外部请求进入集群后,会依次经过以下三道独立的权限校验:

  1. 第一道:外部客户端入口鉴权(由 users.xml 控制)

    • 校验维度:验证用户名、密码(SHA256 哈希或明文)以及客户端来源网段(` ` 需包含 `0.0.0.0/0` 以兼容纯 IPv4 环境)。
    • 读写权限隔离:
      • 写入/运维账号(default):绑定 writer 配置档案,允许建表(DDL)与高频写入(INSERT)。
      • 只读查询账号(readuser):绑定 reader 配置档案,强制开启 ` 1
  2. 第二道:跨分片内部通信鉴权(由 remote_servers.xml 控制)

    • 触发场景:当客户端向 clickhouse-00-0 写入分布式表或发起跨分片查询时,00-0 需要作为客户端去连接另一个分片的节点(如 clickhouse-01-0:9000)。
    • 凭证来源:00-0 会读取 remote_servers.xml 中对应 ` ` 节点下配置的 “ 和 “ 进行认证。若未配置,节点间默认使用空密码连接,会直接触发 `Code: 516 (AUTHENTICATION_FAILED)` 报错。
  3. 第三道:控制面与副本同步隔离(内网信任模型)

    • Keeper 通信(9181 / 9444)与副本数据拉取(9009):均运行在 Kubernetes 内部 Pod 网络平面上。只要通过 NetworkPolicy 或防火墙确保这三个端口不暴露给集群外部,即可在保证最高同步吞吐性能的同时确保通信安全。

🔒 原创版权声明

本文标题:ClickHouse 分布式集群架构(K8S)

原文链接:https://www.infraserviceonline.com/clickhouse-%e5%88%86%e5%b8%83%e5%bc%8f%e9%9b%86%e7%be%a4%e6%9e%b6%e6%9e%84k8s/

版权来源:Infraservicenow

⚠️ 重要声明:本站所有文章均为原创技术文档,未经作者书面正式授权,严禁任何形式转载、复制、摘抄、二次发布。

如需转载、引用、整理发布,请务必提前联系作者获得授权,违者将依法追究侵权责任。

© 2026 Infraservicenow All Rights Reserved. 保留所有权利。


发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

错误: Content is protected !!