企业官网建设流程全解析

ClickHouse v21.3.5.42 LTS 补丁版本解析：Bug Fix 清单、回滚陷阱与源码佐证

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

本指南基于当前仓库docs/changelogs/archive/v21.3.5.42-lts.md中记录的 v21.3.5.42-lts 版本变更，逐条解读该补丁版本相比 v21.3.4.25-lts 修复的 23 项 Bug Fix，结合仓库源码说明每个修复背后的机制、可能的行为变化与升级注意事项，并针对少数可能引发行为差异的修复给出回退（workaround）方案。阅读后，你将能系统掌握该 LTS 补丁版本覆盖的功能面，并能在升级后快速定位与这些修复相关的潜在回归。

ClickHouse 的 LTS（Long-Term Support）分支在发布后仍会持续接收针对关键缺陷的 backport（向后移植）补丁。v21.3.5.42-lts即属于 21.3 LTS 分支上的一个补丁版本，其变更主体是相对v21.3.4.25-lts的Bug Fix集合（共 23 项），外加一条NOT FOR CHANGELOG的说明性条目。整份 changelog 不含新特性、不涉及破坏性改动，属于典型的"稳定优先"维护型发布。

从条目内容看，这批修复覆盖了分布式查询与表函数、远程连接（S3/hedged/异步 socket）、ReplicatedMergeTree 的合并与变更（mutation）、Log 系存储引擎、JOIN 与 arrayJoin、TSV 解析、全文索引、Docker 镜像入口脚本等多个模块，恰好对应 21.3 时代生产环境最容易踩到的几类问题。

分布式查询与复制表核心修复

clusterAllReplicas 的 _shard_num 错误

第一个修复针对表函数clusterAllReplicas：它曾返回错误的_shard_num列值（对应 issue #21481）。该修复被 backport 到 21.3 分支，合并自 PR #21498。

clusterAllReplicas的语义是"查询集群中每个分片的所有副本，每个副本都被当作独立的 shard/连接来使用"，因此_shard_num是区分查询结果来自哪个分片的关键虚拟列。在源码 TableFunctionRemote.cpp 中可以看到其定义与cluster表函数的关联：

is_cluster_function = (name == "cluster" || name == "clusterAllReplicas");

其调用语法（来自同一文件的文档注释）为：

clusterAllReplicas(['cluster_name', db.table, sharding_key][, SETTINGS name = value, ...]) clusterAllReplicas(['cluster_name', db, table, sharding_key][, SETTINGS name = value, ...])

源码注释 TableFunctionRemote.cpp 还给出了重要的性能提示：cluster/clusterAllReplicas表函数每次请求都会重建服务器连接，效率低于预先创建Distributed表；在大量查询场景下应优先使用Distributed表。因此，如果业务代码长期通过clusterAllReplicas聚合多分片数据并依赖_shard_num做分片归属判断，本修复会改变该列的值，升级后应对照system.clusters重新核对结果分片映射。

外部数据库引擎 JOIN 的未知列裁剪

针对 MySQL/PostgreSQL 外部数据库引擎，此前在WHERE子句中会出现"从被连接表中移除未知列"的逻辑缺陷，导致查询报错或行为异常（关联 issue #14614、#19288、#19645）。修复 PR #21640 确保在对外部引擎表做 JOIN 并下推过滤条件时，只移除确实不存在的列，不再误删合法列。这与外部数据库引擎（MySQL/PostgreSQL 引擎位于src/Storages下）的查询下推逻辑相关，升级后若发现外部表 JOIN 结果列数变化，属预期行为修正。

标量子查询索引分析

修复了标量子查询（scalar subquery）的索引分析缺陷（issue #21717，由 PR #18896 引入），合并自 PR #21766。这属于查询优化器对子查询可索引性的判断问题，修复后标量子查询可能走索引或产生不同的执行计划，对依赖EXPLAIN调优的用户，升级后建议复核相关查询计划。

ReplicatedMergeTree：等待 OPTIMIZE / ALTER 不再挂起

修复了ReplicatedMergeTree表引擎下等待OPTIMIZE与ALTER查询的问题：此前当表被 detach 或服务重启时，等待操作可能无限挂起。修复（PR #22118）保证在上述场景下查询会正常结束。对线上运维而言，这直接改善了"kill 不掉、等不到结果"的运维体验。

对已覆盖 part 执行 mutation 不再抛 LOGICAL_ERROR

此前对已经被其他 part 覆盖（covered）的 part 执行变更（mutation）时，会抛出LOGICAL_ERROR异常（issue #22013）。修复 PR #22291 后该操作被优雅处理。对于频繁执行ALTER TABLE ... UPDATE/DELETE的流水线，这是重要的稳定性改进。

CollapsingMergeTree 的 granule 行数越界

一个"罕见但致命"的修复：CollapsingMergeTree在合并时可能生成index_granularity + 1行的 granule，进而触发内部检查Incomplete granules are not allowed while blocks are granules size（该检查由 #18928 引入，影响 21.2 与 21.3），最终导致 part 无法合并。修复 PR #21976 消除了该越界情况。若你的业务大量使用折叠树做状态去重，此修复直接关系到合并链的可用性。

连接层修复：hedged requests、异步 socket 与 Linux 内核兼容

21.3 时代引入了 hedged requests（对冲请求）与异步远程 socket 机制来提升分布式查询效率，但也带来了一批内核/竞态相关问题，本版本集中修复：

