写文件成功但重启后内容丢失，原子更新还缺少什么步骤

我第一次碰到这个问题时，日志里每一步都显示成功：临时文件写完了，os.Rename 也返回了 nil。可机器突然掉电再启动，配置却回到了旧版本。真正缺的不是“再写一次”，而是把两种不同的保证分开：原子替换保证读者不会看到半份文件，持久化保证系统崩溃后这次替换仍然存在。

面向类 Unix 本地文件系统，一个更完整的耐久更新顺序是：在目标目录创建临时文件，写完后对临时文件调用 Sync，关闭文件，再用 Rename 替换目标路径，最后打开父目录并对目录调用 Sync。

为什么写成功和重命名都不等于持久化

Write 返回成功，说明数据已交给内核；Close 负责关闭描述符，但它不是“强制落到稳定存储”的同义词。Go 官方对 File.Sync 的定义是把文件当前内容提交到稳定存储。这个调用对应的是文件对象本身。

Rename 解决的是另一层问题：名字从临时路径切换为目标路径。在 Unix 上，同一文件系统内的替换通常可作为原子切换使用；但 Go 的 os.Rename 文档也明确提醒，跨目录存在系统限制，而且非 Unix 平台即使在同一目录也不保证它是原子操作。

最容易漏掉的是父目录。目录里保存着“文件名指向哪个文件对象”的命名空间信息。Linux 的 fsync(2) 手册指出：只同步文件并不一定让包含它的目录项也落盘；需要对目录描述符再执行一次同步。于是，文件数据和目录项是两个要分别确认的持久化边界。

旧写法的风险不在 Rename 本身

常见写法是 os.WriteFile(temp) 后直接 os.Rename(temp, target)。它比直接覆盖目标文件安全，因为进程在写到一半时崩溃，旧目标文件通常仍然完整；但它仍有三处空档：

• 临时文件的内容可能仍在页缓存里，尚未达到稳定存储。
• 临时文件若建在系统临时目录，可能与目标文件不在同一文件系统，导致 Rename 失败或失去预期语义。
• Rename 修改了父目录中的目录项；如果父目录未同步，异常重启后的命名空间结果仍取决于文件系统和平台实现。

因此我现在把“同目录临时文件”看成原子替换的前提，把“文件 Sync + 目录 Sync”看成崩溃持久性的补充。两者解决的不是同一个问题，不能互相替代。

新的更新顺序应该补齐哪些动作

1. 在目标文件的父目录创建临时文件。这样临时文件与目标路径位于同一文件系统，减少 Rename 的平台限制。
2. 写入全部内容并处理短写或返回错误。不要忽略 Write、Chmod、Close 的错误。
3. 在 Rename 前调用临时文件的 Sync。先让新文件的数据及相关元数据达到文件系统提供的稳定存储边界。
4. 关闭临时文件后再 Rename。这对 Windows 等平台尤其重要，也让资源生命周期更清楚。
5. Rename 成功后打开父目录并调用 Sync。这一步针对目录项；失败时要向上返回，不能把更新报告成“已耐久”。

如果业务还要求保留原文件的所有者、扩展属性、ACL 或时间戳，这些都应在 Rename 前显式复制并检查。单独传一个权限位只覆盖最基础的 mode，并不等于完整继承文件属性。

把更新封装成一个可复查的 Go 函数

下面的实现聚焦类 Unix 本地文件系统。它不声称为所有网络文件系统、Windows 文件系统或虚拟文件系统提供相同保证；生产使用前仍要在目标平台做故障注入和重启测试。

package durablefile

import (
    "fmt"
    "io/fs"
    "os"
    "path/filepath"
)

