企业官网建设流程全解析

ClickHouse v25.10.3.100-stable 发布详解：Alias 引擎实验化、文件缓存改进与关键 Bug 修复

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

导读

本文基于 ClickHouse 官方变更日志 docs/changelogs/v25.10.3.100-stable.md，全面解读 v25.10.3.100-stable 版本的核心变更：Alias表引擎正式转入实验特性、文件系统缓存（filesystem cache）监控与清理策略的多项改进，以及覆盖查询分析器、数据序列化、合并任务、对象存储备份等数十项用户可见的 Bug 修复。读完本文，你将掌握该版本每类变更的适用场景、涉及的核心设置与底层实现依据，能够据此评估升级风险并快速定位相关问题的修复行为。

版本概览

v25.10.3.100-stable 是 ClickHouse 25.10 系列的一个补丁（patch）稳定版，基于 v25.10.2.65-stable 演进而来。变更日志按官方惯例分为四类：

其中所有变更均为先前开发版本的回移植（backport），因此本版本的关注重点是稳定性收敛而非新功能扩张。

Experimental Feature：Alias表引擎转入实验特性

本版本最值得注意的变更，是把Alias表引擎标记为实验特性（Experimental Feature），只有显式设置allow_experimental_alias_table_engine=1才能使用，相关实现见 PR #89712（作者 Kai Zhu）。

从源码看，Alias存储引擎是一个轻量级的"表指针"：它本身不存储任何数据，而是把读取、写入、Alter、Truncate、Optimize、分区操作、轻量级更新/删除等全部"代理"（proxy）到目标表。类定义位于 src/Storages/StorageAlias.h，核心结构如下：

• 构造函数接收table_id_（别名自身的 StorageID）以及target_database_、target_table_（被指向的目标表），见 src/Storages/StorageAlias.h；
• read()/write()/distributedWrite()分别把 SELECT、INSERT、分布式写入转发给目标表；
• storesDataOnDisk()恒返回false，明确 Alias 不落盘（src/Storages/StorageAlias.h）；
• 大量的能力探测接口（supportsReplication、getStoragePolicy、totalBytesUncompressed、lifetimeRows、lifetimeBytes、getSerializationHints、tryLockForShare、lockForShare等）都委托给目标表，使 Alias 在优化器与系统表眼中"看起来就像目标表本身"。

该引擎通过registerStorageAlias(factory)注册到存储引擎工厂，见 src/Storages/registerStorages.cpp 与 src/Storages/registerStorages.cpp。

同批次还修复了 Alias 的稳定性问题（PR #89812）：禁止别名再指向另一个别名（避免链式嵌套）、与SharedDatabaseCatalog配合时的StrictnessLevel问题，并补齐了上述若干接口。这意味着使用 Alias 引擎时需要留意：

• 必须在查询或配置中开启allow_experimental_alias_table_engine=1，否则创建会被拒绝；
• 别名不应指向另一个别名（本版本起被明确禁止）；
• 由于它不存储数据，DROP 只会删除别名本身，不会删除目标表（源码注释明确"Drop alias, not the target table"，见 src/Storages/StorageAlias.h）。

说明：该设置定义于 src/Core/Settings.cpp，在后续版本中已被标记为MAKE_OBSOLETE（废弃开关），表明 Alias 引擎在仓库后续演进中已进一步调整；本文以 v25.10.3.100-stable 变更日志描述为准。

Improvement：文件缓存与 S3 生态的多项增强

本版本的五项改进集中围绕文件系统缓存（filesystem cache）与 S3 对象存储场景，反映出该版本对"缓存正确性 + 远端 I/O 韧性"的侧重。

1.system.asynchronous_metrics中缓存指标的修复（PR #89640）

此前FilesystemCacheBytes等指标在system.asynchronous_metrics中存在计算错误。本版本修复为：

• SYSTEM查询对每个文件系统缓存只执行一次，避免重复统计；
• 指向同一路径的多个缓存，在system.filesystem_caches中提供原子化（atomic）的统一视图。

对运维人员而言，这意味着缓存指标更可信，可用于更准确地判断缓存命中率与占用量。

2.keep_free_space_remove_batch默认值调整（PR #90030）

文件缓存设置keep_free_space_remove_batch的默认值从 10 调整为 100，官方说明称"因为更优（more optimal）"。该设置控制后台线程为维持空闲空间/元素比例而执行的单次批量删除的缓存元素个数。

