Protector4J 高階模式設定

高階模式用於手動決定保護範圍、相容性選項和應用型別專用引數。第一次處理新應用時，建議先使用簡單模式或在高階引數頁執行一次相容性掃描，再根據掃描結果調整。

本文是 GUI 使用指南 中高階模式的展開說明。需要判斷哪些類應保持未加密時，配合閱讀 相容性與保護範圍；需要編寫自動化命令時，以 CLI 引數參考 為準。

1. 進入高階模式

  1. 選擇應用型別和輸入 JAR/WAR。
  2. 選擇隨包 Java 版本和至少一個目標平臺。
  3. 在 Mode 中選擇 Advanced — customise the options yourself。
  4. 點選 Next 進入高階引數頁。

如果已經進入輸出確認頁，可點選 Customize… 返回高階引數頁。修改完成後再次進入輸出頁，確認摘要已經反映新設定。

Java 版本和目標平臺不在高階引數頁修改；需要調整時返回輸入頁。多平臺任務會為每個平臺生成獨立輸出，其中的 vlxjre 不能互換。

2. 通用選項

四種應用型別共用高階引數區，但部分設定會按型別生效。Library Encryption 不生成啟動指令碼，因此不使用 JVM 啟動引數；其歸檔字尾設定會用於建議並同步輸出檔名。

GUI 設定預設值作用建議
Archive suffixp4jx將應用歸檔命名為 .p4jx 或 .jar保持 .p4jx；只有第三方元件硬編碼 .jar 檔名時才改為 jar
Disable JIT for protected methods關閉讓保護方法只在直譯器中執行安全敏感且已完成效能壓測時啟用
Append scanner ZIP overlay關閉增加供 ZIP 結構掃描工具讀取的相容檢視僅在相容性掃描建議或應用確實讀取物理 ZIP 結構時啟用
JVM startup options空把 JVM 引數寫入生成的啟動指令碼每行填寫一個完整引數
Compatibility scan…不自動執行掃描輸入並給出保守建議新應用、框架升級或保護範圍變化後重新執行

各應用型別實際出現的專用設定如下：

應用型別專用設定初始狀態CLI 對應項
Java ApplicationMain class、Classes to exclude、JavaFX/WebView主類取 Manifest；預設不排除類、不打包 JavaFX--main、--exclude、--javafx、--javafx-webview / --no-javafx-webview
Spring BootMain class、Layout、Protect dependency JARs、Classes to exclude、JavaFX/WebView主類取 Start-Class；p4jx-fat；不保護依賴、不排除類、不打包 JavaFX--main、--layout、--protect-lib、--exclude、JavaFX 相關選項
TomcatTomcat version、Context path、Classes to exclude版本未選擇；/app；不排除類--tomcat-version、--context、--exclude

“不排除類”表示預設保護該應用型別的全部應用類，不表示連第三方依賴也一併保護。Spring Boot 的 BOOT-INF/lib 和 Tomcat 的 WEB-INF/lib 預設保持普通狀態。

歸檔字尾

選擇 jar 只改變檔名，檔案內容仍是 P4JX 格式，不能用普通 ZIP/JAR 工具修改，也不能使用普通 JRE 載入。對於 Library Encryption，該設定會切換已選輸出檔案的 .p4jx/.jar 字尾；如果使用者填寫了其他自定義字尾，則保留完整檔名。

對應 CLI：

--archive-suffix p4jx
--archive-suffix jar

禁止保護方法 JIT

啟用 Disable JIT for protected methods 後，保護方法不會進入 JIT 編譯器，可減少編譯後機器碼暴露面，但計算密集型程式碼可能明顯變慢。該設定隻影響保護方法，不會把整個 JVM 切換為純解釋模式。

對應 CLI：

--no-jit

掃描器 ZIP overlay

overlay 只暴露公開資源、目錄和保護類的後設資料樁，不包含真實方法體。它用於相容直接讀取 ZIP 中央目錄的工具，但不能替代 Spring Boot fat 佈局，也不能解決從記憶體流使用 ZipInputStream/JarInputStream 解析歸檔的場景。

對應 CLI：

--zip-overlay scanner

JVM 啟動引數

每行填寫一個完整引數，例如：

-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8

每一行就是一個引數邊界，不要把多個引數寫在同一行。引數會寫入 macOS/Linux 和 Windows 啟動指令碼；Tomcat 引數也會進入其啟動路徑。Library Encryption 不生成啟動指令碼，因此輸入框不可用。更完整的平臺示例見 JVM 啟動引數配置。

對應 CLI 需要重複使用選項：

--jvm-option -Xms512m --jvm-option -Xmx2g

3. 相容性掃描與應用建議

四種應用型別都可點選 Compatibility scan… 掃描當前輸入。接受結果時，工具會把該應用型別支援的建議合併到當前設定中，主要包括：

  • 增加需要保持未加密的類；
  • 啟用掃描器 ZIP overlay；
  • 調整歸檔字尾；
  • 為 Java Application 或 Spring Boot 啟用 JavaFX/WebView；
  • 為 Spring Boot 選擇佈局；
  • 為 Tomcat 選擇 9 或 10.1。

Library Encryption 只會自動應用掃描器 ZIP overlay 和歸檔字尾建議。它按設計保護輸入 JAR 中的所有類，不支援類排除；如果掃描發現 JNI/原生類等需要保持未加密的內容，報告會明確提示將它們拆到普通 JAR，或改用支援選擇性保護的應用打包模式。

接受建議後仍可繼續編輯。掃描會保留已有排除規則，不會因為未檢測到 JavaFX 而主動關閉使用者已啟用的 JavaFX。取消對話方塊則不應用建議。

