dnscrypt-proxy 中的 safefile:Go 实现安全"原子"文件写入的机制与实战指南
dnscrypt-proxy 中的 safefile:Go 实现安全"原子"文件写入的机制与实战指南
导读
vendor/github.com/dchest/safefile 是 dnscrypt-proxy 依赖的第三方 Go 库,核心价值是提供一种安全的"原子"文件保存方式:不再直接截断并覆盖目标文件,而是在目标文件所在目录中先创建临时文件、写入数据、最后通过 Commit 将其重命名回原名。在 dnscrypt-proxy 中,它被用于 PID 文件写入 与 服务器列表缓存文件写入,确保代理在崩溃、断电或并发读写时不会留下半截损坏的配置文件。阅读本文后,你将掌握 safefile 的 API 用法、原子性原理、跨平台实现差异,以及它在 dnscrypt-proxy 中的真实落地场景。
一、问题背景:为什么"直接覆盖写文件"不安全
日常开发中最常见的写文件方式是这样的:以 O_TRUNC 打开目标文件,写入新内容后 Close。这种方式存在两类隐患:
- 写入中途失败导致文件损坏:进程被 kill、磁盘写满、机器断电,都可能让目标文件停留在"新旧内容混合"或"内容不完整"的状态,读取方拿到的是损坏数据。
- 读取方可能看到中间态:正在
Close之前读取该文件的进程,读到的是截断后、尚未写满的新内容。
safefile 采用经典的"同目录临时文件 + 原子重命名"方案规避以上问题:先在同目录创建临时文件并完整写入、刷盘,再通过 rename 一次性替换目标文件名。重命名在文件系统层面是原子的,读者永远只能看到"完整的旧文件"或"完整的新文件"两个状态之一,不会看到中间态。这正是其 README 所描述的核心机制:
"Instead of truncating and overwriting the destination file, it creates a temporary file in the same directory, writes to it, and then renames the temporary file to the original name when calling Commit."
二、safefile 的安装与项目来源
safefile 由 Dmitry Chestnykh 编写,采用 BSD 风格许可(见仓库内 LICENSE)。原文档给出的安装方式为 Go 传统模式:
$ go get github.com/dchest/safefile
在 dnscrypt-proxy 项目中,它作为 vendored 依赖被固定,版本记录于 go.mod(github.com/dchest/safefile v0.0.0-20151022103144-855e8d98f185),源码位于 vendor/github.com/dchest/safefile 目录下,无需额外安装即可随主项目一起编译。
三、核心 API 与 README 完整示例
safefile 的核心 API 非常精简,全部位于 safefile.go:
| API | 签名 | 作用 |
|---|---|---|
Create |
func Create(filename string, perm os.FileMode) (*File, error) |
在目标文件同目录创建临时文件,Commit 时重命名回 filename |
Commit |
func (f *File) Commit() error |
同步刷盘 → 关闭临时文件 → 重命名为原名,完成原子提交 |
Close |
func (f *File) Close() error |
关闭并删除未提交的临时文件;已提交则为无操作 |
OrigName |
func (f *File) OrigName() string |
返回最初传给 Create 的目标文件名 |
WriteFile |
func WriteFile(filename string, data []byte, perm os.FileMode) error |
ioutil.WriteFile 的安全版,一步完成"创建 + 写入 + 提交" |
ErrAlreadyCommitted |
var ErrAlreadyCommitted = errors.New("file already committed") |
对已成功提交的文件再次 Commit 时返回的错误 |
原文档给出的示例完整展示了四步用法(创建临时文件 → 写入 → 提交 → 重命名):
f, err := safefile.Create("/home/ken/report.txt", 0644)
if err != nil {
// ...
}
// Created temporary file /home/ken/sf-ppcyksu5hyw2mfec.tmp
defer f.Close()
_, err = io.WriteString(f, "Hello world")
if err != nil {
// ...
}
// Wrote "Hello world" to /home/ken/sf-ppcyksu5hyw2mfec.tmp
err = f.Commit()
if err != nil {
// ...
}
// Renamed /home/ken/sf-ppcyksu5hyw2mfec.tmp to /home/ken/report.txt
注意其中的两个关键细节:
defer f.Close()与f.Commit()同时存在并不冲突:Commit成功后Close变成无操作(no-op);若写入或提交出错,defer会兜底清理临时文件,避免磁盘残留。Commit成功后临时文件即不存在于磁盘,临时文件路径由随机名生成,示例中的sf-ppcyksu5hyw2mfec.tmp只是某次运行的展示值。
四、源码级原理:从临时文件名到原子提交
1. 不可预测的临时文件名
makeTempName(safefile.go)负责生成临时文件名:
- 使用
filepath.Clean清洗目标路径;若路径为空或以分隔符结尾,直接返回os.ErrInvalid; - 从
crypto/rand读取 10 字节(80 bit 熵) 随机数,文档注释明确说明"足够使临时文件名不可预测"; - 随机数经 base32 编码、转小写,拼成
"sf-" + 随机串 + ".tmp"形式; - 临时文件放在
filepath.Dir(origname),即与目标文件同一目录——这是跨目录rename无法保证原子性的前提。
Create 使用 os.OpenFile(tempname, os.O_RDWR|os.O_CREATE|os.O_EXCL, perm) 创建,O_EXCL 保证独占创建;若因巧合撞名(os.IsExist),循环重试生成新名字。
2. Commit 的三阶段提交
Commit(safefile.go)是原子性的核心:
f.Sync()刷盘:把临时文件内容强制落盘,防止系统崩溃后出现"目录里已重命名、文件内容还在页缓存中"的丢数据窗口;- 关闭底层
os.File,并标记isClosed; rename(f.Name(), f.origName)重命名:同目录内、目标已存在的情况下,大多数系统上rename会原子地覆盖旧文件。
Commit 成功后设置 closeFunc = closeCommitted 与 isCommitted = true;此后再次调用 Commit 会返回 ErrAlreadyCommitted。失败时临时文件仍存在且可能仍打开,调用者需 Close 清理或重新 Commit。源码还给出了一条重要提示:提交失败后再二次 Commit(此时文件已关闭未重命名)无法保证临时文件未被改写,若需要绝对原子性,失败后应放弃旧临时文件、重新写入整个文件,而不是盲目重试 Commit。
3. 状态机式的 Close 处理
File 内部通过 closeFunc 字段实现状态机(safefile.go):
closeUncommitted:正常关闭并删除未提交的临时文件;closeAfterFailedRename:重命名失败后,删除临时文件(依赖临时名的不可预测性,无需担心误删它文件);closeCommitted:已提交成功,Close直接返回 nil;closeAgainError:重复Close返回os.ErrInvalid。
4. WriteFile 便捷封装
WriteFile(safefile.go)是 ioutil.WriteFile 的安全版:内部依次执行 Create → Write → Commit,并用 defer f.Close() 保证失败时清理。它还额外检查了短写:若 n < len(data) 返回 io.ErrShortWrite。dnscrypt-proxy 的 PID 文件写入正是用它一行完成的。
五、跨平台差异:rename 并非处处原子
safefile 依据操作系统选择不同重命名策略,这是原 README 未展开、但源码中非常关键的一部分:
- rename.go(构建约束
!plan9,!windows windows,go1.5):直接调用os.Rename,在 POSIX 系统与 Go 1.5 及以上的 Windows 上,rename覆盖已存在文件的行为是原子的。 - rename_nonatomic.go(构建约束
plan9 windows,!go1.5):用于 Plan 9 以及 Go 1.5 之前的 Windows——这些平台上os.Rename不覆盖已存在文件,无法靠单一重命名保证原子性。源码采用"三步替换法"兜底:- 先把旧文件(原名文件)重命名到一个新的随机临时名;
- 再把新临时文件重命名为原名;
- 最后删除被挪走的旧文件。 若在步骤之间崩溃,原文件仍以临时名存在于磁盘,用户可手动找回数据(注释明确说明崩溃后临时名不可知,无法自动恢复)。若步骤 2 仍失败,则尝试把旧文件重命名回去进行回滚。
结论:在 Linux/macOS 等主流平台、以及新版 Go 的 Windows 上,safefile 提供真正的原子写入;在 Plan 9 与旧版 Windows 上,它退化为"最大限度减少数据丢失"的近似保证。
六、在 dnscrypt-proxy 中的真实应用场景
safefile 之所以被引入 dnscrypt-proxy,是因为代理需要持续、可靠地维护两类"运行时生成"的关键文件。
1. PID 文件写入(pidfile.go)
dnscrypt-proxy/pidfile.go 在 PidFileCreate 中先 os.MkdirAll 确保目录存在,然后一行调用 safefile:
return safefile.WriteFile(*pidFile, []byte(strconv.Itoa(os.Getpid())), 0o644)
每次启动都把当前进程 PID 以 0644 权限写入指定文件。使用 WriteFile 而非普通写文件,保证 PID 文件内容要么是完整的新 PID,要么是完整的旧 PID,进程管理脚本(如 windows/service-install.bat 一类的守护脚本)永远不会读到截断的 PID。对应的 -pidfile 命令行参数定义在同一文件:flag.String("pidfile", "", "Store the PID into a file")。
2. 服务器列表缓存文件写入(sources.go)
dnscrypt-proxy 从远程源(如 public-resolvers.md)下载服务器列表,并将其缓存到本地文件。writeSource(dnscrypt-proxy/sources.go)同时写入数据文件与 .minisig 签名文件:
func writeSource(f string, bin, sig []byte) error {
var err error
var fSrc, fSig *safefile.File
if fSrc, err = safefile.Create(f, 0o644); err != nil {
return err
}
defer fSrc.Close()
if fSig, err = safefile.Create(f+".minisig", 0o644); err != nil {
return err
}
defer fSig.Close()
if _, err = fSrc.Write(bin); err != nil {
return err
}
if _, err = fSig.Write(sig); err != nil {
return err
}
if err = fSrc.Commit(); err != nil {
return err
}
return fSig.Commit()
}
这里的原子性价值极为明显:updateCache 会先写缓存文件再更新内存中的 source.bin,后续读取方(fetchFromCache,见同文件)在启动时读回缓存并校验 minisign 签名。若缓存文件在写入中途损坏,代理可能因校验失败而无法加载任何解析服务器;safefile 保证磁盘上的缓存始终是"上一份完整版本"或"这一份完整版本"。这正是原文档"安全保存"理念在真实项目中的直接体现——cache 写入失败只打日志不致命(dlog.Warnf("Couldn't write cache file [%s]: %s", ...)),但文件本身绝不损坏。
对应缓存行为由配置项控制(见 dnscrypt-proxy/example-dnscrypt-proxy.toml 的 [sources] 段):
[sources.public-resolvers]
urls = [
'https://raw.githubusercontent.com/DNSCrypt/dnscrypt-resolvers/master/v3/public-resolvers.md',
'https://download.dnscrypt.info/resolvers-list/v3/public-resolvers.md',
'https://cdn.jsdelivr.net/gh/DNSCrypt/dnscrypt-resolvers@master/v3/public-resolvers.md'
]
cache_file = 'public-resolvers.md'
minisign_key = 'RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3'
refresh_delay = 73
prefix = ''
cache_file即 safefile 写入的本地缓存路径,urls缺失时要求缓存与签名已存在(参见 example-dnscrypt-proxy.toml 中[sources]上方的说明注释);refresh_delay控制正常运行期间的下载更新频率,必须在<a href="https://link.gitcode.com/i/80e71ab02e022c081629a84a731b1a66" target="_blank">25..169]区间,越界会被钳制(对应 [sources.go 中NewSource的钳制逻辑:refreshDelay < DefaultPrefetchDelay时取默认值);cache_ttl控制启动时缓存可容忍的旧程度,默认 168 小时,必须在<a href="https://link.gitcode.com/i/32c8a5c5c5aafbf11d1c93e69c4e72e2" target="_blank">refresh_delay..168]区间([sources.go 同样有上下限钳制,上限 168 小时);- 缓存是否过期由
fetchFromCache通过比较os.Stat(cacheFile).ModTime()与cacheTTL判断(见 sources.go)。
七、使用 safefile 的最佳实践清单
综合 README 示例与源码注释,在实际项目中安全使用 safefile 应遵守:
- 固定流程:
Create→ 写入 →Commit,并用defer Close兜底;Commit成功后再Close是安全的无操作。 - 提交失败不要盲目重试
Commit:源码明确提示二次提交可能操作的是已被改写、或已不是原来的临时文件;需要绝对原子性时应放弃重写整个文件。 - 充分利用
WriteFile:纯内容替换场景(如 PID 文件)直接用WriteFile,少写样板代码,还能获得io.ErrShortWrite短写检查。 - 同目录原则:临时文件必须与目标文件同目录,否则
rename可能跨文件系统而丧失原子性——makeTempName已强制如此,自定义封装时不要破坏这一约束。 - 权限参数:
perm直接传给os.OpenFile,dnscrypt-proxy 中统一使用0o644(属主读写、组与其他人只读)。 - 敏感场景注意双文件一致性:当需要数据与签名两个文件同时原子更新时(如
writeSource),safefile 保证的是单个文件的原子性,两个文件之间无法做到一次事务性切换;dnscrypt-proxy 的做法是让签名校验容忍"新数据 + 旧签名"等瞬时组合,并在下一次刷新时自愈。
八、总结
vendor/github.com/dchest/safefile 以极小的 API 面(Create、Commit、Close、WriteFile)实现了"写临时文件 + 原子重命名"这一经典可靠写入模式,并针对 Plan 9 与旧版 Windows 提供了降级的容错替换策略。在 dnscrypt-proxy 中,它是 PID 文件与服务器列表缓存文件一致性的底层保障:无论代理何时崩溃、磁盘何时写满,磁盘上永远不会留下被截断的半成品文件。理解 safefile 的机制,对任何需要安全持久化配置、缓存或状态文件的 Go 服务都有直接借鉴意义。