HDFS FsImage 详解

FSImage 子系统核心文件：
  FSImage.java                 — 主控类，协调所有加载/保存/恢复/升级操作
  FSImageFormat.java           — LoaderDelegator + 旧版格式
  FSImageFormatProtobuf.java   — Protobuf 格式的 Loader/Saver
  FSImageFormatPBINode.java    — INode 序列化（PB 格式）
  FSImageFormatPBSnapshot.java — Snapshot 序列化（PB 格式）
  FSImageUtil.java             — 文件头/摘要/压缩包装工具
  FSImageCompression.java      — 压缩编码管理
  FSImageStorageInspector.java — 存储检查抽象
  FSImageTransactionalStorageInspector.java — 当前格式检查器
  FSImagePreTransactionalStorageInspector.java — 旧格式检查器
  FsImageValidation.java       — 镜像校验
  fsimage.proto                — Protobuf schema 定义

传输/工具相关：
  ImageServlet.java            — HTTP 镜像传输端点
  TransferFsImage.java         — 镜像下载/上传客户端
  FSImageLoader.java           — OfflineImageViewer 加载器
  FSImageHandler.java          — OIV Web 处理
  BackupImage.java             — BackupNode 镜像

FILE := MAGIC SECTION* <FileSummary> FileSummaryLength
MAGIC := 'HDFSIMG1' (8 字节)
SECTION := <NameSystemSection> | <INODE> | <INODE_DIR> | ...
FileSummaryLength := 4 字节 int（小端）

message FileSummary {
  required uint32 ondiskVersion = 1;    // 文件格式版本（当前=1）
  required uint32 layoutVersion = 2;    // NameNode layout 版本
  optional string codec         = 3;    // 压缩编码器全类名
  message Section {
    optional string name = 1;           // section 名称
    optional uint64 length = 2;         // section 长度
    optional uint64 offset = 3;         // section 起始偏移
  }
  repeated Section sections = 4;        // section 索引列表
}

message NameSystemSection {
  optional uint32 namespaceId = 1;
  optional uint64 genstampV1 = 2;       // legacy generation stamp
  optional uint64 genstampV2 = 3;       // generation stamp of latest version
  optional uint64 genstampV1Limit = 4;
  optional uint64 lastAllocatedBlockId = 5;
  optional uint64 transactionId = 6;
  optional uint64 rollingUpgradeStartTime = 7;
  optional uint64 lastAllocatedStripedBlockId = 8;
}

message INode {
  enum Type { FILE = 1; DIRECTORY = 2; SYMLINK = 3; };
  required Type type = 1;
  required uint64 id = 2;
  optional bytes name = 3;
  optional INodeFile file = 4;
  optional INodeDirectory directory = 5;
  optional INodeSymlink symlink = 6;
}

recoverTransitionRead(startOpt, target, recovery)
  │
  ├── recoverStorageDirs()
  │     遍历所有存储目录，分析状态（NON_EXISTENT / NOT_FORMATTED / NORMAL），
  │     执行恢复（doRecover），读取 VERSION 文件验证一致性
  │
  ├── processStartupOptionsForUpgrade()
  │     处理 UPGRADE / ROLLBACK / REGULAR 等启动选项
  │
  └── loadFSImage(target, startOpt, recovery)
       │
       ├── storage.readAndInspectDirs(nnfs, startOpt)
       │     使用 FSImageTransactionalStorageInspector 扫描所有存储目录，
       │     找到所有镜像文件并记录 txid
       │
       ├── initEditLog(startOpt)
       │     根据 HA 状态初始化编辑日志（write mode / read mode）
       │
       ├── editLog.selectInputStreams()
       │     选择需要回放的编辑日志流
       │
       ├── 循环 loadFSImageFile()（失败自动尝试下一个镜像副本）
       │    │
       │    ├── storage.readProperties() 读取存储属性
       │    │
       │    └── loadFSImage(curFile, expectedMd5, target, ...)
       │         │
       │         ├── FSImageFormat.newLoader(conf, fsn)
       │         │    └── LoaderDelegator.load(file)
       │         │         ├── 读取前 8 字节检测 MAGIC
       │         │         ├── MATCH → FSImageFormatProtobuf.Loader
       │         │         └── 不匹配 → FSImageFormat.Loader（旧版）
       │         │
       │         ├── loader.load(curFile, requireSameLayoutVersion)
       │         │    加载镜像数据到 FSNamesystem
       │         │
       │         ├── 验证 MD5 校验和
       │         └── storage.setMostRecentCheckpointInfo()
       │
       ├── loadEdits()（加载编辑日志回放）
       │     FSEditLogLoader 按顺序回放 EditLogInputStream 中的操作
       │
       ├── rollingRollback()（如适用）
       │
       └── needsResaveBasedOnStaleCheckpoint()
             判断 checkpoint 是否过时，返回 needToSave

