企业官网建设流程全解析

ClickHouse v25.1.6.34-stable 发行说明：Join 预分配、S3 备份与权限检查等修复的源码级解读

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

本文基于 ClickHouse 官方变更记录 v25.1.6.34-stable 撰写，完整梳理该 25.1 分支稳定版相对 v25.1.5.31-stable 的全部 13 项变更，覆盖 Performance Improvement、Improvement、Bug Fix 与内部变更（NOT FOR CHANGELOG）四个类别，并结合当前仓库源码对每项变更涉及的关键实现（如ConcurrentHashJoin的预分配逻辑、Join 内存限制设置、异步读取缓冲区等）给出可验证的落点，帮助运维与开发者准确评估该补丁版本的价值与升级理由。

版本概览

• 发布版本：v25.1.6.34-stable，构建号004003dccf8
• 对比基线：v25.1.5.31-stable，构建号48f17e8a805
• 变更性质：这是一次针对 25.1 维护分支的回归移植（backport）发布。变更日志中每条记录均标注 “Backported in #XXXXX”，表示这些修改最初合入主干（master），随后被移植回 25.1 分支以修复已在正式发布中发现的问题。对于锁定在 25.1 大版本线上的生产集群，这类 stable 补丁版是升级的主要依据。
• 变更规模：2 项性能改进 + 2 项功能改进 + 7 项 Bug 修复 + 4 项不面向用户的内部变更。

一、Performance Improvement：Join 路径的两项性能修复

1. 修复优化器交换 Join 顺序后ConcurrentHashJoin的双重预分配

变更条目：Backported in #76700，Pull #75149，作者 Nikita Taranov（nickitat）。

当优化器根据统计信息交换了 Join 两侧（把原本作为 build 侧的表换到另一侧）时，ConcurrentHashJoin曾发生双重预分配，即同一份哈希表空间被重复预留，导致内存占用与分配开销翻倍。

从源码结构看，当前仓库中 src/Interpreters/ConcurrentHashJoin.cpp 完整保留了这一机制的现行实现：预分配大小来源于 build 侧统计信息提示（build_stats_collecting_params的 size hint），注释明确说明“Hash map is shared between allHashJoininstances, so themedian_sizeis actually the total size we need to preallocate in all buckets of all hash maps”。每个HashJoin实例在 build 阶段“拥有”桶的一个子集，因此只对各自负责的桶做预分配。此外源码中还有space_was_preallocated布尔标志（src/Interpreters/ConcurrentHashJoin.cpp），确保同一实例不会重复执行reserveSpaceInHashMaps——这正是本条修复防止“双重预分配”的结构性保障：

if (!hash_join->space_was_preallocated && hash_join->data->twoLevelMapIsUsed()) { reserveSpaceInHashMaps(*hash_join->data, i, stats_collecting_params.build, slots, external_join_threshold); hash_join->space_was_preallocated = true; }

源码还展示了预分配与外溢（spilling）阈值的联动：当外层包裹SpillingHashJoin时，预分配量会被压缩到external_join_threshold / (8 * cell_size)的预算内，以避免在触发溢出检查之前就占满内存上限。对于使用join_algorithm = parallel_hash（ConcurrentHashJoin的触发条件）且 Join 两侧规模差异明显、优化器经常交换 build 侧的大表 Join 场景，升级到该版本可避免无谓的内存尖峰与分配延迟。

2. 修复max_rows_in_join = max_bytes_in_join = 0时parallel_hash的不必要争用

变更条目：Backported in #76696，Pull #75155，作者 Nikita Taranov（nickitat）。

当用户显式把 Join 内存限制都设为 0（表示不限制）时，parallel_hash算法内部却仍会产生不必要的锁争用（contention），影响并发 build 吞吐。该修复消除了限制值为 0 场景下的多余同步路径。

对应的配置项可在 src/Core/Settings.cpp 中确认：max_rows_in_join默认值即为0，含义是限制 Join 右侧数据结构（通常为哈希表）的行数，应用于SELECT ... JOIN与 Join 表引擎。该设置的说明还指出，只有hash、parallel_hash和ie_join三种join_algorithm值会尊重这些限制，其他算法（partial_merge、grace_hash、auto等）通过落盘、重分区或切换策略的方式处理超限。因此该修复直接惠及使用默认配置（限制为 0）且依赖parallel_hash并发的查询负载。

二、Improvement：外部表函数与 S3 备份可用性改进

1.postgresql/mysql表函数支持带路径的后端地址

变更条目：Backported in #76437，Pull #75944，作者 Nikita Mikhaylov（nikitamikhaylov）。

此前在 v25.1 线上，postgresql()/mysql()表函数无法解析形如localhost:1234/handle这样携带路径段的 endpoint 写法，这是一个由上游 Pull #52503 引入的回归。修复后，表函数地址解析会剥除或正确处理路径部分，使得经过带路由路径的代理或中间件连接 PostgreSQL / MySQL 时不再报错。典型使用方式示例：

SELECT * FROM postgresql('127.0.0.1:5432/handle', 'mydb', 'table_name', 'user', 'password');

2. S3 备份在 Access Denied 时改用正确的 multipart copy 回退路径

变更条目：Backported in #76609，Pull #76515，作者 Antonio Andelic（antonio2368）。

跨桶（尤其是两侧桶使用不同凭证）做BACKUP/RESTORE时，S3 的 multipart copy 可能返回 Access Denied。本修复让 ClickHouse 在该错误出现时改用正确的回退（fallback）拷贝方式，而不是让整个备份任务失败。对于在多个 S3 账号/桶之间迁移备份数据的场景，这是直接的可用性修复。

