Nginx + MinIO 私有文件访问网关实战:token 鉴权、路径隐藏与双方案性能对比

环境:Docker(MinIO RELEASE.2023-03-20 / Nginx 1.29.8 + njs 0.9.6)、Spring Boot 4.1.1(Java 17+)、minio-java 8.6.0。
全部配置与代码在文中完整给出,文末附验证清单与 500MB 实测对比。

一、要解决的问题

最初的链路很简单:客户端请求 nginx,nginx 用 auth_request 把请求转给后端做 token 校验,通过后再 proxy_pass 到 MinIO 取文件:

location /files/ {
    auth_request /auth;
    rewrite ^/files/(.*)$ /$1 break;
    proxy_pass http://minio:9000;   # 无签名转发
}

跑起来后发现三个问题:

问题 1:bucket 必须设为 public,否则一律 401/403。
原因:MinIO 的 S3 API 用 AWS SigV4 签名鉴权。nginx 转发的是客户端的原始请求,不携带任何 MinIO 签名,MinIO 把它当匿名访问处理——bucket 不开 anonymous download 就拒绝。

问题 2:bucket 一旦 public,鉴权形同虚设。
MinIO 容器的 9000 端口是发布在宿主机 0.0.0.0 上的,局域网里任何人都可以绕过 nginx 直接 curl http://<宿主机IP>:9000/<bucket>/<key>,nginx 那一层鉴权完全被架空。

问题 3:换预签名 URL(presigned URL)也不适合敏感场景。
预签名 URL 是官方给的"带过期时间的分享链接",但它有两个绕不开的硬伤:

  • URL 里明文携带 endpoint、bucket、object key,等于把存储结构暴露给客户端;
  • 签发后在过期前无法单独撤回,链接泄漏即失控。

于是明确了敏感场景的目标:

  1. bucket 保持私有;
  2. 客户端只见到不透明的文件 ID,bucket/key 路径永不出服务端;
  3. 支持图片/PDF 内联预览与 Range 断点续传;
  4. MinIO 端口不直接对外。

二、方案总览:两条链路都实现,实测对比

最终的架构是两条共存的链路,用不同 URL 前缀区分,方便直观对比:

GET /files/a/<fileId>?token=xxx
  → nginx → 后端 /file/download/{fileId}
  → 校验 token → fileId 映射 bucket/key → MinIO SDK 流式中转          【方案A:后端流式中转】

GET /files/b/<fileId>?token=xxx
  → nginx auth_request → 后端 /file/auth(校验 token,返回 X-Object-Path 真实路径)
  → nginx njs 现场计算 SigV4 签名 → 直连私有 bucket                     【方案B:签名直代理】
  • 方案A:文件字节流经后端 JVM。实现简单、逻辑全在 Java 里,代价是后端带宽与吞吐。
  • 方案B:后端只做"签字放行",文件字节不碰后端,由 nginx 用 njs 模块现场给请求做 SigV4 签名后直连私有 bucket。性能天花板高,代价是多维护一段签名脚本。

两个方案共享同一套 token 与同一份 fileId → bucket/key 映射。

三、环境搭建(docker compose 一体化)

一体化 compose 下各组件的依赖关系:

file-gateway/
├── docker-compose.yml
├── nginx/
│   ├── Dockerfile
│   ├── nginx.conf
│   ├── conf.d/default.conf
│   └── njs/s3sign.js
└── other-test/            # Spring Boot 后端
    ├── Dockerfile
    ├── pom.xml
    └── src/...

3.1 docker-compose.yml

services:
  minio:
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    container_name: minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    volumes:
      - minio_data:/data
    ports:
      # 9000 不对外发布,只有 compose 内网可达;回环绑定仅为了方便本机调试/初始化
      - "127.0.0.1:9000:9000"
      - "127.0.0.1:9001:9001"   # 控制台只绑回环
    networks: [file-net]

  backend:
    build: ./other-test
    container_name: file-backend
    environment:
      # Spring Boot relaxed binding:环境变量覆盖 application.yaml
      MINIO_ENDPOINT: http://minio:9000
      MINIO_ACCESSKEY: minioadmin
      MINIO_SECRETKEY: minioadmin
      FILE_AUTHTOKEN: test-token-123
    # 不发布端口:后端只对 nginx 暴露,外部无法直连
    networks: [file-net]
    depends_on: [minio]

  nginx:
    build: ./nginx
    container_name: nginx
    ports:
      - "80:80"                 # 整个系统唯一的对外入口
    environment:
      MINIO_AK: minioadmin      # 凭证只注入 nginx 容器,不下发给任何客户端
      MINIO_SK: minioadmin
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/njs:/etc/nginx/njs:ro
    networks: [file-net]
    depends_on: [minio, backend]