saveNamespace(source, NameNodeFile, canceler)
  │
  ├── editLog.endCurrentLogSegment(true)
  │     结束当前日志段，确保一致性
  │
  ├── getCorrectLastAppliedOrWrittenTxId()
  │     获取当前 txid 作为镜像 txid
  │
  ├── addToCheckpointing(txid) 防并发
  │
  ├── saveFSImageInAllDirs(source, nnf, txid, canceler)
  │    │
  │    ├── 为每个 IMAGE 类型存储目录创建 SaveNamespaceContext
  │    │
  │    ├── 启动 N 个 FSImageSaver 线程（每个目录一个）
  │    │    │
  │    │    └── saveFSImage(context, sd, dstType)
  │    │         │
  │    │         ├── FSImageFormatProtobuf.Saver 实例化
  │    │         ├── FSImageCompression.createCompression(conf)
  │    │         ├── saver.save(newFile, compression)
  │    │         │    ├── saveInternal() → 写各 section
  │    │         │    └── 计算全文件 MD5
  │    │         ├── MD5FileUtils.saveMD5File() 写入 .md5 文件
  │    │         └── storage.setMostRecentCheckpointInfo()
  │    │
  │    ├── waitForThreads() 等待所有线程完成
  │    │
  │    ├── renameCheckpoint(IMAGE_NEW → IMAGE) 原子重命名
  │    │    fsimage_NEW_00000... → fsimage_00000...
  │    │
  │    ├── purgeOldStorage() 清理旧文件
  │    └── archivalManager.purgeCheckpoints() 清理旧 checkpoint
  │
  ├── editLog.startLogSegmentAndWriteHeaderTxn(txid+1)
  │     重新打开编辑日志
  │
  └── removeFromCheckpointing(txid)

if (exitAfterSave.get()) {
  LOG.error("NameNode process will exit now... The saved FsImage " +
      nnf + " is potentially corrupted.");
  ExitUtil.terminate(-1);
}

class Loader implements FSImageFormat.AbstractLoader {
  // 关键字段
  private final Configuration conf;
  private final FSNamesystem fsn;
  private final LoaderContext ctx;     // 包含 stringTable + refList
  private MD5Hash imgDigest;           // 加载文件的 MD5
  private long imgTxId;                // 最后 txid
  private boolean requireSameLayoutVersion; // 滚动升级回滚时要求版本一致
  private File filename;
}

