ClickHouse v20.10.5.10-stable 补丁版本深度解析:SNI 安全连接支持与 11 项关键修复

原创2026-09-09 13:19:021,838 阅读
文章标签:数据库列式数据库OLAP大数据分布式数据库实时分析数据仓库数据分析SQL

ClickHouse v20.10.5.10-stable 补丁版本深度解析:SNI 安全连接支持与 11 项关键修复

导读

本文基于仓库 docs/changelogs/archive/v20.10.5.10-stable.md 发布的官方版本说明,系统解析 ClickHouse 20.10 系列补丁版本 v20.10.5.10-stable 相对 v20.10.4.1-stable 的全部变更:包括 1 项功能改进(支持 SNI 的安全连接)与 11 项 bug 修复,覆盖聚合函数、分布式查询、S3 存储、Avro 格式、类型转换与运维工具等模块。读者通过本文可以理解每个修复的触发场景、背后的实现原理,以及在当前源码仓库中对应的代码位置,为评估升级风险与排查类似问题提供直接参考。

一、版本背景与定位

v20.10.5.10-stable 是 ClickHouse 20.10 稳定分支上的一个补丁(patch)版本,属于 bugfix 发布。这类版本的核心特征是:

  • 只合入经过验证的修复:从变更日志可以看到,几乎所有条目都带有 "Backported in #xxxxx" 标记,说明每个修复都先在主线或较新版本中被验证,再反向移植(backport)到 20.10 稳定分支;
  • 少量改进 + 大量修复:本版本仅含 1 项 Improvement,其余 11 项全部为 Bug Fix,符合补丁版本"求稳"的定位;
  • 对应修复项按模块归档:主要涉及聚合函数、查询执行、存储 IO、配置部署与工具链。

对于生产环境用户,这类补丁版本通常建议在升级窗口内跟进,特别是当线上命中下列任一场景时。

二、功能改进:支持需要 SNI 的安全端点连接

本次版本唯一的功能改进是:使 clickhouse-server 客户端能够连接到要求 SNI(Server Name Indication)的加密端点。典型场景是 clickhouse-server 部署在 TLS 代理(如 Nginx、HAProxy、云负载均衡器)之后,代理需要 TLS ClientHello 中的 SNI 字段来路由请求到正确的后端证书。

2.1 底层原理:为何 SNI 曾经失败

在 ClickHouse 的客户端连接实现 src/Client/Connection.cpp 中,建立加密连接时通常先通过 DNS 解析得到 IP,再基于 IP 建立 socket。而 TLS 握手时,SNI 字段需要的是原始主机名(host name),而不是解析后的 IP 地址——如果 ClientHello 中携带的是 IP,或者根本没有 SNI 扩展,位于前端的 TLS 代理就无法确定该为哪个虚拟主机提供服务,导致握手失败。

本次修复在源码中的关键实现位于 src/Client/Connection.cpp:

if (static_cast<bool>(secure))
{
#if USE_SSL
    /// we resolve the ip when we open SecureStreamSocket, so to make Server Name Indication (SNI)
    /// work we need to pass host name separately. It will be send into TLS Hello packet to let
    /// the server know which host we want to talk with (single IP can process requests for multiple hosts using SNI).
    static_cast<Poco::Net::SecureStreamSocket *>(socket.get())
        ->setPeerHostName(tls_sni_override.empty() ? host : tls_sni_override);
    /// we want to postpone SSL handshake until first read or write operation
    /// so any errors during negotiation would be properly processed
    static_cast<Poco::Net::SecureStreamSocket*>(socket.get())->setLazyHandshake(true);
#endif
}

核心逻辑是:IP 已被解析,因此必须把主机名单独传递给 SecureStreamSocket::setPeerHostName,让它写入 TLS Hello 包的 SNI 字段,从而使单个 IP 可以承载多个虚拟主机。

2.2 可配置的 SNI 覆盖:tls-sni-override

对于"连接地址与期望 SNI 主机名不一致"的场景(例如通过 IP 直连但代理按域名路由),代码还预留了覆盖机制。字段声明于 src/Client/Connection.h:

String tls_sni_override;             /// Override for TLS SNI field.

取值来源在 src/Client/ConnectionParameters.cpp:

tls_sni_override = config.getString("tls-sni-override", "");

即客户端配置项 tls-sni-override(默认空字符串)。当它非空时,SNI 字段优先使用该值;为空时回退到连接的主机名:

tls_sni_override.empty() ? host : tls_sni_override

同样的逻辑也出现在连接复用(adoptSocket)路径中(src/Client/Connection.cpp),保证通过 SecureStreamSocket::attach 复用已建立连接时 SNI 行为一致。

2.3 使用方式与前提

