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
출력 디렉터리에 있는 vlxjre를 시스템 JRE로 대체하지 마십시오.
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 관련 클래스들은 일반 클래스로 남겨두는 것이 권장됩니다:
@Controller,@RestController,@ControllerAdvice;@Configuration, 자동 설정 클래스, AOT/CGLIB 증강 클래스;- Jackson DTO, JPA Entity, record 및 검증 모델;
- 애플리케이션의 시작점과 프레임워크에 의해 직접 생성/프록시되는 클래스;
- 런타임 바이트코드 증강이 필요한 클래스.
서비스 구현체를 보호하며, 공개된 패사드나 인터페이스를 통해 접근할 수 있습니다. 규칙은 정확한 클래스명, 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 매개변수 참고를 참조하십시오.