Spring Boot 文件操作实战：URL 代理下载 + GridFS 大文件存储

Wed, 20 Jun 2018 00:00:00 +0800

Spring Boot 文件操作实战：URL 代理下载 + GridFS 大文件存储

背景与价值

Spring Boot 项目中常见的文件场景：

场景 1：内网文件代理下载。A 系统对外暴露，B 系统在内网跑 MinIO 等对象存储。A 需要把 B 的文件地址代理出去给外网用户。
场景 2：大文件存储。100MB+ 的文件、PDF、视频不能用 MySQL BLOB（性能差），改用 MongoDB GridFS 分片存储。

本文给出两个场景的完整代码方案。

场景 1：URL 代理中转下载

1. 架构

1
2
3
4
5


用户浏览器
 ↓ http://A_HOST:8080/file/test/xxx.mp3
A 系统（外网）
 ↓ http://B_HOST:9000/test/xxx.mp3
B 系统（内网 MinIO，不对外）

问题：如果 A 把 B 的 URL 直接返回给用户，用户无法访问 B（B 在内网）。

方案：A 解析 /file/xxx 路径 → A 自己用 HttpURLConnection 去 B 下载 → A 把字节流转发给用户。

2. 核心工具类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


public class FileOperateUtil {

 private static final Logger log = LoggerFactory.getLogger(FileOperateUtil.class);

 /**
 * URL 文件代理中转
 * @param response Servlet 响应
 * @param address 内网真实下载地址
 * @param contentType MIME 类型（null 自动判断）
 * @param fileName 下载文件名
 */
 public static void proxyUrlFile(HttpServletResponse response, String address,
 String contentType, String fileName) throws IOException {
 InputStream inputStream = null;
 ServletOutputStream outputStream = null;
 HttpURLConnection httpURLConnection = null;

 try {
 // 1. 连接内网真实地址
 URL url = new URL(address);
 httpURLConnection = (HttpURLConnection) url.openConnection();
 httpURLConnection.setConnectTimeout(5000);
 httpURLConnection.setReadTimeout(30000);
 httpURLConnection.connect();

 int code = httpURLConnection.getResponseCode();
 if (code != 200) {
 response.setStatus(HttpServletResponse.SC_NOT_FOUND);
 return;
 }

 inputStream = httpURLConnection.getInputStream();
 outputStream = response.getOutputStream();

 // 2. 设置响应头
 if (contentType != null) {
 response.setContentType(contentType);
 } else {
 response.setContentType("application/octet-stream");
 }
 if (fileName != null) {
 String encoded = new String(fileName.getBytes("utf-8"), "ISO8859-1");
 response.setHeader("Content-disposition", "attachment; filename=\"" + encoded + "\"");
 }

 // 3. 流式转发（1024 字节 buffer）
 byte[] buffer = new byte[1024];
 int len;
 while ((len = inputStream.read(buffer)) != -1) {
 outputStream.write(buffer, 0, len);
 }
 outputStream.flush();
 } catch (Exception e) {
 log.error("Proxy URL File error, address={}", address, e);
 throw e;
 } finally {
 if (inputStream != null) inputStream.close();
 if (outputStream != null) outputStream.close();
 if (httpURLConnection != null) httpURLConnection.disconnect();
 }
 }
}

3. Controller 暴露

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@RestController
public class FileProxyController {

 /**
 * 通用文件代理接口
 * @param url 内网真实 URL
 * @param fileName 下载文件名
 */
 @GetMapping("/file/proxy")
 public void proxy(@RequestParam("url") String url,
 @RequestParam(value = "fileName", required = false) String fileName,
 HttpServletResponse response) throws IOException {
 FileOperateUtil.proxyUrlFile(response, url, null, fileName);
 }
}

4. 替代方案

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


