Go 文件下载接口怎么防路径穿越：filepath.Clean、根路径约束和审计日志

文件下载接口看起来很简单：前端传一个 path，后端把它和服务器上的下载根路径拼起来，再把文件返回给浏览器。真正上线后，风险也常常藏在这里。只要把 ../../etc/passwd、绝对路径、重复斜杠、特殊文件名这些情况处理不好，原本只想下载报表的接口，就可能被绕到服务器敏感文件上。

先界定要保护的资产

路径穿越防护保护的不是某一段 Go 代码，而是服务器文件访问边界。下载接口本来只允许访问 /data/downloads 下的报表、图片、导出文件，攻击者却可能尝试访问配置文件、日志文件、密钥文件，甚至读取其他租户的数据。

这里有个容易忽略的细节：文件名通常来自业务数据或用户输入。即使前端下拉框里只显示安全文件名，也不能相信请求参数一定来自前端。后端必须独立完成校验。

攻击路径：Join 之后不检查就会出事

很多漏洞来自这一类代码：filepath.Join(root, userPath) 后直接打开文件。问题在于，Join 和 Clean 只负责整理路径格式，不负责替你判断用户是否越界。攻击者传入 ../ 后，最终路径可能已经跑到下载根路径外面。

正确思路是先把用户路径变成相对路径，再拼到固定根路径下，最后把结果反向检查一遍：最终文件是否仍然属于下载根路径。如果不属于，立即返回 403 或 400，不要继续探测文件是否存在。

Go 里先写一个安全拼接函数

下面这个函数把用户输入当作相对路径处理，并用 filepath.Rel 判断最终文件是否越界。它适合放在下载 handler 的最前面，先挡住明显的路径穿越。

package download

import (
	"errors"
	"os"
	"path/filepath"
	"strings"
)

var errInvalidPath = errors.New("invalid download path")

func safeJoin(root, userPath string) (string, error) {
	if strings.TrimSpace(userPath) == "" {
		return "", errInvalidPath
	}

	rootAbs, err := filepath.Abs(root)
	if err != nil {
		return "", err
	}

	clean := filepath.Clean("/" + userPath)
	clean = strings.TrimPrefix(clean, string(os.PathSeparator))
	full := filepath.Join(rootAbs, clean)
	fullAbs, err := filepath.Abs(full)
	if err != nil {
		return "", err
	}

	rel, err := filepath.Rel(rootAbs, fullAbs)
	if err != nil {
		return "", errInvalidPath
	}
	if rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
		return "", errInvalidPath
	}
	return fullAbs, nil
}

这里故意给用户路径前面补了一个 / 再 Clean，是为了把 a/../../b 这类路径先压平，然后去掉开头的路径分隔符，重新当作下载根路径下的相对文件。真正判断安全边界的是后面的 Rel 检查。

只判断路径还不够

路径留在根路径下，只能说明没有直接越界，不代表这个文件就应该被返回。一个生产下载接口还要继续检查扩展名、大小、文件类型和打开方式。

• 扩展名白名单：只允许 .pdf、.csv、.xlsx、.png 等业务需要的类型。
• 大小限制：避免接口被用来拉取超大文件，把带宽和内存打满。
• 只读打开：下载接口不需要写权限，打开文件时保持最小权限原则。
• 符号链接：如果业务不需要软链，优先拒绝软链文件，减少绕过空间。
• 响应头：使用安全的下载文件名，不把用户传入的原始路径直接放进响应头。

一个可落地的下载 handler

下面的示例保留了核心校验逻辑：先安全拼接路径，再查文件信息，拒绝文件夹、软链、超大文件和非白名单扩展名，最后用只读方式打开。

func DownloadHandler(root string) http.HandlerFunc {
	allowExt := map[string]bool{
		".pdf": true,
		".csv": true,
		".png": true,
		".jpg": true,
	}

	return func(w http.ResponseWriter, r *http.Request) {
		raw := r.URL.Query().Get("path")
		filePath, err := safeJoin(root, raw)
		if err != nil {
			auditReject(r, raw, "bad_path")
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}

		info, err := os.Lstat(filePath)
		if err != nil || info.IsDir() {
			auditReject(r, raw, "not_found")
			http.NotFound(w, r)
			return
		}
		if info.Mode()&os.ModeSymlink != 0 {
			auditReject(r, raw, "symlink")
			http.Error(w, "forbidden", http.StatusForbidden)
			return
		}
		if info.Size() > 50

审计日志要记录哪些字段

路径穿越经常是批量探测行为的一部分。一次被拒绝不一定代表马上有事故，但如果同一个 IP 连续尝试 ../、绝对路径、配置文件名，就应该能在日志里看出来。

• user_id：已登录用户或调用方身份。
• remote_ip：来源 IP，便于限流和封禁。
• request_id：关联网关、应用和对象存储日志。
• raw_path：用户传入的原始路径，必要时做脱敏。
• reason：例如 bad_path、symlink、bad_ext。
• status：最终返回的 HTTP 状态码。

上线前怎么验收

验收时别只点一个正常文件。建议准备一组恶意样例和边界样例，用自动化测试跑完，再看日志是否能正确记录拒绝原因。

• ../../etc/passwd 必须被拒绝。
• /etc/passwd 这类绝对路径必须被拒绝。
• reports/../report.pdf 这类路径归一化后仍在根路径内，可以按规则继续检查。
• 非白名单扩展名必须被拒绝。
• 超大文件必须被拒绝。
• 拒绝日志能看到用户、IP、原始路径和原因。

常见问题

filepath.Clean 能彻底防路径穿越吗？

不能。它只整理路径格式，不判断最终文件是否还在下载根路径内。安全检查必须在 Clean 之后继续做根路径约束。

为什么不要把文件是否存在暴露得太细？

如果接口对不同路径返回过于细的错误，攻击者可能用它枚举服务器文件结构。非法路径优先统一返回拒绝状态，正常业务场景下再区分缺失文件的情况。

软链文件一定不能下载吗？

不一定，但如果业务没有明确需要，下载接口最好拒绝软链。允许软链时要额外校验软链目标仍在允许范围内，否则容易留下绕过点。

文件名可以直接用用户传入的 path 吗？

不建议。响应头里的文件名应该来自最终文件的安全名称，或者来自数据库里可信的展示名，不要直接使用原始 path。

小结

Go 文件下载接口的安全边界不在 http.ServeContent，而在打开文件之前。把用户路径先归一化，再确认最终路径没有越界，随后补上白名单、大小限制、只读打开和审计记录，才能把一个看似简单的下载接口做稳。