Spring-Boot on Liangweidong's blog

GraalVM Native Image 实战：从安装到 Spring Boot 3 原生镜像

Fri, 20 Dec 2024 00:00:00 +0800

GraalVM Native Image 实战：从安装到 Spring Boot 3 原生镜像

背景与价值

GraalVM 是 Oracle 主导的高性能多语言运行时，提供两种工作模式：

JIT 模式（默认）：替代 OpenJDK HotSpot，C2 编译器替换为 Graal 编译器（Java 17 前在 GraalVM 上跑更快，Java 21+ 已接近 HotSpot C2 性能）。
AOT 模式（Native Image）：通过 SubstrateVM 把 Java 字节码提前编译成独立的二进制可执行文件，启动时间从秒级降到毫秒级、内存占用降到 50-100MB、可执行文件可作为容器镜像直接 FROM scratch 部署。

Spring Boot 3 官方原生支持 GraalVM Native Image（无需 reflect-config.json 手写），把传统 100MB+ Fat Jar 缩小到 80MB 级别的可执行文件，是云原生 Serverless 场景下 Java 挑战 Go/Rust 的关键技术。

本文按"安装 → 创建项目 → 编译 → 调优"完整路径展开，含 Windows + Visual Studio 环境踩坑、Spring Boot 3.4.3 + GraalVM 21.0.2 实测可复现。

GraalVM 安装与版本选择

社区版 vs 企业版

维度	GraalVM CE（社区版）	GraalVM EE（企业版）
来源	`github.com/graalvm/graalvm-ce-builds`	`www.oracle.com/cn/java/graalvm/`
授权	GPLv2 + Classpath Exception	Oracle 免费下载，商业可用
Native Image	内置（GraalVM 21+ 起无需 `gu install`）	内置 + 商业增强
性能优化	基础	额外 G1/ZGC 调优、PGO 配置文件
推荐场景	学习、开源、本地开发	生产环境、商业项目

GraalVM 21+ 已经把 native-image 内置到发行版，不再需要早期 gu install native-image 那种安装方式。

下载与配置（Windows 为例）

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


# 1. 下载（社区版 JDK 21）
# https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-21.0.2/graalvm-community-jdk-21.0.2_windows-x64_bin.zip

# 2. 解压到 <DEV_DIR>\graalvm-community-openjdk-21.0.2+13.1

# 3. 配置环境变量（PowerShell 管理员）
setx /M GRAALVM_HOME "<DEV_DIR>\graalvm-community-openjdk-21.0.2+13.1"
setx /M JAVA_HOME "%GRAALVM_HOME%"
setx /M Path "%JAVA_HOME%;%Path%"

# 4. 验证
java -version
# openjdk version "21.0.2" 2024-01-16
# OpenJDK Runtime Environment GraalVM CE 21.0.2+13.1 (build 21.0.2+13-jvmci-23.1-b30)

Windows 编译前置：Visual Studio + MSVC

Native Image 在 Windows 上需要 Visual Studio 2022 17.6.0+ 的 MSVC 工具链。

关键坑：Visual Studio 默认安装中文语言包，但 GraalVM Native Image 内部调用 cl.exe 时只识别英文输出。报错：

1

Native-image building on Windows currently only supports target architecture: AMD64 (?? unsupported)

解决方案：

打开 开始菜单 → Visual Studio Installer → 修改
在"语言包"页签：取消勾选中文，勾选英语
重新打开 x64 Native Tools Command Prompt for VS 2022 编译

需安装的组件清单：

组件	必需
C++ 桌面开发	✅
MSVC v143 工具集	✅
实时调试器	✅
C++ CMake 工具	✅
C++ AddressSanitizer	可选
Windows 11 SDK (10.0.22621.0)	✅

Spring Boot 3 项目创建

1. IDEA 初始化

https://start.spring.io 是官方脚手架，国内访问可用阿里云镜像 https://start.aliyun.com/（注意：阿里镜像可能落后 1-2 个版本，生产项目建议直连官方源）。

依赖选择：

Spring Boot：3.4.3（最新 GA）
Developer Tools：GraalVM Native Support（关键，自动配置 native-maven-plugin）、Lombok
Web：Spring Web
其他按业务需求：Spring Data JPA / MyBatis-Plus / Redis / Nacos Discovery 等

2. 验证运行时

1
2
3
4
5
6


# 启动（首次启动约 1.0 秒）
mvn spring-boot:run

# 验证端口
curl http://localhost:8080/hello
# 输出：Hello GraalVM!

原生镜像编译

1. 编译命令

1
2


# 必须从 x64 Native Tools Command Prompt for VS 2022 进入
mvn -Pnative native:compile

2. 编译过程（典型 8 阶段）

GraalVM Native Image 在 8 个阶段中完成 AOT 编译：

阶段	动作	典型耗时	输出
1. Initializing	解析 `native-image` 参数、加载 metadata	5-10s	内存中的配置
2. Performing analysis	静态分析，构建可达类型/字段/方法图	20-30s	Reachability metadata
3. Building universe	关闭点（Points-to）分析，构建类型图	3-5s	Universe 模型
4. Parsing methods	解析每个方法的字节码	2-3s	字节码 IR
5. Inlining methods	方法内联优化	1-2s	优化后 IR
6. Compiling methods	Graal 编译器把 IR 转成机器码	15-25s	机器码
7. Layouting methods	内存布局（对象头、字段偏移）	3-5s	布局信息
8. Creating image	链接所有部分生成可执行文件	5-8s	`target/<app>.exe`

实测 Spring Boot 3.4.3 Hello World 完整编译：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[1/8] Initializing... (5.6s @ 0.32GB)
[2/8] Performing analysis... [******] (24.1s @ 1.85GB)
 17,395 reachable types (90.2% of 19,284 total)
 26,735 reachable fields (64.7% of 41,310 total)
 82,470 reachable methods (62.9% of 131,060 total)
 5,538 types, 458 fields, and 6,309 methods registered for reflection
[8/8] Creating image... [***] (5.6s @ 2.52GB)
 40.58MB (50.77%) for code area: 53,053 compilation units
 38.89MB (48.67%) for image heap: 405,127 objects and 304 resources
 79.92MB in total

3. 关键产物

1
2
3


# 生成的二进制（80MB 级别）
target/graalvm-spb-demo.exe # Windows
target/graalvm-spb-demo # Linux

启动性能对比

JVM 模式 vs Native Image

维度	JVM（HotSpot）	GraalVM Native Image
启动时间	1.0-3.0s	50-150ms（毫秒级）
内存占用	200-500MB	50-100MB（RSS 内存峰值）
镜像大小	50-200MB Fat Jar	80MB 二进制 + 极小运行时
峰值吞吐	高（JIT 热点优化）	略低 5-15%（缺 JIT 持续优化）
冷启动延迟	高（类加载 + JIT 预热）	极低（无 JIT）
反射/动态代理	✅ 完整支持	⚠️ 需配置 metadata

容器化部署（FROM scratch）

1
2
3
4
5
6
7
8


# 多阶段构建第一阶段：在 x64 Native Tools 环境编译
# 略（见上 mvn -Pnative native:compile）

# 第二阶段：极简运行时镜像（无需 JRE）
FROM scratch
COPY --from=builder /workspace/target/graalvm-spb-demo /app
EXPOSE 8080
ENTRYPOINT ["/app"]

最终镜像约 85-120MB，对比传统 openjdk:21-jre + app.jar 的 250-400MB 缩小 60-70%。

调优与常见坑

1. 反射 / 动态代理配置

Native Image 在 AOT 时无法做运行时类加载，所以反射、动态代理、序列化等场景需要提前通过 reflect-config.json 声明：

1
2
3
4
5
6
7


[
 {
 "name": "com.example.User",
 "fields": [{"name": "id"}, {"name": "name"}],
 "methods": [{"name": "<init>", "parameterTypes": ["long", "java.lang.String"]}]
 }
]

Spring Boot 3 + GraalVM Native Support 自动生成常见场景的 metadata，但自定义反射/序列化仍需手动补充。

2. 资源与初始化时机

1
2
3
4
5
6
7
8


// ❌ 错误：运行时类加载 + 反射
Class.forName("com.example.Plugin").newInstance();

// ✅ 正确：AOT 时确定类型 + 显式调用
@BuildTimePlugin
public class MyPlugin implements Plugin {
 public MyPlugin() { /* 显式构造 */ }
}

3. GraalVM Reachability Metadata 仓库

1
2
3
4
5
6
7


# 在 pom.xml 配置 reachability metadata 自动下载
<configuration>
 <metadataRepository>
 <enabled>true</enabled>
 <url>https://repo1.maven.org/maven/org/graalvm/buildtools/maven-plugin-reachability-metadata/</url>
 </metadataRepository>
</configuration>

例如 logback-classic 1.5.16 自动匹配到 1.4.9 的 metadata（向后兼容），无需手动写。

4. 启动优化建议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# application.yml 关闭不必要功能
spring:
 main:
 lazy-initialization: true # 延迟初始化（首请求稍慢但启动更快）
 jpa:
 hibernate:
 ddl-auto: validate  # 不要每次启动重建表
 data:
 redis:
 repositories:
 enabled: false # 不用 Spring Data Redis Repository

适用场景与不适用场景

不推荐用

长时间运行的高吞吐服务：JIT 持续优化下 HotSpot 性能反而更好
大量反射 / 字节码生成（AOP、ORM、动态代理密集）：metadata 维护成本高
依赖大量 Java 生态库（Hadoop、Flink 等）：native 兼容性需逐个验证

前置知识与下一步

前置：

Spring Boot 3 基础（推荐先读 Spring Boot 入门）
Java 17+ 语法（Sealed Class、Record、Pattern Matching）
Docker 多阶段构建基础

