Go fs.Sub 为什么不能阻止符号链接越界

把 os.DirFS 再交给 fs.Sub，看起来像是把文件系统“锁”在了某个子目录里；但这个理解只对了一半。fs.Sub 改变的是 io/fs 调用方看到的逻辑根，它不会接管操作系统对符号链接的解析，因此目录里的链接仍可能指向子树之外。

只要底层是会跟随符号链接的磁盘文件系统，fs.Sub 就不能充当安全沙箱。它能拒绝名称中的 ..，却无法阻止一个合法名称最终解析到根外目标。

官方地址：https://pkg.go.dev/io/fs#Sub

本文适合正在用 os.DirFS、fs.Sub 提供静态文件、插件资源或租户目录的 Go 开发者。下面先复现现象，再拆开 ValidPath、逻辑前缀和内核路径解析这三层职责，最后给出 Go 1.24 及以上版本可采用的 os.Root。

fs.Sub 限制的是逻辑名称，不是内核解析

fs.Sub(fsys, "public") 返回一个以 public 为逻辑根的 fs.FS。对通用包装实现来说，打开 assets/latest 的效果近似于让原文件系统打开 path.Join("public", "assets/latest")。如果底层文件系统实现了 fs.SubFS，标准库会直接调用底层的 Sub 方法。

这层映射解决的是“调用方从哪个目录开始看”的问题，并没有改变底层文件系统处理符号链接的方式。名称进入 os.DirFS 后，操作系统仍会按磁盘上的目录项解析链接。

所以，Sub(os.DirFS("/srv/site"), "public") 可以隐藏逻辑名称中的 public/ 前缀，却不能保证实际打开的对象仍位于 /srv/site/public。

用最小示例看见越界发生在哪里

下面的程序只在临时目录中构造文件和符号链接。调用 fs.ReadFile 时传入的是合法名称 assets/latest，但链接目标通过磁盘元数据指向了 public 外的 secret.txt。

package main

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

func main() {
    base, err := os.MkdirTemp("", "fs-sub-demo-")
    if err != nil {
        log.Fatal(err)
    }
    defer os.RemoveAll(base)

    assets := filepath.Join(base, "public", "assets")
    if err := os.MkdirAll(assets, 0o755); err != nil {
        log.Fatal(err)
    }
    if err := os.WriteFile(filepath.Join(base, "secret.txt"), []byte("outside public"), 0o600); err != nil {
        log.Fatal(err)
    }

    // 链接位于 public 内，目标却回到 public 外。
    if err := os.Symlink("../../secret.txt", filepath.Join(assets, "latest")); err != nil {
        log.Fatal(err)
    }

    publicFS, err := fs.Sub(os.DirFS(base), "public")
    if err != nil {
        log.Fatal(err)
    }

    data, err := fs.ReadFile(publicFS, "assets/latest")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(string(data))
}

在支持符号链接的平台上，这段代码会读到 outside public。关键不是调用参数里出现了 ..——它没有出现——而是操作系统在打开 assets/latest 时读取了链接目标 ../../secret.txt。

核对点很简单：如果把 latest 换成普通文件，访问会留在 public；如果保留符号链接，真实目标就由底层文件系统决定。这也解释了为什么同一个 fs.Sub 用在纯内存文件系统和磁盘文件系统上，安全含义并不相同。

ValidPath 为什么挡不住符号链接

fs.ValidPath 负责检查 io/fs 名称是否符合词法规则。它会接受 assets/latest，拒绝空名称、绝对路径、空路径段以及包含 .、.. 路径段的名称。

这项检查发生在逻辑名称层。它不读取目录项，不判断某个路径段是不是符号链接，也不解析链接最终落到哪里。一个名称完全合法，只代表它满足 fs.FS.Open 的输入规范，不代表对应磁盘对象一定留在某个物理目录中。

从标准库源码也能看到这条边界：通用 subFS 先调用 ValidPath，再用 path.Join 拼出带子目录前缀的名称。两者都只处理字符串；真正打开文件时，链接是否被跟随仍取决于底层 fs.FS。

哪些场景适合继续使用 fs.Sub