从源码定义看（src/Interpreters/FileCache/FileCacheSettings.cpp），该参数类型为UInt64，描述为"后台线程为维持空闲空间/元素比例而移除的缓存元素批量大小"。较大的批量意味着每次触发清理时能一次回收更多条目，从而减少后台清理任务的调度频率。当前仓库源码中的默认常量定义在 src/Interpreters/FileCache/FileCache_fwd.h（值为 250），可见该默认值在后续版本中仍被持续调优；同一常量还被用于invalidated_entries_cleanup_remove_batch（每次后台迭代在单个写锁下移除的失效优先级队列条目上限，见 src/Interpreters/FileCache/FileCacheSettings.cpp）。

3. S3Queue 清理降低 Keeper 节点上限（PR #90201）

S3Queue 清理过程中发出的 RemoveRecursive Keeper 请求现在使用更低的节点数上限，避免在队列元数据清理时对 Keeper（协调服务）造成过大的单次负载，改善大规模 S3Queue 场景下的协调稳定性。

4. S3 XML 响应解析失败自动重试（PR #90216）

当 S3 库解析 XML 响应时遇到网络错误，现在会进行重试。此前网络抖动导致的 XML 解析失败可能直接中断 S3 相关操作；重试机制提升了 S3 场景（含表引擎、备份等）对瞬时网络故障的韧性。

5. guardrails 限制告警信息增强（PR #90438）

当接近 guardrails（护栏/资源使用上限）时，告警消息现在会同时展示当前值与触发抛错的值（throw 值），让用户无需查阅日志即可判断距离上限还有多少余量，便于提前调整。

Bug Fix：按主题解析本版本的修复全景

Bug Fix 是本版本的主体，官方将其定义为"官方稳定版中用户可见的错误行为修复"。按主题归类如下。

JOIN / ARRAY JOIN 与懒列复制（enable_lazy_columns_replication）

enable_lazy_columns_replication是本版本 Bug Fix 中出现频率最高的设置，共有 4 处修复与之相关：

• 崩溃修复：JOIN 右侧使用ARRAY JOIN且开启该设置时崩溃（PR #89551）；
• 逻辑错误修复：对 Map 列执行ARRAY JOIN时可能触发逻辑错误（PR #89717，关闭 issue #89705）；
• 远端查询崩溃：IN内嵌ARRAY JOIN且开启该设置时可能崩溃（PR #89997，解决 #90361）；
• 插入报错：插入时使用ARRAY JOIN报Column with Array type is not represented by ColumnArray column: Replicated（PR #90066）。

这四类修复均指向同一个底层特性（懒列复制），强烈建议开启该设置的复制表用户优先升级。

查询分析与优化器

• query_plan_convert_join_to_in导致逻辑错误（PR #89554，解决 #89066）：修复了 JOIN 转 IN 优化在特定计划形态下的误判；
• analyzer_compatibility_join_using_top_level_identifier在多 JOIN 场景下的逻辑错误（PR #90010）；
• 聚合投影（aggregated projection）优化下部分查询异常（PR #90288）；
• 旧分析器（old analyzer）中无论optimize_injective_functions_in_group_by取值如何，都从GROUP BY移除单射函数以保证兼容性（PR #89870，解决 #89854）。

查询屏蔽（query masking）

• 修复查询屏蔽规则被错误应用到 DDL 语句的问题（PR #89272）。此前 DDL（如CREATE/DROP）可能被匹配到查询内容的正则屏蔽规则误拦截或误改写，本版本确保屏蔽规则仅作用于查询语句。

数据序列化、格式与类型推断

• 二进制反序列化（data types binary deserialization）可能的栈溢出（PR #89822，关闭 #88710）；
• 聚合状态等来源的反序列化增加大小检查（size checks），防止越界读取（PR #90031）；
• 高级 JSON 共享数据序列化中读取路径及子列时的逻辑错误（PR #89819，关闭 #89805）；
• 文本格式下部分情况下从字符串推断错误 DateTime64 值（PR #90013，解决 #89368）；
• BSONEachRow与MsgPack格式中空元组列导致的逻辑错误（PR #90018，同时关闭 #89814 与 #71536）；
• SHOW COLUMNS与SHOW FUNCTIONS的错误转义修复（PR #89942）；
• user_files目录允许以点开头的文件（PR #90079，关闭 #89662）：此前file()表函数等场景无法访问隐藏文件。

标量函数与向量检索