networks:
  file-net:
volumes:
  minio_data:

国内环境拉不动 Docker Hub 时,把镜像换成自己的镜像仓库地址即可。

3.2 后端 Dockerfile(other-test/Dockerfile)

FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn -q -DskipTests package

FROM eclipse-temurin:17-jre
WORKDIR /app
COPY --from=build /app/target/*.jar app.jar
ENTRYPOINT ["java", "-jar", "app.jar"]

3.3 nginx 镜像(nginx/Dockerfile)

SigV4 签名用 nginx 官方的 njs 模块实现:

FROM nginx:1.29.8
RUN apt-get update -o Acquire::http::Timeout=15 -o Acquire::https::Timeout=15 \
    && apt-get install -y --no-install-recommends nginx-module-njs \
    && rm -rf /var/lib/apt/lists/*

部分镜像已预装 njs(我用的 mirror 里 nginx-module-njs 1.29.8+0.9.6 就在 /usr/lib/nginx/modules/ 下),这一步属于保险;官方 nginx 镜像必须装。

3.4 nginx.conf

load_module /usr/lib/nginx/modules/ngx_http_js_module.so;

user  nginx;
worker_processes  auto;

# 声明后 njs 里才能用 process.env 读到
env MINIO_AK;
env MINIO_SK;

error_log  /var/log/nginx/error.log notice;
pid        /run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    js_import s3 from /etc/nginx/njs/s3sign.js;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    include /etc/nginx/conf.d/*.conf;
}

3.5 conf.d/default.conf(核心路由)

server {
    listen 80;
    server_name localhost;

    # ===== 方案A:后端流式中转 =====
    # token 校验与文件读取都在后端 /file/download/{fileId} 完成
    location /files/a/ {
        rewrite ^/files/a/(.*)$ /file/download/$1 break;
        proxy_pass http://backend:81;          # 后端跑在宿主机时改成 http://host.docker.internal:81
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;                   # 大文件流式下发,不在 nginx 落缓存
        proxy_read_timeout 3600s;              # 容忍慢速客户端下载大文件
    }

    # ===== 方案B:鉴权 + njs 现场签名,直连私有 bucket =====
    location /files/b/ {
        # proxy_pass 含变量时 nginx 启动期不解析域名,必须走 Docker 内嵌 DNS 运行时解析
        resolver 127.0.0.11 valid=30s ipv6=off;

        auth_request /auth;
        # 从鉴权响应头捕获真实对象路径(客户端永远看不到)
        auth_request_set $obj $upstream_http_x_object_path;

        # js_set 变量每个请求只计算一次并缓存:sign 一次性算出 amzdate 和签名,
        # 另外两个变量只做拆分,避免两次取时间戳跨秒导致签名不一致
        js_set $sig_pack s3.sign;
        js_set $authz s3.authz;
        js_set $amzdate s3.amzdate;

        # 变量形式的 proxy_pass 不会自动拼接客户端 query string,
        # 客户端的 ?token= 不会被透传给 MinIO,与签名时的空 canonical query 匹配
        proxy_pass http://minio:9000/$obj;

        proxy_set_header Host minio:9000;      # 必须与签名里的 host 逐字符一致
        proxy_set_header Authorization $authz;
        proxy_set_header x-amz-date $amzdate;
        # GET/HEAD 无请求体,载荷哈希恒为空串的 SHA256
        proxy_set_header x-amz-content-sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855;
        proxy_buffering off;

        # 抹掉 MinIO/S3 指纹头,客户端无法从响应判断存储实现
        proxy_hide_header X-Amz-Id-2;
        proxy_hide_header X-Amz-Request-Id;
        proxy_hide_header X-Amz-Bucket-Region;
    }

    # ===== 内部鉴权子请求:只转发鉴权所需信息 =====
    location = /auth {
        internal;                              # 外部无法直接访问
        proxy_pass http://backend:81/file/auth;
        proxy_pass_request_body off;           # 不转发 body……
        proxy_set_header Content-Length "";    # ……必须配套清空 Content-Length,否则上游会等 body 直到超时
        proxy_set_header Authorization $http_authorization;
        # 原始 URI(含 query)塞进头里,后端从中解析 fileId 和 ?token=
        proxy_set_header X-Original-URI $request_uri;
    }
}

3.6 njs/s3sign.js(SigV4 签名实现)

var crypto = require('crypto');

var REGION = 'us-east-1';   // MinIO 默认 region
var SERVICE = 's3';
var HOST = 'minio:9000';    // 必须与 default.conf 里 proxy_set_header Host 一致
var EMPTY_PAYLOAD_SHA256 = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
var SIGNED_HEADERS = 'host;x-amz-content-sha256;x-amz-date';

// SigV4 规则的单段 URI 编码(保留字 A-Z a-z 0-9 - _ . ~ 不编码,其余按 UTF-8 字节 %XX 大写)
function uriEncodeSegment(s) {
    var bytes = Buffer.from(String(s), 'utf8');
    var out = '';
    for (var i = 0; i < bytes.length; i++) {
        var b = bytes[i];
        var unreserved =
            (b >= 0x41 && b <= 0x5A) || (b >= 0x61 && b <= 0x7A) ||
            (b >= 0x30 && b <= 0x39) ||
            b === 0x2D || b === 0x5F || b === 0x2E || b === 0x7E;
        out += unreserved ? String.fromCharCode(b)
                          : '%' + (b < 16 ? '0' : '') + b.toString(16).toUpperCase();
    }
    return out;
}

function canonicalUri(obj) {
    if (!obj) { return '/'; }
    return '/' + String(obj).split('/').map(uriEncodeSegment).join('/');
}

function hmacBuffer(key, data) {
    return crypto.createHmac('sha256', key).update(data).digest(); // 无参返回 Buffer,用于密钥派生链
}

// 每个请求只执行一次(js_set 缓存),返回 'amzdate|authorization'
function sign(r) {
    var ak = process.env.MINIO_AK || '';
    var sk = process.env.MINIO_SK || '';

    var iso = new Date().toISOString();                          // 2026-10-22T02:09:37.123Z
    var amzdate = iso.slice(0, 19).replace(/[-:]/g, '') + 'Z';   // 20261022T020937Z
    var datestamp = amzdate.slice(0, 8);
    var scope = datestamp + '/' + REGION + '/' + SERVICE + '/aws4_request';

    var canonicalRequest =
        r.method + '\n' +                    // GET/HEAD 均为空载荷,直接取真实方法以兼容 HEAD
        canonicalUri(r.variables.obj || '') + '\n' +
        '\n' +                               // canonical query 恒为空(客户端 query 不透传)
        'host:' + HOST + '\n' +
        'x-amz-content-sha256:' + EMPTY_PAYLOAD_SHA256 + '\n' +
        'x-amz-date:' + amzdate + '\n' +
        '\n' +
        SIGNED_HEADERS + '\n' +
        EMPTY_PAYLOAD_SHA256;

    var requestHash = crypto.createHash('sha256').update(canonicalRequest).digest('hex');
    var stringToSign = 'AWS4-HMAC-SHA256\n' + amzdate + '\n' + scope + '\n' + requestHash;

    var kDate = hmacBuffer('AWS4' + sk, datestamp);
    var kRegion = hmacBuffer(kDate, REGION);
    var kService = hmacBuffer(kRegion, SERVICE);
    var kSigning = hmacBuffer(kService, 'aws4_request');
    var signature = crypto.createHmac('sha256', kSigning).update(stringToSign).digest('hex');

    return amzdate + '|AWS4-HMAC-SHA256 Credential=' + ak + '/' + scope +
        ', SignedHeaders=' + SIGNED_HEADERS + ', Signature=' + signature;
}

function amzdate(r) { return (r.variables.sig_pack || '').split('|')[0] || ''; }
function authz(r)   { return (r.variables.sig_pack || '').split('|')[1] || ''; }

export default { sign, amzdate, authz };

3.7 后端代码

pom.xml 增加依赖:

<dependency>
    <groupId>io.minio</groupId>
    <artifactId>minio</artifactId>
    <version>8.6.0</version>
</dependency>
<!-- okhttp 5.x 主 jar 是 Kotlin Multiplatform 元数据桩(767 字节),Maven 不会自动重定向到 okhttp-jvm,
     不显式引入会编译报"无法访问 okhttp3.HttpUrl"。Gradle 无此问题 -->
<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp-jvm</artifactId>
    <version>5.1.0</version>
</dependency>

application.yaml:

server:
  port: 81

minio:
  endpoint: http://localhost:9000   # compose 里由 MINIO_ENDPOINT=http://minio:9000 覆盖
  access-key: minioadmin
  secret-key: minioadmin

file:
  auth-token: test-token-123        # 演示用固定 token,生产换成真实鉴权体系
  mapping:                          # 不透明 fileId -> bucket/key,生产放数据库
    demo01: test/test.jpg
    demo02: test/demo.pdf
    demo03: test/big.bin

FileProperties.java:

@Component
@ConfigurationProperties(prefix = "file")
public class FileProperties {
    private String authToken;
    private Map<String, String> mapping = new HashMap<>();
    // getter/setter 略
}

FileTestController.java(方案A 下载 + 方案B 鉴权):

@RestController
@RequestMapping("/file")
public class FileTestController {

    private static final int BUFFER_SIZE = 32 * 1024;

    private final FileProperties fileProperties;
    private final MinioClient minioClient;

    public FileTestController(FileProperties fileProperties,
                              @Value("${minio.endpoint}") String endpoint,
                              @Value("${minio.access-key}") String accessKey,
                              @Value("${minio.secret-key}") String secretKey) {
        this.fileProperties = fileProperties;
        this.minioClient = MinioClient.builder()
                .endpoint(endpoint).credentials(accessKey, secretKey).build();
    }

    /**
     * 方案A:校验 token 后从 MinIO 流式中转文件,支持 Range
     */
    @GetMapping("/download/{fileId}")
    public void download(@PathVariable String fileId,
                         @RequestParam(required = false) String token,
                         @RequestHeader(value = "Authorization", required = false) String authorization,
                         @RequestHeader(value = "Range", required = false) String range,
                         HttpServletResponse response) throws Exception {
        if (!checkToken(token, authorization)) {
            response.sendError(HttpServletResponse.SC_UNAUTHORIZED);
            return;
        }
        String mapped = fileProperties.getMapping().get(fileId);
        if (mapped == null) {
            response.sendError(HttpServletResponse.SC_NOT_FOUND);
            return;
        }
        String[] parts = mapped.split("/", 2);

        StatObjectResponse stat;
        try {
            stat = minioClient.statObject(StatObjectArgs.builder()
                    .bucket(parts[0]).object(parts[1]).build());
        } catch (ErrorResponseException e) {
            if ("NoSuchKey".equals(e.errorResponse().code())) {
                response.sendError(HttpServletResponse.SC_NOT_FOUND);
                return;
            }
            throw e;
        }
        long size = stat.size();

        // 解析 Range:bytes=a-b / bytes=a- / bytes=-N,非法值兜底为全量
        long start = 0, end = size - 1;
        boolean partial = false;
        if (range != null && range.startsWith("bytes=")) {
            String spec = range.substring(6).trim();
            int comma = spec.indexOf(',');
            if (comma >= 0) { spec = spec.substring(0, comma).trim(); }  // 多区间只取第一段
            int dash = spec.indexOf('-');
            if (dash >= 0) {
                String a = spec.substring(0, dash).trim();
                String b = spec.substring(dash + 1).trim();
                try {
                    if (a.isEmpty()) {                       // suffix 形式:最后 N 字节
                        long suffix = Long.parseLong(b);
                        if (suffix > 0) {
                            start = Math.max(0, size - suffix);
                            partial = start <= end;
                        }
                    } else {
                        start = Long.parseLong(a);
                        end = b.isEmpty() ? size - 1 : Math.min(Long.parseLong(b), size - 1);
                        partial = start <= end && start < size;
                    }
                    if (!partial) { start = 0; end = size - 1; }
                } catch (NumberFormatException e) {
                    start = 0; end = size - 1;
                }
            }
        }
        long length = end - start + 1;

        GetObjectArgs.Builder getBuilder = GetObjectArgs.builder().bucket(parts[0]).object(parts[1]);
        if (partial) { getBuilder.offset(start).length(length); }

        try (GetObjectResponse in = minioClient.getObject(getBuilder.build());
             OutputStream out = response.getOutputStream()) {
            response.setContentType(stat.contentType());   // 透传 Content-Type,保证内联预览
            response.setHeader("Accept-Ranges", "bytes");
            // 注意:不设置 Content-Disposition: attachment,否则浏览器一律变下载
            if (partial) {
                response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT);
                response.setHeader("Content-Range", "bytes " + start + "-" + end + "/" + size);
                response.setContentLengthLong(length);
            } else {
                response.setStatus(HttpServletResponse.SC_OK);
                response.setContentLengthLong(size);
            }
            byte[] buffer = new byte[BUFFER_SIZE];         // 32KB 缓冲流式拷贝,文件不进内存
            int n;
            while ((n = in.read(buffer)) != -1) { out.write(buffer, 0, n); }
            out.flush();
        }
    }

    /**
     * 方案B:nginx auth_request 鉴权,通过时返回 X-Object-Path 供 njs 签名代理使用
     */
    @GetMapping("/auth")
    public ResponseEntity<Void> auth(@RequestHeader(value = "X-Original-URI", required = false) String originalUri,
                                     @RequestHeader(value = "Authorization", required = false) String authorization) {
        String fileId = null, token = null;
        if (originalUri != null) {
            String path = originalUri, query = null;
            int q = path.indexOf('?');
            if (q >= 0) { query = path.substring(q + 1); path = path.substring(0, q); }
            String prefix = "/files/b/";
            if (path.startsWith(prefix)) { fileId = path.substring(prefix.length()); }
            if (query != null) {
                for (String kv : query.split("&")) {
                    int eq = kv.indexOf('=');
                    if (eq > 0 && "token".equals(kv.substring(0, eq))) {
                        token = URLDecoder.decode(kv.substring(eq + 1), StandardCharsets.UTF_8);
                    }
                }
            }
        }
        if (!checkToken(token, authorization)) {
            return ResponseEntity.status(HttpServletResponse.SC_UNAUTHORIZED).build();
        }
        String mapped = fileId == null ? null : fileProperties.getMapping().get(fileId);
        if (mapped == null) {
            // 关键坑:auth_request 只会把 401/403 透给客户端,其余状态码一律变成 500
            return ResponseEntity.status(HttpServletResponse.SC_FORBIDDEN).build();
        }
        return ResponseEntity.ok().header("X-Object-Path", mapped).build();
    }

    private boolean checkToken(String token, String authorization) {
        if (token != null && !token.isEmpty()) {
            return fileProperties.getAuthToken().equals(token);
        }
        if (authorization != null) {
            String value = authorization.trim();
            if (value.regionMatches(true, 0, "Bearer ", 0, 7)) { value = value.substring(7).trim(); }
            return fileProperties.getAuthToken().equals(value);
        }
        return false;
    }
}