load(File file)
  │
  ├── 启动 DigestThread 异步计算文件 MD5（与加载并行进行）
  │
  ├── 打开 RandomAccessFile + FileInputStream
  │
  └── loadInternal(raFile, fin)
       │
       ├── FSImageUtil.checkFileFormat(raFile)
       │     验证前 8 字节是否为 "HDFSIMG1"
       │
       ├── FSImageUtil.loadSummary(raFile)
       │     从文件末尾读取 FileSummary（4 字节 trunkSize 确定位置）
       │     验证 ondiskVersion=1、layoutVersion 支持 PROTIBUF_FORMAT
       │
       ├── 解析 FileSummary.sections
       │     按 SectionName.ordinal() 排序，分离 _SUB 子 section
       │
       ├── 判断是否启用并行加载
       │     conf.getBoolean("dfs.image.parallel.load", false)
       │
       └── 按顺序处理每个 section：
            │
            ├── NS_INFO → loadNameSystemSection()
            │   GenerationStamp、BlockId、TxId、RollingUpgrade 信息
            │
            ├── STRING_TABLE → loadStringTableSection()
            │   重建 SerialNumberManager.StringTable
            │
            ├── INODE → inodeLoader.loadINodeSection()
            │   或 loadINodeSectionInParallel() — 并行版
            │   读取 header（lastInodeId, numInodes），然后循环读取每个 INode
            │   Root INode 特殊处理，其他添加到 inodeMap
            │   异步更新 NameCache 和 BlockMap（各用单线程 ExecutorService）
            │
            ├── INODE_DIR → inodeLoader.loadINodeDirectorySection()
            │   或并行版
            │   重建父-子关系（children + refChildren）
            │   完成后等待 BlockMap 和 NameCache 更新完成
            │
            ├── INODE_REFERENCE → snapshotLoader.loadINodeReferenceSection()
            │   加载引用节点到 refList，顺序必须严格一致
            │
            ├── FILES_UNDERCONSTRUCTION → 兼容性读取
            │   Lease 信息已从 INode 文件属性中读取
            │
            ├── SNAPSHOT → 快照元数据
            ├── SNAPSHOT_DIFF → 快照差异
            ├── SECRET_MANAGER → DelegationToken
            ├── CACHE_MANAGER → 缓存指令/池
            └── ERASURE_CODING → EC 策略
       │
       └── 等待 DigestThread 结束，获取 imgDigest

class Saver {
  private final SaveNamespaceContext context;
  private final SaverContext saverContext;
  private long currentOffset = MAGIC_HEADER.length;
  private long subSectionOffset = currentOffset;
  private MD5Hash savedDigest;
  private FileChannel fileChannel;
  private OutputStream sectionOutputStream;
  private CompressionCodec codec;
}

save(File file, FSImageCompression compression)
  │
  ├── enableSubSectionsIfRequired()
  │     根据 INode 数、阈值、目标 section 数判断是否启用子 section
  │     阈值：dfs.image.parallel.inode.threshold（默认 1000000）
  │     目标 section：dfs.image.parallel.target.sections（默认 4）
  │
  └── saveInternal(fout, compression, filePath)
       │
       ├── 写入 MAGIC_HEADER ("HDFSIMG1")
       │
       ├── 构建 FileSummary.Builder
       │
       ├── 确定压缩编码器（codec）
       │
       ├── 按固定顺序写各 section：
       │
       │   1. NS_INFO
       │      写入 GenerationStamp、BlockId、TxId、NamespaceId
       │
       │   2. ERASURE_CODING（如果 layout 版本支持）
       │      写入 EC 策略列表
       │
       │   3. INODE
       │      serializeINodeSection():
       │        - 写 header（lastInodeId, numInodes）
       │        - 遍历 inodeMap，对每个 INode 调用 save()
       │        - 每 inodesPerSubSection 个 INode 提交一个 _SUB 子 section
       │      serializeINodeDirectorySection():
       │        - 遍历所有目录，序列化子节点列表
       │        - 普通 children + refChildren 引用索引
       │      serializeFilesUCSection():
       │        - 从 LeaseManager 获取正在写入的文件列表
       │
       │   4. SNAPSHOT
       │      序列化快照计数器、可快照目录、快照根节点
       │
       │   5. SNAPSHOT_DIFF
       │      序列化 DiffEntry（DirectoryDiff / FileDiff）
       │
       │   6. INODE_REFERENCE
       │      序列化 WithCount/WithName/DstReference 引用节点
       │
       │   7. SECRET_MANAGER
       │      序列化 DelegationToken 密钥和 token
       │
       │   8. CACHE_MANAGER
       │      序列化缓存指令和池
       │
       │   9. STRING_TABLE
       │      序列化字符串去重表（用户/组名映射）
       │
       ├── 刷新压缩流，写 FileSummary + 4 字节 trunk size 到文件末尾
       │
       └── 计算全文件 MD5 摘要

