Go DirFS 怎样限制文件访问根目录

如果你只想让业务代码读取某个目录下的文件，os.DirFS(root) 是 Go 标准库里很顺手的入口：它把宿主机目录包装成 io/fs.FS，上层只传 docs/readme.md 这样的相对路径，不再直接拼接绝对路径。但要先记住一个容易被忽略的边界：DirFS 限制的是文件系统接口的路径命名空间，不是自动完成的 chroot。目录里如果有指向外部的符号链接，DirFS 仍可能跟随它。

本文按一个文件预览服务的实际取舍来写：普通应用用 DirFS 统一读取接口；外部输入先遵守 io/fs 的路径规则；目录内容不完全可信、必须防止符号链接逃逸时，在 Go 1.24 及以后使用 os.OpenRoot(root).FS()。官方地址：https://pkg.go.dev/os#DirFS

想限制“调用方只能从某个根目录开始找文件”，用 os.DirFS；想让根目录里的符号链接也不能把访问带到外部，再用 os.OpenRoot(...).FS()。两者都要求传入 io/fs 规定的相对路径，不能把用户字符串直接当成宿主机路径。

先看 DirFS 建立的是什么边界

os.DirFS(root) 返回一个 fs.FS。当调用方执行 fsys.Open("docs/readme.md") 时，底层访问相当于从 root 开始寻找 docs/readme.md。这让文件读取函数可以只依赖抽象的 fs.FS，不需要知道根目录的绝对路径。

它的使用方式很短，但建议把根目录的检查放在创建阶段。空字符串不是合法的 DirFS 根目录；如果根目录来自配置，先明确它代表的目录，再把这个 fs.FS 传给业务层。

package main

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

func main() {
    root := "/srv/app/public"
    publicFS := os.DirFS(root)

    // 业务层只接收相对的 fs 路径，不再拼接宿主机绝对路径。
    data, err := fs.ReadFile(publicFS, "docs/readme.txt")
    if err != nil {
        // 保留 PathError，调用方可以继续使用 errors.Is 判断原因。
        fmt.Printf("读取失败: %v\n", err)
        return
    }
    fmt.Printf("读取到 %d 字节\n", len(data))
}

这里的“限制”是接口层限制：调用者拿到的是以 public 为根的文件系统，而不是一个可以随意传入绝对路径的 os.Open 包装器。fs.ReadFile、fs.Stat 和 fs.WalkDir 都可以复用这个对象。

让外部文件名符合 io/fs 路径规则

fs.FS.Open 的名字不是操作系统路径。它必须是 UTF-8、无根、使用正斜杠分隔的路径；除了根目录特殊名字 .，不能出现 ..、. 或空路径元素。因此 /etc/passwd、../secret.txt、docs/../secret.txt 和 docs\\secret.txt 都不应该直接交给文件系统接口。

可以用 fs.ValidPath 做第一道明确的输入判断。它不会替你决定业务上允许哪些扩展名、文件大小或目录层级，但能把路径语法边界和业务规则分开。

func readPublicFile(publicFS fs.FS, name string) ([]byte, error) {
    // ValidPath 只接受 io/fs 的相对路径；先挡住绝对路径和上级跳转。
    if !fs.ValidPath(name) {
        return nil, fmt.Errorf("非法文件名 %q", name)
    }

    // 业务规则可以继续收窄允许的目录或后缀。
    if !strings.HasPrefix(name, "docs/") {
        return nil, fmt.Errorf("文件必须位于 docs 目录")
    }
    return fs.ReadFile(publicFS, name)
}

这个示例需要额外导入 fmt 和 strings。如果文件名是由 URL 路径转换来的，还要在转换层明确处理编码和斜杠，不要用 filepath.Join 把一段用户输入重新拼成宿主机路径后再传给 fs.FS。

把 DirFS 接到遍历和子目录接口

当服务只负责公开 public/docs 时，可以先创建整个根目录的 DirFS，再通过 fs.Sub 暴露子树。这样函数签名仍然是 fs.FS，调用方不会把 public/docs 误当成绝对路径。