// ReplaceDurably 在类 Unix 本地文件系统上耐久地替换一个文件。
func ReplaceDurably(path string, data []byte, perm fs.FileMode) (err error) {
    dir := filepath.Dir(path)
    base := filepath.Base(path)

    // 临时文件必须位于目标目录，避免跨文件系统重命名。
    tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
    if err != nil {
        return fmt.Errorf("创建临时文件: %w", err)
    }
    tmpName := tmp.Name()

    // 无论在哪一步失败，都尝试关闭并清理尚存的临时文件。
    defer func() {
        _ = tmp.Close()
        _ = os.Remove(tmpName)
    }()

    // 先设置最终权限，使相关元数据也包含在文件同步范围内。
    if err := tmp.Chmod(perm); err != nil {
        return fmt.Errorf("设置临时文件权限: %w", err)
    }
    if _, err := tmp.Write(data); err != nil {
        return fmt.Errorf("写入临时文件: %w", err)
    }

    // 先同步文件内容与文件元数据，再发布新的目录项。
    if err := tmp.Sync(); err != nil {
        return fmt.Errorf("同步临时文件: %w", err)
    }
    if err := tmp.Close(); err != nil {
        return fmt.Errorf("关闭临时文件: %w", err)
    }

    // 同目录替换用于保证读者看到旧文件或新文件，而不是半份文件。
    if err := os.Rename(tmpName, path); err != nil {
        return fmt.Errorf("替换目标文件: %w", err)
    }

    // 最后同步父目录，使新的文件名映射具备持久化保障。
    parent, err := os.Open(dir)
    if err != nil {
        return fmt.Errorf("打开父目录: %w", err)
    }
    defer parent.Close()
    if err := parent.Sync(); err != nil {
        return fmt.Errorf("同步父目录: %w", err)
    }

    return nil
}

这个函数有一个值得保留的“麻烦”：父目录 Sync 失败时，它会返回错误，即便 Rename 已经成功。此时目标路径可能已经指向新文件，只是这次变更的崩溃持久性没有得到确认。调用方不应盲目回滚或再次覆盖，而应记录错误、检查当前文件内容，并根据业务幂等策略决定是否重试。

回归检查不能只看函数返回 nil

这类代码最有价值的测试不是只读回文件，而是让每个系统调用都能被故障注入。可以把创建、写入、文件 Sync、Rename、打开目录、目录 Sync 抽成一个很薄的接口，在单元测试中逐项返回错误，确认函数不会吞错，并确认临时文件能被清理。

集成测试则需要在真实目标文件系统上进行：并发读者要始终读到完整旧版本或完整新版本；更新进程在 Rename 前退出时，旧文件应保持可用；Rename 后目录 Sync 失败时，程序应明确报告“可见但未确认耐久”。真正的掉电、虚拟机强制断电或文件系统崩溃测试要在隔离环境里完成，不能用普通进程退出代替。

迁移现有代码时的最小清单

• 临时文件是否与目标文件在同一目录、同一文件系统？
• 是否检查了 Chmod、Write、文件 Sync、Close、Rename 和目录 Sync 的每一个错误？
• 是否在 Rename 前同步新文件，在 Rename 后同步父目录？
• 目录 Sync 失败时，业务是否区分“已经可见”和“已经耐久”？
• 是否明确支持的平台与文件系统，并对 Windows、网络盘、容器挂载卷分别验证？
• 原文件的权限、所有者、ACL 与扩展属性是否需要保留？

我的结论是：如果更新的是可以随时重建的缓存，直接 Write + Rename 可能已经够用；如果是配置、状态快照、事务日志或用户数据，就应该把文件 Sync 和父目录 Sync 当成设计的一部分。原子性让读者看不到半成品，持久性才负责在重启之后把承诺兑现。

常见问题

只调用 os.WriteFile 可以吗？

它适合普通文件写入，但函数返回并不等价于“异常重启后一定存在”。需要崩溃持久性时，应显式控制文件句柄并调用 Sync。

文件 Sync 之后还必须关闭吗？

必须处理 Close 的错误并释放描述符。示例选择 Sync 后关闭，再 Rename，使资源边界清楚，也避开部分平台对打开文件重命名的限制。

为什么父目录也能调用 Sync？

在支持该语义的类 Unix 文件系统上，目录描述符代表目录项集合；同步它用于提交 Rename 带来的文件名映射变化。如果目标平台返回不支持，应把它视为平台能力差异，而不是忽略错误。

Rename 失败后能改成复制吗？

不能无条件降级。复制会暴露部分内容并改变原子性语义。跨文件系统更新应重新设计发布位置或使用经过目标平台验证的方案。