3.8 初始化数据

bucket 默认就是私有的(不要设置 anonymous 策略即可)。用 Python 客户端建 bucket、传测试文件;若之前开通过匿名访问,用 delete_bucket_policy 关掉:

# pip install minio
from minio import Minio

c = Minio("127.0.0.1:9000", access_key="minioadmin", secret_key="minioadmin", secure=False)

if not c.bucket_exists("test"):
    c.make_bucket("test")

c.fput_object("test", "test.jpg", "./test.jpg", content_type="image/jpeg")
c.fput_object("test", "demo.pdf", "./demo.pdf", content_type="application/pdf")

try:
    c.delete_bucket_policy("test")   # 关掉匿名访问,恢复私有
except Exception:
    pass

# 验证匿名直连必须 403
import urllib.request
try:
    urllib.request.urlopen("http://127.0.0.1:9000/test/test.jpg")
except Exception as e:
    print("anonymous access:", e)    # 期望 HTTP Error 403

3.9 启动

docker compose up -d --build
docker compose exec nginx nginx -t    # 验证配置

四、请求流程详解

方案A:后端流式中转

client ──GET /files/a/demo01?token=xxx──▶ nginx
                                           │ 原样转发
                                           ▼
                                     后端 /file/download/demo01
                                           │ 1. 校验 token,失败 401
                                           │ 2. fileId → bucket/key(映射表),没有 404
                                           │ 3. statObject 取大小/Content-Type
                                           │ 4. 有 Range 则换算 offset/length
                                           ▼
                                     MinIO getObject(SDK 带凭证,bucket 私有也能读)
                                           │
                                           ▼
                                     32KB 缓冲流式写回 client(200 或 206)