// ✅ 方案 B：Spring 5+ Resource 方式
@GetMapping("/file/proxy2")
public ResponseEntity<Resource> proxy2(@RequestParam String url) throws IOException {
 URL urlObj = new URL(url);
 InputStreamResource resource = new InputStreamResource(urlObj.openStream());
 return ResponseEntity.ok()
 .contentType(MediaType.APPLICATION_OCTET_STREAM)
 .body(resource);
}

// ✅ 方案 C：直接 redirect（适用于 B 系统本身能对外）
@GetMapping("/file/redirect")
public ResponseEntity<Void> redirect(@RequestParam String url) {
 return ResponseEntity.status(302)
 .header("Location", url)
 .build();
}

5. 实战坑

坑 1：大文件 OOM

1
2
3
4
5
6
7
8
9


// ❌ 错误：把整个文件读进内存
byte[] data = inputStream.readAllBytes();
response.getOutputStream().write(data);

// ✅ 正确：流式 1024 字节 buffer 转发
byte[] buffer = new byte[1024];
while ((len = inputStream.read(buffer)) != -1) {
 outputStream.write(buffer, 0, len);
}

坑 2：Content-Length 缺失导致下载速度慢

1
2


// 主动设置 Content-Length（浏览器可显示进度条）
response.setContentLengthLong(httpURLConnection.getContentLengthLong());

坑 3：中文文件名乱码

1
2


// 文件名 UTF-8 → ISO8859-1 编码（HTTP Header 只支持 ASCII）
String encoded = new String(fileName.getBytes("utf-8"), "ISO8859-1");

坑 4：Nginx 反代超时

如果 A 在 Nginx 后面，Nginx 默认 proxy_read_timeout 60s 会切断长文件传输：

1
2
3
4
5
6


location /file/ {
 proxy_pass http://A_BACKEND;
 proxy_read_timeout 600s; # 10 分钟
 proxy_send_timeout 600s;
 proxy_buffering off; # 关闭缓冲，支持流式
}

场景 2：MongoDB GridFS 大文件存储

1. 适用场景

单文件 > 16MB（MySQL BLOB 不合适）
文件数量大（百万级），需要分布式存储
不想引入 MinIO / HDFS 额外组件

2. 依赖

1
2
3
4


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

1
2
3
4
5


spring:
 data:
 mongodb:
 uri: mongodb://{{MONGO_USER}}:{{MONGO_PASSWORD}}@{{MONGO_HOST}}:27017/files
 database: files

3. GridFS 存储原理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


文件 > 16MB 自动分片存储：

fs.files collection:
 {
 _id: ObjectId("..."),
 filename: "video.mp4",
 length: 524288000, // 总大小
 chunkSize: 261120, // 单 chunk 255KB
 uploadDate: ISODate("..."),
 md5: "abc123..."
 }

fs.chunks collection:
 { files_id: ObjectId("..."), n: 0, data: BinData(...) } // chunk 0
 { files_id: ObjectId("..."), n: 1, data: BinData(...) } // chunk 1
 ...

4. Service 层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


@Service
public class GridfsService {

 @Autowired
 private MongoDbFactory mongoDbFactory;

 /**
 * 上传文件
 */
 public String save(MultipartFile file) throws IOException {
 GridFS gridFS = new GridFS(mongoDbFactory.getDb());

 try (InputStream in = file.getInputStream()) {
 GridFSInputFile gridFile = gridFS.createFile(in);
 gridFile.setFilename(file.getOriginalFilename());
 gridFile.setContentType(file.getContentType());
 gridFile.save();

 return gridFile.getId().toString(); // 返回 ObjectId
 }
 }

 /**
 * 按 ID 查询
 */
 public GridFSDBFile getById(String id) {
 GridFS gridFS = new GridFS(mongoDbFactory.getDb());
 return gridFS.findOne(new BasicDBObject("_id", new ObjectId(id)));
 }

 /**
 * 删除
 */
 public void remove(String id) {
 GridFS gridFS = new GridFS(mongoDbFactory.getDb());
 gridFS.remove(new ObjectId(id));
 }