下一步：

复杂反射场景用 Micrometer + tracing + 显式代理规避 metadata
用 Buildpacks（mvn -Pnative spring-boot:build-image）一键出 OCI 镜像
生产部署用 Native Image + Kubernetes + Horizontal Pod Autoscaler，结合 HPA 实现 0 延迟弹性

小结

GraalVM Native Image 是 Java 在云原生时代的关键拼图。Spring Boot 3 让上手成本降到 1 个依赖（GraalVM Native Support）+ 1 个命令（mvn -Pnative native:compile）。80MB 级别镜像 + 毫秒级启动 + FROM scratch 部署，让 Java 在 Serverless 场景首次具备和 Go/Rust 正面竞争的性能。代价是反射/动态代理受限，需要在 AOT 可达性分析边界内设计应用架构。

Spring Boot 与 JDK 版本演进：从 1.5 到 3.2 的二十年 Java 生态大事记

Sun, 15 Dec 2024 00:00:00 +0800

2024 年 12 月，Spring Boot 3.4 刚发布、JDK 21 LTS 满一年、JDK 17 LTS 满三年。回看过去 28 年（1996 JDK 1.0 - 2024 Spring Boot 3.4），Java 生态的版本节奏从"5 年一版 LTS"加速到"2 年一版 LTS"。对于一个 Java 团队来说，版本选型就是技术战略。

本文写于 2024 年 12 月——JDK 17 LTS 是当下主推、JDK 21 LTS 崭露头角，Spring Boot 3.3/3.4 是生产首选。下文的部分早期版本（JDK 8、JDK 11、Spring Boot 2.x）以"2024 视角回望"的方式呈现。

一、JDK 版本演进时间线（1996-2024）

版本	发布日期	关键特性	状态
JDK 1.0	1996-01-23	Java 起点	已淘汰
JDK 1.1	1997-02-19	内部类、反射、JavaBeans	已淘汰
JDK 1.2	1998-12-04	Collections 框架、JIT、Swing	已淘汰
JDK 1.3	2000-05-08	HotSpot JVM、JavaSound	已淘汰
JDK 1.4	2002-02-13	正则、NIO、日志、XML	已淘汰
JDK 1.5	2004-09-30	泛型、注解、枚举、并发包	已淘汰
JDK 1.6	2006-04	动态语言支持、HTTP Server API	已淘汰
JDK 1.7	2011-07-28	G1 回收器、try-with-resources、菱形语法	已淘汰
JDK 1.8 LTS	2014-03-18	Lambda、Stream、Optional、Nashorn、移除 PermGen	当前生产主力
JDK 9.0	2017-09-21	模块系统（JPMS）、JShell、HTTP/2 Client	已淘汰
JDK 10.0	2018-03-21	局部变量类型推断 `var`	已淘汰
JDK 11 LTS	2018-09-25	HttpClient、ZGC（实验）、Lambda var、移除 Java EE/CORBA	生产新主力
JDK 12.0	2019-03-19	Switch 表达式（预览）	已淘汰
JDK 13.0	2019-09-17	文本块（预览）	已淘汰
JDK 14.0	2020-03-17	Records（预览）、NPE 增强提示	已淘汰
JDK 15.0	2020-09-15	ZGC + 密封类（预览）	已淘汰
JDK 16.0	2021-03-16	Records 正式	已淘汰
JDK 17 LTS	2021-09-15	Sealed Classes 正式、Switch 模式匹配	2024 当下生产主力
JDK 21 LTS	2023-09	虚拟线程正式	2024 新晋 LTS

1.1 LTS 节奏

1.6 (2006) → 1.7 (2011)：5 年
1.7 (2011) → 1.8 (2014)：3 年
1.8 (2014) → 11 (2018)：4 年（Oracle 改为"3 年一版 LTS"）
11 (2018) → 17 (2021)：3 年
17 (2021) → 21 (2023)：2 年（开始加速）

对企业选型的启示：

5-7 年一个 LTS 周期，意味着企业 JDK 升级周期约为 3-5 年
选 LTS 版本长期维护，规避非 LTS 短期版本

1.2 JDK 8 的"长寿"原因

JDK 8（2014-03-18 发布）到 2024 年 12 月已经 10 年，至今仍有一批存量系统在跑（行业惯性 + 商业 JDK 8 商业支持仍在售）。原因：

Lambda + Stream 改变 Java 编程范式
Optional + CompletableFuture 提升函数式能力
方法引用 / 默认方法 增强接口演进能力
Nashorn（已废弃）首次带来 JVM 跑 JS 能力
PermGen → Metaspace 减少 OOM 痛点

直到 JDK 11 出现，Java 生态才"集体升级"。2024 视角回望：JDK 8 的"长寿"在 JDK 11 / JDK 17 之后才被真正打破——这也是 LTS 节奏从 5 年压缩到 2 年的拐点。

1.3 JDK 11 的 5 大新特性

HTTP Client API 标准化（孵化多版本后正式）
ZGC 可用（毫秒级 GC 暂停，4TB 堆支持）
Lambda 参数 var（写 (var x, var y) -> ...）
移除 Java EE / CORBA（瘦身 30%+）
飞行记录器（JFR）开放（生产可启用）

二、Spring Boot 版本演进时间线（2014-2024）

版本	发布日期	关键特性	JDK 要求
Spring Boot 1.0	2014-04	起步	JDK 6+
Spring Boot 1.2	2015-01	引入 starter 体系	JDK 6+
Spring Boot 1.3	2015-11	`@SpringBootApplication`	JDK 6+
Spring Boot 1.4	2016-04	`@SpringBootTest`	JDK 6+
Spring Boot 1.5	2017-01	Kafka/Actuator 完善	JDK 7+
Spring Boot 2.0	2018-03	WebFlux、Reactive、Java 8+	JDK 8+
Spring Boot 2.1	2018-10	GraalVM（实验）、性能优化	JDK 8+

2.1 Spring Boot 版本命名规则

1
2
3
4
5
6
7
8
9


Alpha：不建议使用，主要是以实现软件功能为主，通常只在软件开发者内部交流，Bug 较多；
Beta：该版本相对于α版已有了很大的改进，消除了严重的错误，但还是存在着一些缺陷，需要经过多次测试来进一步消除；
GA：General Availability，正式版本，官方推荐使用此版本，在国外都是用GA来说明release版本；
M：又叫里程碑版本，表示该版本较之前版本有功能上的重大更新；
PRE(不建议使用)：预览版，内部测试版，主要是给开发人员和测试人员测试和找BUG用的；
Release：最终版本，Release不会以单词形式出现在软件封面上，取而代之的是符号®；
RC：该版本已经相当成熟了，基本上不存在导致错误的BUG，与即将发行的正式版相差无几；
SNAPSHOT：快照版，可以稳定使用，且仍在继续改进版本。
SR.X：修正版，服务版本，当项目发布积累到一定程度，需要修复该版本中的某个错误后以此来命名，X表示数字。

2.2 截至 2024-12 的版本选择

1
2
3


3.0.0(SNAPSHOT) 最少 java17 （未发布）
2.7.5(SNAPSHOT) 最少 java8 （生产）
2.6.13(SNAPSHOT) 最少 java8 （生产）

生产推荐（2024 视角）：

保守派：Spring Boot 3.3 + JDK 17（LTS 长期维护组合）
激进派：Spring Boot 3.4 + JDK 21（虚拟线程 + 模式匹配）
存量维护：Spring Boot 2.7（已于 2023-11 停止 OSS 支持，仅商业支持）

2.3 Spring Boot 2.6 → 2.7 关键变化

2.6（2021-11）默认禁止循环引用：

1
2
3
4


# application.yml
spring:
 main:
 allow-circular-references: true # 2.6 之前隐式允许，2.6+ 默认禁止

2.7（2022-05）核心新特性：

@AutoConfiguration 注解（替换过时的注册方式）
GraphQL 支持
Podman 支持（替代 Docker）
RabbitStreamTemplate 支持
Hazelcast 支持
Cache2k 支持
Web Server SSL 增强
Info 端点增强
单元测试加强

三、版本选型实战建议（2024 年时点）

3.1 新项目起步

场景	JDK	Spring Boot
企业内部管理系统	17	3.3
互联网电商	21（虚拟线程）	3.4
金融/政府强合规	17（合规）	3.2（稳定）
IoT 边缘计算	21	3.4

3.2 升级路径

JDK 8 → JDK 11 升级清单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# 1. 升级构建工具
mvn -version # 确认 Maven 3.5+

# 2. 升级依赖
<dependency>
 <groupId>javax.xml.bind</groupId> <!-- 移除 -->
 <artifactId>jaxb-api</artifactId>
</dependency>
<!-- 替换为 -->
<dependency>
 <groupId>jakarta.xml.bind</groupId> <!-- JDK 11+ -->
 <artifactId>jakarta.xml.bind-api</artifactId>
 <version>2.3.3</version>
</dependency>

# 3. 升级 IDE
# IntelliJ IDEA 2018.3+ 支持 JDK 11

# 4. 升级框架
<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>2.1.0.RELEASE</version>
</parent>

Spring Boot 1.5 → 2.1 升级清单：

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


<!-- javax → jakarta 替换 -->
<dependency>
 <groupId>javax.servlet</groupId>
 <artifactId>javax.servlet-api</artifactId>
</dependency>
<!-- 替换为 -->
<dependency>
 <groupId>javax.servlet</groupId>
 <artifactId>javax.servlet-api</artifactId>
 <version>4.0.1</version> <!-- 升级到 4.0+ 支持 Jakarta EE -->
</dependency>

