Apache Iceberg 数据湖表生产维护完整指南
Apache Iceberg 为对象存储或分布式文件系统上的数据提供表、快照、Schema 演进、分区演进和并发提交能力。它解决了“目录里堆放 Parquet 文件”难以事务化管理的问题，但也会带来快照、Manifest、小文件、孤儿文件、Catalog 和多引擎兼容性治理。生产数据湖如果只负责写入而不做维护，查询性能和存储成本会持续恶化。
一、表元数据结构
Iceberg 表由数据文件、删除文件、Manifest、Manifest List、Metadata JSON 和快照引用组成。Catalog 负责定位当前表元数据，查询引擎根据快照读取对应文件。
Catalog → 当前 Metadata JSON
│
Snapshot
│
Manifest List
│
Manifests
│
Data Files / Delete Files
快照让时间旅行和回滚成为可能，但每次提交都会增加元数据。文件还存在于对象存储不代表它仍属于当前快照；相反，随意删除“看起来很旧”的文件可能破坏仍被历史快照引用的数据。
二、Catalog 选择与高可用
常见 Catalog 包括 REST、Hive、Glue、JDBC、Nessie 等。选择时考虑：
- 多引擎兼容；
- 认证授权；
- 高可用与备份；
- 锁与并发提交；
- 多租户和命名空间；
- 分支与标签；
- 灾难恢复；
- 跨地域访问延迟。
Catalog 是控制面，不应成为单点。备份不仅包括 Catalog 数据库，还要保存对象存储路径、凭据、Warehouse 配置、表属性和引擎版本。恢复后必须验证 Metadata 指针与对象存储一致。
三、对象存储与文件系统
生产环境应使用稳定的对象存储或分布式文件系统，启用版本控制、加密、访问日志和生命周期策略。生命周期规则不能独立于 Iceberg 快照维护直接删除数据文件。
对象存储账号使用最小权限，按 Warehouse 或环境隔离 Bucket/Prefix。Spark、Flink、Trino 等引擎的凭据和 Endpoint 必须统一，避免同一对象以不同路径表达造成重复或不可达。
需要监控请求失败、延迟、限流、跨区域流量、删除错误和费用。大量小文件会同时增加对象存储请求成本。
四、Schema 演进
Iceberg 通过字段 ID 跟踪列，而不只依赖名称和位置。支持添加、删除、重命名、重排和部分类型提升，但业务兼容性仍需治理。
安全流程：
- 建立 Schema 变更评审；
- 核对所有写入和读取引擎兼容性；
- 先发布能够兼容新旧字段的消费者；
- 再修改表 Schema；
- 灰度写入并对账；
- 观察失败和 NULL 比例；
- 最后清理旧字段。
列重命名不会自动修复所有 SQL、BI、数据质量规则和下游导出。Schema 技术兼容不等于业务兼容。
五、分区演进与隐藏分区
Iceberg 支持按年、月、日、小时、Bucket、Truncate 等转换定义隐藏分区，查询无需直接拼接分区目录。分区演进允许新数据使用新规则，旧数据继续保留旧布局。
选择分区时分析查询过滤、写入速率、文件大小和基数。过细分区产生大量小分区和元数据；过粗分区则扫描过多数据。
变更分区后要验证：
- 新旧快照查询一致；
- 过滤能正确裁剪；
- 写入引擎使用最新规范；
- Compaction 能处理多种分区布局；
- 数据质量和生命周期任务识别新规则。
六、小文件与 Compaction
流式写入、低并发分区和频繁提交容易产生小文件。小文件会增加 Manifest、对象存储请求、规划时间和打开文件开销。
治理方法：
- 调整写入批次、并行度和目标文件大小；
- 定期执行数据文件重写；
- 按分区和时间窗口控制维护范围；
- 避免多个 Compaction 任务处理同一分区；
- 维护后验证文件数、平均大小和查询性能；
- 保留足够资源和对象存储带宽。
Compaction 是一次新的事务提交，不会立即物理删除旧文件。旧文件要等快照过期后才能安全清理。
七、快照过期
每次写入生成快照。快照支持审计、时间旅行和回滚，但无限保留会增加元数据和存储。
过期策略应考虑：
- 法规和审计保留；
- 业务回滚窗口；
- 流式作业和长查询；
- 分支与标签引用；
- 灾备复制延迟；
- 备份周期。
永远不要用“删除 N 天前对象”的存储生命周期替代 expire_snapshots。先通过表级维护确认文件不再被任何有效快照引用。
八、孤儿文件清理
作业在提交前失败、网络中断或手工上传可能留下未被表元数据引用的文件。remove_orphan_files 可以识别并删除孤儿，但这是高风险操作。
安全原则：
- 设置足够长的保留时间；
- 避开仍在运行的长作业；
- 确认所有引擎时钟一致；
- 先输出候选列表并抽查；
- 确认路径规范一致；
- 在低峰执行并记录删除清单；
- 对关键表先做对象存储版本保护。
路径重写、跨 Bucket 迁移和不同 URI 表达可能导致正常文件被误判，必须在测试表演练。
九、Manifest 与删除文件维护
大量小 Manifest 会增加查询规划开销，可以定期重写 Manifest。Merge-on-Read 表还可能积累 Position Delete 或 Equality Delete 文件，需要按引擎与格式版本执行删除文件重写和数据文件合并。
维护顺序通常是：
重写数据/删除文件 → 重写 Manifest → 过期快照 → 清理孤儿文件
实际顺序要结合引擎实现和并发写入验证。不要同时对全部大表执行维护，避免计算和对象存储流量峰值。
十、分支、标签与发布
Branch/Tag 可用于隔离写入、审计快照、数据验证和 WAP（Write-Audit-Publish）。写入先进入审核分支，经过质量检查后再发布到主分支，能降低错误数据直接可见的风险。
分支也会延长文件引用，快照清理必须识别所有引用。为每个分支定义负责人、用途、保留期和清理流程，禁止长期无人管理的临时分支。
十一、多引擎兼容
Spark、Flink、Trino、Doris 等对 Iceberg 格式版本、Catalog、删除文件、分支和维护过程的支持程度可能不同。建立兼容矩阵：
| 项目 | 需要记录 |
|---|---|
| 引擎 | 名称与版本 |
| Iceberg 库 | 连接器版本 |
| 表格式 | Format v1/v2 等 |
| Catalog | 类型和协议 |
| 能力 | 读、写、Merge、Delete、Branch |
| 限制 | 已知缺陷和回退方式 |
升级一个写入引擎前，必须确认其他读取引擎仍能读取新提交的元数据和删除文件。
十二、并发写入与提交冲突
Iceberg 使用乐观并发控制。多个作业修改同一表时可能发生提交冲突。合理冲突可以重试，但不能无限重试掩盖分区设计或调度问题。
治理建议：
- 不同作业写不同分区；
- 维护任务与业务写入错峰；
- 重试使用退避和上限；
- 记录冲突表、分区和作业；
- 合并过于频繁的小提交；
- 不让多个调度器重复启动同一维护任务。
十三、监控与数据质量
监控维度：提交成功率与延迟、快照数、Metadata/Manifest 数、文件数、平均文件大小、删除文件、分区数、对象存储错误、Catalog 延迟、维护任务时长和失败。
数据质量：行数、唯一键、NULL 比例、分区完整性、源目标对账、Schema 漂移、时间范围和业务汇总。
查询性能基线应记录规划时间、扫描文件数、扫描字节、分区裁剪、P95/P99 和对象存储请求数。
十四、备份与灾难恢复
Iceberg 的快照不是独立备份。误操作、Catalog 损坏、账号泄露或对象存储故障可能同时影响所有快照。
保护对象包括：
- Catalog 数据库或服务状态；
- Warehouse 对象；
- 对象版本与跨区域复制；
- 表属性和权限；
- 引擎与连接器版本；
- 维护作业代码和调度；
- 关键快照与 Tag 清单。
恢复时先恢复对象，再恢复 Catalog 指针，使用兼容引擎验证快照链、Schema、分区、行数和查询。不要在未验证的恢复副本上运行清理任务。
十五、常见故障排查
查询突然变慢
检查小文件、Manifest、删除文件、分区裁剪、对象存储、Catalog 延迟和近期 Schema/分区演进。
提交持续冲突
定位同时修改的作业和分区，检查维护任务是否与写入重叠，减少提交频率并设置有限重试。
存储增长快
检查快照保留、分支和标签、Compaction 后旧文件、孤儿文件以及对象存储版本。不要直接删除目录。
不同引擎结果不一致
核对快照 ID、Catalog、格式版本、缓存、删除文件支持和时间旅行参数。
误删后恢复
立即停止维护与写入，使用对象版本、备份和仍有效的 Metadata 恢复，避免新的提交覆盖证据。
十六、生产检查清单
- [ ] Catalog 具备高可用与备份；
- [ ] 对象存储启用加密、审计和版本保护；
- [ ] 生命周期规则不直接删除活跃表文件；
- [ ] Schema 和分区变更有兼容评审；
- [ ] 小文件与 Manifest 有定期维护；
- [ ] 快照保留符合回滚和合规需求；
- [ ] 孤儿清理先预览并设置安全窗口；
- [ ] 分支与标签有负责人和保留期；
- [ ] 多引擎兼容矩阵保持更新；
- [ ] 提交冲突与维护任务可观测；
- [ ] Catalog 与对象数据完成恢复演练；
- [ ] 所有清理操作都有审计清单。
参考资料
- Apache Iceberg 官方文档：https://iceberg.apache.org/docs/latest/
- Iceberg 维护指南：https://iceberg.apache.org/docs/latest/maintenance/
- Iceberg 可靠性：https://iceberg.apache.org/docs/latest/reliability/
- Iceberg 表演进：https://iceberg.apache.org/docs/latest/evolution/