Go afero CopyOnWriteFs 为什么能读到基础层却无法改原文件

如果用 afero.NewCopyOnWriteFs(base, layer) 包了一层文件系统，读取基础层里的文件通常没有问题，但随后用 afero.WriteFile 或带写标志的 OpenFile 修改它，原来的磁盘文件却保持不变。这不是写入失败，而是 CopyOnWriteFs 的核心承诺：读可以看到 base，改动只进入 layer。

官方地址：https://github.com/spf13/afero

故障现场：读得到，改不回原文件

常见代码是先准备一个真实文件系统作为基础层，再用内存文件系统承接临时修改：

package main

import (
    "fmt"

    "github.com/spf13/afero"
)

func main() {
    // base 只提供初始内容；layer 负责承接 Copy-on-Write 的修改。
    base := afero.NewOsFs()
    layer := afero.NewMemMapFs()
    fs := afero.NewCopyOnWriteFs(base, layer)

    // 读取时如果 layer 没有该文件，CopyOnWriteFs 会回退到 base。
    before, err := afero.ReadFile(fs, "config/app.conf")
    if err != nil {
        panic(err)
    }
    fmt.Println(string(before))

    // 写入的是 overlay 副本，不会直接改动磁盘上的 base 文件。
    if err := afero.WriteFile(fs, "config/app.conf", []byte("mode=test\n"), 0644); err != nil {
        panic(err)
    }
}

这里的变量名很容易造成误解：fs 看起来像一个普通可写文件系统，但它其实是两个文件系统的组合视图。第一次 ReadFile 看到的是 base 的内容；写入完成后，同一路径在组合视图中会优先看到 layer 的副本，而真实 base 文件仍然保留原内容。

根因在于 base 和 layer 的职责完全不同

CopyOnWriteFs 的构造函数接收两个 afero.Fs：一个是 base，一个是 layer。官方实现先检查 layer 是否已经有目标路径；如果没有，再去 base 查找。因此，读取行为像“覆盖层优先、基础层兜底”的联合视图。

但写入路径不能继续沿用这个直觉。对于带有 O_WRONLY、O_RDWR、O_APPEND、O_CREATE 或 O_TRUNC 的 OpenFile，如果目标当前只存在于 base，CopyOnWriteFs 会先执行复制，再调用 layer 的 OpenFile。这一步把“要修改原文件”转换成了“先建立隔离副本，再修改副本”。

所以问题不在 afero.WriteFile 没有写入，也不在 MemMapFs 丢失了数据，而在于你观察的对象错了：业务通过组合文件系统看到的是修改后的 layer，操作系统磁盘上的 base 则没有被授权写入。

沿着一次写入看清副本何时出现

可以把一次对 base 文件的写操作拆成三个静态事实：

1. layer 中不存在目标路径，组合视图因此从 base 返回文件内容。
2. 写操作命中 base 文件时，copyToLayer 把文件内容和必要的路径结构复制到 layer。
3. 真正的打开、截断、追加或写入由 layer 完成，后续读取优先命中这份副本。

func updateInOverlay(fs afero.Fs, path string) error {
    // OpenFile 的写标志会让 CopyOnWriteFs 选择可写的 layer。
    file, err := fs.OpenFile(path, os.O_RDWR|os.O_TRUNC, 0644)
    if err != nil {
        return err
    }
    // 关闭文件，避免句柄一直占用 layer 的资源。
    defer file.Close()

    // 这里只修改隔离副本；是否回写由更外层的持久化策略决定。
    _, err = file.WriteString("mode=test\n")
    return err
}

这段代码的关键不是 O_TRUNC 本身，而是 fs 的动态类型。传入普通 OsFs 时，写入目标就是磁盘；传入 CopyOnWriteFs 时，写入目标是它的 layer。把接口类型都写成 afero.Fs，并不会抹掉底层实现的语义。

如何确认修改只在 overlay

排查时不要只通过同一个组合视图再次读取，因为它会优先返回 layer，容易让人误以为 base 已经改变。应当同时读取 base 和组合视图；如果 layer 使用内存文件系统，还可以直接读取 layer 判断副本是否存在。

