企业官网建设流程全解析

ClickHouse v23.7.2.25-stable 版本技术解析：磁盘函数变更、字典 IP 支持与关键 Bug 修复

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse

本文以 ClickHouse 官方发布版本 v23.7.2.25-stable 的变更日志为骨架，逐条解析该版本引入的向后不兼容变更、构建打包改进与用户可见 Bug 修复，并结合仓库源码说明其底层实现与影响范围。读完本文，你将清楚该版本中disk表函数的新语法规则、字典对 IPv4/IPv6 属性的支持方式，以及各修复项所对应的核心代码路径，便于评估升级影响与排查问题。

版本概览与定位

v23.7.2.25-stable（commit8dd1107b032）是 ClickHouse 2023 年 7 月发布周期中的一个 stable 补丁版本，基于 v23.7.1.2470-stable 修复了若干用户可见问题。从变更日志结构看，本次发布包含三类内容：

• 1 项Backward Incompatible Change（向后不兼容变更）：disk表函数参数语法调整；
• 1 项Build/Testing/Packaging Improvement（构建/测试/打包改进）：clickhouse-keeper-client符号链接加入 server 包；
• 6 项Bug Fix（用户可见行为修复），涉及 Nullable(IPv4) 运算、字典 IP 属性、c-ares 生命周期、稀疏列 tuple 崩溃、Keeper 重配置数据竞争、poll() 服务器实现等；
• 另有若干标记为 "NOT FOR CHANGELOG / INSIGNIFICANT" 的内部改动，包括设置项重命名、SYSTEM STOP LISTEN 修复、稀疏序列化协议版本提升与 Docker 改进。

以下按类别展开分析。

向后不兼容变更：disk表函数参数语法收紧

变更内容

本次发布引入的唯一向后不兼容变更（对应 PR #52820）如下：

如果动态磁盘（dynamic disk）包含名称，那么在disk函数参数中必须写作disk = disk(name = 'disk_name', ...)形式。在之前的版本中，它可以写成disk = disk_<disk_name>(...)，这种写法现已不再支持。

换句话说，旧语法disk = disk_my_disk(...)中的命名约定被废弃，所有动态磁盘的引用必须统一采用显式的name参数。这项变更收紧了语法解析规则，避免磁盘名称与函数名的隐式拼接带来的歧义。

仓库中的实现佐证

在仓库的生成器代码（TableSettings.cpp）中可以看到各类型磁盘的内联disk(...)定义均遵循结构化参数形式，例如：

• 本地磁盘：disk(type = local, path = '...')；
• 对象存储磁盘：disk(type = object_storage, object_storage_type = local_blob_storage, path = '...')；
• 加密磁盘：disk(type = encrypted, disk = '...', path = '...')；
• 缓存磁盘：disk(type = cache, disk = '...', path = '...')。

可见disk函数的参数均由type、name、disk、path等具名键组成，磁盘名称应通过name键显式传入。升级到 v23.7 及以上版本时，如果配置中仍使用disk = disk_<name>(...)旧写法，需要在升级前改写成disk = disk(name = 'name', ...)，否则相关表函数调用会解析失败。

构建/打包改进：clickhouse-keeper-client 符号链接

变更内容

本次发布在clickhouse-server安装包中新增了clickhouse-keeper-client符号链接（对应 PR #51882）。

背景说明

ClickHouse 将 keeper 相关工具与主二进制整合在同一个可执行文件中，通过不同的命令字（如keeper、keeper-client）分发功能。此前clickhouse-keeper-client命令仅存在于独立安装包中；本次打包改进让安装了clickhouse-server包的用户也能直接在命令行中调用clickhouse-keeper-client，简化了运维部署。

从仓库的程序布局看，keeper-client 目录对应独立的客户端实现，keeper-bench 提供基准测试工具，二者在构建时统一挂载到主二进制。安装 server 包后即可通过符号链接获得 keeper 客户端能力，无需额外安装。

Bug 修复逐项解析

本次发布的 6 项用户可见 Bug 修复覆盖数据运算、字典、网络库、稀疏列、Keeper 协调与 I/O 模型几个方向，逐一说明其影响。

1. 修复 Nullable(IPv4) 的二进制算术

• 对应 PR：#51642
• 影响：当 IPv4 类型的值出现在Nullable容器中并参与二进制算术（如加减、比较）时，之前存在结果错误或异常，本版本修复了该问题。

IPv4在 ClickHouse 中基于 UInt32 存储（见 IPv4andIPv6.h），其二进制算术需要正确处理空值（NULL）的传播。修复后，Nullable(IPv4)与普通数值的算术运算行为与数值类型保持一致。

2. 支持 IPv4 与 IPv6 作为字典属性

• 对应 PR：#51756
• 影响：外部字典（Dictionary）现在可以将IPv4、IPv6声明为属性类型，并支持对应的键/值容器。

