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 接入:
- 集群内部接入(Vector、同集群应用)
- 入口地址:
clickhouse.test-clickhouse.svc.cluster.local(端口8123或9000)。 - 负载均衡机制:当前配置为 Headless Service(
clusterIP: None),DNS 解析会返回全部 6 个健康 Pod 的 IP,客户端驱动会自动轮询分发流量。
- 入口地址:
- 集群外部接入(外部 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 节点间互连,严禁对外暴露)。 |
四、 全链路三层鉴权机制解析
一条外部请求进入集群后,会依次经过以下三道独立的权限校验:
-
第一道:外部客户端入口鉴权(由
users.xml控制)- 校验维度:验证用户名、密码(SHA256 哈希或明文)以及客户端来源网段(` ` 需包含 `0.0.0.0/0` 以兼容纯 IPv4 环境)。
- 读写权限隔离:
- 写入/运维账号(
default):绑定writer配置档案,允许建表(DDL)与高频写入(INSERT)。 - 只读查询账号(
readuser):绑定reader配置档案,强制开启 ` 1
- 写入/运维账号(
-
第二道:跨分片内部通信鉴权(由
remote_servers.xml控制)- 触发场景:当客户端向
clickhouse-00-0写入分布式表或发起跨分片查询时,00-0需要作为客户端去连接另一个分片的节点(如clickhouse-01-0:9000)。 - 凭证来源:
00-0会读取remote_servers.xml中对应 ` ` 节点下配置的 “ 和 “ 进行认证。若未配置,节点间默认使用空密码连接,会直接触发 `Code: 516 (AUTHENTICATION_FAILED)` 报错。
- 触发场景:当客户端向
-
第三道:控制面与副本同步隔离(内网信任模型)
- Keeper 通信(
9181/9444)与副本数据拉取(9009):均运行在 Kubernetes 内部 Pod 网络平面上。只要通过 NetworkPolicy 或防火墙确保这三个端口不暴露给集群外部,即可在保证最高同步吞吐性能的同时确保通信安全。
- Keeper 通信(
🔒 原创版权声明
本文标题:ClickHouse 分布式集群架构(K8S)
版权来源:Infraservicenow
⚠️ 重要声明:本站所有文章均为原创技术文档,未经作者书面正式授权,严禁任何形式转载、复制、摘抄、二次发布。
如需转载、引用、整理发布,请务必提前联系作者获得授权,违者将依法追究侵权责任。
© 2026 Infraservicenow All Rights Reserved. 保留所有权利。