os.Root 路径校验仍失败时的相对路径规则

我第一次把一段文件下载代码迁到 os.Root 时，保留了原来的习惯：先用 filepath.Join 把基础目录和用户文件名拼成完整路径，再把结果传给 root.Open。路径看上去完全正确，校验也做过，却还是被拒绝。问题不在文件是否存在，而在于 Root 的参数语义已经变了。

os.OpenRoot(base) 已经把 base 设成访问边界，后续方法接收的是相对于这个根的名称。因此应传 assets/logo.png，而不是再次传入 /srv/app/assets/logo.png。如果路径来自 io/fs 约定，先用 filepath.Localize 转成本地路径；如果本来就是本地操作系统路径，可用 filepath.IsLocal 做词法预检，最后仍由 Root 完成受限访问。

最常见的失败：把根目录又拼了一遍

下面的写法在普通 os.Open 中很常见，但迁到 Root 后就把“完整路径”误当成了“根内名称”。在 Unix 上，拼接结果往往是绝对路径；而 Root 不允许方法参数引用根目录之外的位置。

package files

import (
    "os"
    "path/filepath"
)

func openWrong(base, userPath string) (*os.File, error) {
    root, err := os.OpenRoot(base)
    if err != nil {
        return nil, err
    }
    defer root.Close()

    // 错误：这里得到的是带 base 的操作系统路径，
    // 但 Root.Open 只接收相对于 root 的名称。
    full := filepath.Join(base, userPath)
    return root.Open(full)
}

修正时不要想办法“让完整路径通过校验”，而是删掉重复的根目录。base 只交给 os.OpenRoot，外部文件名只作为根内名称交给 root.Open。

func openRelative(base, userPath string) (*os.File, error) {
    root, err := os.OpenRoot(base)
    if err != nil {
        return nil, err
    }
    defer root.Close()

    // 先做便于提示用户的词法检查；真正访问仍由 Root 约束。
    if !filepath.IsLocal(userPath) {
        return nil, fmt.Errorf("路径必须是根目录内的相对路径: %q", userPath)
    }

    // 正确：不再把 base 拼进来。
    return root.Open(userPath)
}

os.Root 到底限制了什么

Go 1.24 引入的 os.Root 代表本地文件系统中的一个目录。官方文档明确说明：Root 的方法只能访问根目录树下的文件和目录；名称的任意组成部分如果指向根外位置，就返回错误。它会跟随符号链接，但符号链接不能指向根外，链接本身也不能是绝对路径。

这里有一个容易被“清理路径”经验误导的细节：Root 并不是看到任何 .. 都拒绝。只要解析后没有逃出根目录，类似 a/../b 的名称可以被允许；. 也可以引用根目录本身。真正被拒绝的是会越过根边界的名称、绝对路径，以及指向根外的符号链接。

这也是我后来不再把 strings.Contains(name, "..") 当安全规则的原因。它会误伤合法的根内解析，也没有覆盖绝对路径、Windows 保留设备名和符号链接等边界。

把路径来源分开处理

另一个高频混淆来自“路径”这个词其实有两套约定。io/fs 使用斜杠分隔、跨平台一致的路径名；path/filepath 处理的是当前操作系统路径。两者不要靠手工替换斜杠混用。

路径来自 io/fs、归档目录或 URL 风格字段

如果上游约定名称必须满足 io/fs.ValidPath，使用 filepath.Localize 最直接。它要求输入是有效的斜杠分隔路径，并转换为当前系统能表达的本地路径；返回成功时，结果保证满足 filepath.IsLocal。

func openFSName(root *os.Root, fsName string) (*os.File, error) {
    // Localize 同时验证 io/fs 路径格式并转换成当前系统路径。
    localName, err := filepath.Localize(fsName)
    if err != nil {
        return nil, fmt.Errorf("无效的 io/fs 路径 %q: %w", fsName, err)
    }

    // localName 已保证是本地相对路径，最终边界仍由 Root.Open 执行。
    f, err := root.Open(localName)
    if err != nil {
        return nil, fmt.Errorf("无法在受限根目录打开 %q: %w", localName, err)
    }
    return f, nil
}

io/fs.ValidPath 的规则比一般本地相对路径更严格：. 可表示根，但空字符串、..、前导斜杠、尾随斜杠、空路径段，以及路径段中的 . 或 .. 都无效。它适合规范化的 FS 名称，不应拿来断言所有 Root 可接受的本地名称。

路径本来就是本地操作系统路径

这时使用 filepath.IsLocal。它只做词法分析：路径非空、不是绝对路径、按当前平台解释时位于当前目录子树内；Windows 上还会排除 NUL 等保留名称。返回 true 时，filepath.Clean 的结果不会含有 .. 路径段。

但 IsLocal 不查看文件系统，也不考虑已存在的符号链接。因此它适合尽早返回友好的“输入格式错误”，不能替代 Root.Open 的访问边界。