<!-- Tomcat 8 → 9 -->
<!-- Hibernate 5 → 6 -->
<!-- Thymeleaf 3 → 4 -->

3.3 监控升级

升级后必做的几件事：

JVM 启动参数对比：

1
2
3
4
5


# JDK 8
JAVA_OPTS="-Xms4g -Xmx4g -XX:PermSize=512m -XX:MaxPermSize=512m"

# JDK 11+（PermGen 已被移除）
JAVA_OPTS="-Xms4g -Xmx4g -XX:MetaspaceSize=512m -XX:MaxMetaspaceSize=512m"

GC 切换：

1
2
3
4
5
6
7
8
9


# JDK 8 默认
-XX:+UseParallelGC

# JDK 11 推荐（低延迟）
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200

# JDK 11 试验（超低延迟）
-XX:+UseZGC

监控接入：

1
2
3
4
5
6
7
8
9


# Spring Boot 2.1 Actuator
management:
 endpoints:
 web:
 exposure:
 include: "*"
 endpoint:
 health:
 show-details: always

四、写在最后

2024 年这个时点，Java 生态已经历了"JDK 17 → JDK 21"、“Spring Boot 2.x → 3.x"两轮大升级。对于一个想保持竞争力的 Java 团队：

保守策略：JDK 17 + Spring Boot 3.3 → 2025 评估 JDK 21 升级
激进策略：JDK 21 + Spring Boot 3.4（2024 当下就用，吃虚拟线程红利）

个人建议：

2024 年新项目：直接用 JDK 21 + Spring Boot 3.4

已有项目升级：以 JDK 17 + Spring Boot 3.3 为目标版本，2025 上半年完成

长期规划：2026 年底前完成所有项目 JDK 21 升级

五、2024 视角回望 2018

站在 2024 年 12 月回望 2018 年 12 月那篇文章的选型判断，6 年时间 Java 生态的演进有三条主线：

LTS 节奏真正加速：2018 年还是"3 年一版 LTS"的预期，2024 年看是"2 年一版 LTS”（17→19→21）。企业升级窗口期被进一步压缩
Spring Boot 2.6/2.7 完成了 1.x → 2.x 最后的过渡：默认禁止循环引用（2.6）、@AutoConfiguration 注解（2.7）都是为 3.0 破坏性升级铺路
GraalVM 从实验变实战：2018 年 Spring Boot 2.1 提"GraalVM 实验"，到 2024 年 Spring Boot 3.x + GraalVM Native Image 已成云原生部署标配
JDK 8 的"超长服役"被打破：2024 年新项目几乎默认 JDK 17+，“用 JDK 8 起步"已是历史

参考资料

MinIO 对象存储实战：单节点 / 集群 / 桶复制 / Spring Boot 集成

Thu, 15 Sep 2022 00:00:00 +0800

MinIO 是 S3 兼容的开源对象存储——国内用得最多的"自建 S3"。本篇把单节点部署、4 节点集群搭建、桶复制双向同步、漏洞修复、Spring Boot 集成一次性整理清楚。

阅读对象：需要自建对象存储的后端 / 运维工程师 覆盖范围：MinIO 单节点 / 4 节点集群 / mc 客户端 / 桶复制 / 主主双向同步 / CVE 漏洞修复 / Nginx 反代安全加固 / Spring Boot 集成 / 分片上传 / 断点续传

一、MinIO 简介

MinIO 的核心特点：

S3 兼容：所有 S3 SDK / 工具都能直接对接
高性能：单机读写可达 100+ GB/s
纠删码：默认 EC:4（4 份数据分片可容忍 4 块盘坏）
多语言 SDK：Java / Go / Python / Node.js / .NET
部署简单：单二进制 + 一个目录就能跑

对比：

维度	MinIO	Ceph	SeaweedFS
部署难度	极简	复杂	中等
性能	极高	高	高
集群最少节点	1（4 节点为生产推荐）	3	3
S3 兼容	100%	✅	✅
适用规模	TB ~ 100PB	PB+	TB ~ PB

When to use：

替代 AWS S3、阿里云 OSS 做自托管

存图片 / 视频 / 备份文件 / 日志

大数据 / AI 训练数据湖

二、单节点部署

2.1 拉取镜像

1

docker pull minio/minio:RELEASE.2023-06-09T07-32-12Z.fips

2.2 启动

1
2
3
4
5
6
7
8
9


docker run -d --name minio --restart=always \
 -p 9091:9091 \
 -p 9090:9090 \
 -v /home/docker/data:/data \
 -e "MINIO_ROOT_USER=root" \
 -e "MINIO_ROOT_PASSWORD={{REDACTED}}" \
 -e "MINIO_SERVER_URL=http://internal.example.com:9091" \
 minio/minio:RELEASE.2023-06-09T07-32-12Z.fips \
 server /data --console-address ":9090" --address ":9091"

端口分配：

9091：S3 API（程序用这个）
9090：Web Console（管理用这个）

环境变量：

MINIO_ROOT_USER / MINIO_ROOT_PASSWORD：管理员账号（旧版本是 MINIO_ACCESS_KEY / MINIO_SECRET_KEY）
MINIO_SERVER_URL：S3 API 外部地址——代码里要用这个

2.3 启动后状态

1
2
3


Status: 1 Online, 0 Offline.
S3-API: http://172.17.0.12:9000 http://127.0.0.1:9000
Console: http://172.17.0.12:9090 http://127.0.0.1:9090

进入容器：

1
2


docker exec -it minio bash
# 配置文件：/usr/local/minio/config

三、4 节点集群部署

3.1 集群规划

节点	IP	角色
node1-1	10.0.1.1	机房 1
node1-2	10.0.1.2	机房 1
node2-1	10.0.2.1	机房 2
node2-2	10.0.2.2	机房 2

3.2 /etc/hosts 配置

1
2
3
4
5
6
7


# 4 个节点都执行
cat >> /etc/hosts <<'EOF'
10.0.1.1 node1-1
10.0.1.2 node1-2
10.0.2.1 node2-1
10.0.2.2 node2-2
EOF

3.3 启动集群

1
2
3
4
5
6
7
8
9


docker run -d --restart=always --name minio \
 --net=host \
 -e MINIO_ROOT_USER=root \
 -e MINIO_ROOT_PASSWORD={{REDACTED}} \
 -v /data/minio/data1:/data1 \
 -v /data/minio/data2:/data2 \
 minio/minio:RELEASE.2023-06-09T07-32-12Z.fips \
 server http://node1-{1...2}:9000/data{1...2} http://node2-{1...2}:9000/data{1...2} \
 --console-address ":9090" --address ":9091"

关键参数：

--net=host：集群通信必须 host 网络
4 节点 8 盘：默认 EC:4 编码，可容忍 4 块盘同时损坏
/data1 /data2：每个节点挂 2 块盘
node1-{1...2}：Docker 展开为 node1-1 node1-2

3.4 集群运维

1
2
3
4
5


# 查看集群状态
mc admin info minio-cluster

# 看每个节点磁盘
mc admin info minio-cluster --json | jq '.info.servers[].state'

四、mc 客户端

4.1 安装

1
2
3
4
5
6


# Linux
curl https://dl.min.io/client/mc/release/linux-amd64/mc -o /usr/local/bin/mc
chmod +x /usr/local/bin/mc

# Windows
# 下载 https://dl.min.io/client/mc/release/windows-amd64/mc.exe

4.2 常用命令

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


# 配置 server alias
mc config host add <ALIAS> <S3-ENDPOINT> <ACCESS-KEY> <SECRET-KEY>

# 列出文件
mc ls <ALIAS>/<bucket>

# 创建 bucket
mc mb <ALIAS>/<bucket-name>

# 上传
mc cp <local-path> <ALIAS>/<bucket>/<key>

# 同步
mc mirror <src> <dst>

# 删除
mc rm <ALIAS>/<bucket>/<key> --recursive --force

4.3 完整示例

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


# 1. 加 alias
mc alias set prod http://minio.internal.example.com:9091 root {{REDACTED}}
mc alias set staging http://minio-staging.internal.example.com:9091 root {{REDACTED}}

# 2. 列出所有 bucket
mc ls prod

# 3. 上传整个目录
mc cp ./uploads/ prod/file/ --recursive

# 4. 同步两个 bucket（增量）
mc mirror prod/file staging/file

# 5. 带版本号恢复
mc cp --rewind "2025-12-12T08:00:00Z" --recursive prod/file/dev/ prod/file/dev/

五、桶复制：跨集群数据同步

5.1 单向复制

1
2
3
4
5
6
7
8
9


# 源集群：minio-prod
# 目标集群：minio-staging

# 在目标集群创建 bucket
mc mb minio-staging/file

# 在源集群加复制规则
mc replicate add minio-prod/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-staging.internal.example.com:9091/file

注意：

源和目标 MinIO 版本必须一致
桶复制只同步新文件，存量数据用 mc mirror 全量同步

5.2 双向主主复制

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


# 在两个集群都执行

# prod 集群
mc replicate add minio-prod/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-staging.internal.example.com:9091/file \
 --replicate "delete,delete-marker,existing-objects" \
 --sync

# staging 集群
mc replicate add minio-staging/file \
 --remote-bucket http://{{REPL_USER}}:{{REPL_PASS}}@minio-prod.internal.example.com:9091/file \
 --replicate "delete,delete-marker,existing-objects" \
 --sync

# 启用版本控制
mc version enable minio-prod/file
mc version enable minio-staging/file

效果：

上传到 prod 自动同步到 staging
上传到 staging 自动同步到 prod
删除同步

停机测试：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1. 停 staging
docker stop minio-staging

# 2. 上传到 prod
mc cp test.txt minio-prod/file/