 /**
 * 分片查询（分页展示文件列表）
 */
 public List<GridFSDBFile> listByFilename(String filename, int skip, int limit) {
 GridFS gridFS = new GridFS(mongoDbFactory.getDb());
 return gridFS.find(filename == null ? new BasicDBObject()
 : new BasicDBObject("filename", filename))
 .skip(skip)
 .limit(limit)
 .toList();
 }
}

5. Controller 层

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


@RestController
public class FileController {

 @Autowired
 private GridfsService gridfsService;

 @PostMapping("/file/upload")
 public Map<String, Object> upload(@RequestParam("file") MultipartFile file) throws IOException {
 String id = gridfsService.save(file);

 Map<String, Object> result = new HashMap<>();
 result.put("id", id);
 result.put("name", file.getOriginalFilename());
 result.put("size", file.getSize());
 result.put("url", "/file/download/" + id);
 return result;
 }

 @GetMapping("/file/download/{id}")
 public void download(@PathVariable String id, HttpServletResponse response) throws IOException {
 GridFSDBFile file = gridfsService.getById(id);
 if (file == null) {
 response.setStatus(HttpServletResponse.SC_NOT_FOUND);
 return;
 }

 response.setContentType(file.getContentType());
 response.setContentLengthLong(file.getLength());
 response.setHeader("Content-Disposition",
 "attachment; filename=\"" +
 new String(file.getFilename().getBytes("utf-8"), "ISO8859-1") + "\"");

 try (OutputStream out = response.getOutputStream()) {
 file.writeTo(out);
 }
 }

 @DeleteMapping("/file/{id}")
 public Map<String, Object> delete(@PathVariable String id) {
 gridfsService.remove(id);
 return Map.of("success", true, "id", id);
 }
}

6. Spring Boot 3.x 用 Spring Data MongoDB 4.x 替代

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


@Service
public class GridfsServiceV2 {

 @Autowired
 private GridFsTemplate gridFsTemplate;
 @Autowired
 private GridFsOperations gridFsOperations;

 public String save(MultipartFile file) throws IOException {
 DBObject metaData = new BasicDBObject();
 metaData.put("uploadUser", "anonymous");
 GridFSFile gridFile = gridFsTemplate.store(
 file.getInputStream(),
 file.getOriginalFilename(),
 file.getContentType(),
 metaData
 );
 return gridFile.getObjectId().toString();
 }

 public void download(String id, HttpServletResponse response) throws IOException {
 GridFSFile gridFile = gridFsOperations.findOne(
 new Query(Criteria.where("_id").is(new ObjectId(id)))
 );
 if (gridFile == null) {
 response.setStatus(HttpServletResponse.SC_NOT_FOUND);
 return;
 }

 response.setContentType(gridFile.getMetadata().get("_contentType").toString());
 response.setContentLengthLong(gridFile.getLength());

 try (OutputStream out = response.getOutputStream()) {
 gridFsOperations.getResource(gridFile).getInputStream().transferTo(out);
 }
 }
}

7. 实战坑

坑 1：Spring Boot 3.x 不再使用 MongoDbFactory

com.mongodb.gridfs.GridFS API 在 Spring Data MongoDB 4.x 中被移除，改用 GridFsTemplate + GridFsOperations。

坑 2：GridFS 单文档 16MB 限制的真相

MongoDB BSON 单文档限制 16MB
GridFS 自动分片：文件 > 16MB 自动拆成 255KB 的 chunk 存储
GridFS 适合任意大小文件（KB 到 GB）

坑 3：分片集群下 GridFS 性能

GridFS 用 fs.files + fs.chunks 两个 collection，推荐对 fs.chunks.files_id + n 建复合索引：

1

db.fs.chunks.createIndex({ files_id: 1, n: 1 });

坑 4：删除文件后磁盘不释放

GridFS 删除只是删除 fs.files 和 fs.chunks 文档，MongoDB 不会立即归还磁盘。需在主节点上执行 db.runCommand({ compact: "fs.chunks" }) 释放空间（运维慎用）。

坑 5：上传大文件超时

