Go 问答：文件下载接口如何防路径穿越，filepath.Clean 够不够？

很多 Go 项目都会有文件下载接口，比如导出报表、下载附件、预览上传文件。最容易写出的版本是从查询参数拿到文件名，然后拼到本地目录里读取。问题也出在这里：如果用户传入 ../../etc/passwd 这类路径，接口可能读到业务目录之外的文件。

所以这个问答的核心不是“filepath.Clean 能不能用”，而是：Clean 只能整理路径字符串，不能证明路径仍然落在安全根目录下。真正的防护要把根目录、相对路径、文件类型和审计日志一起做完整。

保护资产：下载接口到底要保护什么

文件下载接口保护的不是“某个文件名”，而是整个服务进程能访问到的文件范围。只要进程有读权限，错误的路径拼接就可能读到配置文件、日志文件、临时文件，甚至上传目录里其他用户的附件。

在设计防护前，先把资产划出来：

• 允许下载的根目录，例如 /data/app/reports。
• 允许暴露的文件类型，例如 .csv、.xlsx、.pdf。
• 不允许用户控制的目录前缀，例如系统配置目录、程序源码目录。
• 需要记录的请求信息，例如用户 ID、原始参数、拦截原因。

攻击路径：../ 是怎么逃出目录的

错误示例通常长这样：

func unsafeDownload(w http.ResponseWriter, r *http.Request) {
    name := r.URL.Query().Get("file")
    fullPath := "/data/app/reports/" + name
    http.ServeFile(w, r, fullPath)
}

如果请求是：

GET /download?file=2026/june.csv

这看起来正常。但如果请求变成：

GET /download?file=../../config/app.yaml

拼接后的字符串就不再代表报表目录里的文件。即使用了 filepath.Clean，它也只是把路径整理得更规范：

/data/app/reports/../../config/app.yaml
clean 后可能变成：
/data/config/app.yaml

Clean 没有“安全根目录”这个概念，它不知道 /data/config/app.yaml 是否应该被下载。

风险分级：哪些接口最值得先改

不是所有文件接口风险都一样。建议先按三个维度分级：

• 是否直接接收用户传入的路径片段。
• 是否允许下载历史文件、临时文件或上传文件。
• 服务进程是否拥有较大的文件读取权限。

如果一个接口同时满足“外部可访问、路径由用户传、进程权限较大”，就应该优先整改。后台管理接口也不能放松，因为内部账号泄露或越权调用时，同样可能被用来读敏感文件。

防护控制：Clean 之后还要做根目录校验

比较稳的写法是：固定根目录，清理用户路径，拼接成绝对路径，再用 filepath.Rel 判断目标文件是否仍在根目录内。

func safeJoin(rootDir, userPath string) (string, error) {
    if userPath == "" {
        return "", fmt.Errorf("empty file path")
    }

    cleaned := filepath.Clean(userPath)
    if filepath.IsAbs(cleaned) {
        return "", fmt.Errorf("absolute path is not allowed")
    }

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

    targetAbs := filepath.Join(rootAbs, cleaned)
    rel, err := filepath.Rel(rootAbs, targetAbs)
    if err != nil {
        return "", err
    }
    if rel == "." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) || rel == ".." {
        return "", fmt.Errorf("path leaves download root")
    }
    return targetAbs, nil
}

下载接口再补上扩展名白名单和文件信息检查：

func downloadReport(w http.ResponseWriter, r *http.Request) {
    fileName := r.URL.Query().Get("file")
    target, err := safeJoin("/data/app/reports", fileName)
    if err != nil {
        http.Error(w, "invalid file", http.StatusBadRequest)
        return
    }

    ext := strings.ToLower(filepath.Ext(target))
    if ext != ".csv" && ext != ".xlsx" && ext != ".pdf" {
        http.Error(w, "file type not allowed", http.StatusBadRequest)
        return
    }

    info, err := os.Stat(target)
    if err != nil || info.IsDir() {
        http.Error(w, "file not found", http.StatusNotFound)
        return
    }

    http.ServeFile(w, r, target)
}

下面这张图展示了防护后的分层路径：HTTP 参数先进入 API 层，经过 Clean、根目录校验和白名单，最后才允许打开文件。

审计记录：被拦截的路径也要能追踪

安全接口不要只返回 400，还要记录足够的审计信息。建议日志包含：

• 用户 ID 或调用方标识。
• 原始文件参数。
• 拦截原因，例如绝对路径、越出根目录、类型不允许。
• 请求来源 IP 和接口路径。

日志示例：

level=warn msg="download blocked" user=1001 file="../../config/app.yaml" reason="path leaves download root" ip=10.0.2.15

注意审计日志不要把真实目标绝对路径暴露给前端响应，前端只需要知道文件参数不合法即可。

验证清单：用几组路径确认防护有效

最后用一组最小用例验证：

• 2026/june.csv：应该通过。
• ../secret.txt：应该返回 400。
• /etc/passwd：应该返回 400。
• 2026/report.exe：应该返回 400。
• 2026：如果是目录，应该返回 404 或业务错误。

curl 'http://127.0.0.1:8080/download?file=2026/june.csv'
curl 'http://127.0.0.1:8080/download?file=../secret.txt'
curl 'http://127.0.0.1:8080/download?file=/etc/passwd'
curl 'http://127.0.0.1:8080/download?file=2026/report.exe'

结论很明确：filepath.Clean 是必要的整理步骤，但不是安全边界。真正能防路径穿越的是“固定根目录 + 相对路径判断 + 类型白名单 + 审计记录 + 回归用例”。只要文件下载接口对外开放，这几个检查就应该成为默认配置。