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 子目录。

生成后必须在每个目标平台使用包内启动脚本验证启动、框架扫描、序列化、反射、资源加载和核心业务路径。高级参数页配置正确只能说明任务参数已设置，不能代替最终产物验证。