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,等于把存储结构暴露给客户端;
- 签发后在过期前无法单独撤回,链接泄漏即失控。
于是明确了敏感场景的目标:
- bucket 保持私有;
- 客户端只见到不透明的文件 ID,bucket/key 路径永不出服务端;
- 支持图片/PDF 内联预览与 Range 断点续传;
- 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 不需要动客户端。
八、生产化加固方向
演示环境为了聚焦主链路做了简化,上生产前建议补齐:
- token 换真实鉴权:固定 token → JWT/OAuth2,注意
auth_request子请求是无 body 的 GET,鉴权接口设计要适配。 - 映射表进数据库:
fileId → bucket/key加属主、权限、原始文件名等字段;映射表本身就是天然的防路径穿越白名单。 - 不可变 key:每次上传生成新 UUID 作为对象 key,文件永不原地覆盖,"续传到一半文件被换"从根上消失。
- ETag / If-Range:方案A 目前不回 ETag、不识别 If-Range,且越界 Range 兜底为 200(RFC 允许但 416 更规范)。生产应带上
statObject的 ETag/Last-Modified,If-Range不匹配时回 200 全量,越界回416 + Content-Range: bytes */size。 - 敏感文件响应头:
Cache-Control: no-store,避免浏览器/中间代理落盘缓存。 - HTTPS 与限流:nginx 层终结 TLS,按 IP/用户限速限并发。
九、结语
敏感场景下 MinIO 文件访问的正确姿势,核心就两条:bucket 私有 + 客户端只见不透明 fileId。预签名 URL 把存储结构写进 URL 且无法撤回,只适合低敏感场景。在此之上,"后端中转"和"nginx 签名直代理"是用复杂度换性能的两个档位——按自己的文件量级和并发挑一个即可。
浙公网安备 33010602011771号