方案B:auth_request + njs 签名直代理

client ──GET /files/b/demo01?token=xxx──▶ nginx /files/b/
                                           │
                                           │ ① auth_request 子请求
                                           ▼
                                     后端 /file/auth
                                     (头:Authorization、X-Original-URI=/files/b/demo01?token=xxx)
                                           │ 2. 校验 token → 失败 401 / 无映射 403
                                           │ 3. 通过 → 200 + 响应头 X-Object-Path: test/test.jpg
                                           ▼
                                     nginx 捕获响应头:
                                       auth_request_set $obj = "test/test.jpg"
                                           │
                                           │ ④ njs 现场计算 SigV4:
                                           │   用容器环境变量里的 AK/SK,
                                           │   对 GET /test/test.jpg、host=minio:9000、空载荷签名
                                           ▼
                                     MinIO(私有 bucket)
                                           │ ⑤ 签名验证通过,返回文件
                                           ▼
                                     nginx 抹掉 X-Amz-* 指纹头 → client

方案B 各环节参数的"出处":

参数 来源
对象路径 $obj 后端鉴权响应头 X-Object-Path,被 auth_request_set 捕获
AK/SK docker compose 注入 nginx 容器的环境变量,nginx.conf 用 env 声明后由 njs process.env 读取
Authorization / x-amz-date njs 用 AK/SK 对每个请求现场计算
Host 写死 minio:9000,必须与签名内 host 逐字符一致
x-amz-content-sha256 GET/HEAD 恒为空串哈希常量

