Go HTTP服务中安全提供文件下载需用白名单映射ID到路径，调用filepath.Clean()并校验目录范围，配合签名/Session权限控制、时效Token、日志审计及http.ServeContent流式传输。
Go HTTP服务中如何安全提供文件下载（非上传）
表单触发的文件下载，本质是服务端生成或读取文件后通过 Content-Disposition 响应头告知浏览器保存。Golang 标准库完全支持，但关键在路径控制和权限校验——否则可能被构造恶意路径（如 ../../../etc/passwd）导致任意文件读取。
- 永远用
filepath.Clean()规范客户端传入的文件名，再检查是否仍在允许目录内 - 不要直接拼接
r.URL.Query().Get("file")到os.Open() - 推荐用白名单映射：表单提交固定 ID（如
report_id=2024Q3），服务端查数据库或配置获取真实路径 - 若必须传文件名，限定后缀（如只允许
.pdf、.csv），并拒绝含..或绝对路径符号
func downloadHandler(w http.ResponseWriter, r *http.Request) {
fileID := r.FormValue("id") // 表单字段，非原始文件名
allowed := map[string]string{
"q3_report": "/var/data/reports/q3-final.pdf",
"user_export": "/tmp/export_123.csv",
}
if path, ok := allowed[fileID]; ok {
f, err := os.Open(path)
if err != nil {
http.Error(w, "File not found", http.StatusNotFound)
return
}
defer f.Close()
w.Header().Set("Content-Type", "application/octet-stream")
w.Header().Set("Content-Disposition", `attachment; filename="`+filepath.Base(path)+`"`)
http.ServeContent(w, r, filepath.Base(path), time.Now(), f)
} else {
http.Error(w, "Invalid file ID", http.StatusBadRequest)
}
}
为什么不用 http.ServeFile？
http.ServeFile 会自动处理路径遍历，但它不校验来源，且默认返回 200 而非 404（当文件不存在时返回空响应），容易暴露目录结构。更严重的是：它不支持设置自定义 Content-Disposition，无法控制下载后的文件名。
-
http.ServeFile适合静态资源公开访问（如前端 JS/CSS），不适合受控下载 - 下载场景必须显式调用
http.ServeContent或手动io.Copy，才能插入校验逻辑和头信息 - 如果文件很大，
http.ServeContent支持断点续传（基于If-Range和Range头），http.ServeFile也支持，但前提是你已做路径净化
如何防止表单伪造和未授权下载
仅靠 URL 参数或隐藏字段（）无法保证安全。攻击者可轻易修改 HTML 提交任意 id。必须绑定用户上下文和时效性。
- 生成下载链接时，用服务端签名：如
/download?id=q3_report&sig=sha256(user_id:q3_report:20240915:secret)，验证签名后再放行 - 结合 session 或 JWT：检查
r.Context().Value(auth.UserKey)是否有对应权限 - 对敏感文件加临时 token，有效期 5 分钟，用完即销毁（存 Redis 或内存 map）
- 记录每次下载日志：
user_id、file_id、ip、timestamp，便于审计
大文件下载的内存与超时控制
用 io.Copy 直接写响应体虽简单，但若不设限，可能耗尽内存或阻塞 goroutine。标准库的 http.ServeContent 内部已做流式处理，但仍需注意底层连接和上下文。
- 为 handler 设置超时：
http.TimeoutHandler包裹 handler，避免慢客户端拖垮服务 - 确保文件句柄及时关闭（用
defer f.Close()），尤其在错误分支里 - 若文件来自网络（如 S3），用带 context 的 client 方法，并传入
r.Context()实现请求取消 - 避免在 handler 中做重计算（如动态压缩 ZIP），应预生成并缓存
最易忽略的是：没校验文件 MIME 类型就直接设 Content-Type: application/octet-stream。虽然下载安全，但若用户误点打开，浏览器可能因类型不匹配而失败。真正稳妥的做法是用 net/http.DetectContentType 检查前 512 字节，再决定是否允许下载。
