企业官网建设流程全解析

ClickHouse v25.3.2.39-lts 版本变更解析：队列引擎、聚合函数与 HTTP/SSH 接口的关键修复

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

本文基于 ClickHouse 仓库中的 LTS 发布记录 docs/changelogs/v25.3.2.39-lts.md，系统梳理 v25.3.2.39-lts 相对 v25.3.1.2703-lts（对比基线 commit 为 3ec1fd3f690 对 b684e195f96）的全部修复项。读完本文，你可以明确该 LTS 补丁版本解决了哪些崩溃、信息泄露与行为不一致问题，并结合仓库源码（队列存储、聚合函数、HTTP 处理器）理解每项修复的落地位置，为生产环境的 LTS 升级决策提供依据。

1. 版本定位：LTS 分支内的回滚式补丁发布

该文档是 ClickHouse 官方 2025 年变更日志的一部分（文档元数据中标注sidebar_label: 2025），对应一条明确的 LTS 版本条目：

ClickHouse release v25.3.2.39-lts (3ec1fd3f690) as compared to v25.3.1.2703-lts (b684e195f96)

版本号遵循大版本.修订版.补丁号.构建号-lts的规则：25.3 是 2025 年第 3 个季度的 LTS 大版本线，2.39 表示在 LTS 分支上的第 2 轮补丁系列中的第 39 个构建。本次发布的所有条目均以 "Backported"（回移）形式出现，即修复先在主干完成、再通过 backport 进入 25.3 LTS 分支——这正是 LTS 分支持续提供安全与稳定性补丁、但不引入新特性的典型模式。仓库根目录的 CHANGELOG.md 则指向按年份归档的完整变更日志，与docs/changelogs/目录下的分文件记录互为镜像。

本版本共包含16 项用户可见的 Bug Fix、1 项 NO CL ENTRY（不写入变更日志的变更）和3 项 NOT FOR CHANGELOG / INSIGNIFICANT（对用户无实质影响的内部变更），以下按主题分组解读。

2. 对象存储队列引擎（S3/Azure Queue）修复

2.1 修复 StorageS3(Azure)Queue 因上下文过期导致的崩溃

PR #77720（backport 记录 #77947，作者 Kseniia Sumarokova）修复了StorageS3Queue/StorageAzureQueue因上下文（context）过期而崩溃的问题。队列类表引擎依赖 server 上下文执行文件轮询、元数据读取等操作，当查询生命周期或连接上下文被回收后仍被异步任务持有引用时，就会触发访问失效上下文的崩溃。

在仓库中，队列存储的完整实现位于 src/Storages/ObjectStorageQueue/ 目录，核心类StorageObjectStorageQueue见 StorageObjectStorageQueue.cpp 与 StorageObjectStorageQueue.h，S3/Azure 两个引擎的注册逻辑在 registerQueueStorage.cpp。若你在线上使用S3Queue/AzureQueue引擎做流式摄取且遇到过进程级崩溃，这是本次补丁中最值得关注的修复之一。

2.2 修复 system.s3_queue_settings 中 alterable 列恒为 false

PR #78187（backport #78239）修复了system.s3_queue_settings系统表的alterable列始终返回false的问题。该列用于指示某个队列表设置项是否可以通过ALTER TABLE ... MODIFY SETTING修改，恒为false会让运维工具误判所有设置都不可热改。该问题同样落在 src/Storages/ObjectStorageQueue/ 下的设置描述结构（如 ObjectStorageQueueSettings.cpp）中。

3. 凭据隐藏：RabbitMQ、Nats、Redis、AzureQueue 表引擎

PR #77755（backport #78087）让 RabbitMQ、Nats、Redis、AzureQueue 四个表引擎在展示自身定义（SHOW CREATE TABLE/toTableEngine等信息通道）时隐藏连接串中的用户名与密码。在此之前，凭据可能以明文出现在表定义输出中，任何有元数据读取权限的用户或备份/迁移工具都可能带走这些敏感信息。对于多租户或审计要求较高的部署，这是本次版本中安全收益直接的修复。

4. 聚合函数与函数行为修正

4.1 ArgMin/ArgMax 的 NaN 比较不再产生未定义行为

PR #77756（backport #78038，作者 Raúl Marín）修复了argMin/argMax在遇到 NaN 比较时的未定义行为（undefined behavior）。浮点比较 NaN 时 C++ 标准下不产生明确定义的结果，可能触发分支预测异常行为甚至 UB sanitizer 报告。该函数的实现位于 src/AggregateFunctions/AggregateFunctionsArgMinArgMax.cpp。在时序数据中 NaN 值并不罕见（传感器断流、除零），此前这类输入可能让聚合结果不可复现，升级后可消除这一隐患。

