Table of Contents

本地文件系统使用指南（DiskFileSystem · local://）

给谁看：要落盘持久化的人（目录树形态、宿主工具可直接查看）。 回答什么：怎么构造、有什么能力位、DIO 怎么用、元数据怎么存、什么不要做。 四类文件系统的公共契约（IFileSystem/IFileHandle 打开/读写/FileExtra/句柄池/镜像导出）见 io.md——本篇只讲本地文件系统的差异面。

0. 一句话定位

本地文件系统 = 可视化目录 / 性能稳定的落盘形态：目录树结构、宿主工具全兼容、fsync 持久化。 数据面速度与其他三类带内持平（实测见 perf/io-performance.md §9）， 差异在元数据面与一致性语义。

1. 构造（spec 一行）

using var fs = TierFs.New("local:///" + rootDir);     // 绝对路径（推荐）
using var fs2 = TierFs.New("local:data/tier");        // 相对——构造时对 CWD 固化
using var fs3 = TierFs.New("local:///C:/data");       // Windows 盘符
using var fs4 = TierFs.New("local://host/share");     // UNC

// 类型层直构（工厂底座）：
using var d = DiskFileSystem.New("/var/lib/tier", new DiskFileSystemOptions
{
    QuotaBytes = 100L << 30,
    MetadataMode = DiskMetadataMode.Sidecar,          // 元数据模式，见 §4
    Preallocation = PreallocationMode.Metadata,       // 预分配方式轴（IS-04）：Metadata = best-effort 稀疏降级（缺省）；Full = 物理占位强制（失败显式报错，不静默降级）
});
  • New = 创建空镜像（已存在且非空抛 AlreadyExists）；Open = 打开既有；OpenOrCreate = 懒初始化。
  • quota 一词制：空间根硬上限（-1/缺省 = 无上限）。

2. 能力位（与内存/网络/虚拟的差异点）

能力位 本地（Win） 本地（Linux） 说明
Sparse ✓ ✓ PunchHole 物理回收
DirectIO NTFS/ReFS 非压缩 ✓ ✓ 逐句柄探测对齐（UnbufferedSupport/RequiredAlignment）
DurableRename / AtomicDirectoryMove ✓（同卷 rename） ✓ Move 内建目录刷盘
RangeLock ✓（LockFileEx） ✓（OFD） advisory 契约
Mmap ✓（手工 MMF） ✓（mmap） 非 BCL MMF（OVERLAPPED 复刻）
FlushDataOnly ✗ ✓（真 fdatasync） 未置位时 FlushData ≡ Flush 不抛
CopyRange ✗（回退循环） ✓ Linux copy_file_range

消费规则：按能力位决策，不按文件系统硬编码分支。

3. DIO（Direct IO）

  • 请求：FileOpenOptions { Hints = FileOpenHints.NoBuffering }；真实生效与否经句柄 UnbufferedSupport 报告（部分环境不吃 DIO，报 Ignored）。
  • 三重对齐：offset/length/buffer 按 h.RequiredAlignment（Win = max(扇区, 内存页) / Linux = 逻辑块）——对齐 buffer 必须走 AlignedMemoryManager/PinnedBufferPool （见 memory.md）。
  • 组合合法性构造时校验（写模式配 Access=Read → 抛）。

4. 元数据模式（FileExtra 落点，DiskMetadataMode）

模式 行为 何时用
Fallback（缺省） xattr/ADS 优先，失败回退 sidecar .{name} 伴生文件 默认——兼容性最好
ExtendedAttr 仅 xattr，惰性探测 fail-fast 文件系统确定支持扩展属性
Sidecar 单通道 sidecar（tmp+WriteThrough+Flush+原子换名） 文件系统不支持 xattr（如部分网络盘）

FileExtra 语义（≤1536B 不透明数据，Delete 必清除 / Move 必保留）见 io.md §4.5。

5. 陷阱（本地文件系统特有）

  1. Windows 句柄打开时删除被拒——删段顺序必须是 pool.RemoveAll(...) → fs.Delete(...)。
  2. FileSharing 是 advisory——仅约束同进程同 fs 实例；跨进程用卷锁（AcquireExclusive）。
  3. 映射必须 Dispose（独立 fd）——IMappedSection 泄漏；View 越界 = 段错误。
  4. 锁语义平台差异：Win LockFileEx（mandatory 不可依赖）/ Linux OFD（F_OFD_SETLK）——同句柄重锁 不保证幂等，调用方去重。
  5. 大小写敏感：路径比较一律 Ordinal（Linux 敏感；Windows 上不依赖大小写区分路径）。
  6. 卷锁：AcquireExclusive（RAII + 异常安全；lock file 崩溃自愈；非重入）。

6. 想深入？指路

想懂什么 去哪
公共契约（打开/读写/FileExtra/句柄池/镜像导出） io.md
性能（DIO/fsync/并发） perf/io-performance.md
能力位矩阵全表 源码 IFileSystem.Capabilities 注释
Edit this page