保护 Spring Boot 应用

springboot 用于保护 Spring Boot 应用，能够处理 BOOT-INF/classes、BOOT-INF/lib、Spring Boot Loader 和框架扫描。

1. GUI 操作

在应用类型页面选择 Spring Boot。
选择要保护的 Spring Boot 应用、随包 Java 版本和目标平台，并选择简单模式或高级模式。
使用高级模式时，按需选择输出布局、保护依赖 JAR、JavaFX、JVM 参数和排除规则；简单模式会根据兼容性扫描自动建议布局和排除项。各选项含义见 Protector4J 高级模式设置。
选择输出目录，复核参数摘要，然后点击 Run protection。

2. CLI 示例

最小命令：

p4j springboot app.jar dist

默认使用 p4jx-fat 布局。显式选择其他布局：

p4j springboot app.jar dist --layout fat
p4j springboot app.jar dist --layout separate

选择性保护：

p4j springboot app.jar dist \
  --protect 'com.example.service.impl.**' \
  --exclude 'com.example.dto.**,com.example.config.**'

3. 输出结构与布局

`p4jx-fat`：默认，单个受保护应用归档

dist/
├── app.p4jx              # 使用 jar 后缀时为 app.jar
├── vlxjre/
├── run.sh
├── run.command
└── run.bat

特点：

以单个 P4JX 应用归档交付；
物理文件默认不是 ZIP；
Spring Boot 资源、嵌套依赖和元数据通过虚拟 JAR 视图提供；
保护面最大，适合没有第三方 classpath 扫描器依赖的应用。

`fat`：Spring Boot 兼容布局

dist/
├── app.jar
├── app.p4jx              # jar 后缀时为 app-protected.jar
├── vlxjre/
└── run.*

特点：

app.jar 保留标准 BOOT-INF 物理结构；
保护类的真实实现位于相邻 P4JX 归档；
适合 ClassGraph、Reflections 等必须扫描物理 Spring Boot JAR 结构的应用；
两个文件存在绑定关系，必须一起更新和交付。

`separate`：分离式兼容布局

dist/
├── plain-launcher.jar
├── app.p4jx
├── lib/
├── vlxjre/
└── run.*

特点：

Spring Boot Loader、公开类和依赖分离；
适合需要扁平 lib/* 类路径的旧集成环境；
保护类由生成的启动器预加载；
新项目优先使用 p4jx-fat 或扫描器建议的 fat。

如何选择布局

场景	建议布局
常规 Spring Boot 服务	`p4jx-fat`
应用实际调用 ClassGraph、Reflections 等扫描器	`fat`
必须使用扁平外部依赖目录，或者需要单独加密依赖文件的时候	`separate`
不确定	先执行 `--compat-scan`

ZIP overlay 只帮助直接读取 ZIP 中央目录的工具，不能替代 ClassLoader/classpath 扫描器所需的物理 Spring Boot 结构。

4. 启动

./run.sh --spring.profiles.active=prod

Windows：

run.bat --spring.profiles.active=prod

不要用系统 JRE 替代输出目录中的 vlxjre

JVM 启动参数

打包时可通过 GUI 的 JVM startup options（每行一个）或 CLI 固化 JVM 参数：

p4j springboot app.jar dist \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

部署时临时追加：

APP_JAVA_OPTS="-Duser.timezone=Asia/Shanghai" ./run.sh

也可直接修改当前部署脚本：

macOS/Linux：在 run.sh 已生成的 JVM_OPTS=(...)/JVM_OPTS+=(...) 之后追加 JVM_OPTS+=("-Xms1g" "-Xmx2g")。
Windows：在 run.bat 已生成的 set "JVM_OPTS=..." 之后追加 set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"。

不要删除 Spring Boot 或 JavaFX 自动生成的 --add-opens、module path 等内部参数。重新打包会覆盖手工修改；详见 JVM 启动参数配置。

5. 保护范围

默认保护 BOOT-INF/classes 下的应用类。建议保留以下 Spring-facing 类为普通类：

@Controller、@RestController、@ControllerAdvice；
@Configuration、自动配置、AOT/CGLIB 增强类；
Jackson DTO、JPA Entity、record 和校验模型；
应用入口和由框架直接构造/代理的类；
需要运行时字节码增强的类。

保护服务实现，通过公开 facade 或接口进入。规则支持精确类名、pkg.* 和 pkg.**。

6. 保护依赖 JAR

--protect-lib 可保护匹配的 BOOT-INF/lib 依赖，三种布局都支持：

p4j springboot app.jar dist \
  --protect-lib 'company-core-*.jar,pricing-*.jar'

只保护自有闭源依赖。不要为了“保护更多”而加密 Spring、Tomcat、日志、数据库驱动等第三方框架包。

7. 兼容性扫描

p4j springboot app.jar --compat-scan
p4j springboot app.jar dist --compat-apply

这两个选项不能同时使用，它们的区别是：

选项	行为	何时使用
`--compat-scan`	只扫描输入 JAR，打印风险和配置建议后退出；不编码、不生成 `dist`，因此不需要输出目录	首次保护应用、升级 Spring Boot 或其他依赖、调整保护范围或布局后，以及排查兼容性问题时，先用它查看报告
`--compat-apply`	扫描后自动合并保守建议，然后继续编码并生成输出，因此必须指定输出目录	已阅读扫描结果并接受自动建议时，用它完成打包；也可用于已验证过规则的重复构建或 CI 流程

对 springboot，--compat-apply 可根据扫描结果选择布局、追加排除类，并调整 ZIP overlay、JavaFX 和归档后缀等选项。对排除类以外的这些选项，命令行中显式指定的值优先；建议的排除类则默认与显式 --exclude 合并。如不希望自动追加排除类，可同时传入 --no-compat-excludes。扫描器只做静态启发式分析，需要修改代码的问题不会被 --compat-apply 自动修复，生成后仍需在目标平台回归测试。

其他 CLI 命令、全部选项、环境变量和自动化示例，请参阅 CLI 参数参考。