4.2 groupArray* 对 Int 类型的 0 值 max_size 直接报 BAD_ARGUMENTS

PR #78140（backport #78158）让groupArray*系列函数在max_size参数为Int 类型且值为 0时抛出BAD_ARGUMENTS错误，与既有对 UInt 类型 0 值的处理保持一致，而不是"带着 0 去执行"（等价于丢弃所有元素或行为未定义）。

仓库源码中这一校验逻辑集中在 AggregateFunctionGroupArray.cpp：参数解析处（约 L792–L840）已统一使用

throw Exception(ErrorCodes::BAD_ARGUMENTS, "Parameter for aggregate function {} should be positive number", name);

对非正数参数进行拦截，本次修复正是把 Int 0 这一缺口补齐到同一校验路径上。例如groupArray(0)(x)、groupArraySample(0)(x)这类写法现在会在解析阶段快速失败，而不是静默执行。

4.3 mapFromArrays 对 LowCardinality(Nullable) 键数组的崩溃/错误结果修复

PR #78240（backport #78312）修复了mapFromArrays在键数组为LowCardinality(Nullable(...))类型时的崩溃或错误结果。LowCardinality列的数据布局与稀疏字典（dictionary）强相关，函数若直接按键数组的裸内存处理就会读错偏移；这类修复通常体现在按键数组做convertToFullColumnIfLowCardinality之类的展开处理上。对于大量使用字典编码 + 可空键构造 Map 的 ETL 查询，这是一个正确性修复。

5. HTTP 接口：禁止空 session_id

PR #78098（backport #78116）禁止在 HTTP 接口的查询参数中指定空的session_id。空字符串此前会被当作一个合法会话标识传入，可能产生一个"匿名会话"，使session_timeout与session_check语义变得含糊。

仓库中 HTTP 侧的会话处理位于 src/Server/HTTPHandler.cpp：请求参数解析处在约 L275–L297 读取session_id（params.has("session_id")判断后取params.get("session_id")），修复后的行为即在取到空串时（session_id.empty()）直接拒绝，而不是进入session->makeSessionContext(session_id, ...)创建空标识会话。如果你用curl "http://host/?session_id="这类脚本化调用方式，升级后需注意带上真实会话 ID 或干脆省略该参数（省略与空值现在是不同的语义：省略不会创建会话）。

6. SSH 服务端（ClickHouse 内置 SSH 接口）三项修复

ClickHouse 的 client 支持以 SSH 方式连接服务端（clickhouse client --ssh），本次发布对该通道做了三处修正，均由 Azat Khuzhin 提交：

1. 禁用历史记录的模糊搜索（PR #78002，backport #78050）：SSH 服务端的嵌入式客户端原本启用历史记录 fuzzy search，但该特性依赖终端工具skim，部署环境通常没有安装，会造成功能异常。修复后在 SSH 场景直接禁用。
2. 修复二进制输出确认提示（PR #78095，backport #78105）：修复了"The requested output format {} is binary... Do you want to output it anyway? [y/N]"这个交互提示的问题——此前提示中的格式名占位符可能未被正确填充，影响对二进制输出格式的确认体验。
3. 不再尝试为 SSH 嵌入式客户端创建 history_file（PR #78112，backport #78121）：SSH 通道下的嵌入式客户端不应写历史文件，避免在服务器上产生意料之外的文件。

另有 PR #78011（backport #78048）修复了 SSH 服务端的表头高亮显示问题，归入"对用户无实质影响"一类，但会改善交互界面的可读性。

7. 元数据一致性：detached_tables 与 Database Replicated

7.1 system.detached_tables 在 RENAME DATABASE / DROP TABLE 后显示错误

PR #78126（backport #78147）修复了执行RENAME DATABASE或DROP TABLE之后system.detached_tables显示错误信息的问题。DETACH出来的分区/表在元数据中记录的是路径与库名前缀，库重命名或表删除后旧记录若不做同步清理，系统表就会出现指向已不存在对象的"僵尸"条目，误导运维判断。

7.2 Database Replicated 的表数量上限检查前置

PR #78127（backport #78199）做了两件事：

• 修正了此前 PR #77274 引入的"Replicated 数据库中表数量过多"（too many tables with Database Replicated）检查逻辑的回归；
• 把该检查提前到存储对象创建之前执行，从而避免在检查失败后已经在 ZooKeeper 中留下了无人记账的节点（unaccounted nodes）。在 RMT（DatabaseReplicatedWithSharding）或 KeeperMap 场景下，残留的 ZooKeeper 节点会污染复制协调状态，使后续建表、迁移操作出错。