1
2
3
4
5
6
7
8


spring:
 servlet:
 multipart:
 max-file-size: 500MB  # 单文件最大
 max-request-size: 500MB
 data:
 mongodb:
 uri: mongodb://...?socketTimeoutMS=60000&connectTimeoutMS=10000

Nginx 也需要配置 client_max_body_size 500m; 和 proxy_read_timeout。

方案选型

场景	推荐方案
小文件 < 16MB	MySQL BLOB / OSS / MinIO
大文件 16MB-1GB	MongoDB GridFS（轻量、零运维）
视频 / 备份 > 1GB	MinIO / S3（对象存储、CDN 友好）
实时流媒体	ZLMediaKit + go2rtc（专用流媒体）
跨外网文件下载	Spring URL 代理（A 系统转发 B 系统）

前置知识与下一步

前置：

Spring Boot 基础
HTTP 协议（响应头、流式传输）
MongoDB 基础（可选）

下一步：

用 MinIO 替代 GridFS（专业对象存储）
断点续传：前端切片 + 后端合并，避开单文件上传限制
CDN 加速：OSS / MinIO + CDN 域名降源站压力

小结

两个场景都是企业级常见需求：

URL 代理下载：用 HttpURLConnection + Servlet 流式转发，避开 A→B 内网穿透限制
GridFS 大文件：MongoDB 自动分片（255KB/chunk），适合 16MB-1GB 范围

关键注意点：

URL 代理必须流式转发（不要 readAllBytes 全部读进内存）
GridFS 在 Spring Boot 3.x 改用 GridFsTemplate API
大文件链路全栈（Spring + Nginx + MongoDB）都要调超时参数

2024+ 视角：MinIO / S3 主导的大文件时代

对象存储是 2024+ 的"正确答案"

2024 之后，MinIO / S3 / OSS 已成为大文件存储的事实标准——GridFS 仅在"不想引入额外组件"的小型项目里用。

1
2
3
4
5
6
7


// Spring Boot 3.x + MinIO（生产推荐）
@Dependency
<dependency>
 <groupId>io.minio</groupId>
 <artifactId>minio-java</artifactId>
 <version>8.5.10</version>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


@Service
public class MinioService {

 @Autowired
 private MinioClient minioClient;

 public String upload(MultipartFile file) throws Exception {
 String objectName = UUID.randomUUID() + "-" + file.getOriginalFilename();

 minioClient.putObject(
 PutObjectArgs.builder()
 .bucket("my-bucket")
 .object(objectName)
 .stream(file.getInputStream(), file.getSize(), -1)
 .contentType(file.getContentType())
 .build()
 );
 return objectName;
 }

 public InputStream download(String objectName) throws Exception {
 return minioClient.getObject(
 GetObjectArgs.builder()
 .bucket("my-bucket")
 .object(objectName)
 .build()
 );
 }

 public String presignedUrl(String objectName, int expirySeconds) throws Exception {
 return minioClient.getPresignedObjectUrl(
 GetPresignedObjectUrlArgs.builder()
 .method(Method.GET)
 .bucket("my-bucket")
 .object(objectName)
 .expiry(expirySeconds)
 .build()
 );
 }
}

预签名 URL（2024+ 推荐方案）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 上传预签名：客户端直传 MinIO，不经过 Java 后端
String uploadUrl = minioClient.getPresignedObjectUrl(
 PutObjectUrlArgs.builder()
 .bucket("my-bucket")
 .object(objectName)
 .expiry(600) // 10 分钟
 .build()
);

// 客户端拿到 URL 直接 PUT 文件
// curl -X PUT --data-binary @file.mp4 "https://minio.example.com/..."

核心优势：

大文件不经过 Java 后端——降低带宽、内存压力
URL 有时效（默认 10 分钟），防盗链
客户端断点续传：Range: bytes=0-10485759 原生支持

MinIO 2024+ 核心特性