func docsFS(root string) (fs.FS, error) {
    // DirFS 把 root 变成 fs.FS；Sub 只改变调用方看到的相对起点。
    allFiles := os.DirFS(root)
    docs, err := fs.Sub(allFiles, "docs")
    if err != nil {
        return nil, fmt.Errorf("创建 docs 子树: %w", err)
    }
    return docs, nil
}

func listNames(files fs.FS) error {
    // WalkDir 的根用 "."，表示从当前 fs.FS 的逻辑根开始遍历。
    return fs.WalkDir(files, ".", func(path string, entry fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        fmt.Println(path)
        return nil
    })
}

fs.Sub 只是改变了路径视图。官方文档特别提醒：fs.Sub(os.DirFS("/"), "prefix") 与 os.DirFS("/prefix") 在符号链接边界上没有本质区别。也就是说，子树不是额外的安全沙箱。

为什么 DirFS 不能单独防止符号链接越界

假设 public/downloads/latest 是一个符号链接，实际指向根目录之外的目录。DirFS 看到的名字仍然是 downloads/latest，但底层打开操作会跟随这个链接。于是“名字在根目录内”和“最终访问对象在根目录内”是两个不同问题。

因此，下面两件事不要混为一谈：

• 路径规范化：拒绝绝对路径、上级跳转、空路径元素。
• 对象边界约束：即使目录中存在符号链接，也不能把访问带出根目录。

前者可以由 fs.ValidPath 配合业务规则完成；后者不能靠字符串的 path.Clean 或简单前缀判断可靠完成，因为符号链接解析发生在文件系统访问阶段。

Go 1.24+ 需要更强边界时使用 Root.FS

如果文件树里可能出现不受你完全控制的内容，官方文档建议使用 os.Root。Go 1.24 起可以用 os.OpenRoot 打开根目录，再调用 Root.FS() 获得一个 fs.FS：

func openConfinedFS(rootPath string) (fs.FS, func() error, error) {
    root, err := os.OpenRoot(rootPath)
    if err != nil {
        return nil, nil, fmt.Errorf("打开根目录: %w", err)
    }

    // Root 持有操作系统资源；由调用方在服务退出或任务结束时关闭。
    closeRoot := func() error { return root.Close() }
    return root.FS(), closeRoot, nil
}

Root.FS 仍然遵循 io/fs 的相对路径规则，所以之前的 fs.ValidPath 和业务白名单依然有价值。区别在于，Root 的文件系统实现会把符号链接解析限制在这个根目录树内。使用时要把 Root.Close 的生命周期安排清楚，不能在返回 fs.FS 后马上关闭 Root。

如果只是一次性打开文件，也可以使用 Go 1.24 起的 os.OpenInRoot(dir, name)；它直接表达“在某个目录中打开文件”，并在名字指向目录外时返回错误。需要复用 fs.ReadFile、fs.WalkDir 等抽象接口时，Root.FS() 更合适。

DirFS、Sub 和 Root.FS 怎么选

常见问题

DirFS 能不能接收绝对路径？

不应该。fs.FS 的 Open 名称是相对的 slash-separated 路径；先用 fs.ValidPath 拒绝绝对路径和上级跳转。

把路径 Clean 后再传给 DirFS 就安全了吗？

不安全。清理字符串只能处理文本中的 .. 等片段，不能解决符号链接指向根目录外部的问题。需要对象边界时使用 os.Root 方案。

fs.Sub 会不会自动隔离符号链接？

不会。它主要提供一个子树视图；在底层是 DirFS 时，符号链接边界仍然继承 DirFS 的限制。

Root.FS 创建后能马上关闭 Root 吗？

不能把它当成无资源的纯值。Root.FS 返回的文件系统依赖 Root 的生命周期，应该在所有读取结束后再调用 Root.Close。

总结

Go DirFS 限制文件访问根目录的核心，是把绝对目录变成遵守 io/fs 约定的文件系统对象，再让业务代码只使用相对文件名。最小组合是 os.DirFS 加 fs.ValidPath；子目录视图可以加 fs.Sub。如果根目录中存在不可信符号链接，别把 DirFS 当成安全沙箱，升级到 Go 1.24+ 的 os.OpenRoot(...).FS()，并把 Root 的关闭时机纳入资源管理。