这一修复对使用Replicated数据库且单库建表规模较大的集群尤为重要——检查前置意味着失败路径不再产生需要人工清理的 ZK 垃圾节点。

7.3 recoverLostReplica 在本地表已被删除时的崩溃防护

PR #78173（backport #78233）阻止了在recoverLostReplica执行过程中、本地表在 detach 之前已被删除时触发的崩溃。这是副本恢复（通常配合SYSTEM RESTART REPLICA一类运维手段）路径上的防御性修复，针对的是"恢复动作与元数据变更并发"这一边缘窗口。

7.4 NOT_FOUND_COLUMN_IN_BLOCK 错误路径的崩溃修复

PR #78854（backport #78280）修复了当NOT_FOUND_COLUMN_IN_BLOCK错误发生时可能引发的崩溃。该错误码表示查询引用了当前数据块中不存在的列（常见于投影/物化视图列与表实际数据不一致的边缘场景），此前错误抛出路径中某些资源释放不完整，升级后此类查询会稳定地以错误返回而非拖垮进程。

8. 其他值得记录的变更

文档另外列出两类"不进入变更日志"的条目，对排障仍有参考价值：

NO CL ENTRY（1 项）

• 回滚了 "Backport #72833 to 25.3: Support low cardinality decimal data types"（PR #78078）。即 25.3 LTS 分支暂时撤销了 LowCardinality 十进制数据类型的支持，说明该特性在 LTS 线上的稳定性尚未达标。如果你的工作流依赖LowCardinality(Decimal*)，注意该特性在此补丁版本中不可用。

NOT FOR CHANGELOG / INSIGNIFICANT（3 项）

• 支持CASE语句中THEN 分支使用非常量表达式（PR #77995，backport #78030，作者 Yarik Briukhovetskyi）。虽然被标记为"对用户无实质影响"，但它放宽了一个 SQL 表达式能力：CASE WHEN ... THEN <任意表达式> ELSE ... END现在可以正常工作，对需要动态返回值的条件逻辑是实际可用的小改进。
• SSH 服务端表头高亮修复（PR #78011，见第 6 节）。
• CI 侧修复：修复向 ci-logs 发送system.*_log数据时的挂起问题（PR #78266，backport #78297），属于持续集成基础设施修复，不影响生产行为。

9. 升级建议与验证方式

从这份变更单的构成看，v25.3.2.39-lts 是典型的"稳定性补丁"：核心收益集中在进程崩溃防护（队列引擎上下文、NATS 引擎、副本恢复、NOT_FOUND_COLUMN_IN_BLOCK、mapFromArrays）、信息泄露收敛（四个引擎的凭据隐藏）和元数据一致性（detached_tables、Replicated 建表检查前置）三条线。建议：

• 若生产部署停留在 v25.3.1.x LTS，升级到 25.3.2.39-lts 属于低风险、高收益的补丁升级，重点受益场景：使用 S3/Azure 队列引擎的流式摄取、使用 SSH 客户端通道、大规模Replicated数据库、以groupArray/argMin/mapFromArrays为核心的聚合查询。
• 升级前确认脚本中不存在依赖"空session_id参数创建会话"的 HTTP 调用（第 5 节），以及不依赖LowCardinality(Decimal*)（第 8 节回滚项）。
• 升级后可用下列方式快速自检修复是否生效：

-- 校验 s3_queue_settings 的 alterable 列是否如实反映可改设置 SELECT name, value, default_value, alterable FROM system.s3_queue_settings; -- 校验 groupArray 对 0 参数的快速失败（预期抛出 BAD_ARGUMENTS 而不是执行） SELECT groupArray(0)(x) FROM numbers(3); -- 校验 detached_tables 在 RENAME/DROP 后不再出现陈旧条目 SELECT * FROM system.detached_tables;

• 变更条目的原始记录见 docs/changelogs/v25.3.2.39-lts.md；同目录下的其他v25.3.x.x-lts.md文件可对照阅读 25.3 LTS 线的完整补丁演进。

10. 小结

v25.3.2.39-lts 没有引入新特性，其价值在于一次性回移了 16 项修复，覆盖队列型存储引擎的崩溃路径、多引擎凭据脱敏、聚合函数对 NaN 与 0 参数的边界处理、HTTP 空会话的语义收紧，以及副本/元数据管理的一致性。对 25.3 LTS 用户而言，这是一个应当跟进的补丁版本；而CASE非常量 THEN 的放开与 LowCardinality Decimal 支持的回滚，则分别代表了 LTS 分支"小幅能力放宽"与"特性稳定性兜底"两种典型取舍。

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