保護 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 引數參考。