# 3. 启动 staging
docker start minio-staging

# 4. 等待 sync 自动同步（一般 30 秒内）
mc ls minio-staging/file/

六、漏洞修复：桶路径遍历

6.1 漏洞描述

CVE 严重等级：高。当 MinIO 暴露在公网 + 配置 Access Policy 为 public 时，任何人通过桶路径就能列出所有文件：

1

http://minio.example.com:9091/file/

返回的 XML 包含整个桶的所有文件元信息（文件名 + 大小 + 修改时间）。敏感数据直接泄露。

6.2 漏洞根源

listObjects 默认返回 1000 条
公开 bucket + 公开 URL = 可遍历所有资源

6.3 修复方案

方案 A：Nginx 反代 + 路径屏蔽（最推荐）

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


server {
 listen 80;
 server_name minio.example.com;

 # 屏蔽桶路径直接访问
 location ^~ /images {
 rewrite ^/images/(.+)$ /images/$1 break;
 proxy_pass http://minio_local_url/;
 }
 # 其他路径禁止
 location / {
 return 403;
 }
}

效果：

http://minio.example.com/images/bucket/file.txt → ✅ 正常下载
http://minio.example.com/images/bucket/ → ❌ 403 禁止列出

方案 B：Bucket 权限收紧

进入 MinIO Console → Bucket → Access Policy → Custom：

1
2


Prefix: *
Access: Read Only (no List)

这样单个文件还能下载，但桶路径列出被禁止。

方案 C（最佳实践）：

MinIO 不暴露公网：只在内网
Nginx 反代 + 路径重写：唯一对外的入口
Bucket 全部 private：永远不开 public
预签名 URL 访问：临时分享用 mc share 或 SDK 生成

七、Spring Boot 集成

7.1 添加依赖

1
2
3
4
5


<dependency>
 <groupId>io.minio</groupId>
 <artifactId>minio</artifactId>
 <version>8.5.10</version>
</dependency>

7.2 配置文件

1
2
3
4
5


minio:
 endpoint: http://minio.internal.example.com:9091
 access-key: root
 secret-key: {{REDACTED}}
 bucket: file

7.3 Spring Boot 配置类

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


@Configuration
public class MinioConfig {
 @Value("${minio.endpoint}")
 private String endpoint;
 @Value("${minio.access-key}")
 private String accessKey;
 @Value("${minio.secret-key}")
 private String secretKey;

 @Bean
 public MinioClient minioClient() {
 return MinioClient.builder()
 .endpoint(endpoint)
 .credentials(accessKey, secretKey)
 .build();
 }
}

7.4 上传服务

 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


@Service
public class MinioService {
 @Autowired
 private MinioClient minioClient;

 public String uploadFile(MultipartFile file, String bucket) throws Exception {
 String objectName = UUID.randomUUID().toString() + "-" + file.getOriginalFilename();

 // 1. 确保 bucket 存在
 boolean found = minioClient.bucketExists(BucketExistsArgs.builder().bucket(bucket).build());
 if (!found) {
 minioClient.makeBucket(MakeBucketArgs.builder().bucket(bucket).build());
 }

 // 2. 上传
 minioClient.putObject(
 PutObjectArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .stream(file.getInputStream(), file.getSize(), -1)
 .contentType(file.getContentType())
 .build()
 );

 return minioClient.getPresignedObjectUrl(
 GetPresignedObjectUrlArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .method(Method.GET)
 .build()
 );
 }
}

八、Spring Boot 高级特性

8.1 分片上传

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


public String initiateMultipartUpload(String bucket, String fileName) throws Exception {
 return minioClient.initiateMultipartUploadAsync(
 InitiateMultipartUploadArgs.builder()
 .bucket(bucket)
 .object(fileName)
 .build()
 ).get().uploadId();
}

public void uploadPart(String bucket, String fileName, String uploadId,
 int partNumber, InputStream data, long size) throws Exception {
 minioClient.uploadPartAsync(
 UploadPartArgs.builder()
 .bucket(bucket)
 .object(fileName)
 .uploadId(uploadId)
 .partNumber(partNumber)
 .stream(data, size, -1)
 .build()
 ).get();
}

8.2 断点续传

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 1. 客户端检查已上传的分片
ListPartsResponse parts = minioClient.listParts(listPartsArgs);

// 2. 跳过已上传的分片
for (int i = 0; i < parts.result().partList().size(); i++) {
 Part part = parts.result().partList().get(i);
 log.info("已上传分片: {} ({} bytes)", part.partNumber(), part.size());
}

// 3. 接着上传未完成部分

8.3 秒传

1
2
3
4
5
6


public boolean isFileExist(String bucket, String md5) throws Exception {
 Iterable<Result<Item>> results = minioClient.listObjects(
 ListObjectsArgs.builder().bucket(bucket).prefix(md5).build()
 );
 return results.iterator().hasNext();
}

前端流程：

1
2
3
4


1. 计算文件 MD5
2. 调后端接口 "isFileExist(md5)"
3. 如果存在 → 秒传成功（直接返回 URL）
4. 如果不存在 → 走后端生成上传凭证 → 前端直传 MinIO

8.4 文件合并

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


// 前端传完所有分片后调
public void composeFile(String bucket, String targetName, List<String> parts) throws Exception {
 List<ComposeSource> sources = new ArrayList<>();
 for (int i = 0; i < parts.size(); i++) {
 sources.add(ComposeSource.builder()
 .bucket(bucket)
 .object(parts.get(i))
 .build());
 }
 minioClient.composeObject(
 ComposeObjectArgs.builder()
 .bucket(bucket)
 .object(targetName)
 .sources(sources)
 .build()
 );
}

8.5 Nginx 上传调优

1
2
3


# 加大请求体（默认 1m 太小）
client_max_body_size 1024m;
keepalive_timeout 75s;

8.6 Spring Boot 上传调优

1
2
3
4
5


spring:
 servlet:
 multipart:
 max-file-size: 1024MB
 max-request-size: 1024MB

九、监控与运维

9.1 Prometheus metrics

MinIO 默认暴露 /minio/v2/metrics/cluster 端点：

1
2
3
4
5
6


# prometheus.yml
scrape_configs:
 - job_name: 'minio'
 metrics_path: '/minio/v2/metrics/cluster'
 static_configs:
 - targets: ['minio.internal.example.com:9091']

9.2 关键指标

minio_cluster_disk_used_total：磁盘使用
minio_cluster_disk_free_total：剩余空间
minio_s3_requests_total：S3 请求数
minio_s3_requests_errors_total：错误数

9.3 告警规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


groups:
- name: minio
 rules:
 - alert: MinIODiskFull
 expr: minio_cluster_disk_free_total / minio_cluster_disk_total < 0.1
 for: 5m
 labels:
 severity: critical
 annotations:
 summary: "MinIO 磁盘使用率超过 90%"

十、典型坑位

10.1 启动报 “no credentials”

修复：

1
2


# 环境变量要用 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD（v4 之后）
# 不是 MINIO_ACCESS_KEY / MINIO_SECRET_KEY

10.2 集群节点无法通信

症状：集群启动后某个节点状态 Offline。

修复：

4 个节点 /etc/hosts 都加完整映射
检查 9000 端口互通：nc -zv node1-2 9000
防火墙放过 9000

10.3 上传文件 0 字节

症状：Java 上传后文件 0 字节。

修复：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 错误写法
minioClient.putObject(bucket, objectName, inputStream);

// 正确写法：必须传 size
minioClient.putObject(
 PutObjectArgs.builder()
 .bucket(bucket)
 .object(objectName)
 .stream(inputStream, inputStream.available(), -1)
 .build()
);

inputStream.available() 在某些流上返回 0，必须手动传 size。

十一、最佳实践清单

MinIO 永远不暴露公网：内网 + Nginx 反代
Bucket 全部 private：用预签名 URL 临时分享
Nginx 路径重写：屏蔽桶路径直接访问
集群至少 4 节点：生产强烈推荐
EC 编码：默认 EC:4，可容忍 4 块盘坏
版本控制必开：防止误删除
桶复制必配：跨机房 / 跨地域容灾
Prometheus 监控：磁盘 / 请求 / 错误率
定期备份：用 mc mirror 备份到 OSS

2024+ 视角补充

本文写于 2022-09，2024-2026 期间 MinIO 关键演进：

MinIO RELEASE.2024-08+：AI 推理优化（GPU 直通 / 大模型权重加载）；Iceberg / Delta Lake 表格式支持（数据湖场景）
MinIO 2024+ 性能：单节点 100+ GB/s（NVMe + 网络优化）；EC 编码 8+2（vs 之前 4+2）—— 更大集群容错
MinIO 2025+：Kubernetes Operator GA——minio/operator 已是生产级（强烈推荐 K8s 部署）
MinIO 许可证变更（2024-01）：AGPL 3.0——之前是 Apache 2.0。这对SaaS 厂商影响大（必须开源），企业内部自用无影响
竞品（2024+ 视角）：
- Ceph Quincy / Reef（2024-2025）：Ceph 18 Reef 性能优化（vs MinIO 优势在多协议——RBD / CephFS / RGW）
- Garage 1.0+（2024-2025）：Rust 写的小型 S3 兼容存储——轻量替代
- SeaweedFS 3.x（2024）：FUSE 挂载 / 极简部署
- Cloudflare R2 / Backblaze B2 / 阿里云 OSS（公有云 S3 兼容）——按量计费无需运维

实战建议（2025-2026 视角）：

