Go 文件下载如何防路径穿越：用 filepath.Rel 校验用户传入的文件名

文件下载接口最容易被低估的地方，不是把文件读出来，而是确认读到的文件仍然在允许的目录里。只要把用户输入直接拼到下载根目录后面，../、绝对路径和清理后的别名就可能让请求越过边界。Go 里可以先用 filepath.Rel 计算相对路径，再拒绝以 .. 开头的结果，最后交给 http.ServeFile 输出文件。

核心判断只有一个：用户输入解析后的路径，必须仍然位于下载根目录之下；不满足就返回 400，不要让文件系统替你“猜”意图。

下载根目录才是需要保护的资产

假设服务只允许下载 /srv/app/downloads 下的公开文件，请求参数是 name。下面这种写法看起来直观，却把权限判断交给了路径拼接结果：

func download(w http.ResponseWriter, r *http.Request) {
    path := filepath.Join("/srv/app/downloads", r.URL.Query().Get("name"))
    http.ServeFile(w, r, path)
}

filepath.Join 会清理路径片段，但“清理”不等于“授权”。真正要回答的问题是：清理后的路径是否仍在下载根目录内。攻击者关注的是这个边界，防守代码也应围绕这个边界写。

先用 filepath.Rel 判断请求有没有越界

把校验单独放在 safePath 函数里，下载处理器只接收已经通过边界检查的路径。filepath.Rel 返回从根目录到目标路径的相对结果：结果等于 .. 或以 .. 加路径分隔符开头，就说明目标在根目录之外。

func safePath(root, name string) (string, error) {
    root, err := filepath.Abs(root)
    if err != nil {
        return "", err
    }
    candidate := filepath.Join(root, name)
    rel, err := filepath.Rel(root, candidate)
    if err != nil {
        return "", err
    }
    if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
        return "", fmt.Errorf("path escapes download root")
    }
    return candidate, nil
}

func download(w http.ResponseWriter, r *http.Request) {
    path, err := safePath("/srv/app/downloads", r.URL.Query().Get("name"))
    if err != nil {
        http.Error(w, "invalid file name", http.StatusBadRequest)
        return
    }
    http.ServeFile(w, r, path)
}

这里的控制流很短，但顺序不能调换：先算 rel，再检查 .. 边界，最后才执行 http.ServeFile。越界请求的可见结果应是 HTTP 400，而不是 404，也不应进入文件读取分支。

把边界判断写成可重复的测试

不要只测一个 ../secret.txt。至少覆盖当前目录文件、子目录文件、返回根目录的路径，以及绝对路径风格的输入。测试关注的是返回值和错误，不需要真的启动 HTTP 服务。

func TestSafePath(t *testing.T) {
    root := t.TempDir()
    tests := []struct {
        name string
        ok   bool
    }{
        {"report.txt", true},
        {"daily/report.txt", true},
        {"../secret.txt", false},
        {"../../etc/passwd", false},
    }

    for _, tt := range tests {
        _, err := safePath(root, tt.name)
        if (err == nil) != tt.ok {
            t.Fatalf("safePath(%q) error = %v, want ok=%v", tt.name, err, tt.ok)
        }
    }
}

测试通过后，再在 HTTP 层核对 400 响应和正常文件的内容类型。这里别急着把所有输入都当成恶意请求：合法的子目录下载仍应可用，安全边界不应误伤正常目录结构。

几个容易漏掉的边界

• 不要用 strings.Contains(path, "..") 代替相对路径判断，它会误伤合法文件名，也无法表达目录边界。
• 根目录应使用绝对路径，避免进程工作目录变化造成校验和读取不一致。
• 如果文件名来自数据库或业务对象，仍要在最终文件系统路径处做一次边界校验。
• 符号链接是另一层策略问题；高敏感目录应限制链接，或把公开文件复制到专用目录后再提供下载。

相关问题

为什么 filepath.Clean 不能单独当权限校验？

它只负责规范化路径，不判断规范化后的目标是否仍在授权根目录内；授权判断要比较相对路径边界。

合法文件不存在时应该返回什么？

让 http.ServeFile 按文件不存在处理即可，但越界输入应在此之前明确返回 400，避免把两类问题混在日志里。

只允许单层文件名时还需要 filepath.Rel 吗？

仍建议保留统一边界校验，再额外拒绝包含路径分隔符的输入；这样以后放开子目录时不会悄悄失去保护。

发布前检查清单

上线前用一个合法子目录文件和两个越界样例做回归：合法请求能下载，../secret.txt 与 ../../etc/passwd 返回 400，日志中能区分“文件不存在”和“路径越界”。只要所有文件读取都经过 safePath，这条边界就有了明确的代码入口和测试证据。