保護 Tomcat Web 應用

tomcat 把 WAR 轉換為一個自包含的 Tomcat base。執行時使用編碼器內建的 Tomcat 元件，不讀取使用者本機的 Tomcat 安裝。

1. GUI 操作

在應用型別頁面選擇 Tomcat WAR。
選擇輸入 WAR、隨包 Java 版本和目標平臺，並選擇簡單模式或高階模式。
使用高階模式時，選擇 Tomcat 9/10.1 或保持自動檢測，並按需設定 Context Path、JVM 引數和排除規則；簡單模式會通過相容性掃描建議 Tomcat 版本。各選項含義見 Protector4J 高階模式設定。
選擇輸出目錄，複核引數摘要，然後點選 Run protection。

2. CLI 示例

指定 Context Path：

p4j tomcat app.war dist --context /app

相容性掃描與自動應用建議：

p4j tomcat app.war --compat-scan
p4j tomcat app.war dist --compat-apply --context /app

這兩個選項不能同時使用，它們的區別是：

選項	行為	何時使用
`--compat-scan`	只掃描輸入 WAR，列印風險和配置建議後退出；不編碼、不生成 `dist`，因此不需要輸出目錄	首次保護應用、升級 Tomcat 相關依賴、調整保護範圍或 JSP 配置後，以及排查相容性問題時，先用它檢視報告
`--compat-apply`	掃描後自動合併保守建議，然後繼續編碼並生成輸出，因此必須指定輸出目錄	已閱讀掃描結果並接受自動建議時，用它完成打包；也可用於已驗證過規則的重複構建或 CI 流程

對 tomcat，--compat-apply 可根據掃描結果追加排除類，並調整 Tomcat 版本、ZIP overlay 和歸檔字尾等選項。對後三類選項，命令列中顯式指定的值優先；建議的排除類則預設與顯式 --exclude 合併。如不希望自動追加排除類，可同時傳入 --no-compat-excludes。掃描器只做靜態啟發式分析，需要修改程式碼的問題不會被 --compat-apply 自動修復，生成後仍需在目標平臺迴歸測試。

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

--tomcat-version 預設為 auto。必要時可顯式指定 9 或 10.1：

p4j tomcat app.war dist --context /app --tomcat-version 10.1

3. 輸出結構

dist/
├── bin/
│   ├── catalina.sh
│   ├── startup.sh
│   ├── shutdown.sh
│   └── *.bat
├── conf/p4jx/
│   ├── contexts.list
│   ├── protected-classes.list
│   └── allowed-prefixes.list
├── protected/
│   └── app.p4jx
├── lib/
│   ├── p4jx-tomcat-runtime.jar
│   └── tomcat-runtime-deps.jar
├── vlxjre/
├── run.sh
└── run.bat

預設不生成物理 WAR。web.xml、靜態資源、公開類、後設資料樁和保護實現都位於 protected/<context>.p4jx，由 P4JX WebResourceSet 呈現給 Tomcat。

4. 啟動與停止

前臺執行：

./run.sh

Tomcat 風格後臺啟動：

./bin/startup.sh
./bin/shutdown.sh

Windows 使用對應 .bat 檔案。日誌寫入輸出目錄的 logs/。

JVM 啟動引數

打包時可在 GUI 的 JVM startup options 中每行填寫一個引數，或使用 CLI：

p4j tomcat app.war dist \
  --context /app \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

部署後直接修改：

macOS/Linux：編輯 bin/catalina.sh，在 run_java() 內的 JVM_OPTS=(...) 後增加 JVM_OPTS+=("-Xms1g" "-Xmx2g")，前臺和 startup.sh 後臺啟動都會生效。
Windows 前臺：編輯 bin\catalina.bat，在原 set "JVM_OPTS=..." 後增加 set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"。
Windows 後臺：在 bin\startup.bat 呼叫 catalina.bat 之前增加 set "APP_JAVA_OPTS=-Xms1g -Xmx2g"。若需前後臺共用一套持久引數，推薦通過 GUI/CLI 重新生成。

臨時啟動也可在命令前設定 APP_JAVA_OPTS。完整的 CMD、PowerShell 和指令碼示例見 JVM 啟動引數配置。

5. Tomcat 版本選擇

WAR API 名稱空間	Tomcat	Java 要求
`javax.servlet.*`	Tomcat 9	Java 8/11/17/21/25
`jakarta.servlet.*`	Tomcat 10.1	Java 11/17/21/25

自動檢測優先從應用類和部署描述符識別 API 名稱空間，依賴 JAR 名稱僅作為輔助證據。檢測到 javax 與 jakarta 混用時，工具會拒絕自動猜測。

6. JSP

WAR 含 JSP 時，預設自動在編碼階段預編譯為 servlet 類和 URL 對映。原因是執行時動態 JSP 編譯會從 Tomcat 工作目錄定義新類，不符合保護執行時的類定義邊界。

可顯式控制：

--precompile-jsp
--no-precompile-jsp

生產環境建議保持預設自動預編譯。停用後，含 JSP 的應用可能在訪問頁面時失敗。

7. 保護範圍與排除規則

預設保護 WEB-INF/classes 下的應用類，WEB-INF/lib 依賴預設不保護。可排除 Web-facing 類：

p4j tomcat app.war dist \
  --context /app \
  --exclude 'com.example.web.**,com.example.dto.**'

重點排除 servlet/filter/listener、DTO、配置、實體、JNI 橋接類和需要由容器增強的類。相容性掃描會提供保守建議。

8. 在同一 Tomcat 包中增加應用

p4j tomcat second.war dist \
  --append-app \
  --context /second

約束：

context path 不能與已有應用重複；
新舊應用必須使用相同 Tomcat 主版本、Java 版本和目標平臺；
未傳 --append-app 時，工具拒絕寫入已有 Tomcat 包；
GUI 中勾選“Append application to an existing Tomcat folder”，並直接選擇現有目錄。

9. Java 8 注意事項

Java 8 目標會自動啟用 ZIP overlay，使 Tomcat WebResourceSet 可以開啟受保護歸檔。