企业内部 S3 兼容存储 → MinIO 仍是首选（AGPL 不影响自用）
K8s 部署 → MinIO Operator（K8s Operator 模式）2025+ 是生产级
数据湖 / 大数据 → MinIO + Iceberg / Delta Lake（2024-2025 主流）
公有云 → 直接用 R2 / OSS / S3，避免运维
轻量自托管 → Garage 1.0+（10MB 级别二进制）

下一步

想看 NextCloud 网盘自托管（家用云盘）→ NextCloud 网盘自托管
想看 Seafile 私有云盘（高性能文件同步）→ Seafile 私有云盘
想看 FTP 服务自托管（vsftpd / pure-ftpd）→ FTP 服务自托管
想看 Cloudreve 网盘（多存储后端）→ Cloudreve 网盘
想看 Nginx 自建镜像实战（含反代安全加固）→ Nginx 自建镜像实战

Java 应用 Docker 化：Tomcat / Spring Boot 打包 + HTTPS / 时区 / 字体坑

Sat, 15 Dec 2018 00:00:00 +0800

Java 应用的 Docker 化比 Go / Node 麻烦得多——JVM、字体、时区、HTTPS 证书、Tomcat 配置每一个都是坑。本篇把"从 Spring Boot fat jar 到可生产的 Java 容器"完整流程整理清楚。

阅读对象：Java 后端 / 运维工程师 覆盖范围：Tomcat 镜像选型 + Spring Boot fat jar 打包 + anapsix/alpine-java 镜像使用 + HTTPS 证书导入 + 时区 / 中文乱码 / 字体 / DNS 解决 + 镜像瘦身 + 完整 docker-compose 部署

一、Java 容器化三大流派

1.1 流派对比

方案	镜像	体积	启动速度	适用
完整 JDK	`openjdk:8`	~ 800 MB	慢	需要 javac
JRE only	`openjdk:8-jre-slim`	~ 250 MB	中	生产应用
Alpine JRE	`anapsix/alpine-java:8u201b09_server-jre_nashorn`	~ 150 MB	快	生产首选
Native（GraalVM）	`ghcr.io/graalvm/native-image`	~ 50 MB	极快	性能要求高

默认推荐 anapsix/alpine-java——体积小、glibc 兼容好、社区维护。

1.2 为什么需要 alpine

alpine 镜像小 5x（musl libc vs glibc）
冷启动快：JVM 加载速度快 30%+
CVE 少：alpine 包更新频繁，CVE 修复更及时

二、Tomcat 镜像

2.1 官方 Tomcat 镜像

1
2
3
4
5


docker pull tomcat:8.5
docker run -d -p 8098:8080 \
 -v /data/my_tomcat_3/webapps:/usr/local/tomcat/webapps \
 --name my_tomcat_3 \
 tomcat:8.5

2.2 自建 Tomcat 镜像

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


# 1. 准备目录
mkdir tomcat_web && cd tomcat_web
touch Dockerfile start.sh

# 2. Dockerfile
cat > Dockerfile <<'EOF'
FROM tomcat:8.5
ADD ./webapps /usr/local/tomcat/webapps
CMD ["catalina.sh", "run"]
EOF

# 3. 构建
docker build -t tomcat_web:v2 .

# 4. 保存 / 加载（离线分发）
docker save -o tomcat_web.tar.gz tomcat_web:v2
docker load -i tomcat_web.tar.gz

2.3 完整 Tomcat 部署示例

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


# 创建工作目录
mkdir -p /home/epadmZZ && cd /home/epadmZZ
touch server.xml
mkdir logs ROOT

# 部署容器
docker run -tid --restart=always --name epadmZZ \
 -p 28081:8080 \
 -v /home/project/epadmZZ/:/Webs \
 -v /etc/localtime:/etc/localtime \
 -m 2048m --memory-swap=2048m --cpu-shares=256 \
 tomcat_web:v2 start.sh run -config /Webs/server.xml

关键参数：

-m 2048m --memory-swap=2048m：内存硬限——避免 OOM 影响宿主机
--cpu-shares 256：CPU 权重（默认 1024，相对值）
-v /etc/localtime:/etc/localtime：时区同步

三、Spring Boot fat jar 容器化

3.1 构建 Spring Boot 应用

1
2


mvn clean package
# 生成 target/myapp-1.0.0.jar

3.2 最小化 Dockerfile

1
2
3
4
5


FROM anapsix/alpine-java:8u201b09_server-jre_nashorn
VOLUME /tmp
ADD myapp-1.0.0.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

3.3 启动参数注入

1
2
3
4
5
6
7
8


# 普通启动
docker run -d --restart=always \
 --name myapp \
 -p 8080:8080 \
 -v /home/project/myapp:/jar \
 -v /etc/localtime:/etc/localtime \
 anapsix/alpine-java:8u201b09_server-jre_nashorn \
 java -jar -Duser.timezone=GMT+08 /jar/myapp-1.0.0.jar

多端口 + 特殊权限（IoT 项目）：

1
2
3
4
5
6
7
8
9


docker run -d --restart=always \
 -v /home/project/iot:/jar \
 -v /home/project/iot/logs:/kde-iot-log \
 -v /etc/localtime:/etc/localtime \
 -p 8080:8080 -p 443:443 -p 18888:18888 \
 --net mynetwork --ip 172.18.0.5 \
 --privileged=true \
 --name iot anapsix/alpine-java:8u201b09_server-jre_nashorn \
 java -jar -Duser.timezone=GMT+08 /jar/iot-0.0.1-SNAPSHOT.jar

3.4 JVM 参数调优

1
2
3
4
5
6
7


docker run -d \
 -e JAVA_OPTS="-Xms2g -Xmx2g -Xmn1g -Xss1m \
 -XX:SurvivorRatio=8 \
 -XX:MetaspaceSize=256m \
 -XX:MaxMetaspaceSize=256m \
 -XX:NativeMemoryTracking=detail" \
 myapp:latest

容器内 JVM 调优要点：

JVM 看到的 CPU 数可能与宿主机不同——加 -XX:+UseContainerSupport（Java 10+）
JVM 看到的内存可能不准——加 -XX:MaxRAMPercentage=75.0
容器感知：java -XX:+PrintFlagsFinal -version | grep UseContainerSupport

1

ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0 -XX:+PrintFlagsFinal"

四、HTTPS 证书导入

4.1 场景

小程序后台 + 数据接收 + 第三方 HTTPS 对接——需要 SSL 证书。

4.2 阿里云免费证书申请

1
2
3
4


1. 阿里云控制台 → SSL 证书 → 购买证书
2. 选择：单域名 / DV SSL / 免费版 / DigiCert
3. 域名验证（DNS 解析添加 TXT 记录）
4. 下载证书：Tomcat 类型（.pfx + password.txt）

4.3 PFX → JKS 转换

容器内 Java 用 JKS 格式：

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


# 1. 进入 JDK 容器
docker exec -it myapp bash

# 2. 找 keytool
which keytool
# /usr/lib/jvm/default-jvm/bin/keytool

# 3. 转换 PFX → JKS
keytool -importkeystore \
 -srckeystore /path/to/xxx.pfx \
 -destkeystore /app/wx.jks \
 -srcstoretype PKCS12 \
 -deststoretype JKS

# 4. 输入 PFX 密码（password.txt 中的密码）
# 5. 记好 alias（jks 文件别名）

4.4 挂载到容器

1
2
3


docker run -d \
 -v /home/project/wx.jks:/app/wx.jks \
 myapp:latest

4.5 Spring Boot 配置

1
2
3
4
5
6
7


server:
 port: 443
 ssl:
 key-store: classpath:wx.jks
 key-store-password: {{JKS_PASS}}
 key-store-type: JKS
 key-alias: alias

4.6 强制 HTTPS

 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


@SpringBootApplication
public class Application {

 @Bean
 public TomcatServletWebServerFactory servletContainer() {
 TomcatServletWebServerFactory tomcat = new TomcatServletWebServerFactory() {
 @Override
 protected void postProcessContext(Context context) {
 SecurityConstraint constraint = new SecurityConstraint();
 constraint.setUserConstraint("CONFIDENTIAL");
 SecurityCollection collection = new SecurityCollection();
 collection.addPattern("/*");
 constraint.addCollection(collection);
 context.addConstraint(constraint);
 }
 };
 tomcat.addAdditionalTomcatConnectors(httpConnector());
 return tomcat;
 }

 @Bean
 public Connector httpConnector() {
 Connector connector = new Connector("org.apache.coyote.http11.Http11NioProtocol");
 connector.setScheme("http");
 connector.setPort(8080);
 connector.setSecure(false);
 connector.setRedirectPort(443);
 return connector;
 }

 public static void main(String[] args) {
 SpringApplication.run(Application.class, args);
 }
}

效果：

80 / 8080 收到请求 → 自动 302 重定向到 443
443 走 HTTPS

五、时区问题

5.1 三种方法

方法 A：挂载宿主机时区（最简单）

1

docker run -v /etc/localtime:/etc/localtime:ro ...

方法 B：环境变量 TZ（Java 8u72+）

1

docker run -e TZ=Asia/Shanghai ...

方法 C：JVM 参数

1

java -Duser.timezone=GMT+08 -jar app.jar

生产推荐 A + B 一起用。

5.2 容器内修改

1
2
3
4
5
6


# 进入容器
docker exec -it 2c87bcc41378 /bin/bash

# 拷贝时区文件
cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime
echo "Asia/Shanghai" > /etc/timezone

alpine 镜像特殊处理：

1
2
3


RUN apk add --no-cache tzdata \
 && ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
 && echo "Asia/Shanghai" > /etc/timezone

六、中文乱码

6.1 三处必设

Dockerfile / 启动参数：

1
2
3
4
5


java -Dfile.encoding=UTF-8 \
 -Dsun.jnu.encoding=UTF-8 \
 -Duser.language=zh \
 -Duser.country=CN \
 -jar app.jar

