从MinIO下载文件时如何将哈希文件名恢复为原文件名？

核心思路 #

通过对象元数据存储原始文件名，再结合预签名URL自定义响应头或代理层，绕过MinIO重定向限制，实现下载时自动恢复原始文件名。

方法1：上传存元数据+预签名URL自定义响应头 #

这是最直接的方案，无需额外服务，利用MinIO原生特性解决问题。

步骤1：上传时添加原始文件名到元数据

用MinIO SDK上传文件时，把原始文件名存入对象的自定义元数据：

from minio import Minio

client = Minio("minio.example.com",
               access_key="YOUR_ACCESS_KEY",
               secret_key="YOUR_SECRET_KEY",
               secure=True)

# 哈希后的对象键：a1b2c3d4.jpg，原始文件名：vacation_photo.jpg
client.fput_object(
    "my-bucket",
    "a1b2c3d4.jpg",
    "/local/path/vacation_photo.jpg",
    metadata={"X-Amz-Meta-Original-Filename": "vacation_photo.jpg"}
)

步骤2：生成带自定义响应头的预签名下载URL

生成预签名URL时，通过response_headers指定下载文件名，用户访问该URL时，浏览器会直接用原始文件名保存：

# 从元数据中读取原始文件名
obj_stat = client.stat_object("my-bucket", "a1b2c3d4.jpg")
original_filename = obj_stat.metadata.get("X-Amz-Meta-Original-Filename")

# 生成带Content-Disposition的预签名URL
presigned_url = client.presigned_get_object(
    "my-bucket",
    "a1b2c3d4.jpg",
    response_headers={
        "response-content-disposition": f"attachment; filename=\"{original_filename}\""
    }
)

若文件名含中文或特殊字符，用UTF-8编码避免乱码：

import urllib.parse
response_header = f"attachment; filename*=UTF-8''{urllib.parse.quote(original_filename)}"

方法2：搭建轻量代理层（适合无法用预签名URL的场景） #

如果业务场景限制不能使用预签名URL，可写一个简单后端接口作为MinIO和用户的中间代理：

from flask import Flask, make_response
from minio import Minio
import urllib.parse

app = Flask(__name__)
minio_client = Minio("minio.example.com",
                     access_key="YOUR_ACCESS_KEY",
                     secret_key="YOUR_SECRET_KEY",
                     secure=True)

@app.route("/download/<hash_filename>")
def download_file(hash_filename):
    bucket_name = "my-bucket"
    # 获取对象元数据
    obj_stat = minio_client.stat_object(bucket_name, hash_filename)
    original_filename = obj_stat.metadata.get("X-Amz-Meta-Original-Filename", hash_filename)
    # 获取对象内容
    obj = minio_client.get_object(bucket_name, hash_filename)
    # 构造响应并设置正确的下载文件名
    response = make_response(obj.read())
    encoded_filename = urllib.parse.quote(original_filename)
    response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
    response.headers["Content-Type"] = obj_stat.content_type
    return response

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

用户访问http://your-proxy/download/a1b2c3d4.jpg时，浏览器会自动以原始文件名下载文件。

关键注意事项 #

• MinIO会给自定义元数据自动添加X-Amz-Meta-前缀，读取时需对应使用该前缀的键名；
• 必须处理文件名中的特殊字符（如引号、中文），避免Content-Disposition头解析错误；
• 预签名URL的自定义响应头特性要求MinIO版本在v7.0及以上。

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