这类修复对运行在新内核（如 5.x 后续小版本）上的集群尤为重要。升级后若仍遇到分布式查询挂起，可显式设置：

SET async_socket_for_remote = 0; SET use_hedged_requests = 0;

作为兜底排查手段。

内存与 I/O 边界修复

• 并行解析内存记账缺失：并行解析（parallel parsing）例程此前缺少内存统计，结果集包含超大 block 时可能 OOM（issue #22008）。修复 PR #22425 补齐了 accounting，max_memory_usage等内存限制从本版本起在并行解析路径下真正生效。
• HTTP chunk 不再被限制：移除了 HTTP 响应 chunk 大小限制（issue #21907），合并自 PR #22322，改善了大结果集通过 HTTP 接口传输时的吞吐。
• WriteBufferFromS3 错误处理与日志：改进了 S3 写入缓冲区的错误处理与日志记录（PR #21836），方便 S3 存储场景下的故障诊断。

存储引擎：Log 系与 TinyLog 的并发安全

两个修复都围绕*Log存储引擎的 rwlock（读写锁）：

1. TinyLog 同线程解锁：修复在同一线程中解锁 rwlock 的未定义行为（UB），PR #22560。
2. 跨线程解锁规避：*Log引擎因另一线程解锁导致 rwlock UB，PR #22583 做了规避。

此外，#22654 修复了SELECT子句不含列时，Log表嵌套类型触发LOGICAL_ERROR的问题。对于使用 TinyLog/Log 做轻量缓存表的场景，这组修复消除了潜在的崩溃与异常风险。

JOIN、TSV 解析与格式相关修复

• JOIN + TOTALS + arrayJoin：修复Invalid number of rows in Chunk错误（issue #19303），PR #22129。
• partial merge join 与 LowCardinality：修复部分合并 JOIN（partial merge join）与LowCardinality类型组合时的缺陷（issue #22386、#22388），PR #22510。
• TSV 空字符串反序列化：修复 TSV 格式下文件末尾无换行的空字符串反序列化问题（issue #20244），PR #22527。

⚠️ 行为变化提示：TSV 修复涉及input_format_null_as_default的语义。changelog 明确指出，若不想升级版本，可设置input_format_null_as_default = 0（旧版本默认即为此值）作为 workaround。也就是说，该修复可能使该设置在新版本中的默认行为发生变化，依赖 TSV 中空字符串/NULL语义的导入任务，升级后建议用代表性样本数据先做一次导入比对。

• 客户端过早断连 segfault：仅在写缓冲区已初始化时才尝试 flush，修复客户端极早关闭连接时的段错误（issue #22579），PR #22591。

全文索引与内存安全修复

修复了tokenbf_v1全文索引潜在的**缓冲区越界读取（buffer overflow on read）**问题：超出的字节虽不会被使用，但读取操作在罕见情况下可能导致崩溃（issue #19233），合并自 PR #22421。tokenbf_v1是 ClickHouse 内置的基于 Bloom Filter 的全文索引类型，用于STRING列的子串/分词加速查询。使用该索引的表升级后应重点观察查询稳定性。

Docker 镜像入口脚本修复

两个修复均针对官方 Docker 镜像的entrypoint脚本：

• 空 LOG_PATH 不再 chown.：当LOG_PATH为空时，避免对整个当前目录执行chown（issue #22100），PR #22102。
• 配置中无 http_port 时兼容：修复http_port不在配置中时 entrypoint 报错的问题，PR #22132。

容器化部署的用户应同步升级镜像标签至21.3.5.42，这两处修复直接关系容器启动阶段的行为。

杂项修复：线程池命名与跨库变更 backport

• 后台线程池名称：修复后台线程池名称错误，PR #22122。这影响system.processes、system.metrics等观测接口中线程名的可读性，便于排查"哪个后台任务占用资源"。
• 最后一条NOT FOR CHANGELOG / INSIGNIFICANT条目为 #21429 的手动 backport（PR #22504），属于内部整理性质，不涉及用户可见行为。

升级建议与验证清单

综合以上 23 项修复，针对运行 21.3 LTS 分支的集群给出如下升级验证清单：

1. 分布式一致性：升级后用SELECT * FROM clusterAllReplicas(...)抽查_shard_num与system.clusters的映射是否一致；
2. TSV/CSV 导入回归：重点比对含空字符串、文件末尾无换行的导入场景，必要时显式设置input_format_null_as_default；
3. ReplicatedMergeTree 运维：验证OPTIMIZE TABLE ... FINAL与ALTER TABLE ... UPDATE在 detach/重启后的等待与执行行为；
4. JOIN 查询：回归TOTALS、arrayJoin、LowCardinality与partial_merge_join组合的查询；
5. 内存限制生效性：观察大结果集并行解析场景下max_memory_usage是否按预期触发；
6. 内核兼容：若部署在较新内核上，确认不再出现分布式查询挂起；如仍有异常，临时关闭async_socket_for_remote与use_hedged_requests定位。

整体上，v21.3.5.42-lts 是一个"含金量高、行为侵入性低"的稳定补丁版本：修复面覆盖分布式查询、复制表合并、存储引擎并发、格式解析与内存安全等关键路径，且绝大多数修复保持原有默认行为不变，仅 TSV 空字符串解析一处提示了可能的默认值变化。作为 21.3 LTS 分支的用户，建议优先升级至此版本及以上，以获得更稳定的合并、变更与远程查询体验。

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