几个容易踩的细节:

  • proxy_pass_request_body off 必须配套 proxy_set_header Content-Length "":前者是不转发 body,后者是告诉鉴权后端"别等 body"。只设前者,遇到带 Content-Length 的请求,上游会傻等 body 直到超时。
  • 变量形式的 proxy_pass http://minio:9000/$obj 不会自动拼接原始 query string,客户端的 ?token= 天然不会泄漏给 MinIO——同时签名里的 canonical query 也必须是空串,二者匹配。
  • x-amz-content-sha256 写死空载荷哈希,等于声明"此签名不担保任何 body":带 body 的请求哈希对不上会被 MinIO 直接拒掉,签名无法被滥用到写操作。
  • 客户端的 Range 头不在 SignedHeaders 里,默认透传给 MinIO 且不影响签名校验——所以方案B 一行 Range 代码没写就支持 206。

五、验证清单(含实测结果)

TOKEN="test-token-123"

# 1. 安全:匿名直连 MinIO,必须 403
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9000/test/test.jpg
# → 403

# 2. 负向用例
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost/files/a/demo01"                      # → 401
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost/files/b/demo01?token=wrong"         # → 401
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost/files/a/noid?token=$TOKEN"          # → 404
curl -s -o /dev/null -w "%{http_code}\n" "http://localhost/files/b/noid?token=$TOKEN"          # → 403