MySQL 连接串：

1
2
3


spring:
 datasource:
 url: jdbc:mysql://10.0.1.1:3306/mydb?useUnicode=true&characterEncoding=UTF-8

Linux locale（容器内）：

1
2
3
4
5
6
7


docker exec -it myapp locale
# 看到 POSIX / C 是错的

# 设置
docker exec -it myapp bash
localedef -i en_US -f UTF-8 en_US.UTF-8
export LANG=en_US.UTF-8

根治：

1
2


ENV LANG=C.UTF-8
ENV LC_ALL=C.UTF-8

七、字体问题

7.1 症状

Java 应用：

导出 PDF 中文变方块
生成图形验证码 OOM
POI 操作 Excel 报错

原因：JDK 本身不带字体，alpine / slim 镜像里 fontconfig 也没装。

7.2 修复

Debian / Ubuntu 基础：

1

RUN apt-get update && apt-get install -y fontconfig

Alpine 基础（alpine 3.15+ 必需）：

1

RUN apk add --no-cache fontconfig

完整中文字体（把 Windows 字体拷进容器）：

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


# 1. 宿主机准备字体目录
mkdir -p /home/fonts

# 2. 从 Windows 拷贝
# C:\Windows\Fonts\msyh.ttc (微软雅黑)
# C:\Windows\Fonts\simfang.ttf (仿宋)
# C:\Windows\Fonts\simhei.ttf (黑体)
# C:\Windows\Fonts\simsun.ttc (宋体)

# 3. 挂载到容器
docker run \
 -v /home/fonts:/usr/share/fonts/win \
 ...

容器内更新字体缓存：

1
2
3


docker exec -it myapp bash
fc-cache -fv
fc-list :lang=zh

7.3 Spring Boot PDF 字体

1
2
3
4
5
6
7
8
9


@Bean
public PdfReportFontConfig pdfFontConfig() {
 return new PdfReportFontConfig() {
 @Override
 public String getFontFile() {
 return "/usr/share/fonts/win/msyh.ttc";
 }
 };
}

八、容器化常用工具

8.1 必备工具清单

1
2
3
4
5


# Alpine 镜像（最小化，几乎啥都没有）
apk add --no-cache curl wget iputils-ping iproute2 bash vim fontconfig tzdata

# Debian 镜像
apt-get install -y curl wget iputils-ping iproute2 vim fontconfig dnsutils

8.2 容器内调试

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


# 进容器
docker exec -it myapp bash

# 看进程
ps -ef
ps aux

# 看端口
netstat -tnlp # alpine: apk add net-tools
ss -tnlp # 通用

# 看内存
free -h

九、DNS 问题

症状：容器内 ping internal.example.com 失败。

修复：

1
2
3
4
5
6
7
8
9


# 1. 修改 docker daemon DNS
vim /etc/docker/daemon.json
{
 "dns": ["114.114.114.114", "8.8.8.8"]
}
systemctl restart docker

# 2. 或容器内指定
docker run --dns 114.114.114.114 --dns 8.8.8.8 ...

十、镜像瘦身

10.1 多阶段构建

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


# 阶段 1：编译
FROM maven:3.9-eclipse-temurin-17 AS build
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn clean package -DskipTests

# 阶段 2：运行时
FROM anapsix/alpine-java:8u201b09_server-jre_nashorn
COPY --from=build /target/myapp-1.0.0.jar /app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

效果：编译镜像 ~ 800MB，运行时镜像 ~ 150MB。

10.2 清理缓存

1
2


RUN apt-get update && apt-get install -y fontconfig \
 && rm -rf /var/lib/apt/lists/* # 必须清！

10.3 JLink 定制 JRE

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


# 用 jlink 裁剪 JDK（Java 9+）
jlink \
 --module-path $JAVA_HOME/jmods \
 --add-modules java.base,java.logging,java.sql,java.naming,java.management,java.security.jgss,java.desktop \
 --output /opt/jre-mini \
 --strip-debug --no-man-pages --compress=2

# 用自定义 JRE 做基础镜像
FROM scratch
COPY --from=builder /opt/jre-mini /opt/jre
ENV JAVA_HOME=/opt/jre
ENV PATH=$JAVA_HOME/bin:$PATH

效果：JRE 50MB 级别。

十一、完整生产 Dockerfile

 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


# 阶段 1：构建
FROM maven:3.9-eclipse-temurin-17 AS build
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src ./src
RUN mvn clean package -DskipTests

# 阶段 2：运行时
FROM anapsix/alpine-java:8u201b09_server-jre_nashorn

# 必备工具
RUN apk add --no-cache \
 fontconfig \
 tzdata \
 tini \
 && cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
 && echo "Asia/Shanghai" > /etc/timezone \
 && fc-cache -fv

# JVM 容器感知
ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0 -XX:+ExitOnOutOfMemoryError"

# 中文环境
ENV LANG=C.UTF-8 \
 LC_ALL=C.UTF-8 \
 TZ=Asia/Shanghai

WORKDIR /app
COPY --from=build /build/target/*.jar /app/app.jar

# 暴露端口
EXPOSE 8080

# tinit 收僵尸进程
ENTRYPOINT ["/sbin/tini", "--", "sh", "-c", "exec java $JAVA_OPTS -jar /app/app.jar"]

十二、典型坑位

12.1 容器里 `ping` 找不到

1

RUN apt-get install -y iputils-ping

12.2 容器里 `curl` / `wget` 找不到

1

RUN apt-get install -y curl wget

12.3 catalina.out 无限膨胀

1
2
3
4


# 清空
cat /dev/null > /opt/sxt/logs/catalina.out

# 配置 logrotate

12.4 DNS 解析失败

1
2


# 容器内
docker run --dns 114.114.114.114 ...

12.5 内存超限被 OOM

1
2
3
4
5


# 加硬限
docker run -m 2g --memory-swap=2g ...

# JVM 也限
java -Xmx1500m ...

十三、生产部署清单

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# 1. 构建
docker build -t myapp:20240315 .

# 2. 保存离线
docker save -o myapp.tar.gz myapp:20240315

# 3. 推 Harbor
docker push myapp.example.com/library/myapp:20240315

# 4. 部署
docker run -d --restart=always \
 --name myapp \
 --net=mynetwork \
 -p 8080:8080 \
 -v /home/myapp/logs:/app/logs \
 -v /home/myapp/config:/app/config \
 -v /etc/localtime:/etc/localtime:ro \
 -m 2g --memory-swap=2g \
 myapp.example.com/library/myapp:20240315

# 5. 接入日志
docker logs -f myapp 2>&1 | tee -a /var/log/myapp/app.log

十四、最佳实践清单

JRE 镜像而非 JDK（生产不需要 javac）
anapsix/alpine-java 默认推荐（社区维护 + glibc 兼容）
-XX:+UseContainerSupport JVM 容器感知
-XX:MaxRAMPercentage=75.0 内存自适应
-XX:+ExitOnOutOfMemoryError OOM 退出（让编排系统重启）
tini 收僵尸进程（Java 不会自动 reap）
LANG=C.UTF-8 + 字体 解决中文乱码
/etc/localtime 挂载 解决时区
-m 2g --memory-swap=2g 硬限内存
多阶段构建 镜像瘦身

2024+ 视角补充

本文写于 2018-12，2024-2026 期间 Java 应用容器化关键演进：

JDK 17 / 21 主流化：JDK 8 官方支持 2024-03 已结束（最后 LTS）——新项目必须 JDK 17 或 21；JDK 21（2023-09 LTS，支持到 2031）已成 2024+ 主流
Spring Boot 3.2+ 全面 Jakarta EE：从 javax.* 迁移到 jakarta.*——Tomcat 10+ 是默认；JDK 17 最低要求
Spring Boot 3.4+（2025）：Virtual Threads（虚拟线程）默认集成——JDK 21 协程天然适配
GraalVM Native Image 1.0+（2024-2026）：Spring Boot 3.x 官方支持——spring-boot:build-image 直接生成 native 可执行文件，启动 < 100ms，内存 < 100MB
CRaC（Coordinated Restore at Checkpoint）：OpenJDK 17+ 实验，JVM 启动 < 10ms——Serverless / K8s 冷启动杀手
容器镜像生态：
- Eclipse Temurin（2024-2026）：前 Adoptium，JDK 21 主流发行版——OpenJDK + 商业支持
- BellSoft Liberica JDK（2024-2026）：Native Image Kit + Alpine glibc 兼容——容器首选
- Azul Zulu Prime（2024-2026）：C4 Pauseless GC——延迟敏感场景
- Amazon Corretto（2024-2026）：AWS 维护，生产级 LTS
多阶段构建 已成 Java 容器化标准
JLink 定制 JRE：50MB 级别运行时镜像

实战建议（2025-2026 视角）：

新项目 → JDK 21 LTS + Spring Boot 3.4+ + GraalVM Native Image（Serverless / 冷启动敏感场景）
存量项目 → 升 JDK 17 LTS（避免 JDK 8 / 11 停服）→ 再逐步升 21
Serverless / K8s 冷启动 → GraalVM Native Image 或 CRaC
基础镜像：BellSoft Liberica JDK 21 是 2024+ 容器首选

下一步

想看 JDK 自建镜像实战（Debian / Ubuntu / Alpine 三大流派）→ JDK 自建镜像实战
想看 Nginx 自建镜像实战（前端 dist / 反代）→ Nginx 自建镜像实战
想看 Java 微服务治理（Sentinel 限流 / Spring Boot Admin）→ Java 微服务治理
想看 XXL-Job 分布式调度（任务调度平台）→ XXL-Job 分布式调度

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 目标

Spring Boot 防御式编程：防重复提交 + 缓存 + 配置加密 + AOP

Wed, 20 Dec 2017 00:00:00 +0800

Spring Boot 防御式编程：防重复提交 + 缓存 + 配置加密 + AOP

背景与价值

“防御式编程"是指预设攻击/异常场景并提前拦截的编程范式。在 Spring Boot 项目中，常见的防御场景：

防重复提交：用户网络卡顿 / 双击按钮导致的同一请求多次执行
缓存雪崩 / 穿透 / 击穿：恶意请求打垮数据库
配置泄露：明文密码、API Key 出现在 application.yml 中，被提交到 Git
横切关注点：日志、鉴权、限流等重复代码抽离

本文按"问题 → 方案 → 代码"完整路径，给出生产可复用的 4 套方案。

一、防重复提交（Redis 分布式锁 + AOP）

1. 场景

用户点击"提交订单"按钮，由于：

网络延迟用户多次点击
浏览器自动重试
客户端脚本 bug

导致同一笔订单被重复创建（库存被扣两次、支付两次）。

2. 方案

利用Redis SETNX 原子性 + AOP 切片，把"防重"逻辑与业务逻辑解耦。

3. 依赖

1
2
3
4
5
6
7
8


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

4. Redis 配置

1
2
3
4
5
6
7


spring:
 redis:
 database: 0
 host: {{REDIS_HOST}}
 port: 6379
 timeout: 5000
 password: {{REDIS_PASSWORD}}

5. 自定义注解

1
2
3
4
5
6
7
8


@Inherited
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RepeatSubmit {
 /** 锁定时间（秒） */
 int time() default 1;
}