仓库中的字典数据结构已确认对 IP 类型的支持：

• DictionaryStructure.h 中将IPv4、IPv6作为合法的 map_item 键类型（map_item(IPv4), map_item(IPv6)）；
• DictionaryHelpers.h 在处理字典属性时对DictionaryAttributeType为IPv4/IPv6的分支做了专门处理；
• FlatDictionary.h 与 CacheDictionaryStorage.h 的容器类型列表中均包含ContainerType<IPv4>与ContainerType<IPv6>，说明 flat、cache 等字典布局都已覆盖 IP 类型。

这意味着用户可以在字典定义中将源数据中的 IP 列声明为IPv4/IPv6属性，并在查询中直接以 IP 形式参与字典查询，避免先转换为字符串或整数。

3. 按需初始化与销毁 c-ares 通道

• 对应 PR：#52634
• 影响：c-ares（异步 DNS 解析库）的通道（channel）由原来的生命周期管理方式改为按需 init/destroy。

该改动降低了常驻服务中 DNS 相关资源的使用，并规避了通道复用带来的状态污染问题，对使用主机名作为远端地址的远程表、Keeper 等场景的稳定性有正向作用。

4. 修复tuple函数与稀疏列的崩溃

• 对应 PR：#52659
• 影响：当tuple函数的某个参数是稀疏列（sparse column）时，此前可能触发崩溃，本版本修复。

稀疏列是 ClickHouse 对大量默认值列的内存优化表示（相关序列化见 SparseSerialization 与SparseColumn实现）。从tuple相关代码看，tuple 构造需要把各列包装进ColumnTuple（见 ITupleFunction.h），稀疏列在装箱到 tuple 元素前需要先完成稠密化转换。本次修复确保单个稀疏列参数也能被正确处理，且同版本还通过"提高稀疏序列化的最小协议版本"（见下文的 PR #52835）避免旧客户端解析稀疏数据。

5. 修复 Keeper 重配置中的数据竞争

• 对应 PR：#52804
• 影响：修复 Keeper（ClickHouse 内置的 ZooKeeper 兼容协调服务）在动态重配置（reconfiguration）过程中存在的数据竞争问题。

Keeper 支持在线调整集群成员，重配置会修改内存中的服务器列表。仓库中相关状态管理位于 KeeperContext.cpp 与 KeeperServer.cpp。本次修复为成员变更路径增加了正确的同步，避免并发请求读到不一致的集群视图。运行 Keeper 且频繁做成员变更的环境，建议升级本版本。

6. 修复 clickhouse-keeper 基于 poll() 的服务端实现

• 对应 PR：#52833
• 影响：修复了clickhouse-keeper在特定平台/配置下使用poll()实现的事件循环的缺陷。

该修复主要面向使用 poll() I/O 多路复用的运行环境（如部分 BSD 系平台），确保 keeper 服务端在连接事件处理上的正确性。

内部改动（NOT FOR CHANGELOG）

除用户可见修复外，本版本还包含几项被标记为不进入变更日志的内部改进：

• 设置项重命名：disable_url_encoding重命名为enable_url_encoding并补充了测试（PR #52656）。从命名语义看，新名以"启用"为正逻辑，更符合 ClickHouse 设置项的风格；
• SYSTEM STOP LISTEN 修复：修复SYSTEM STOP LISTEN（停止监听端口）的若干缺陷并增强测试（PR #52680 目录；
• 稀疏序列化最小协议版本提升：提高稀疏列序列化的最小客户端协议版本（PR #52835），避免旧协议客户端在读取稀疏数据时出错；
• Docker 镜像改进：多项 Docker 构建与镜像优化（PR #52869 目录。

升级建议与影响评估

综合本版本变更，建议在升级前重点核查以下几点：

1. 磁盘语法：全量搜索配置与建表语句中disk = disk_开头的表达式，改写为disk = disk(name = '...', ...)形式。这是本版本唯一需要主动改动的向后不兼容项；
2. 字典定义：若希望在字典中使用 IP 类型属性，本版本已支持IPv4/IPv6，可在字典 schema 中直接声明；
3. Keeper 集群：运行 Keeper 且使用动态重配置或在线成员调整的场景，建议尽快升级以消除数据竞争风险；
4. 稀疏列：若启用了稀疏列存储（ratio_of_defaults_for_sparse_serialization相关设置），升级后注意与客户端协议版本的兼容性，避免使用过旧的客户端连接。

整体而言，v23.7.2.25-stable 是一次以稳定性和兼容性收敛为主的补丁版本：语法层面的不兼容变更仅有一处且易于迁移，其余均为行为修复与内部质量改进，升级风险可控。

【免费下载链接】ClickHouseClickHouse® is a real-time analytics database management system项目地址: https://gitcode.com/GitHub_Trending/cli/ClickHouse