• base32Encode缓冲区大小计算修复：长度小于 5 的字符串列可能导致崩溃（PR #89929，解决 #89911）；
• IN函数中空元组导致逻辑错误（PR #89850，关闭 #88343）；
• reverse与CAST中空元组逻辑错误（PR #89908，关闭 #89137）；
• equals函数罕见场景逻辑错误（PR #90557，关闭 #88142）；
• concatWithSeparator使用 const 非字符串列时逻辑错误（PR #90655，关闭 #90596）；
• L2DistanceTransposed修复两个问题：precision 参数超出合法范围导致崩溃（PR #90405，关闭 #90401）；参考向量（默认Array(Float64)）与QBit列元素类型（如Float32、BFloat16）不一致时距离计算错误——函数现在会自动将参考向量强制转换为QBit的元素类型（PR #90485，解决 #89976）；
• numbers系统表大步长（step）时的逻辑错误与取模缺陷（PR #90123，关闭 #83398）。

MergeTree 合并、元数据与复制

• 合并任务被内存限制等中断时的清理竞态：此前部分创建的结果 part 可能在 merge mutate 后台执行器锁外被取消而不清理，最终触发磁盘事务回滚并从 S3 删除数据；本版本修复了该垃圾清理竞态（PR #89875）；
• 某些 skip index 在表定义中的格式化错误导致METADATA_MISMATCH，进而破坏 Replicated Database 新副本创建（PR #90251）；
• 空 LowCardinality 索引的误报错误修复（PR #89680，属 NOT FOR CHANGELOG 类）；
• 磁盘对象存储事务回滚时，将所有待删除对象合并为单个移除批次、执行单次 S3 交互（PR #89877，属 NOT FOR CHANGELOG 类）。

数据湖与外部数据源

• data lake catalog 数据库现在默认出现在SHOW DATABASES结果中（PR #89914），解决此前需要额外配置才能看到的问题；
• MongoDB 表引擎 URL 校验修复：用户名包含@字符时因编码不当导致连接失败（PR #89970）；
• Hive 分区中静态KeyValuePairExtractor的竞态问题：并发文件读取时可能造成数据损坏或崩溃，已修复（PR #90474）；
• Iceberg 设置文档中的变更历史修正（PR #89804，属 NOT FOR CHANGELOG 类）。

备份、远端查询与对象存储

• GCS 备份启用原生复制（native copy）：由于客户端克隆不正确，此前 GCS 原生复制始终失败，退化为手动读写数据的低效路径；本版本修复克隆逻辑（PR #89923）；
• 远端查询在取消过程中，连接断开后仍尝试读取远端服务器数据导致崩溃（PR #89740，解决 #89468）；
• Prewhere 在index_granularity_bytes=0且 JSON 路径不存在时的逻辑错误（PR #90375，解决 #86924）。

其他内部改进

• 回移植firstNonDefault函数（PR #88441）；
• S3Queue 元数据仅在初始副本上写入 Keeper（PR #89259）；
• JSON 逻辑错误增加更多诊断信息（PR #90286）。

Build/Testing/Packaging：依赖版本升级

本版本包含三项依赖升级，均由 Konstantin Bogdanov 提交：

依赖升级通常带来安全修复与性能改进，且均经过回移植测试，属于低风险变更。

升级建议与验证

综合上述变更，v25.10.3.100-stable 是一版典型的稳定性收敛补丁，建议以下场景优先升级：

1. 开启enable_lazy_columns_replication的复制表集群：本版本集中修复了该设置下的 4 个崩溃/逻辑错误，收益最直接；
2. 重度使用文件缓存（含远端磁盘缓存）的部署：缓存指标、清理批量与垃圾回收竞态均有改善；
3. 使用 S3Queue、S3/备份、MongoDB/Hive 等对象存储与外部数据源场景：获得重试、清理与竞态修复；
4. 向量检索用户：L2DistanceTransposed的崩溃与类型不匹配问题修复，建议更新后回归QBit列上的相似度查询。

验证手段方面，可以结合仓库内置测试体系：所有修复均来自先前的开发版本回移植，相应行为可在 tests/queries 与 tests/integration 中找到回归用例的对应场景（例如ARRAY JOIN、JSON 序列化、S3/备份、system.filesystem_caches等主题）；升级后建议重点跑一遍SELECT/INSERT冒烟测试、SHOW DATABASES输出检查，以及开启 Alias 引擎时的allow_experimental_alias_table_engine=1配置验证。

小结

v25.10.3.100-stable 通过"1 项实验特性 + 5 项改进 + 30 余项 Bug 修复"的补丁组合，重点解决了Alias表引擎的稳定性与实验化边界、文件系统缓存的正确性与清理效率，以及 JOIN/ARRAY JOIN、序列化、对象存储等高频路径上的用户可见问题。对于运行 25.10 系列的部署，本版本是值得跟进的一次稳定性更新；对于计划启用懒列复制或向量检索等新特性的用户，本版本修复的正是这些特性在实际负载中暴露出的核心缺陷。

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