通过Django代理MinIO预签名URL下载文件时出现损坏与文件名错误

一、修复文件名乱码与文件损坏问题 #

1. 正确设置Content-Disposition响应头 #

浏览器对Unicode文件名的解析规则不一致，需同时兼容RFC 5987（UTF-8编码）和传统格式，代码示例：

from django.utils.http import urlquote
from django.http import StreamingHttpResponse
import requests

def proxy_download(request):
    # 从FastAPI获取预签名URL和原始文件名
    download_url = "xxx"
    original_filename = "测试文件.docx"  # 支持西里尔字母等非ASCII文件名

    # 构建兼容多浏览器的Content-Disposition头
    encoded_filename = urlquote(original_filename)
    content_disposition = f"attachment; filename*=UTF-8''{encoded_filename}; filename={encoded_filename}"

    # 请求MinIO预签名URL，确保二进制流原样传输
    resp = requests.get(download_url, stream=True)
    resp.raw.decode_content = True  # 禁用自动解码，避免压缩导致文件损坏

    # 生成流式响应，复用MinIO返回的Content-Type和Content-Length
    response = StreamingHttpResponse(resp.raw, content_type=resp.headers.get('Content-Type'))
    response['Content-Disposition'] = content_disposition
    if 'Content-Length' in resp.headers:
        response['Content-Length'] = resp.headers['Content-Length']
    
    return response

关键注意点：

• 用Django内置的urlquote处理文件名编码，适配HTTP头规则
• 同时设置filename*（UTF-8标准）和filename（兼容旧浏览器）
• 开启resp.raw.decode_content = True，防止gzip压缩导致docx等二进制文件损坏
• 直接复用MinIO返回的Content-Type和Content-Length，避免类型或大小异常

2. 排查文件损坏的其他可能 #

• 禁止对响应流做额外编码处理（如decode()再encode()），直接传递二进制流
• 确保使用最新稳定版requests，避免版本bug导致的流处理错误
• 临时关闭Django的GZip等压缩中间件，排查是否是中间件修改了二进制内容

二、更优的代理/文件分发方案 #

1. 直接返回预签名URL给前端（推荐） #

完全跳过Django代理环节，让前端直接请求MinIO预签名URL：

• Django从FastAPI获取download_url和original_filename后返回给前端
• 前端通过<a download="原始文件名" href="预签名URL">触发下载，或用JS处理
  优点：
  • 减少Django服务器的带宽和CPU消耗，文件直接从MinIO传输到用户
  • 避免代理过程中的流处理错误
  • 天然支持所有浏览器的文件名解析，MinIO会自动处理响应头

2. HTTP重定向代理 #

如果必须通过Django做权限校验等中转，用重定向替代流代理：

from django.http import HttpResponseRedirect

def proxy_redirect(request):
    download_url = "xxx"  # 从FastAPI获取的预签名URL
    return HttpResponseRedirect(download_url)

注意：预签名URL有有效期，需确保重定向时URL未过期；若在意域名统一，可结合Nginx反向代理MinIO，让URL域名与Django一致。

3. Nginx反向代理（生产环境适配） #

配置Nginx直接转发MinIO请求，Django仅负责生成指向Nginx代理地址的预签名URL：

server {
    listen 80;
    server_name your-domain.com;

    location /minio-proxy/ {
        proxy_pass https://your-minio-server/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

此方案既保留域名统一，又避免Django处理流传输，性能更优。

内容的提问来源于stack exchange，提问作者Nika