为什么只做字符串校验还不够

如果攻击者能影响根目录内的文件或符号链接，先校验、后打开的两步方案可能遇到 TOCTOU：校验结束后，路径组成部分被替换成符号链接，普通 os.Open 随后就可能访问另一个位置。filepath.EvalSymlinks 再加 IsLocal 也无法从根本上消除两步之间的竞态。

os.Root 的价值正在这里：它把“只允许访问这个目录树”放到实际文件操作中处理。官方建议的经验规则很实用——如果代码正在用 filepath.Join 把固定目录与外部文件名组合起来，而且不应该访问固定目录之外，通常就应该考虑 os.Root 或 os.OpenInRoot。

不过 Root 不是完整沙箱。官方文档说明，它不会阻止跨文件系统边界、Linux bind mount、/proc 特殊文件或 Unix 设备文件的访问；GOOS=js 下还受 Node.js 文件系统 API 限制，符号链接校验可能存在 TOCTOU 风险。Unix 上的部分元数据操作也有单独的竞态注意事项。对普通下载目录、归档解压目录和租户文件区，它提供的是针对路径遍历的边界，不是隔离所有内核资源的安全容器。

按失败阶段定位，不要把所有错误都叫路径非法

我现在会把错误分成三层，这比对错误字符串做模糊匹配稳定得多：

1. 来源格式错误：filepath.Localize 返回错误，说明输入不是合法的 io/fs 路径，或当前系统无法表示它。
2. 本地词法错误：filepath.IsLocal 返回 false，说明输入为空、是绝对路径、词法上会逃出当前目录，或触发 Windows 保留名规则。
3. 受限访问错误：root.Open 返回错误，可能是越界、符号链接逃逸、文件不存在、权限不足或普通 I/O 错误。继续用 errors.Is 判断 fs.ErrNotExist、fs.ErrPermission 等具体类别。

func readRootFile(root *os.Root, name string) ([]byte, error) {
    if !filepath.IsLocal(name) {
        return nil, fmt.Errorf("不是可接受的本地相对路径: %q", name)
    }

    data, err := root.ReadFile(name)
    if err == nil {
        return data, nil
    }

    // 用标准错误类别区分不存在和权限问题，不依赖平台错误文本。
    switch {
    case errors.Is(err, fs.ErrNotExist):
        return nil, fmt.Errorf("根目录内没有该文件 %q: %w", name, err)
    case errors.Is(err, fs.ErrPermission):
        return nil, fmt.Errorf("没有权限读取 %q: %w", name, err)
    default:
        return nil, fmt.Errorf("受限根目录读取失败 %q: %w", name, err)
    }
}

如果输入包含很多目录组成部分或大量 ..，Root 的解析成本可能明显高于普通文件操作。Go 官方博客建议，对需要限制操作成本的程序，可先用 filepath.Clean 去掉多余的双点号组成部分，并限制目录层数；但这个优化不能替代 Root 的安全边界。

什么时候直接用 OpenInRoot

只打开一次文件时，os.OpenInRoot(base, name) 更简洁；需要在同一根目录执行多次读取、创建、删除或子根操作时，复用 os.Root 更清楚。反过来，如果命令行工具本来就允许用户指定任意输出位置，那么 Root 反而会错误收窄合法功能。

我的选择标准很简单：路径是否来自外部，以及业务是否明确承诺“只能访问某个目录树”。两个条件都成立时使用 Root；只有第一个条件但业务允许任意位置时，只做符合产品语义的路径处理，不强行套受限根。

常见问题

root.Open 可以传 ./a.txt 吗？

Root 允许引用根目录本身和不越界的相对组成部分，但如果上游走 io/fs.ValidPath，路径段中的 . 会被该规则拒绝。想要一致输入，可先按来源规范化，再把结果传给 Root。

为什么 filepath.IsLocal 通过，Root 仍可能失败？

IsLocal 只判断字符串的词法性质，不检查文件是否存在、权限是否足够，也不考虑符号链接。Root 访问时仍可能因为这些实际文件系统条件返回错误。

可以先 filepath.Rel 把绝对路径转换成相对路径吗？

只有当绝对路径来自可信内部逻辑，而且业务确实要验证它位于该根下时才考虑这样做。对外部输入，直接接受根内相对名称更清楚；先接收绝对路径再转换，容易掩盖调用方传参契约错误。

Root 会阻止挂载点和设备文件吗？

不会。Root 主要防御路径组成部分和符号链接导致的根外访问，不禁止跨挂载点、bind mount、/proc 特殊文件或 Unix 设备文件。需要更强隔离时，应结合操作系统权限、容器或沙箱机制。

参考资料

• Go 标准库：os.Root
• Go 标准库：filepath.IsLocal
• Go 标准库：filepath.Localize
• Go 标准库：io/fs.ValidPath
• Go Blog：Traversal-resistant file APIs