三、Bug Fix：用户可见行为修复（7 项）

1. 修复forwarded_for字段中 IPv4 映射 IPv6 地址解析异常

变更条目：Backported in #76142，Pull #75133，作者 Yakov Olkhovskiy（yakov-olkhovskiy）。

::ffff:1.1.1.1这类 IPv4-mapped IPv6 地址出现在X-Forwarded-For头中时会被错误解释，最终导致客户端连接以异常方式断开。修复后 HTTP 接入层可正确解析该形态的地址，修复了经由反向代理接入时的偶发断连问题。

2.NumRowsCache统计total_number_of_rows时不再误用key_condition

变更条目：Backported in #76395，Pull #75164，作者 Daniil Ivanik（divanik）。

在查询system表中total_number_of_rows指标所依赖的行数缓存（NumRowsCache）逻辑里，新增了对key_condition参数的校验：统计全表行数时不应携带 key 条件，否则会返回错误的行数。该修复保证行数缓存路径下统计口径的正确性。

3.materialized_views_ignore_errors对 URL 引擎目标生效

变更条目：Backported in #76529，Pull #75679，作者 Christoph Wurm（cwurm）。

当物化视图的写入目标是URL 引擎（例如把结果推送到远端 HTTP 端点）且远端出现连通性问题时，此前materialized_views_ignore_errors = 1不会生效，异常会向上传播并可能阻塞数据流。本修复让该设置在这一路径上被正确尊重：开启后网络类错误会被忽略，物化视图主写入流程继续运行。

4. 修复部分UNION ALL查询的Block structure mismatch in QueryPipeline stream错误

变更条目：Backported in #76540，Pull #75715，作者 Nikolai Kochetov（KochetovNicolai）。

部分含UNION ALL的查询会抛出Block structure mismatch in QueryPipeline stream异常，根源在于查询管线（QueryPipeline）各流之间的 Block 结构不一致。修复后此类查询可正常执行，属于典型的查询执行层结构对齐问题。

5. 修复ALTER RENAME错误要求CREATE USER权限

变更条目：Backported in #76475（关闭 #74372），Pull #76241，作者 pufit。

权限检查逻辑存在缺陷：执行ALTER RENAME时系统错误地要求操作者拥有CREATE USER授权。这是一个访问控制（Access Control）层的误判，修复后权限语义回归正确，只有真正需要管理用户体系的语句才要求相应授权。

6. 修复WHERE含pointInPolygon时的索引分析逻辑错误

变更条目：Backported in #76403，Pull #76360，作者 Anton Popov（CurtizJ）。

当WHERE条件中包含pointInPolygon函数时，索引分析（index analysis）会产生逻辑错误。修复确保该空间谓词场景下索引条件推断的正确性，避免误判或错误的索引过滤行为。

7. 从信号处理程序中移除内存分配

变更条目：Backported in #76484，Pull #76446，作者 Nikita Taranov（nickitat）。

信号处理函数（signal handler）中原本存在堆内存分配操作。在 POSIX 环境下，信号处理上下文中调用malloc等非 async-signal-safe 函数是未定义行为的经典来源，尤其在 OOM、栈溢出等异常场景下可能加重崩溃或导致死锁。本修复移除了该分配，提升了异常路径下的健壮性。

四、NOT FOR CHANGELOG：不面向用户的内部变更（4 项）

这一类别的变更不影响用户可见行为，但反映了 25.1 分支上 I/O 层与测试基础设施的持续打磨，同样以 backport 形式进入本版本：

1. Backported in #76508，Pull #76322：为ReadBufferFromEncryptedFile增加prefetch方法。该文件在当前仓库位于 src/IO/ReadBufferFromEncryptedFile.h，prefetch接口使加密文件读取缓冲区支持预取，与未加密读取路径的预取能力对齐。
2. Backported in #76465，Pull #76429：修复AsynchronousBoundedReadBuffer的setReadUntilPosition实现。该缓冲区定义于 src/Disks/IO/AsynchronousBoundedReadBuffer.h，是异步批量读取与有界缓冲的核心组件，setReadUntilPosition用于限定“只读到某个位置”的读取边界。
3. Backported in #76577，Pull #76561：在 Azure Blob 存储环境运行02435_rollback_cancelled_queries测试时跳过该测试，属于 CI 环境适配。
4. Backported in #76602，Pull #76575：查询system.distributed_ddl_queue时改用MultiRead方式读取，优化该系统表的读取路径。

五、升级评估建议

综合来看，v25.1.6.34-stable 的变更集中在三类风险面上：

• Join 执行路径：两条性能改进直接作用于parallel_hash/ConcurrentHashJoin，对大表 Join 的内存行为与并发吞吐有正面影响（参见 src/Interpreters/ConcurrentHashJoin.cpp）；
• 接入层与执行层健壮性：forwarded_forIPv4-mapped 地址解析、信号处理程序去分配化、UNION ALL管线结构对齐等，均属于“偶发但影响面大”的修复；
• 外围可用性：URL 引擎物化视图容错、S3 跨桶备份回退、外部表函数 endpoint 解析回归修复。

对于生产环境仍运行在 v25.1.5.x 且满足以下任一条件的集群，建议升级到本版本：大量使用parallel_hashJoin、经由反向代理接入 HTTP 服务、物化视图写入 URL 引擎、或在多 S3 桶之间做备份迁移。变更全文见 docs/changelogs/archive/v25.1.6.34-stable.md。

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