这篇文章是系列的入口。我会先讲为什么要造这个项目、它和 HDFS 的关系，然后给出整体架构，最后完整走一遍"写入一个文件"的端到端链路，让读者对后续每篇文章的位置有一个全局认知。

为什么要自己实现一个分布式文件系统

学习分布式系统最有效的方式是亲手实现一遍。阅读论文能理解设计意图，但只有真正写出能跑的代码，才会遇到论文中一笔带过的工程问题——事务边界怎么划、并发控制在哪一层做、心跳超时设多长才合理。

HDFS 的源码是 Java 实现，经过十余年演进，代码量庞大（核心模块超过 30 万行），HA、Federation、Erasure Coding 等高级特性与核心逻辑交织在一起，阅读门槛极高。MiniDFS 的目标是一个最小可运行闭环：保留 HDFS 的核心架构决策，砍掉所有非本质复杂度，把精力集中在真正重要的设计问题上。

MiniDFS vs HDFS：保留了什么，砍掉了什么

MiniDFS 的设计哲学是「保留骨架，简化实现」。下面从两个维度做对比。

保留的核心设计：

单 NameNode + 多 DataNode 的 Master/Worker 架构；Block 分块存储 + Pipeline 链式复制；Rack-aware 副本放置策略；Lease 机制实现写互斥；Heartbeat + BlockReport 的注册与上报机制；Block 与 Replica 的双层状态机管理（kAllocating → kCommitted → kDeleted 和 kWriting → kFinalized → kCorrupt → kDeleted）。

砍掉的特性：

HA（Secondary NameNode / JournalNode / ZKFC）、Federation（多 Namespace）、Snapshot / Quota / ACL、Append / Truncate、Erasure Coding、Short-circuit Local Read、HDFS Balancer / Mover。这些特性各自重要，但它们本质上是在核心架构之上的增量演进，不影响对基本原理的理解。

这篇文章深入讲解这个设计选择的 tradeoff，以及在 MySQL 之上构建的三层关键机制：连接池 RAII 封装、事务绑定、ID 原子分配。

HDFS 的 EditLog + FsImage：为什么复杂

HDFS 的元数据持久化遵循经典的 WAL（Write-Ahead Log）思路。每次元数据变更——创建文件、追加 block、修改权限——都以一条 EditLog record 追加写入磁盘。FsImage 则是某一时刻的全量 namespace 快照。NameNode 启动时加载最近的 FsImage，然后顺序重放此后的所有 EditLog 条目，恢复到最新状态。

这个方案的工程复杂度主要体现在三处。第一是 Checkpoint 过程：SecondaryNameNode（或 HA 架构下的 StandbyNameNode）需要定期将 EditLog 合并进 FsImage 以避免重放时间无限增长，大集群的 FsImage 动辄数十 GB，合并本身就是一个不可忽视的 I/O 密集操作。第二是 HA 方案引入的 JournalNode 集群：Active NameNode 将 EditLog 写入多数派 JournalNode，Standby 从 JournalNode 拉取并重放，保持 namespace 同步——这套机制引入了 Paxos 式的多数派确认、fencing、epoch 管理等分布式一致性的全套复杂度。第三是 EditLog 自身的格式管理：segment 滚动、序列化版本升级、损坏恢复工具。

这篇文章深入 NamespaceManager 和 LeaseManager 的实现，重点讲路径解析的逐级查找、mkdir -p 的事务化实现、递归删除的级联问题，以及 Lease 从分配到过期的完整生命周期。

Inode 数据模型

MiniDFS 的目录树由 inode 节点构成。每个 inode 代表一个文件或目录，定义在 types.h 中：

enum class InodeType : uint8_t {
    kDirectory = 1,
    kFile = 2,
};

enum class FileState : uint8_t {
    kNormal = 0,
    kUnderConstruction = 1,
    kDeleted = 2,
};

struct Inode {
    uint64_t inode_id = 0;
    InodeType type = InodeType::kDirectory;
    uint64_t parent_id = 0;
    std::string name;

    std::string owner;
    std::string group;
    uint32_t permission = kDefaultPermission;

    uint64_t length = 0;
    uint32_t replication = kDefaultReplication;
    uint64_t block_size = kDefaultBlockSize;