6. 切片（核心）

 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


@Aspect
@Component
@Slf4j
public class NoRepeatSubmitAspect {

 private static final String JWT_TOKEN_KEY = "Authorization";

 @Autowired
 private RedisTemplate<String, String> redisTemplate;

 @Pointcut("@annotation(com.example.aop.RepeatSubmit)")
 public void pointcut() {}

 @Around("pointcut()")
 public Object around(ProceedingJoinPoint pjp) throws Throwable {
 // 1. 获取 token + URL 作为唯一 key
 HttpServletRequest request = ((ServletRequestAttributes)
 RequestContextHolder.getRequestAttributes()).getRequest();
 String token = request.getHeader(JWT_TOKEN_KEY);
 if (!StringUtils.hasText(token)) {
 token = request.getSession().getId();
 }
 String key = "repeat_submit:" + DigestUtils.md5Hex(token + "-" + request.getRequestURL());

 // 2. Redis 原子 SETNX，锁定 N 秒
 Boolean locked = redisTemplate.opsForValue().setIfAbsent(key, "1", 1, TimeUnit.SECONDS);
 if (Boolean.TRUE.equals(locked)) {
 // 3. 执行业务
 return pjp.proceed();
 } else {
 throw new BusinessException("操作过于频繁，请稍后再试");
 }
 }
}

7. 业务使用

1
2
3
4
5


@PostMapping("/order/create")
@RepeatSubmit(time = 3) // 3 秒内同一用户同一接口只允许一次
public Result<Order> createOrder(@RequestBody OrderDTO dto) {
 return orderService.create(dto);
}

二、缓存雪崩 / 穿透 / 击穿防御

1. 二级缓存架构

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


┌──────────────┐
│ Application │
└──────┬───────┘
 │ 1. 查本地缓存（Caffeine）
 ▼
┌──────────────┐
│ Caffeine │ L1（本地，纳秒级）
└──────┬───────┘
 │ 2. miss 后查 Redis
 ▼
┌──────────────┐
│ Redis │ L2（分布式，毫秒级）
└──────┬───────┘
 │ 3. miss 后查 DB
 ▼
┌──────────────┐
│ Database │ L3（毫秒-秒级）
└──────────────┘

2. 依赖

1
2
3
4
5


<dependency>
 <groupId>com.github.ben-manes.caffeine</groupId>
 <artifactId>caffeine</artifactId>
 <version>3.2.0</version>
</dependency>

3. Caffeine 一级缓存

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


@Configuration
public class CaffeineConfig {

 @Bean
 public Cache<String, Object> caffeineCache() {
 return Caffeine.newBuilder()
 .initialCapacity(100)
 .maximumSize(10_000)
 .expireAfterWrite(Duration.ofMinutes(5)) // 写入 5 分钟后过期
 .refreshAfterWrite(Duration.ofMinutes(1)) // 写入 1 分钟后被动刷新
 .recordStats()
 .build();
 }
}

4. 缓存击穿：分布式锁 + sync 模式

1
2
3
4


@Cacheable(value = "user", key = "#id", sync = true) // sync=true 防止击穿
public User getById(Long id) {
 return userRepository.findById(id).orElse(null);
}

sync=true 让 Spring Cache 在缓存 miss 时只允许一个线程查 DB，其他线程阻塞等待。

5. 缓存穿透：空值缓存 + 布隆过滤器

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


public User getById(Long id) {
 // 1. 查 L1
 User user = (User) caffeineCache.getIfPresent("user:" + id);
 if (user != null) return user;

 // 2. 查 L2
 user = (User) redisTemplate.opsForValue().get("user:" + id);
 if (user != null) {
 caffeineCache.put("user:" + id, user);
 return user;
 }

 // 3. 查 DB
 user = userRepository.findById(id).orElse(null);

 // 4. 即使是 null 也缓存（防穿透）
 redisTemplate.opsForValue().set("user:" + id, user == null ? "" : JSON.toJSONString(user), 60, TimeUnit.SECONDS);
 caffeineCache.put("user:" + id, user);
 return user;
}

6. 缓存雪崩：分散过期时间

1
2
3
4


// 给过期时间加随机值（±10%）
int baseExpire = 300; // 5 分钟
int randomExpire = baseExpire + ThreadLocalRandom.current().nextInt(-30, 30);
redisTemplate.opsForValue().set(key, value, randomExpire, TimeUnit.SECONDS);

7. 缓存更新：Caffeine refreshAfterWrite + Redis Canal 订阅 MySQL binlog

1

MySQL update → binlog → Canal → Kafka → 业务消费 → 更新 Redis

refreshAfterWrite 让 Caffeine 被动刷新（不删除，下次访问时异步加载新值），保证旧值不会长时间存在。

三、配置加密（Jasypt）

1. 场景

application.yml 中经常有明文敏感信息：

1
2
3


spring:
 datasource:
 password: {{DB_PASSWORD}}  # ❌ 提交到 Git = 泄露

2. 依赖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<dependency>
 <groupId>com.github.ulisesbocchio</groupId>
 <artifactId>jasypt-spring-boot-starter</artifactId>
 <version>3.0.5</version>
</dependency>
<plugin>
 <groupId>com.github.ulisesbocchio</groupId>
 <artifactId>jasypt-maven-plugin</artifactId>
 <version>3.0.5</version>
</plugin>

3. 命令行加密

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


# 下载 jasypt JAR
# https://repo1.maven.org/maven2/org/jasypt/jasypt/1.9.3/jasypt-1.9.3.jar

# 加密（输入明文，输出 ENC() 包裹的密文）
java -cp jasypt-1.9.3.jar \
 org.jasypt.intf.cli.JasyptPBEStringEncryptionCLI \
 input="MyPlainPassword" \
 password="MySecretKey" \
 algorithm=PBEWithMD5AndDES

# 输出：
# ----OUTPUT----------------------
# 2ADo+VDsxwyhFO+X6LSUZ2/mS4bbIbcS

4. application.yml 使用

1
2
3


spring:
 datasource:
 password: ENC(2ADo+VDsxwyhFO+X6LSUZ2/mS4bbIbcS)  # ✅ 密文安全提交

5. 启动时指定密钥

1
2
3
4
5
6


# 方式 1：环境变量（推荐）
export JASYPT_ENCRYPTOR_PASSWORD=MySecretKey
java -jar myapp.jar

# 方式 2：命令行参数
java -Djasypt.encryptor.password=MySecretKey -jar myapp.jar

生产关键：密钥 JASYPT_ENCRYPTOR_PASSWORD 绝不能写进 application.yml，必须通过环境变量 / K8s Secret / Vault 注入。

6. 非对称加密（更安全）

1
2
3
4
5
6
7
8


# 生成私钥（输入密码保护）
openssl genrsa -des3 -out privkey.pem 2048

# 提取公钥
openssl rsa -in privkey.pem -outform PEM -pubout -out public.pem

# 转私钥为 PKCS#8 格式（Java 可读）
openssl pkcs8 -topk8 -inform PEM -in privkey.pem -outform pem -nocrypt -out pkcs8.pem

1
2
3
4


# 用公钥加密
mvn jasypt:encrypt \
 -Djasypt.encryptor.public-key-format=pem \
 -Djasypt.encryptor.public-key-location=file:src/main/resources/jasypt/public.pem

非对称优势：开发 / 测试环境持公钥即可加密，私钥只在生产部署服务器（运维保管），开发无法反推。

四、AOP 实战

1. 依赖

1
2
3
4


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

2. 5 种通知类型

 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


@Aspect
@Component
public class LogAspect {

 // 1. @Before：方法前
 @Before("execution(* com.example.service..*(..))")
 public void beforeLog(JoinPoint jp) {
 log.info("调用前: {}", jp.getSignature());
 }

 // 2. @After：方法后（无论成功失败）
 @After("execution(* com.example.service..*(..))")
 public void afterLog(JoinPoint jp) {
 log.info("调用后: {}", jp.getSignature());
 }

