ClickHouse v21.12.4.1-stable 补丁版本解读:S3 磁盘、LowCardinality、ORC 与 Avro 的四个关键修复
ClickHouse v21.12.4.1-stable 补丁版本解读:S3 磁盘、LowCardinality、ORC 与 Avro 的四个关键修复
导读
本文以仓库中归档的发布说明文档 v21.12.4.1-stable.md 为核心骨架,深入拆解 ClickHouse® 21.12 系列在 v21.12.3.32-stable 之后发布的补丁版本所包含的 1 项改进与 3 项 Bug 修复。这些修复分别涉及 S3 对象存储磁盘的目录恢复、Native 格式下 LowCardinality 数据的反序列化空指针、ORC 文件 stripe 读取以及 Avro 文件二次写入崩溃。读完本文,你将掌握 ClickHouse 补丁版本(stable 分支)的发布与 backport 机制、这些修复背后的源码级原因,以及如何在当前仓库中定位对应的实现与测试代码。
一、补丁版本概览:v21.12.4.1-stable 的定位
ClickHouse 的版本号遵循 主.次.补丁.修订-发布通道 的结构。v21.12.4.1-stable 表示 2021 年 12 月功能版本线(21.12)上的第 4 个补丁包、第 1 次修订,发布通道为 stable(官方稳定版)。该文档标题明确写出它“compared to v21.12.3.32-stable”,即它是在上一个稳定补丁包基础上累积的增量更新,这是 ClickHouse 小版本迭代的标准形态:每次只针对上个稳定版本累积修复,不做新功能引入,最大限度降低升级风险。
从文档结构(v21.12.4.1-stable.md)可以看到 changelog 的标准分类法:
Improvement(改进):非缺陷性的健壮性增强;Bug Fix(缺陷修复):一般问题;Bug Fix (user-visible misbehaviour in official stable release)(官方稳定版中的用户可见异常):这类修复会优先被 backport 到 stable 分支,因为其影响面直接暴露给生产用户。
本次发布恰好覆盖了上述全部三类,是理解 ClickHouse 发布治理的典型样本。仓库中所有版本的 changelog 都归档在 docs/changelogs/archive 目录下,每个文件对应一个具体版本,可以横向对比不同补丁包的内容密度与分类规则。
1.1 文档中的 backport 标注如何阅读
文档中每个条目都带有 Backported in #XXXXX 的前缀说明。例如 S3 改进条目标注为“Backported in #33792”,其原始合入 PR 为 #33730。这是 ClickHouse 的常规协作流程:
- 修复首先合入
master(主开发分支); - CI 系统判断该修复属于“用户可见的稳定版问题”后,将其 cherry-pick(backport)到当前维护的 stable 发布分支;
- 发布工程师将若干个 backport 汇总为一个新的补丁版本,并生成如上格式的 changelog。
因此,Backported in 指向的是跟踪该 backport 的 issue,而条目末尾的 #PR 号 才是原始合入主分支的提交。这种标注方式让用户可以同时追踪修复的来龙去脉。
二、改进项:DiskS3::restoreFileOperations 自动创建父目录
2.1 修复内容
文档记录的改进如下:
Backported in #33792:在
DiskS3::restoreFileOperations方法中创建父目录(Create parent directories in DiskS3::restoreFileOperations method)。PR #33730,作者 ianton-ru。
2.2 为什么要修:S3 磁盘的目录模型
ClickHouse 的 DiskS3 是把 S3 对象存储(含 MinIO、GCS 等兼容实现)作为表数据磁盘的一种存储后端。S3 本质上是扁平的对象命名空间(bucket/key),并没有真实目录;但 ClickHouse 内部沿用了本地文件系统的路径心智模型——每个 part(数据分片)在 S3 上的对象 key 形如 data/default/table/part_uuid/ 下的多个文件,并通过“目录标记”对象(directory marker)来表示路径存在。
restoreFileOperations 负责在从 S3 恢复磁盘状态(例如重启、detach/attach 表、迁移数据后重建本地元数据)时重建目录结构。在修复之前,如果父目录对象尚不存在,恢复流程可能直接失败或产生不一致的路径状态;修复后该方法会在执行恢复前先创建父目录,保证恢复操作的幂等性与健壮性。这属于典型的“非缺陷但提升可靠性”的改进项。
2.3 在当前仓库中的对应实现
虽然在当前代码版本中,该方法已经演进并可能被拆分到多个文件,但 S3 磁盘的核心逻辑仍然保留在 src/Disks/DiskObjectStorage/ 目录下,其中与 S3 对象存储操作紧密相关的工具实现在 DiskS3Utils.cpp 及其头文件 DiskS3Utils.h 中,磁盘抽象层则由 DiskObjectStorage 类承载。从源码结构看,restoreFileOperations 这类“恢复磁盘操作”方法的职责,是让基于 S3 的对象存储磁盘在挂载后能够按需重建路径元数据,其行为与修复中“先建目录再恢复”的思路一脉相承。
对使用者而言,这一改进意味着:使用 S3 后端(disk(s3) 配置)的部署在经历重启、表 detach/attach 或跨环境恢复后,出现“目录不存在”类问题的概率显著下降。涉及 S3 磁盘的完整配置示例可以在仓库的 tests/config 与 programs/server 目录中查到相关样例。
三、Bug Fix:Native 格式下 LowCardinality 反序列化的空指针解引用
3.1 修复内容
Backported in #33551:修复在 Native 格式反序列化 LowCardinality 数据时发生的空指针解引用(null pointer dereference)。PR #33021,作者 Harry Lee。
3.2 问题本质:字典与索引的读取时序
LowCardinality 是 ClickHouse 的核心压缩优化类型:它把一列中的重复值抽取为字典(dictionary,去重后的值集合),实际数据列只存储字典索引。在 Native 二进制格式中,序列化 LowCardinality 列时通常需要两段信息:
- 字典数据本身;
- 每行指向字典条目的索引。
在数据损坏、列裁剪(projection)导致字典段缺失,或某些边界场景下字典序列化为空时,反序列化代码可能拿到空字典指针就立即进行解引用,从而触发段错误(segfault)级别的崩溃。本次修复正是在 deserializeBinaryBulk 路径上补上了对字典状态的安全校验。
3.3 源码定位与验证
在当前仓库中,Native 格式的读取与写入实现分别在 NativeReader.cpp 与 NativeWriter.cpp。其中读取侧在 NativeReader.cpp 通过 serialization.deserializeBinaryBulkStatePrefix 初始化反序列化状态,随后调用 deserializeBinaryBulkWithMultipleStreams 按流读取数据;而 LowCardinality 类型的序列化器定义在 DataTypeLowCardinality.h 对应的 SerializationLowCardinality 中,字典读取与索引读取正是分别在独立的流中完成的——这与空指针风险点的成因完全吻合。
值得注意的细节是,NativeReader.cpp 中还存在 recursiveLowCardinalityTypeConversion 这类对 LowCardinality 类型做递归转换的逻辑,说明 Native 读取链路对 LowCardinality 的处理需要同时兼顾类型对齐与数据安全,这也解释了为何此类边界修复会被归类为影响稳定的 Bug Fix。
该修复的落点提示:如果你曾遇到“从 Native 格式(或
clickhouse-local/INSERT ... FORMAT Native)读取 LowCardinality 列时进程崩溃”的问题,升级到 v21.12.4.1-stable 及之后的版本即可解决。
四、Bug Fix:ORC stripe 读取修复
4.1 修复内容
Backported in #33537:修复 ORC stripe 读取(Fix ORC stripe reading)。PR #32929,作者 Ernest Zaslavsky。
4.2 ORC 文件模型与 stripe 读取链路
ORC(Optimized Row Columnar)是 Hive 生态常用的列式存储格式,文件由多个 stripe 组成,每个 stripe 是独立的读取单元,包含自己的索引、数据和字典。ClickHouse 通过 ORC 表函数与 ORC 输入格式读取该类文件。
stripe 读取的正确性依赖两部分信息:
- stripe 的物理布局(文件偏移、长度),用于定位数据;
- stripe 的列编码信息(是否为 dictionary 编码),用于决定如何解析列数据。
在 NativeORCBlockInputFormat.cpp 中可以看到,读取器在解析每个 stripe 时会获取 orc::StripeInformation,并基于 isDictionaryEncoded(stripe_info, orc_type)(见 NativeORCBlockInputFormat.cpp)判断当前 stripe 的物理编码,进而决定是否把字典编码列转化为 LowCardinality。这里有一个关键设计点:分支的选择必须依赖 stripe 的物理编码而不是 schema 声明,因为同一张表的多个 stripe 可能采用不同的编码方式——这也是代码注释强调“branch identity must not depend on the stripe's physical encoding”的原因。
4.3 修复的意义
v21.12.4.1-stable 之前的版本中,stripe 读取在特定编码组合(尤其是字典编码列)下可能出现错位、读错偏移甚至崩溃。本次修复后,读取器能够按 stripe 实际编码正确推进,对包含多个 stripe、混合编码的大 ORC 文件读取更为稳健。写入侧的实现可参考 ORCBlockOutputFormat.cpp。如果你正在用 SELECT ... FROM orc('...') 或 INSERT INTO ... SELECT ... FROM file('*.orc') 处理大规模 ORC 数据,这一补丁直接关系到数据完整性。
五、Bug Fix:Avro 文件二次插入时的段错误
5.1 修复内容
Backported in #33654:修复对同一文件执行第二次 insert 后出现的 Avro 段错误(Fix segfault in Avro that appears after the second insert into file)。PR #33566,作者 Kruglov Pavel。
5.2 问题成因与修复方向
Avro 是一种带 schema 的二进制行式序列化格式,ClickHouse 通过 AvroRowInputFormat(读取,实现在 AvroRowInputFormat.cpp)与 AvroRowOutputFormat(写出,实现在 AvroRowOutputFormat.cpp)支持。触发场景非常具体:同一个文件句柄/数据源执行第二次 insert(追加写入)时崩溃。
从 Avro 的写入模型看,Avro OCF(Object Container File)由 header(含 schema)与一个或多个 data block 组成,写文件的过程涉及解码器/编码器(avro::Encoder/Decoder)、块缓冲与文件状态的重复利用。若在第二次写入时内部状态(如块指针、已写入 block 计数、schema 上下文)未被正确重置,就会出现对已释放或未初始化对象的访问——这正是“第二次 insert 才崩溃”的典型特征。修复 PR #33566 正是清理了该路径上的状态复用问题。
从源码结构看,AvroRowInputFormat.cpp 中大量使用 createDeserializeFn 构建按字段类型的反序列化函数(如对字典类型、嵌套 record 的处理),并依赖 avro::DataFile.hh(见 AvroRowInputFormat.cpp)管理文件级读取状态,任何文件流复用场景下的状态残留都可能触发该缺陷。
5.3 实操启示
该修复提醒我们两条实战经验:
- 对同一个 Avro 文件执行连续两次
INSERT ... FORMAT Avro(或依赖文件可追加语义的写入)时,务必升级到 v21.12.4.1-stable 及以上,否则可能遭遇进程级崩溃; - Avro/ORC 等外部格式的写入通常依赖底层文件的状态机,不推荐在生产环境中对同一文件做追加式多次写入,更稳妥的做法是每次写入新文件或使用唯一文件名,从源头规避状态复用类缺陷。
六、如何验证与跟进此类补丁修复
6.1 在当前仓库中核对修复
若你想在当前代码库中复核这些修复的最终形态,可以按以下路径展开:
| 修复主题 | 核心实现文件(仓库相对路径) | 关注点 |
|---|---|---|
| S3 磁盘目录恢复 | src/Disks/DiskObjectStorage/ObjectStorages/S3/DiskS3Utils.cpp | 目录创建与恢复操作的幂等性 |
| LowCardinality 反序列化 | src/Formats/NativeReader.cpp、src/DataTypes/DataTypeLowCardinality.h | deserializeBinaryBulk* 链路的空指针防护 |
| ORC stripe 读取 | src/Processors/Formats/Impl/NativeORCBlockInputFormat.cpp | stripe 偏移与编码判断逻辑 |
| Avro 二次写入崩溃 | src/Processors/Formats/Impl/AvroRowInputFormat.cpp、src/Processors/Formats/Impl/AvroRowOutputFormat.cpp | 文件级状态的复用与重置 |
格式注册的汇总入口在 src/Formats/registerFormats.cpp,可以看到 ORC、Avro、Native 等格式在编译期的统一注册方式。
6.2 版本选择建议
- 若你正运行在 21.12 功能版本线(
v21.12.x.y-stable),建议升级到 v21.12.4.1-stable 或更高补丁,一次性获得上述 4 项修复; - 若你使用更新的大版本(22.x+),这些修复均已随主分支合入并被后续版本自然继承,无需单独关注;
- 升级前应通过官方
clickhouse-client的SELECT version()确认当前版本号,并在测试环境先行验证(尤其是 S3 磁盘与外部格式读写的业务)。
结语
一个补丁版本往往只包含少量修复,但每一条修复都浓缩了生产环境中真实踩到的坑。v21.12.4.1-stable 的 1 项改进与 3 项修复分别覆盖了对象存储磁盘可靠性、核心压缩类型反序列化的安全边界、列式外部格式(ORC)的读取正确性,以及行式外部格式(Avro)的状态管理——它们共同印证了 ClickHouse 在稳定分支上的维护哲学:不追求新特性,只确保每一次升级都比上一个版本更稳。理解 changelog 的分类与 backport 标注方式,能帮助你在排障和升级决策中更精准地定位问题与版本对应关系。