class Loader {
  private final FSNamesystem fsn;
  private final Map<Integer, Snapshot> snapshotMap;  // snapshotId → Snapshot
}

class LoaderDelegator implements AbstractLoader {
  public void load(File file, boolean requireSameLayoutVersion) {
    is = Files.newInputStream(file.toPath());
    // 读取前 8 字节检测 MAGIC
    IOUtils.readFully(is, magic, 0, magic.length);
    if (Arrays.equals(magic, FSImageUtil.MAGIC_HEADER)) {
      // 新格式 → Protobuf Loader
      impl = new FSImageFormatProtobuf.Loader(conf, fsn, ...);
    } else {
      // 旧格式 → FSImageFormat.Loader
      impl = new Loader(conf, fsn);
    }
  }
}

FSImage {
  layoutVersion: int, namespaceID: int, numItems: long,
  genstampV1: long, genstampV2: long,
  genstampAtBlockIdSwitch: long, lastAllocatedBlockId: long,
  transactionID: long, snapshotCounter: int, numSnapshots: int,
  numSnapshottableDirs: int,
  FSDirectoryTree | FilesUnderConstruction | SecretManagerState
}

FSImageStorageInspector（抽象）
  ├── FSImageTransactionalStorageInspector（当前格式，txid-based）
  └── FSImagePreTransactionalStorageInspector（旧格式，文件名 fsimage）

                      ┌──────────────────────────────┐
                      │       FSImage.java            │  ← 主控协调
                      │  (recoverTransitionRead /     │
                      │   saveNamespace / format /    │
                      │   doUpgrade / doRollback)     │
                      └───┬──────┬──────────┬─────────┘
                          │      │          │
               ┌──────────┘      │          └──────────┐
               ▼                 ▼                     ▼
     ┌─────────────────┐  ┌──────────────┐  ┌───────────────────┐
     │  LoaderDelegator │  │SaveNamespace │  │   FSImageSaver    │
     │ (FSImageFormat)  │  │  Context     │  │ (内部线程类)       │
     └────────┬─────────┘  └──────────────┘  └────────┬──────────┘
              │                                        │
              ▼                                        ▼
     ┌──────────────────┐                   ┌──────────────────────┐
     │ Protobuf Loader  │                   │ Protobuf Saver       │
     │ (并行加载/顺序)   │                   │ (子 section 划分)     │
     ├──────────────────┤                   ├──────────────────────┤
     │ INode Loader     │                   │ INode Saver          │
     │ Snapshot Loader  │                   │ Snapshot Saver       │
     └──────────────────┘                   └──────────────────────┘
              │                                        │
              ▼                                        ▼
     ┌──────────────────┐                   ┌──────────────────────┐
     │FSImageStorage    │                   │ FSImageCompression   │
     │Inspector         │                   │ FSImageUtil          │
     ├──────────────────┤                   ├──────────────────────┤
     │ Transactional    │                   │ fsimage.proto        │
     │ PreTransactional │                   │ (磁盘格式定义)         │
     └──────────────────┘                   └──────────────────────┘

     ┌──────────────────┐
     │   传输工具         │
     ├──────────────────┤
     │ ImageServlet     │  ← HTTP 端点 /imagetransfer
     │ TransferFsImage  │  ← 客户端 HTTP 下载/上传
     │ FSImageLoader    │  ← OIV 离线加载器
     └──────────────────┘