func compareLayers(base, layer, view afero.Fs, path string) error {
    // 直接读取 base，观察真实来源是否仍保留旧内容。
    baseData, err := afero.ReadFile(base, path)
    if err != nil {
        return fmt.Errorf("read base: %w", err)
    }

    // 读取组合视图，观察业务当前能看到的覆盖内容。
    viewData, err := afero.ReadFile(view, path)
    if err != nil {
        return fmt.Errorf("read view: %w", err)
    }

    // layer 中出现同名文件，说明写入已经被隔离层接管。
    if _, err := layer.Stat(path); err != nil {
        return fmt.Errorf("overlay copy is missing: %w", err)
    }
    fmt.Printf("base=%q view=%q\n", baseData, viewData)
    return nil
}

这个对照的结论应该是：base 仍是旧值，view 是新值，layer 能找到同名副本。它证明了 CopyOnWriteFs 的预期行为，但不等于对真实应用做过运行验证；文章中的结构图同样只是对源码关系的静态解释。

需要持久化时，必须显式设计同步边界

如果 CopyOnWriteFs 的目标是沙箱、预览、测试或失败可回滚，base 不被修改正是它的价值，不需要修复。真正需要修复的是业务把“隔离修改”误当成“自动提交”。

要持久化，先从 layer 读取最终文件，再由业务选择目标 OsFs 或其他持久化后端写入。同步时还要决定新增文件、覆盖文件、删除意图和权限元数据怎样处理，不能把整个 layer 目录未经审查地复制回生产目录。

func persistOne(base, layer afero.Fs, path string) error {
    // 读取 overlay 的最终内容，确保提交的是业务看到的版本。
    data, err := afero.ReadFile(layer, path)
    if err != nil {
        return fmt.Errorf("read overlay: %w", err)
    }

    // 由调用方明确传入可写目标；base 仍可保持只读或受保护状态。
    return afero.WriteFile(base, path, data, 0644)
}

上面的函数只是说明同步边界，不是通用提交器。真实项目至少还要处理路径白名单、目录创建、文件权限、并发冲突以及删除标记。若只需要把处理结果写到新目录，通常比“覆盖原文件”更容易审计：把 layer 内容导出到一个新版本目录，再通过原子替换或发布流程切换入口。

三个边界会让排查方向发生变化

base 使用 ReadOnlyFs 并不是多余的

官方 README 的沙箱示例会把 NewOsFs() 再包成 NewReadOnlyFs，然后作为 base 传给 CopyOnWriteFs。这样即使后续代码绕过组合层拿到 base，也不会意外修改真实文件。CopyOnWriteFs 负责隔离联合视图，ReadOnlyFs 负责把底层写保护说清楚，两者职责不同。

Rename 和 Remove 不会替你生成删除记录

源码对仅存在于 base 的文件禁止直接 Rename，Remove 和 RemoveAll 也会返回权限错误；只有已经出现在 layer 的副本才能在 layer 中被移除。这意味着 overlay 没有一个天然的“白名单删除标记”。如果业务要表达“发布后删除 base 文件”，需要自己记录删除集合，并在提交阶段执行受控删除。

新文件与已有文件的父目录处理不同

写入 base 已有文件时，重点是复制文件；创建新文件时，CopyOnWriteFs 还要判断父目录在 base 或 layer 中是否存在，并在需要时为 layer 创建目录。遇到 ENOTDIR 或路径不存在，先检查父级在两层中的类型，不要只盯着最后一个文件名。

最后的处理选择

常见问题

为什么组合视图里已经是新内容，磁盘文件还是旧内容？

因为组合视图优先读取 layer。新内容只代表覆盖副本已经生效，不代表 base 被同步。

把 base 和 layer 都换成 OsFs 就会自动回写吗？

不会。两个参数即使指向可写文件系统，CopyOnWriteFs 仍会把写入交给 layer；如果两者恰好指向同一目录，反而会破坏隔离边界，应该避免这种配置。

能不能直接调用底层 base 的 WriteFile？

技术上可以绕过组合层，但这会绕开 CopyOnWriteFs 的隔离设计。更稳妥的方式是把“预览修改”和“正式提交”拆成两个明确阶段，并在提交阶段使用受控的同步逻辑。