掃描報告中的程式碼級風險，例如 Agent、JNI、自定義類載入器或執行時位元組碼改寫，通常不能只靠一個開關解決。應按 相容性與保護範圍 調整程式碼邊界並實測。

4. Java Application 設定

普通 Java 應用高階引數

Main class

留空時讀取輸入 JAR Manifest 的 Main-Class。只有 Manifest 缺少主類或需要覆蓋預設啟動類時才填寫完整類名，例如 com.example.Main。

對應 CLI：--main com.example.Main。

Classes to exclude

應用類預設全部保護。此列表中的類或包保持未加密，適合 DTO、實體、配置類、JNI 橋接類以及需要被框架增強或讀取真實位元組碼的類。規則格式見“保護範圍與排除規則”。

JavaFX runtime

普通 JavaFX 應用勾選 Bundle JavaFX into the packaged runtime。WebView 可選擇：

  • Auto：檢測到 javafx.scene.web 時包含；
  • Include：強制包含 fx-webkit；
  • Exclude：強制不包含。

WebView 會增加大約 40 MB。GUI 會為目標 Java 版本和平臺下載素材；需要指定本地離線 JavaFX 目錄時使用 CLI。

對應 CLI：--javafx、--javafx-webview 和 --no-javafx-webview。Auto 不額外寫入強制 WebView 選項，由打包器根據應用引用決定。

5. Spring Boot 設定

Spring Boot 高階引數

Main class

留空時讀取 Manifest 的 Start-Class。需要覆蓋啟動類時填寫完整類名。

對應 CLI：--main com.example.Application。

Layout

佈局適用場景
p4jx-fat預設；常規 Spring Boot 服務，保護面最大
fatClassGraph、Reflections 等需要物理 Spring Boot JAR 結構
separate必須使用扁平 lib/* 類路徑的舊整合環境

如果相容性掃描明確建議 fat，不要只開啟 ZIP overlay 後仍強制使用 p4jx-fat。佈局細節見 保護 Spring Boot 應用。

對應 CLI：--layout p4jx-fat、--layout fat 或 --layout separate。

Protect dependency JARs…

BOOT-INF/lib 中的依賴預設不保護。只勾選自有閉源依賴；不要加密 Spring、Tomcat、日誌、資料庫驅動等第三方框架包。帶簽名的 JAR 會顯示為不可選，因為修改內容會破壞其簽名。

勾選一個依賴後，其中所有類都會保護，但 Classes to exclude 規則仍可為該依賴排除具體類或包。三種 Spring Boot 佈局都支援保護依賴。

對應 CLI：--protect-lib 'company-core.jar,company-domain.jar'。CLI 也支援 glob；GUI 儲存的是選中 JAR 的精確檔名。

Classes to exclude 與 JavaFX

用法與 Java Application 相同。排除規則同時作用於應用類和已選擇保護的依賴 JAR。Spring Boot + JavaFX 桌面應用也可在 JavaFX runtime 頁籤中打包 JavaFX/WebView。

6. Tomcat 設定

Tomcat 高階引數

Tomcat version

  • 使用 javax.servlet.* 的 WAR 選擇 Tomcat 9 · javax；
  • 使用 jakarta.servlet.* 的 WAR 選擇 Tomcat 10.1 · jakarta。

Tomcat 10.1 至少需要 Java 11。不能確定時執行相容性掃描；如果應用同時混用 javax 和 jakarta，不要強行選擇版本，應先修正依賴衝突。

高階模式沒有預選版本，必須接受掃描建議或手動選擇後才能進入下一步。對應 CLI：--tomcat-version 9 或 --tomcat-version 10；CLI 還允許 auto。

Context path

填寫以 / 開頭的部署路徑，例如 /app。留空時使用 /app。向現有 Tomcat 輸出目錄追加應用時，context path 不能與已有應用重複。

對應 CLI：--context /app。

Classes to exclude

預設保護 WEB-INF/classes 下的應用類，WEB-INF/lib 依賴預設不保護。通常應排除 Servlet、Filter、Listener、DTO、配置、實體、JNI 橋接類和容器需要增強的類。

7. 保護範圍與排除規則

高階模式的 GUI 預設保護所有應用類，通過 Classes to exclude 留出框架邊界。支援三種規則：

com.example.SecretService   僅匹配這個類
com.example.service.*       匹配當前包，不含子包
com.example.service.**      匹配當前包及所有子包

可使用 Choose… 從類樹選擇，也可通過 Add… 手工增加。包選擇預設可覆蓋當前包及子包；需要只排除當前包時使用 .*。Spring Boot 類樹還會顯示已選擇保護的依賴 JAR。

推薦結構是“公開邊界/框架入口 → 普通 facade 或介面 → 受保護核心實現”。不要為了擴大保護範圍而加密所有第三方依賴或框架入口。

8. 匯出、複用與最終複核

點選 Export parameters… 可匯出：

  • p4j-encrypt-run.sh
  • p4j-encrypt-run.bat

匯出指令碼儲存當前已解析的選項，但不會寫入賬號郵箱和密碼。之後可通過頂部 Load Task File 恢復任務。

進入輸出頁後，至少複核以下專案：

  • 輸入檔案、應用型別、Java 版本和全部目標平臺；
  • 歸檔字尾、JIT、scanner overlay 和 JVM 引數；
  • JavaFX/WebView、Spring Boot 佈局或 Tomcat 版本/context；
  • 保護的依賴 JAR 和所有排除規則；
  • 輸出目錄以及是否建立新的 p4jx-xxxx 子目錄。

生成後必須在每個目標平臺使用包內啟動指令碼驗證啟動、框架掃描、序列化、反射、資源載入和核心業務路徑。高階引數頁配置正確只能說明任務引數已設定，不能代替最終產物驗證。