Go os.Root.OpenFile 如何限制写入范围：相对路径校验与文件创建边界

当服务需要把用户上传内容写进固定目录时，直接把外部文件名交给 filepath.Join 并不能自动阻止 .. 或越界符号链接。Go 1.24 的 os.Root 提供了更明确的边界：先打开一个根目录，再用 Root.OpenFile 接受相对路径，让创建和写入动作都在这棵目录树内完成。

核心做法是让 os.OpenRoot 持有可信目录，再把不可信文件名作为 root.OpenFile(name, flag, perm) 的相对路径；一旦路径或符号链接试图离开根目录，调用就返回错误。

先把固定目录变成可操作的根

下面的示例把 /srv/app/uploads 作为可信目录。外部输入只允许提供类似 avatars/u-42.png 的相对名称，不能把它改写成另一个绝对位置。

package upload

import (
    "errors"
    "fmt"
    "io"
    "os"
)

func SaveUpload(rootPath, name string, src io.Reader) error {
    root, err := os.OpenRoot(rootPath)
    if err != nil {
        return fmt.Errorf("open upload root: %w", err)
    }
    defer root.Close()

    file, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
    if err != nil {
        if errors.Is(err, os.ErrExist) {
            return fmt.Errorf("upload already exists: %w", err)
        }
        return fmt.Errorf("open upload file: %w", err)
    }
    defer file.Close()

    if _, err := io.Copy(file, src); err != nil {
        return fmt.Errorf("write upload: %w", err)
    }
    return nil
}

这里的关键不是把路径字符串“清理得更漂亮”，而是把信任边界交给 Root。OpenFile 的三个参数分别表达相对文件名、打开标志和权限位：成功后返回文件句柄，后续写入仍然要检查 io.Copy 的错误。

创建标志决定重名时发生什么

os.O_CREATE 表示文件不存在时创建，os.O_EXCL 再把重名视为失败。上传场景通常希望保留已有文件，因此不能只看返回的文件句柄是否非空，而要用 errors.Is(err, os.ErrExist) 区分“目标已存在”和“根目录打不开”等其他错误。

file, err := root.OpenFile(
    "avatars/u-42.png",
    os.O_WRONLY|os.O_CREATE|os.O_EXCL,
    0o600,
)
if errors.Is(err, os.ErrExist) {
    // 交给上层返回冲突，不覆盖旧文件。
}

如果业务明确允许覆盖，可以去掉 os.O_EXCL，但这应是业务决策，不是为了绕过错误而随手修改标志。权限参数也只描述新文件的权限位；最终效果还会受到进程的 umask 等操作系统规则影响。

越界路径和符号链接要按失败处理

Root 的方法接受相对路径，可以包含不越界的目录组件；如果某个组件通过 .. 或符号链接指向根目录之外，调用会返回错误。应用层不应该先把输入拼成绝对路径再调用普通的 os.OpenFile，也不应把越界错误当作“自动修正成功”。

// 这些输入都应由 OpenFile 的错误路径交给上层处理：
// ../outside.txt
// avatars/link-to-outside.txt  // link 指向根目录外
file, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
if err != nil {
    return fmt.Errorf("rejected relative name %q: %w", name, err)
}

这项能力解决的是“操作必须留在某个目录树内”的场景，不等同于完整的权限沙箱：官方文档仍提醒要关注文件系统边界、绑定挂载、特殊文件以及不同 GOOS 的实现差异。若程序运行在 GOOS=js 或 WASI 等环境，应该按该平台的说明重新评估保证范围。

并发使用 Root，不等于共享文件写入

Root 可以被多个 goroutine 同时使用，因此可以把一个根目录交给请求处理函数。但每个请求仍应获得自己的文件句柄；同一个文件的覆盖、追加、临时文件替换和内容一致性，需要由应用层用唯一命名、创建标志或更高层协调来保证。

func SaveMany(root *os.Root, names []string, src func(string) io.Reader) error {
    for _, name := range names {
        file, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
        if err != nil {
            return err
        }
        _, copyErr := io.Copy(file, src(name))
        closeErr := file.Close()
        if copyErr != nil {
            return copyErr
        }
        if closeErr != nil {
            return closeErr
        }
    }
    return nil
}

这个小函数还保留了关闭错误，适合把它作为最小检查点。生产代码若要处理部分成功，还要记录已经创建的文件并决定是否清理；这属于事务策略，不能由 OpenFile 自动完成。

最后用四个问题检查实现

• 根目录是否由可信配置提供，并且在进入请求循环前成功调用了 os.OpenRoot？
• 传给 Root.OpenFile 的是否是相对文件名，而不是重新拼出的绝对路径？
• 创建、写入、关闭三个阶段是否分别检查了错误，并明确处理 os.ErrExist？
• 是否把 Root 的目录边界误认为完整的操作系统沙箱，并针对目标 GOOS 做过核对？

常见问题

Root.OpenFile 能替代所有文件权限检查吗？

不能。它主要限制路径所在的目录树，调用者仍需负责身份授权、文件名策略、大小限制和内容校验。

为什么不用 filepath.Clean 后再 os.OpenFile？

清理字符串只能处理词法形式，不能单独解决符号链接和检查与使用之间的竞态；需要目录边界时，应优先使用 os.Root 或 os.OpenInRoot。

Root.Close 后还能继续调用 OpenFile 吗？

不能把关闭后的根当作可用对象。应让 Root 的生命周期覆盖所有文件操作，并在所有句柄关闭后再关闭 Root。

参考资料

• Go os package 文档
• Go Blog：Traversal-resistant file APIs
• Go 1.24 Release Notes