Go bufio.Reader.Peek 怎样读取受限根目录中的文件

我在处理“用户只能读取某个资料目录”的 Go 工具时，最容易混在一起的是两个问题：文件到底能不能越出根目录，以及读取文件头之后还要不要继续消费完整内容。前一个问题应该交给 os.Root 处理，后一个问题才是 bufio.Reader.Peek 的用武之地。

在 Go 1.24 及以上，先用 os.OpenRoot 固定允许访问的目录，再用 Root.Open 打开相对文件；把返回的文件交给 bufio.NewReader 后，Peek 可以查看前几个字节而不推进读取位置。不要把 Peek 当作目录安全边界，真正的边界来自 os.Root。

本文的示例只做“读取文件头并继续顺序读取”这件事，不会把文件内容打到日志里，也不把路径检查结果包装成已经执行过的运行证据。

先把根目录边界固定下来

os.OpenRoot 打开一个目录并返回 *os.Root。之后的 Root.Open、Root.Stat 等方法都以这个根为边界；如果传入的路径组件指向根目录外，调用会返回错误。官方文档还特别说明，根对象会限制越界的符号链接，但它不是完整的 chroot：文件系统边界、Linux bind mount、/proc 特殊文件和 Unix 设备文件仍然需要额外的部署策略。

根对象的生命周期要和文件读取任务一致。打开成功后立即安排 Close，不要把一个长期持有的根对象塞进全局变量；这样更容易控制文件描述符，也能让配置变更后的任务边界清楚。

用 Root.Open 打开相对路径

应用层最好把“根目录”和“相对文件名”分成两个参数。调用方只提交类似 incoming/report.txt 的相对名字，不能通过拼接字符串重新构造一个绝对路径。即使调用方传入 ../secrets.txt 或指向根外的符号链接，最终也要让 Root.Open 做边界判断。

下面的函数先建立根目录，再从根中打开文件。它没有把路径完整打印出来，生产日志里只保留业务请求编号更稳妥。

package main

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

// readPreview 只接受根目录内的相对文件名，并返回文件头的预览文本。
func readPreview(rootDir, relativeName string) (string, error) {
    // Root 把允许访问的目录固定下来，越界检查由 Root.Open 继续完成。
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return "", fmt.Errorf("打开受限根目录失败: %w", err)
    }
    defer root.Close() // 任务结束时释放根对象持有的目录句柄

    // 只从根对象打开相对文件，不把 rootDir 和 relativeName 拼成绝对路径。
    file, err := root.Open(relativeName)
    if err != nil {
        return "", fmt.Errorf("打开根目录内文件失败: %w", err)
    }
    defer file.Close() // 关闭文件描述符，避免批处理任务持续占用资源

    // 缓冲区要大于本次 Peek 的长度，否则会得到 ErrBufferFull。
    reader := bufio.NewReaderSize(file, 64)
    head, err := reader.Peek(16)
    if err != nil {
        // 短文件可能同时返回已有字节和 io.EOF；已有内容仍可作为预览。
        if !errors.Is(err, io.EOF) || len(head) == 0 {
            return "", fmt.Errorf("读取文件头失败: %w", err)
        }
    }

    // Peek 不推进读取位置，先复制成字符串，再继续从同一个 reader 读取。
    preview := string(head)
    return preview, nil
}

func main() {
    // 这里的根目录和文件名应来自受控配置或已授权的请求参数。
    preview, err := readPreview("/srv/app-data", "incoming/report.txt")
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("文件头预览: %q\n", preview)
}

这个例子有一个刻意保留的细节：Peek 返回的字节只保证在下一次读取前有效。如果后面要继续调用 Read、ReadString 或 Discard，需要像示例一样先把预览复制成字符串，不能把返回的切片长期保存。

理解 Peek 的“看一眼但不前进”

bufio.Reader.Peek(n) 会尝试让缓冲区里至少有 n 个字节，并返回下一段数据，但不会推进 reader 的当前位置。它适合判断 BOM、文件格式前缀或协议头，然后从同一个 reader 继续做真正的解析。

例如，文件头预览后还要逐行读取，可以继续使用同一个 reader：

// inspectAndReadLine 先查看前缀，再从同一缓冲读取器消费一行。
func inspectAndReadLine(file *os.File) (string, string, error) {
    reader := bufio.NewReaderSize(file, 128)

    // 预览切片只在下一次读取前有效，所以立即转成 string。
    prefix, err := reader.Peek(4)
    if err != nil && !errors.Is(err, io.EOF) {
        return "", "", fmt.Errorf("查看文件前缀失败: %w", err)
    }
    preview := string(prefix)

    // Peek 没有前移游标，这里仍然可以读到文件开头的完整一行。
    line, err := reader.ReadString('\n')
    if err != nil && !errors.Is(err, io.EOF) {
        return preview, "", fmt.Errorf("读取首行失败: %w", err)
    }
    return preview, line, nil
}

如果只想判断格式，不需要把整行读出来，也可以在确认前缀后调用解析器。但要注意：Peek 的参数必须小于等于 reader 的缓冲容量，否则会返回 bufio.ErrBufferFull。缓冲区加大只解决“预览长度超过缓冲”的问题，不会改变根目录权限，也不会让一个不可读文件变得可读。

把短文件、越界和缓冲区错误分开

这类代码在生产环境里通常不是因为 API 不会用，而是把几种不同性质的错误混成一类。可以按下面的顺序判断：

尤其不要把所有错误都重试。越界路径和权限错误重试没有意义，反而可能把异常请求放大；只有底层存储的临时故障有明确重试策略时，才应该在更外层处理。

发布前的加固检查

1. 确认构建环境使用 Go 1.24 或更高版本；os.OpenRoot 和 os.Root 是这套写法的基础。
2. 根目录使用专门的数据目录，避免把整个系统目录作为 root 交给业务代码。
3. 让请求只携带相对文件名，并对文件名长度、总读取量和并发数设置业务限制。
4. 把 Peek 的预览长度设为固定的小值；不要因为方便调试而把整文件塞进缓冲区。
5. 日志只保留请求编号、相对路径的脱敏摘要和错误分类，避免输出文件头中的敏感数据。
6. 如果运行在容器或特殊平台，仍要检查挂载、设备文件和平台差异；Root 不是替代操作系统权限模型的万能开关。

官方文档入口：https://pkg.go.dev/os、https://pkg.go.dev/bufio、https://pkg.go.dev/io。

常见追问

Peek 之后再 Read 会不会跳过前几个字节？

不会。Peek 本身不推进 reader 的位置，后续 Read 仍然从同一段数据开始；但 Peek 返回的字节切片只在下一次读取前有效。

把 os.DirFS 当成受限根目录可以吗？

不能直接等同。官方文档明确提示，DirFS 对根外符号链接并不提供 chroot 式保护；需要目录树边界时，应优先使用 Root.FS 或 Root 的文件方法，并结合部署权限继续收窄访问面。

Peek 的长度比文件短时一定返回 nil 吗？

不一定。文件不足请求长度时，Peek 可能返回已经读到的字节以及说明短读的错误，常见的是 io.EOF。代码应同时判断返回字节数和错误类型。