纠删码（Erasure Coding）：12 块盘允许坏 4 块，数据不丢
多云联邦：一份数据跨 AWS S3 / 阿里云 OSS / 腾讯云 COS 自动同步
S3 API 100% 兼容——任何 S3 SDK 都能直接对接
K8s Operator GA——MinIO 集群在 K8s 上的官方部署方案

MinIO vs OSS / S3 / COS 对比

维度	MinIO	AWS S3	阿里云 OSS	腾讯云 COS
部署	自建	云	云	云
成本	硬件成本	按量付费	按量付费	按量付费
性能	极高	极高	高	高
S3 兼容	原生	100%	99%	95%
适合	私有化 / 信创	出海 / 全球	国内 ToB	国内 ToC

大文件上传的 2024+ 范式：客户端直传 + 预签名

1
2
3
4
5
6


1. 客户端 → Java 后端：请求上传 URL
2. Java 后端 → MinIO：申请预签名 URL（10 分钟有效）
3. Java 后端 → 客户端：返回预签名 URL + objectName
4. 客户端 → MinIO：直接 PUT 文件（不经过 Java 后端）
5. 客户端 → Java 后端：通知上传完成
6. Java 后端 → DB：保存文件元数据（objectName、大小、MD5）

优势：Java 后端零带宽消耗——100GB 文件上传也不会压垮应用。

大文件下载的 2024+ 范式：CDN + Range

1
2
3


客户端 → CDN（缓存命中）→ 直接返回
 ↓（未命中）
 MinIO（带 Range 头分片）

1
2
3
4
5
6
7


# Nginx 反代 MinIO，开启 Range 支持
location /files/ {
 proxy_pass http://minio-backend:9000;
 proxy_set_header Range $http_range;
 proxy_buffering off;
 proxy_request_buffering off; # 大文件不缓存请求体
}

2024+ GridFS 的真实定位

GridFS 仍适用的场景：

已经在用 MongoDB，不想引入 MinIO
文件量少（百万级以内）
单文件 < 1GB
团队没人懂 MinIO / S3

不适合：

视频、备份等 GB 级文件
大量小文件（百万级以上）
需要 CDN 加速

实战坑（2024+）

MinIO 在 K8s 上：必须用 distributed 模式（4 节点起步），单节点有数据丢失风险
Nginx 反代 MinIO：必须设 proxy_request_buffering off 否则大文件上传会缓存到磁盘
预签名 URL 时区：MinIO 默认 UTC，签名时系统时区不一致会导致签名失败
Spring Cloud 2024+ 推荐方案：直接用 Spring Cloud AWS / Spring Cloud Alibaba OSS 抽象层，跨云切换零成本

经验补记

MinIO Console（2024+ 改名）：内置管理 UI 替代旧的 mc 命令行
MinIO Bucket Replication：跨集群复制"开箱可用"
Rust 写的：Rustic 是 Rust 写的备份工具，原生支持 S3 / MinIO 目标

URL 代理 on Liangweidong's blog

Spring Boot 文件操作实战：URL 代理下载 + GridFS 大文件存储

Spring Boot 文件操作实战：URL 代理下载 + GridFS 大文件存储

背景与价值

场景 1：URL 代理中转下载

1. 架构

2. 核心工具类

3. Controller 暴露

4. 替代方案

5. 实战坑

场景 2：MongoDB GridFS 大文件存储

1. 适用场景

2. 依赖

3. GridFS 存储原理

4. Service 层

5. Controller 层

6. Spring Boot 3.x 用 Spring Data MongoDB 4.x 替代

7. 实战坑

方案选型

前置知识与下一步

小结

2024+ 视角：MinIO / S3 主导的大文件时代

对象存储是 2024+ 的"正确答案"

预签名 URL（2024+ 推荐方案）

MinIO 2024+ 核心特性

MinIO vs OSS / S3 / COS 对比

大文件上传的 2024+ 范式：客户端直传 + 预签名

大文件下载的 2024+ 范式：CDN + Range

2024+ GridFS 的真实定位

实战坑（2024+）

经验补记