在 clickhouse-client 的命令行或配置中设置该改进相关的连接方式即可,前提条件包括:

  • 服务端与客户端都必须以 USE_SSL 编译(否则会抛出 SUPPORT_IS_DISABLED 错误,见 src/Client/Connection.cpp);
  • 若客户端通过域名直连,SNI 自动使用该域名,无需额外配置;
  • 若客户端通过 IP 连接位于 TLS 代理之后的服务端,可借助 tls-sni-override 显式指定 SNI 主机名。

三、聚合函数模块的三项修复

3.1 修复使用 if 后缀聚合函数时的远程查询失败

问题:当查询中使用了带 if 后缀的聚合函数(如 sumIf、countIf 这类语法)时,远程查询(例如通过分布式表、remote 表函数)可能失败。

背景:if 后缀聚合函数是 ClickHouse 对聚合函数叠加条件过滤的语法糖,服务端在解析与分发阶段需要对这类函数做专门处理(条件参数不能参与分布式聚合参数的序列化)。该修复保证带有 if 后缀的函数在远程执行路径上能正确传递条件表达式。

验证途径:if 后缀相关的聚合函数实现在 src/AggregateFunctions 目录的 *If.* 系列文件中,可结合 tests/queries 中的 *_if 相关用例验证。

3.2 修复 any() 无参数调用时的崩溃

问题:SELECT any() FROM t(不传任何参数调用 any)会导致服务端崩溃。

原因与修复:any 聚合函数要求至少一个参数,实现位于 src/AggregateFunctions/AggregateFunctionAny.cpp:

AggregateFunctionPtr
createAggregateFunctionAny(const std::string & name, const DataTypes & argument_types, const Array & parameters, const Settings * settings)
{
    return AggregateFunctionPtr(
        createAggregateFunctionSingleValue<AggregateFunctionAny, /* unary */ true>(name, argument_types, parameters, settings));
}

其中 /* unary */ true 表示该函数为单参数约束,注册于 src/AggregateFunctions/AggregateFunctionAny.cpp:

factory.registerFunction("any", {createAggregateFunctionAny, documentation, default_properties});
factory.registerAlias("any_value", "any", AggregateFunctionFactory::Case::Insensitive);
factory.registerAlias("first_value", "any", AggregateFunctionFactory::Case::Insensitive);

修复在参数校验路径上增加了对空参数列表的防护,使无参调用在分析阶段即报出清晰的参数错误,而非在运行期触发空指针解引用。anyLast 的注册紧随其后(同文件),同类无参问题一并覆盖。

3.3 防止使用 TimeSeriesGroupSum 时服务端崩溃

问题:timeSeriesGroupSum(时间序列分组求和)聚合函数在特定输入下可能导致服务端崩溃。

背景:时间序列聚合函数族位于 src/AggregateFunctions/TimeSeries 目录,包括 AggregateFunctionTimeSeriesGroupArray.cpp、AggregateFunctionTimeSeriesGroupArray.h、AggregateFunctionTimeSeriesTopKMasks.cpp 等实现。这类函数处理按时间戳/键分组的序列数据,内部涉及复杂的内存结构与桶(bucket)管理。修复针对非法或边界输入增加了防御性校验,避免越界访问。

四、查询执行与类型系统的修复

4.1 修复 ORDER BY 查询的 Illegal type of argument 错误

问题:部分带 ORDER BY 的查询在特定列类型组合下报错 Illegal type of argument。

场景:当排序列的类型在表达式改写(如 ORDER BY 中携带表达式、常量或 Nullable 列)后,排序键的类型推导与后续执行阶段期望不一致时触发。该修复统一了排序键的类型推导路径,保证 ORDER BY 在执行阶段拿到的类型与解析阶段一致。

4.2 修复大整数(128/256 位)从 double 强转时结果错误

问题:将 Float64(double)值转换为 Int128/Int256 等大整数类型时,部分取值会得到错误结果。

技术要点:大整数类型定义于 src/Common/wide_integer.h 与 src/Common/wide_integer_impl.h,其与浮点数的转换在宽整数实现与 src/DataTypes 的类型转换逻辑中完成。浮点转宽整数涉及舍入方向与溢出边界的处理,本次修复纠正了 double → 宽整数转换的舍入/截断语义,覆盖 128 与 256 位两类。

4.3 修复 ALTER TABLE ... MODIFY COLUMN 期间 SELECT 可能导致的崩溃

问题:执行 ALTER TABLE ... MODIFY COLUMN ... NewType 修改列类型后,若 ALTER 尚未完成(还在后台执行),此时一条带 WHERE 条件(且该条件引用了正在被修改的列)的 SELECT 可能使服务端崩溃。

机制:修改列类型属于异步的元数据变更,在变更完成前,表结构的新旧版本并存。SELECT 的 WHERE 表达式若命中正在迁移的列,可能读取到与新旧结构不匹配的数据视图。修复在查询执行与 ALTER 状态之间增加了同步/版本校验,避免结构切换窗口内的非法访问。