    FileState state = FileState::kNormal;

    uint64_t ctime_ms = 0;
    uint64_t mtime_ms = 0;
    uint64_t version = 0;
};

几个关键设计决策值得展开。首先是 parent_id + name 的组合定位方式。每个 inode 不存储完整路径（如 /data/logs/app.log），而是只存储自己的 name（app.log）加上父目录的 inode_id。这个设计使得 rename 操作只需修改一行记录的 parent_id 和 name 字段，而存储完整路径的方案需要更新这个节点及其所有后代的路径——在深层目录树中这是 O(n) 的代价。子目录查询也很自然：WHERE parent_id = ? 即可列出某目录下的所有直接子节点。

这篇文章从一次 put() 调用开始，逐步拆解 Block 分配、目标节点选择、Pipeline 建立与数据传输、两层 CRC32C 校验，以及 chunk 级别的幂等重试设计。

写入请求的完整链路

一次 DfsClient::put(dfs_path, local_path) 调用涵盖五个阶段。首先通过 CreateFile RPC 在 NameNode 创建 inode 并获取 lease（保证写互斥）；接着按 kDefaultBlockSize（128 MB）将本地文件切分成若干 block，对每个 block 执行 AllocateBlock / 多次 WriteBlock / CommitBlock 的循环；最后 CompleteFile 释放 lease，使文件对外可见。

void DfsClient::put(const std::string& dfs_path,
                    const std::string& local_path) {
  auto resp = nn_stub_->CreateFile(dfs_path, block_size_, replication_);
  auto inode_id = resp.inode_id();

  std::ifstream ifs(local_path, std::ios::binary);
  std::vector<char> buf(block_size_);
  while (ifs.read(buf.data(), block_size_) || ifs.gcount() > 0) {
    uint64_t bytes_read = ifs.gcount();
    auto alloc = nn_stub_->AllocateBlock(inode_id);
    write_block(alloc, buf.data(), bytes_read);
    nn_stub_->CommitBlock(alloc.block_id(), bytes_read,
                          alloc.generation_stamp());
  }
  nn_stub_->CompleteFile(inode_id);
}

整个过程中 NameNode 只参与元数据协调——分配 block_id、记录副本位置、推进状态机——从不接触实际数据。Client 将数据通过 DataTransferService::WriteBlock 直接发送给 Pipeline 的头节点（DN1），由 DN1 链式转发给后续节点。应答沿反方向回溯：DN3 完成写入后向 DN2 应答，DN2 再向 DN1 应答，最终 DN1 向 Client 返回结果。这种设计使 Client 只需维护一条连接，复制带宽由各 DataNode 分摊。

LocalBlockStore：本地存储引擎

目录布局

每个 DataNode 的数据根目录下有三个子目录，对应 block 文件的三个生命阶段：

<storage_root>/
  tmp/            — 正在通过 Pipeline 写入的 block
    blk_1001_42.blk
  current/        — 已 finalize 的 block，对外可读
    blk_1000_41.blk
  trash/          — 软删除的 block，等待异步清理
    blk_999_40.blk

文件命名格式为 blk_<block_id>_<generation_stamp>.blk，将 block_id 和 generation_stamp 编码在文件名中，使得文件系统层面即可唯一标识一个 block 的特定版本。

Lease 管理：写互斥的语义保证

在分布式文件系统中，同一个文件不能被两个 Client 同时写入——否则数据会混乱不可恢复。MiniDFS 通过 Lease 机制实现写互斥：Client 在 CreateFile 时获取 Lease，持有期间独占写权限，CompleteFile 时释放。

LeaseManager 的接口设计非常精炼：

class LeaseManager {
public:
    explicit LeaseManager(MetadataStore* store);

    Result<uint64_t> acquire_lease(uint64_t inode_id,
                                   const std::string& client_id);
    Result<Void> renew_lease(uint64_t lease_id,
                             const std::string& client_id);
    Result<Void> release_lease(uint64_t lease_id);
    Result<Void> expire_stale_leases();
    Result<bool> has_active_lease(uint64_t inode_id);

private:
    MetadataStore* store_;
};

几个关键设计决策值得展开讨论。