Go os.Root 实战：文件上传和解压，别再让 ../ 偷偷逃出目录

做后端久了，文件路径这个坑迟早会遇到：用户上传文件名、解压 zip、读取静态资源、插件目录扫描，看起来只是 filepath.Join 一下，实际一不小心就把 ../ 放进来了。

Go 1.24 引入了 os.Root 和 os.OpenInRoot 这组路径遍历防护 API。我觉得它属于那种“平时不显眼，上线能救命”的功能：它不是让你少写几行代码，而是把文件访问限制在指定根目录里。

这篇按生产场景讲：旧写法哪里危险，os.Root 怎么用，文件上传和解压要怎么改，哪些测试一定要补。

旧写法为什么危险

很多项目里会有这种代码：

func openUserFile(root, name string) (*os.File, error) {
    path := filepath.Join(root, name)
    return os.Open(path)
}

如果 name 是 avatar.png，没问题。如果用户传的是 ../../etc/passwd，事情就开始不妙了。你可以先做 Clean、判断前缀、拒绝绝对路径，但这类手写防护很容易漏掉符号链接、Windows 路径、竞态和边界差异。

安全代码最怕“我觉得已经处理了”。文件路径尤其如此，它既有字符串层面的路径规则，又有真实文件系统里的符号链接和目录变化。

OpenInRoot：只打开根目录内的文件

如果只是一次性打开某个根目录下的文件，可以用 os.OpenInRoot：

func openUserFile(root, name string) (*os.File, error) {
    return os.OpenInRoot(root, name)
}

它表达的意思很直接：我要打开 root 里面的 name，不允许这个名字逃出 root。这样代码意图比自己拼路径清楚很多。

这不代表你可以完全不校验用户输入。文件名长度、空字符串、业务允许的扩展名、是否覆盖已有文件，这些还是业务规则。但“不能逃出根目录”这件事，应该交给更可靠的 API。

os.Root：多次操作时更合适

如果一个请求里要多次访问同一个根目录，比如列目录、打开多个文件、创建目标文件，可以先打开根：

r, err := os.OpenRoot(uploadDir)
if err != nil {
    return err
}
defer r.Close()

f, err := r.Open(name)
if err != nil {
    return err
}
defer f.Close()

Root 的好处是把“根目录”变成了一个明确对象。以后所有文件操作都围绕这个 root 做，而不是每次重新拼一个路径字符串。

我会把它放在文件服务、附件服务、静态资源服务、解压任务里。只要这段代码处理不可信路径，就值得考虑。

文件上传怎么改

上传场景里，用户给你的文件名通常不可信。即使前端说只传文件名，后端也不能相信。

func saveUpload(root string, filename string, src io.Reader) error {
    if filename == "" || strings.Contains(filename, " ") {
        return fmt.Errorf("bad filename")
    }

    r, err := os.OpenRoot(root)
    if err != nil {
        return err
    }
    defer r.Close()

    dst, err := r.OpenFile(filename, os.O_CREATE|os.O_WRONLY|os.O_EXCL, 0600)
    if err != nil {
        return err
    }
    defer dst.Close()

    _, err = io.Copy(dst, src)
    return err
}

这里有两个点：第一，用 Root.OpenFile 把文件限制在根目录里；第二，用 O_EXCL 避免不小心覆盖已有文件。安全不是单个 API 完成的，而是一组边界一起收紧。

解压 zip 更要小心

解压是路径遍历事故高发区。压缩包里的文件名可以是 ../../app.conf，也可以藏各种目录结构。老代码常见写法是：

target := filepath.Join(destDir, file.Name)
// 然后创建目录或文件

更稳的做法是把目标目录打开成 Root，然后每个条目都在 root 里创建。业务上还要限制条目数量、单文件大小、总大小、是否允许目录、是否允许符号链接。

我建议解压场景至少有这几条规则：拒绝绝对路径，拒绝空名字，限制总大小，限制文件数量，默认不解压符号链接，所有文件创建都走 Root。

符号链接边界要讲清楚

路径遍历不只有 ../。符号链接也很关键。比如根目录里有个 logs 指向外部目录，如果代码跟着它跑出去，就可能访问到不该访问的文件。

os.Root 的价值之一就是处理这类“看起来在目录里，实际可能跑出去”的情况。你仍然需要决定业务上是否允许符号链接。如果不允许，就在写入和解压时直接拒绝；如果允许，也要清楚它的安全边界。

不要只做字符串前缀判断

这类代码我见过太多：

path := filepath.Join(root, name)
if !strings.HasPrefix(path, root) {
    return fmt.Errorf("bad path")
}

它看起来简单，但很脆。路径分隔符、大小写、符号链接、根目录末尾斜杠、清理后的路径，都可能让判断变复杂。更糟糕的是，它把文件系统安全问题压成了字符串问题。

能用 OpenInRoot 或 Root，就不要靠字符串前缀硬扛。

迁移老项目怎么做

如果仓库里已经有很多 filepath.Join(root, name)，我不建议全量机械替换。比较稳的顺序是：

• 先搜索处理用户输入路径的入口，比如上传、下载、解压、静态文件。
• 给这些入口补路径穿越测试，覆盖 ../、绝对路径、空路径、符号链接。
• 把高风险入口改成 OpenInRoot 或 os.Root。
• 保留业务校验，比如扩展名、大小、覆盖策略。
• 灰度上线，重点看文件找不到、权限错误、历史兼容问题。

安全改造最怕一刀切。先改最危险的入口，跑出经验，再扩大范围。

测试用例别偷懒

我会至少补这些测试：

• avatar.png 能正常打开。
• ../secret.txt 被拒绝。
• /etc/passwd 这类绝对路径被拒绝。
• 目录内符号链接指向目录外时不能逃逸。
• Windows 风格路径在对应平台下行为符合预期。
• 文件不存在、权限不足时错误能被正确返回。

这些测试不是为了追求覆盖率好看，而是为了防止以后有人把 Root 又改回 filepath.Join。

我的 review 清单

• 这段路径是否来自用户输入、压缩包、配置或外部系统。
• 是否用字符串拼接或前缀判断承担安全边界。
• 是否可以改成 os.OpenInRoot 或 os.OpenRoot。
• 是否处理了符号链接、绝对路径、空路径和 ../。
• 上传是否限制大小、扩展名和覆盖策略。
• 解压是否限制总大小、文件数量和符号链接。
• 测试里是否包含路径遍历攻击样例。

最后说句实在话

文件路径安全不是炫技题，它是后端里很朴素也很容易被低估的边界。以前大家靠 Clean、Join、前缀判断和经验拼一套防护，现在 Go 标准库给了更明确的工具，就应该用起来。

我的建议是：只要代码要打开“不可信名字”对应的文件，就先想 os.Root。别等一次上传漏洞或解压事故之后，再回头补这条线。