 // 3. @AfterReturning：方法成功返回
 @AfterReturning(value = "execution(* com.example.service..*(..))", returning = "result")
 public void returnLog(JoinPoint jp, Object result) {
 log.info("返回: {} -> {}", jp.getSignature(), result);
 }

 // 4. @AfterThrowing：方法抛异常
 @AfterThrowing(value = "execution(* com.example.service..*(..))", throwing = "e")
 public void throwLog(JoinPoint jp, Exception e) {
 log.error("异常: {} -> {}", jp.getSignature(), e.getMessage());
 }

 // 5. @Around：环绕（最强大，可控 proceed() 时机）
 @Around("execution(* com.example.service..*(..))")
 public Object aroundLog(ProceedingJoinPoint pjp) throws Throwable {
 long start = System.currentTimeMillis();
 try {
 Object result = pjp.proceed();
 log.info("耗时: {} ms - {}", System.currentTimeMillis() - start, pjp.getSignature());
 return result;
 } catch (Throwable t) {
 log.error("异常耗时: {} ms", System.currentTimeMillis() - start);
 throw t;
 }
 }
}

3. 切入点表达式

表达式	含义
`execution(* com.example.service..*(..))`	service 包下所有方法
`execution(public * *(..))`	所有 public 方法
`@annotation(com.example.aop.Log)`	被 `@Log` 注解的方法
`within(com.example.service..*)`	service 包下所有类的所有方法
`args(String, ..)`	第一个参数是 String 的方法

4. Spring 缓存集成（`@Cacheable` 原理）

@Cacheable 本质是 AOP 实现的：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 简化原理
@Around("@annotation(org.springframework.cache.annotation.Cacheable)")
public Object cacheable(ProceedingJoinPoint pjp) {
 String key = spel(pjp, "key");
 Object cached = cache.get(key);
 if (cached != null) return cached;

 Object result = pjp.proceed();
 cache.put(key, result);
 return result;
}

理解了 AOP 原理，@Cacheable / @RepeatSubmit / @RateLimit 等注解都能自己写。

前置知识与下一步

前置：

Spring Boot 基础
Redis 基础（SETNX 原子性）
AOP 概念（切面 / 切入点 / 通知）

下一步：

接口幂等性：用 Token 机制 + Redis 实现表单防重
限流：用 Guava RateLimiter + Redis 滑动窗口
链路追踪：用 Spring AOP + Sleuth 注入 traceId 到日志

小结

防御式编程的 4 大支柱：

防重复提交：Redis SETNX + AOP 注解，5 行代码解决
二级缓存：Caffeine（L1）+ Redis（L2）+ DB（L3），Caffeine sync=true 防击穿
配置加密：Jasypt ENC() 密文 + 环境变量注入密钥
AOP 切片：5 种通知（Before/After/AfterReturning/AfterThrowing/Around）抽离横切关注点

核心原则：把"防御"逻辑从业务代码中抽离，用注解 + AOP 复用，业务方只需要在方法上加 @RepeatSubmit(time=3) 一行注解即可享受防重保护。

2024+ 视角：Resilience4j + Spring Boot 3.x + 云原生配置中心

Resilience4j 替代 Hystrix 已是事实标准

Hystrix 2018 年停更，Resilience4j 2.x 是 Spring Boot 3.x 官方推荐：

1
2
3
4
5
6
7
8
9


<dependency>
 <groupId>io.github.resilience4j</groupId>
 <artifactId>resilience4j-spring-boot3</artifactId>
 <version>2.2.0</version>
</dependency>
<dependency>
 <groupId>io.github.resilience4j</groupId>
 <artifactId>resilience4j-reactor</artifactId> <!-- WebFlux -->
</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


# application.yml
resilience4j:
 circuitbreaker:
 instances:
 orderService:
 sliding-window-type: COUNT_BASED
 sliding-window-size: 100
 failure-rate-threshold: 50
 wait-duration-in-open-state: 10s
 permitted-number-of-calls-in-half-open-state: 5
 retry:
 instances:
 orderService:
 max-attempts: 3
 wait-duration: 1s
 exponential-backoff-multiplier: 2
 ratelimiter:
 instances:
 orderService:
 limit-refresh-period: 1s
 limit-for-period: 100
 bulkhead:
 instances:
 orderService:
 max-concurrent-calls: 50
 max-wait-duration: 0

防重复提交的 2024+ 升级

setIfAbsent 在 Redis 7.0+ 已是 @Deprecated——改用 set(key, value, SetArgs.Builder.nx().ex(seconds))：

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


@Around("pointcut()")
public Object around(ProceedingJoinPoint pjp) throws Throwable {
 String key = "repeat_submit:" + DigestUtils.md5Hex(token + "-" + request.getRequestURL());
 // ✅ 2024+ 推荐写法
 Boolean locked = redisTemplate.opsForValue()
 .setIfAbsent(key, "1", Duration.ofSeconds(3));
 // 或更精细：
 redisTemplate.execute(connection -> connection.stringCommands().set(
 key.getBytes(), "1".getBytes(),
 Expiration.from(3, TimeUnit.SECONDS),
 SetOption.SET_IF_ABSENT
 ));
 ...
}

或者直接用 Redisson（RLock / RSemaphore）做更高级的分布式锁：

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


@Around("pointcut()")
public Object around(ProceedingJoinPoint pjp) throws Throwable {
 RLock lock = redissonClient.getLock("submit:" + key);
 if (!lock.tryLock(0, 3, TimeUnit.SECONDS)) {
 throw new BusinessException("操作过于频繁");
 }
 try {
 return pjp.proceed();
 } finally {
 lock.unlock();
 }
}

配置加密的 2024+ 新选择

Jasypt 2023 起进入维护模式（社区 fork 持续），Spring Boot 3.x 有更现代的方案：

方案 1：HashiCorp Vault（企业首选）

1
2


@Value("${vault://secret/myapp/db.password}")
private String dbPassword;

1
2
3
4
5
6


# bootstrap.yml
spring.cloud.vault:
 host: vault.example.com
 authentication: KUBERNETES
 kv:
 enabled: true

方案 2：Spring Cloud Alibaba Nacos 加密配置

1
2
3
4


# Nacos 控制台直接编辑密文
spring:
 datasource:
 password: ENC(2ADo+VDsxwyhFO+X6LSUZ2/mS4bbIbcS)

方案 3：Jasypt（继续用，3.0.5+ 兼容 JDK 17/21）

1
2
3
4
5


<dependency>
 <groupId>com.github.ulisesbocchio</groupId>
 <artifactId>jasypt-spring-boot-starter</artifactId>
 <version>3.0.5</version>
</dependency>

二级缓存的 2024+ 演进

Caffeine 3.x 仍是 L1 首选，但 2024+ 多了几个变化：

1
2
3
4
5


<dependency>
 <groupId>com.github.ben-manes.caffeine</groupId>
 <artifactId>caffeine</artifactId>
 <version>3.1.8</version> <!-- 3.x JDK 17 兼容 -->
</dependency>

refreshAfterWrite 性能优化：异步刷新不再阻塞读
W-TinyLFU 算法：命中率比 LRU 高 5-10%
内存统计：recordStats() 输出 hit rate / miss rate / load time

L2 缓存新选择：

Redis 7.x（2022+）内置 FUNCTION（Lua 替代品）+ 多线程 IO
Dragonfly（2022+ 出现）—— Redis 兼容 + 多线程，单实例可达百万 QPS
KeyDB（2024 仍维护）—— Redis 兼容 + 多线程
Apache Kvrocks（2024 活跃）—— Redis 兼容，基于 RocksDB，适合大数据量

限流的 2024+ 新方案

Sentinel 1.8.8+ 仍是 Java 生态首选，新增：

集群限流：Token Server 集群分配配额
网关层流控：与 Spring Cloud Gateway 深度集成
热点参数限流：相同参数值的请求单独限流

1
2
3
4
5
6


@SentinelResource(value = "orderQuery",
 blockHandler = "blockHandlerMethod",
 fallback = "fallbackMethod")
public Order queryOrder(String orderId) {
 return orderService.findById(orderId);
}

链路追踪 2024+

Sleuth 已废弃，Spring Boot 3.x 推荐 Micrometer Tracing + OpenTelemetry：

1
2
3
4
5
6
7
8


<dependency>
 <groupId>io.micrometer</groupId>
 <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
 <groupId>io.opentelemetry</groupId>
 <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

1
2
3
4
5
6


management:
 tracing:
 sampling.probability: 0.1 # 10% 采样
 otlp:
 tracing:
 endpoint: http://jaeger:4318/v1/traces

2024+ 防御式编程的"完整清单”

防御点	2024+ 推荐方案
防重复提交	Redisson `RLock` + AOP
接口幂等	Token 机制 + Redis SETNX
熔断	Resilience4j 2.x
限流	Sentinel 1.8.8+ / Resilience4j
缓存雪崩/穿透/击穿	Caffeine 3.x + Redis 7.x + 空值缓存
配置加密	HashiCorp Vault / Nacos 加密 / Jasypt
链路追踪	Micrometer Tracing + OpenTelemetry
全链路灰度	OpenTelemetry + Sentinel 灰度规则
流量染色	Spring Cloud Gateway + 自定义 Header
异常监控	Sentry / 阿里云 ARMS / SkyWalking 9.x

实战坑（2024+）

Jasypt 3.0.5+ 与 Spring Boot 3.x有兼容问题，加 jasypt.encryptor.algorithm=PBEWithHMACSHA512AndAES_256
Resilience4j 注解 + Sentinel 注解不能混用——AOP 拦截顺序冲突
Redisson 3.17+ 的看门狗自动续期默认 30s，老项目升级要重新评估锁超时
OpenTelemetry Collector 部署后必须先在本地用 otel-cli 验证数据再到生产