fs.Sub 本身并不是错误设计。它很适合做命名空间裁剪，让调用方以更短的相对名称读取资源。例如：

• 从 embed.FS 中取出某个静态资源子目录；
• 对内存文件系统、测试文件系统或已知不会包含危险链接的只读资源建立子树视图；
• 把第三方函数需要的 fs.FS 接口适配到资源目录，而不是暴露完整前缀。

需要警惕的是把“逻辑根”误当成“安全边界”。只要磁盘目录可能由上传内容、解压结果、插件包、构建产物或低信任用户影响，就不能仅凭 fs.Sub 判断访问不会越界。

采用前可以问三个问题：底层文件系统会不会跟随符号链接？目录内容是否完全可信？根外文件被读取后是否会造成敏感信息泄露？其中任何一个答案不确定，就应升级约束方式。

Go 1.24+ 用 os.Root 约束目录树

Go 1.24 引入了 os.OpenRoot 和 os.Root。官方文档明确说明，Root 的方法只能访问根目录树内的文件；它可以跟随符号链接，但链接不能指向根外，也不能是绝对链接。遇到越界目标时，操作会返回错误。

root, err := os.OpenRoot(filepath.Join(base, "public"))
if err != nil {
    log.Fatal(err)
}
defer root.Close()

// 如果 assets/latest 指向 public 外，这里返回错误。
data, err := root.ReadFile("assets/latest")
if err != nil {
    log.Printf("拒绝越界访问: %v", err)
    return
}
fmt.Println(string(data))

如果后续代码只接受 fs.FS，可以使用 root.FS()：

root, err := os.OpenRoot(filepath.Join(base, "public"))
if err != nil {
    log.Fatal(err)
}
defer root.Close()

data, err := fs.ReadFile(root.FS(), "assets/latest")
if err != nil {
    log.Printf("读取失败: %v", err)
    return
}
fmt.Println(string(data))

这时安全边界来自 os.Root，而不是来自 fs.Sub。如果项目仍支持 Go 1.23 或更早版本，应优先升级；无法升级时，需要采用经过审查的目录约束实现或操作系统级隔离，不能自己用一次 EvalSymlinks 加字符串前缀判断拼出一个“看起来安全”的替代品，因为检查与打开之间还可能发生变化。

os.Root 也不是完整沙箱

os.Root 解决的是名称解析离开指定目录树的问题，但官方文档同时列出了边界：它不禁止跨越文件系统边界、Linux bind mount、访问 /proc 特殊文件或 Unix 设备文件；部分平台还有额外差异。若处理的是高风险不可信内容，仍应结合最小权限、独立用户、容器或其他操作系统隔离。

上线前至少做四项检查：

1. 用根内普通文件确认正常读取；
2. 用根内指向根内的相对符号链接确认业务是否允许；
3. 用指向根外和绝对目标的符号链接确认访问会失败；
4. 根据目标操作系统核对 os.Root 文档中的平台限制。

常见疑问

把用户输入先交给 filepath.Clean 可以吗

不够。清理字符串只能处理名称里的点号和分隔符，无法约束磁盘上已有符号链接的目标。安全边界必须覆盖真实的路径解析过程。

WalkDir 不跟随符号链接，是否就安全

fs.WalkDir 默认不会跟随遍历过程中遇到的符号链接，但这不等于之后用 Open 或 ReadFile 打开同名路径也不会跟随。遍历策略和文件打开策略是两个问题。

只读目录还需要关注吗

如果目录内容和链接都由可信发布流程控制，风险会低很多；但“只读”只说明当前调用方不能修改，不代表目录里原本没有指向根外的链接。仍要根据内容来源决定是否需要 os.Root。

总结

fs.Sub 是命名空间工具，不是 chroot。它会把合法的 io/fs 名称映射到子目录，却不会检查底层符号链接最终落在哪里。可信资源可以继续用 fs.Sub 简化路径；当磁盘目录包含不可信内容并需要明确的目录树边界时，Go 1.24 及以上版本应使用 os.Root，并继续按平台与文件系统特性补足系统级隔离。