# 3. 下载完整性:两链路与源文件 sha256 一致
curl -s "http://localhost/files/a/demo01?token=$TOKEN" -o a.jpg
curl -s "http://localhost/files/b/demo01?token=$TOKEN" -o b.jpg
sha256sum a.jpg b.jpg     # → 两个哈希相同

# 4. Range 断点续传:恰好 1024 字节 + 206
curl -s -H "Range: bytes=0-1023" -o /dev/null -w "%{http_code} %{size_download}\n" \
  "http://localhost/files/a/demo03?token=$TOKEN"     # → 206 1024
curl -s -H "Range: bytes=0-1023" -o /dev/null -w "%{http_code} %{size_download}\n" \
  "http://localhost/files/b/demo03?token=$TOKEN"     # → 206 1024

# 5. 预览:Content-Type 正确、无 Content-Disposition: attachment
curl -s -D - -o /dev/null "http://localhost/files/a/demo02?token=$TOKEN" | grep -i content-type
# → content-type: application/pdf(浏览器直接打开 URL 即内联预览)

# 6. 指纹检查:B 链路不应出现 X-Amz-* 头
curl -s -D - -o /dev/null "http://localhost/files/b/demo02?token=$TOKEN" | grep -ci x-amz
# → 0

六、踩坑记录(问题 → 原因 → 解决)

