保護 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 進階模式設定。
選擇輸出目錄，核對參數摘要，然後點選執行保護。

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 檢視提供；
保護範圍最廣，適合不依賴第三方類別路徑掃描器的應用程式。

`fat`：Spring Boot 相容佈局

dist/
├── app.jar
├── app.p4jx              # 使用 jar 字尾時為 app-protected.jar
├── vlxjre/
└── run.*

特點：

app.jar 保留標準的 BOOT-INF 實體結構；
受保護類別的真實實作放在旁邊的 P4JX 歸檔中；
適合需要掃描實體 Spring Boot JAR 結構的應用程式，例如使用 ClassGraph 或 Reflections 的應用程式；
兩個檔案互相依賴，必須一起更新、一起交付。

`separate`：拆分式相容佈局

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

特點：

Spring Boot Loader、未受保護的類別與相依套件三者分開存放；
適合要求 lib/* 扁平類別路徑的舊有整合環境；
受保護類別由產生的啟動器預先載入；
新專案應優先使用 p4jx-fat，或採用掃描器建議的 p4jx-fat / fat。

如何選擇佈局

情境	建議佈局
標準的 Spring Boot 服務	`p4jx-fat`
應用程式確實使用了 ClassGraph、Reflections 這類掃描器	`fat`
需要扁平的外部相依目錄，或需要單獨加密相依檔案	`separate`
不確定	先執行 `--compat-scan`

ZIP 覆蓋層只能幫到那些直接讀取 ZIP 中央目錄的工具，無法取代 ClassLoader 與類別路徑掃描器所需要的實體 Spring Boot 結構。

4. 啟動

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

Windows：

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

不要用系統 JRE 取代輸出目錄中的 vlxjre。

打包 Windows 目標時，還可以額外產生一個原生啟動程式。三種佈局都支援，它與啟動指令碼並存，詳見產生 Windows EXE 啟動器。

JVM 啟動選項

打包時可以固定 JVM 啟動選項，既可以在 GUI 的 JVM 啟動選項中每行填寫一個，也可以在命令列中指定：

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

若要為已部署的包臨時追加選項：

APP_JAVA_OPTS="-Duser.timezone=Asia/Taipei" ./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 與模組路徑。重新打包會覆寫所有手動改動，詳見 JVM 啟動選項設定。

5. 保護範圍

預設保護 BOOT-INF/classes 下的應用程式類別。以下這些與 Spring 相關的類別，通常維持不受保護較為合適：

@Controller、@RestController、@ControllerAdvice 類別；
@Configuration 類別、自動組態類別，以及經 AOT 或 CGLIB 增強的類別；
Jackson DTO、JPA 實體、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 覆蓋層、JavaFX 與歸檔字尾等選項。除排除規則之外的這些選項，命令列中明確指定的值優先。建議排除的類別預設會與你明確寫的 --exclude 合併；若不希望自動追加，同時傳入 --no-compat-excludes 即可。掃描器只做靜態啟發式分析，需要修改程式碼才能解決的問題不會被 --compat-apply 自動修正，打包完成後仍然必須在目標平臺上做迴歸測試。

其他 CLI 命令、全部選項、環境變數與自動化範例，請參閱 CLI 參數參考。