Go 文件服务怎么把访问范围限制在指定目录

文件下载接口常见的旧写法是把固定目录和用户传入的文件名交给 filepath.Join，再调用 os.Open。问题在于，路径清洗并不能完整覆盖符号链接和并发替换带来的逃逸。Go 1.24 起，可以用 os.Root 把文件操作绑定到一个目录树，再让请求文件名只在这个边界内解析。

文件服务应在启动时打开 os.OpenRoot，请求到达后先用 filepath.Localize 转换并检查名称，最后只调用 root.Open；不要再把外部文件名拼成新的绝对路径交给 os.Open。

一、把目录边界交给 os.Root

os.OpenRoot 在启动阶段打开一个目录并返回 *os.Root。之后的 Open、Create、Stat 等方法都接收相对根目录的名称。名称中的 .. 可以在根目录内部回退，但不能越过根；符号链接也不能指向根外位置。

因此，服务启动时只打开一次根目录，并在服务退出时关闭它。这个生命周期比每次请求都拼接绝对路径更清晰，也避免把“目录前缀相同”误当成“访问范围受限”。

二、在请求入口规范化用户路径

URL 查询参数通常使用 /，而 Windows、Unix 等平台对本地路径的解释不同。Go 1.23 提供的 filepath.Localize 可以把斜杠分隔的路径转换为当前系统路径；转换失败时，输入不是一个可接受的本地名称。再交给 Root 打开，形成“入口拒绝明显异常、根对象处理目录逃逸”的两层约束。

下面的示例只服务文件，不把目录列表当成下载结果。代码里的路径来自 name 查询参数，生产环境还可以在此处增加扩展名、文件大小和访问日志策略。

package main

import (
	"errors"
	"log"
	"net/http"
	"os"
	"path/filepath"
)

func fileHandler(root *os.Root) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		name := r.URL.Query().Get("name")
		if name == "" {
			http.Error(w, "缺少文件名", http.StatusBadRequest)
			return
		}

		// 把 URL 路径转换成当前平台的本地路径，失败就拒绝请求。
		localName, err := filepath.Localize(name)
		if err != nil {
			http.Error(w, "文件名不是本地路径", http.StatusBadRequest)
			return
		}

		// Root.Open 负责守住目录边界，不把 localName 拼到根目录前面。
		file, err := root.Open(localName)
		if err != nil {
			if errors.Is(err, os.ErrNotExist) {
				http.NotFound(w, r)
				return
			}
			http.Error(w, "文件不可读取", http.StatusForbidden)
			return
		}
		defer file.Close() // 响应结束后释放文件描述符。

		info, err := file.Stat()
		if err != nil || info.IsDir() {
			http.Error(w, "目标不是文件", http.StatusNotFound)
			return
		}
		http.ServeContent(w, r, filepath.Base(localName), info.ModTime(), file)
	}
}

func run() error {
	root, err := os.OpenRoot("./public-files")
	if err != nil {
		return err
	}
	defer root.Close() // 服务器退出时关闭根目录句柄。

	mux := http.NewServeMux()
	mux.Handle("/files", fileHandler(root))
	return http.ListenAndServe(":8080", mux)
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

访问 /files?name=docs/readme.pdf 时，响应文件名仍取自根内的本地名称。若用户提交绝对路径、空名称或不能本地化的路径，入口会结束请求；若路径通过了入口但经过符号链接指向根外，root.Open 仍会返回错误。

三、打开并响应文件内容

示例把 Stat 放在打开之后，因为服务需要确认目标不是目录，再把文件句柄交给 http.ServeContent。defer file.Close() 只负责当前请求的句柄；根对象的关闭则属于服务器生命周期。错误码可以按业务调整，但不要把所有失败都当成“文件不存在”，否则不利于日志排查。

四、明确平台与迁移边界

这个方案要求 Go 1.24 或更高版本，因为 os.Root 和 os.OpenInRoot 从 Go 1.24 加入标准库；filepath.Localize 则从 Go 1.23 提供。如果项目暂时不能升级，可以先保留输入校验，但不要把“校验后再 Open”的两次操作描述成同等强度的文件系统防护。

还要注意几个边界：Root 不阻止跨越文件系统边界、Linux bind mount、/proc 特殊文件或 Unix 设备文件；GOOS=js 下的符号链接校验仍有 TOCTOU 限制。文件名层级很多时，Root 解析可能比普通 os.Open 更慢，可在明确业务允许的前提下先清理 .. 并限制路径深度。

常见问题

os.OpenInRoot 和 os.OpenRoot 有什么区别？

os.OpenInRoot(dir, name) 适合一次性打开文件；需要连续读取、创建或统计多个文件时，保留 *os.Root 更方便，也更容易管理生命周期。

Root.FS 能不能替代 http.FileServer？

可以把 root.FS() 作为受限的 fs.FS 使用，但仍要检查路由、目录展示、缓存头和错误页面是否符合文件服务需求；不要只因为换成 FS 就省略业务层限制。

filepath.Join 加 filepath.Clean 够不够吗？

对不具备本地文件系统攻击能力的简单输入场景，规范化能减少明显的路径问题；涉及不可信文件名、符号链接或并发文件变化时，应优先使用 os.Root 这类目录边界 API。