五、分布式与存储 IO 的修复

5.1 修复非 leader 的 ReplicatedMergeTree 表 ON CLUSTER 查询可能永久挂起

问题:对非 leader 副本的 ReplicatedMergeTree 表执行 ON CLUSTER 分布式 DDL/DML 时,查询可能无限期挂起。

机制:ReplicatedMergeTree 的复制协调(依赖 ZooKeeper/Keeper)中存在 leader 选举与请求转发逻辑,非 leader 副本收到 ON CLUSTER 指令后需要正确协商执行或等待。修复针对协商死锁场景增加了超时与正确转发处理,防止等待永远不被唤醒。相关复制存储实现位于 src/Storages 的 StorageReplicatedMergeTree* 系列文件中。

5.2 无数据写入时中止 S3 多部分上传

问题:当向 S3 写入数据(例如 S3 表引擎、s3() 表函数或 S3 磁盘)时,如果最终没有任何数据被写入(空结果集/空块流),底层的多部分上传(multipart upload)未正确中止,会在桶中残留未完成的分片对象,造成存储浪费与后续清理负担。

修复:在 src/IO/S3 的 WriteBufferFromS3 实现中,若最终写入字节数为 0,则显式调用 AbortMultipartUpload 接口(对应请求定义在 src/IO/S3/Requests.h)终止上传,而不是静默丢弃。这保证了 S3 侧不会遗留孤儿分片。

5.3 Avro Schema Registry 地址解析失败时自动重解析 IP

问题:format_avro_schema_registry_url(Avro/Confluent Schema Registry 地址)配置的域名在连接出错时不会重新解析,若该域名 DNS 记录变化(例如注册中心切换 IP),已缓存的解析结果会导致持续连接失败。

修复:在注册中心请求出错时重新解析该 URL 的 IP 地址并重试。该配置项的默认值定义于 src/Formats/FormatSettings.h,由格式工厂(src/Formats/FormatFactory.cpp)在创建 Avro 相关输入/输出格式时读取。

六、部署与工具链的修复

6.1 安装脚本始终在配置目录创建子目录

问题:安装脚本在 Docker 构建中使用自定义配置时,未确保配置文件夹中的子目录被创建,导致部分配置引用路径缺失。

修复:clickhouse-server 的安装/初始化逻辑(涉及 programs/install 与 Docker 构建脚本 docker/server)现在无条件创建配置目录下的子目录,保证自定义配置(如日志、临时目录、用户配置等子路径)开箱即用。

6.2 修复 clickhouse-git-import 的 blame 信息计算错误

问题:clickhouse-git-import 工具(源码位于 programs/git-import/git-import.cpp)用于将 Git 仓库历史导入 ClickHouse 以便分析代码演进,其中"每行最后修改者/提交(blame)"信息的计算存在错误,导致导入后的 blame 相关查询结果不准。

修复:修正了 blame 计算的遍历顺序与提交归属逻辑,使导入的数据能准确反映每行代码的最后修改提交与作者。

七、升级建议与验证思路

7.1 升级建议

v20.10.5.10-stable 是稳定分支补丁版本,建议在满足以下任一条件时优先升级:

  • 客户端需要连接位于 TLS 代理之后、依赖 SNI 路由的 clickhouse-server(新增改进直接适用);
  • 线上使用 any()/带 if 后缀聚合函数、timeSeriesGroupSum、ORDER BY 复杂排序列、宽整数(Int128/Int256)转换等能力,且出现过异常报错;
  • 使用 S3 存储(磁盘/表引擎/表函数)且关注孤儿分片残留;
  • 使用 Avro + Schema Registry,或运行 ON CLUSTER 写 ReplicatedMergeTree 分布式表。

7.2 验证思路

  • SNI 支持:在 TLS 代理(如 Nginx stream 模块)后部署服务端,客户端经域名连接并观察 TLS 握手日志中携带的 SNI;
  • any() 无参崩溃:执行 SELECT any() 确认返回参数数量错误而非崩溃;
  • S3 孤儿分片:向空结果集写入后检查桶中无未完成 multipart upload;
  • 回归用例:在 tests/queries 与 tests/integration 中检索对应功能的 SQL 测试,快速定位覆盖场景。

结语

v20.10.5.10-stable 集中体现了 ClickHouse 补丁版本的治理风格:每个修复经过主线验证后反向移植到稳定分支,且改动都聚焦于可复现的崩溃、错误结果与运维痛点。理解这些修复的触发条件与底层实现(如 src/Client/Connection.cpp 中 SNI 主机名透传、src/AggregateFunctions/AggregateFunctionAny.cpp 中参数校验),能帮助开发者在升级与排障时快速定位问题,也为阅读同类归档版本说明提供了方法论参考。

登录后查看全文
ClickHouse