以临时文件加原子重命名安全更新配置

Go 更新配置时，最容易踩的坑是直接用 os.Create 打开正式路径：它会先截断旧内容，随后写入一旦中断，读取者就可能拿到空文件或半份 JSON。更稳妥的做法是把临时文件创建在目标文件同一目录，完整写入、同步并关闭，最后调用 os.Rename 替换目标路径。这样切换点只有一个，失败时旧配置仍在。

官方文档：https://pkg.go.dev/os

一、先把临时文件放到正确位置

临时文件不能随手放到系统临时目录再移动。os.Rename 的语义受操作系统和文件系统约束，最可控的前提是临时文件与目标文件同目录。下面的函数把配置序列化为字节，临时文件成功创建后才进入写入阶段：

func atomicWriteConfig(path string, data []byte, perm os.FileMode) (err error) {
    // 同目录创建临时文件，确保后续 Rename 不跨文件系统。
    dir := filepath.Dir(path)
    tmp, err := os.CreateTemp(dir, ".config-*.tmp")
    if err != nil {
        return err
    }
    tmpName := tmp.Name()
    defer func() {
        // 任一步失败都清理临时文件；成功重命名后 Remove 会自然返回错误，可忽略。
        _ = os.Remove(tmpName)
    }()

    if err = tmp.Chmod(perm); err != nil {
        _ = tmp.Close()
        return err
    }
    if _, err = tmp.Write(data); err != nil {
        _ = tmp.Close()
        return err
    }
    if err = tmp.Sync(); err != nil {
        _ = tmp.Close()
        return err
    }
    if err = tmp.Close(); err != nil {
        return err
    }

    // 只有完整文件准备好后，才让目标路径指向它。
    return os.Rename(tmpName, path)
}

这里的 perm 只决定新文件的权限位，不能替代目录权限和进程权限检查。已有配置文件时，如果必须保留更细的 ACL、属主或扩展属性，也要把这些属性复制策略单独设计。

二、写入完成不等于可以立即切换

写入返回成功，只说明数据已经交给操作系统的文件接口。File.Sync 用来请求把当前文件内容提交到稳定存储；随后 Close 仍然要检查，因为关闭本身也可能报告错误。任一环节失败，保留旧配置比发布一份不完整的新配置更安全。

三、最后用 Rename 完成一次切换

不要先删除目标文件，也不要对目标文件执行截断后再复制。直接把已经关闭的临时文件重命名到目标路径，读者看到的是旧文件或完整新版。Go 官方文档也提醒，跨目录可能受平台限制；在非 Unix 平台，即便同目录重命名也不保证是原子操作，因此跨平台产品应把这一点写进部署约束。

如果配置会被多个进程同时更新，仍需要锁、单写者队列或版本检查；原子替换只保证一次替换动作的可见边界。若应用启动时还要求目录项在断电后可恢复，则还要按目标操作系统补充目录同步策略，这不是 File.Sync 自动完成的。

四、上线前的检查清单

• 临时文件是否和目标配置在同一目录？
• 是否检查了 Write、Sync、Close 和 Rename 的每个错误？
• 失败时是否删除临时文件，但保留旧配置？
• 是否明确 Windows 文件占用、权限、ACL 和并发写入策略？

相关问题

为什么不能直接用 os.WriteFile 更新配置？

os.WriteFile 适合简单写入，但直接写正式路径会暴露截断窗口；需要“旧文件或完整新文件”语义时，应采用临时文件加重命名。

Rename 后还要不要调用 Sync？

文件内容的同步应在 Rename 前完成。Rename 后是否需要同步目录，取决于操作系统对断电持久性的要求，不能用一次文件 Sync 代替目录项持久化。