os.Root 处理符号链接时的安全边界

如果文件名来自用户、归档包或插件配置，单纯用 filepath.Join 拼接路径并不能可靠阻止符号链接越界。Go 1.24 提供的 os.Root 把访问范围绑定到一个目录：Root 的方法会跟随符号链接，但只要解析结果离开根目录，就返回错误。真正需要记住的是，Root.Symlink 创建链接时不会验证 oldname，安全检查要放在“使用链接”的阶段。

先把 os.Root 当成目录能力边界，而不是路径清洗器

os.OpenRoot 接收一个目录并返回 *os.Root。之后的 Open、ReadFile、Stat 等方法都以这个目录为边界处理相对名称。下面的代码适合放在一次任务或请求的最外层：打开失败立即返回，成功后保证关闭 Root。

package main

import (
    "fmt"
    "os"
)

func readConfig(rootDir, name string) ([]byte, error) {
    // Root 持有目录句柄，避免把每次访问重新退化成全局路径拼接。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return nil, fmt.Errorf("打开受限根目录: %w", err)
    }
    // 任务结束时释放目录资源；不要把 Root 跨请求长期缓存。
    defer root.Close()

    // ReadFile 会在解析符号链接后再次确认结果仍位于 root 内。
    data, err := root.ReadFile(name)
    if err != nil {
        return nil, fmt.Errorf("读取根目录内文件 %q: %w", name, err)
    }
    return data, nil
}

这里的关键不是把 name 清理成“看起来安全”的字符串，而是让文件系统解析过程在 Root 的语义下完成。这样，assets/link/config.json 即使经过链接跳转，也不会因为最终目标在根目录外而被悄悄读取。

符号链接能跟随，但不能把访问带出根目录

官方文档对 Root 的描述有三个容易混在一起的点：方法会跟随符号链接；链接不能指向根目录外；符号链接本身不能是绝对路径。因而“存在一个链接”与“可以通过这个链接读取目标”是两件事。

这也是它比“先做 Clean 再拼接”更适合归档解压、模板渲染和插件目录读取的原因：判断对象是最终文件系统解析结果，而不是只看字符串有没有 ..。

Root.Symlink 的 oldname 与 newname 必须分开理解

Root.Symlink(oldname, newname) 的 newname 是要在根目录下创建的链接名，而 oldname 是写入链接的目标文本。Go 文档特别说明，创建时不会验证 oldname，它甚至可以写入一个将来指向根外的目标。因此创建成功只说明链接目录项已建立，不代表目标可被 Root 的读取方法访问。

import (
    "fmt"
    "os"
)

func createAlias(rootDir string) error {
    // 只把链接目录项创建在受限根目录内。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return fmt.Errorf("打开根目录: %w", err)
    }
    defer root.Close()

    // oldname 是链接内容，不是已经完成安全证明的目标。
    if err := root.Symlink("data/current.json", "public/current.json"); err != nil {
        return fmt.Errorf("创建根内别名: %w", err)
    }

    // 只有实际打开或读取时，才验证解析后的目标仍在根目录内。
    if _, err := root.Stat("public/current.json"); err != nil {
        return fmt.Errorf("检查别名目标: %w", err)
    }
    return nil
}

如果业务需要“只允许链接到根内对象”，不要把这个责任寄托在 Symlink 的返回值上。可以在创建前限制输入格式，也要在后续 Open、Stat 或 ReadFile 时把错误当成权限边界信号处理。

生产代码的边界清单

• Root 要在明确的生命周期内创建并关闭；不要把目录句柄泄漏到全局状态。
• 把来自用户或压缩包的文件名视为不可信输入，保留原始错误，便于区分不存在、越界和权限失败。
• Root 不会自动禁止 Linux 挂载边界、/proc 特殊文件或 Unix 设备文件；如果威胁模型要求隔离，还要叠加操作系统级沙箱。
• 官方博客说明该 API 在部分平台仍有符号链接校验的 TOCTOU 限制，高风险写入场景需要额外设计。

常见问题

os.Root 会把所有符号链接都禁用吗？

不会。根内符号链接可以跟随，但最终解析位置不能离开 Root；绝对链接不符合它的限制。

Root.Symlink 返回 nil 就代表目标安全了吗？

不代表。它主要报告链接目录项能否创建，oldname 的目标文本不会在创建阶段被验证；后续访问仍要处理越界错误。

os.Root 能替代容器或沙箱吗？

不能。它解决的是目录树访问边界，不能自动隔离挂载、特殊文件、设备文件或全部操作系统资源。