问题 原因 解决
私有 bucket 经 nginx 访问 401 nginx 转发无 SigV4 签名,被当匿名访问 方案A 用 SDK 带凭证读;方案B 用 njs 现场签名
public bucket 鉴权被绕过 MinIO 9000 端口发布在 0.0.0.0 端口只绑回环 / compose 内网不发布
方案B 启动后 502 proxy_pass 含变量时 nginx 不在启动期解析域名 加 resolver 127.0.0.11(Docker 内嵌 DNS)
未知 fileId 在方案B 返回 500 auth_request 只把 401/403 透给客户端,其他状态码一律 500 鉴权接口对"无映射"返回 403 而非 404
HEAD 请求 403 签名脚本里 method 写死 GET,与真实 HEAD 不匹配 改用 r.method 参与签名(GET/HEAD 载荷哈希相同)
签名偶发失败 amzdate 与 Authorization 分两次取时间戳,跨秒不一致 js_set 变量每请求只算一次并缓存:一个函数算出 amzdate|authz,另两个变量只做拆分
Maven 编译报缺 okhttp 类 okhttp 5.x 主 jar 是 KMP 元数据桩,Maven 不识别 Gradle 元数据 显式引入 okhttp-jvm 同版本
响应暴露存储实现 MinIO 返回 X-Amz-* 头 proxy_hide_header 抹除
客户端 query 泄漏给 MinIO ——(预防性结论) 变量形式 proxy_pass 天然不拼 query,且签名 canonical query 为空串
数据"丢失"教训 原容器数据不在具名卷里,重建容器后 bucket 为空 重建前用临时容器确认卷内容;重要数据先备份

七、500MB 实测对比与选型建议

同一个 500MB 文件(demo03 → test/big.bin),本机回环实测:

方案 耗时 吞吐 文件流量路径 后端负载
A 后端中转 12.79s ~41 MB/s MinIO → JVM → 客户端 占连接、占带宽(恒定低内存)
B 签名直代理 2.08s ~252 MB/s MinIO → nginx → 客户端 零文件流量,只有一次鉴权子请求

约 6 倍差距。 选型建议:

  • 文件访问不是高频核心场景、图省心 → 方案A。 全部逻辑在 Java 里,好调试好维护;<100MB 文件毫无压力,偶发大文件流式拷贝也能恒定内存扛住。
  • 文件下载是核心功能、大文件/高并发 → 方案B。 性能接近 nginx 裸奔,代价是多维护一个自定义镜像和一段签名 JS,排错时面对的是 SignatureDoesNotExist 这类 S3 报错,比 Java 栈难查。
  • 两者鉴权与映射逻辑完全同构,从 A 平滑迁移到 B 不需要动客户端。

八、生产化加固方向

演示环境为了聚焦主链路做了简化,上生产前建议补齐:

  1. token 换真实鉴权:固定 token → JWT/OAuth2,注意 auth_request 子请求是无 body 的 GET,鉴权接口设计要适配。
  2. 映射表进数据库:fileId → bucket/key 加属主、权限、原始文件名等字段;映射表本身就是天然的防路径穿越白名单。
  3. 不可变 key:每次上传生成新 UUID 作为对象 key,文件永不原地覆盖,"续传到一半文件被换"从根上消失。
  4. ETag / If-Range:方案A 目前不回 ETag、不识别 If-Range,且越界 Range 兜底为 200(RFC 允许但 416 更规范)。生产应带上 statObject 的 ETag/Last-Modified,If-Range 不匹配时回 200 全量,越界回 416 + Content-Range: bytes */size。
  5. 敏感文件响应头:Cache-Control: no-store,避免浏览器/中间代理落盘缓存。
  6. HTTPS 与限流:nginx 层终结 TLS,按 IP/用户限速限并发。

九、结语

敏感场景下 MinIO 文件访问的正确姿势,核心就两条:bucket 私有 + 客户端只见不透明 fileId。预签名 URL 把存储结构写进 URL 且无法撤回,只适合低敏感场景。在此之上,"后端中转"和"nginx 签名直代理"是用复杂度换性能的两个档位——按自己的文件量级和并发挑一个即可。

posted on 2026-10-22 14:39  frmine  阅读(21)  评论(0)    收藏  举报