JVM 시작 파라미터 설정

Protector4J는 패키징 시 JVM 시작 파라미터를 설정할 수 있을 뿐만 아니라, 배포 후에도 생성된 시작 스크립트에 임시로 추가하거나 직접 수정할 수 있습니다. GUI의 기타 고급 파라미터는 Protector4J 고급 모드 설정를 참조하십시오.

1. 세 가지 설정 방식

방식적용 범위재패키징 시에도 유지되는지 여부권장 용도
GUI의 JVM startup options이번에 생성된 모든 플랫폼 시작 스크립트를 작성합니다.예, 작업 파라미터가 남아 있으면 다시 생성할 수 있습니다.일상적인 대화형 패키징
CLI의 --jvm-option이번에 생성된 모든 플랫폼 시작 스크립트를 작성합니다.예, 명령/작업 스크립트를 설정 소스로 사용할 수 있습니다.CI/CD, 반복적인 배포 가능
run.sh, run.bat 또는 Tomcat 스크립트 수정현재 배포 디렉토리만 수정합니다.아니요, 재패키징 시 기존 내용이 덮어씌워집니다.배포 후의 긴급한 조정이나 환경 전용 설정 변경.
APP_JAVA_OPTS 환경 변수현재 프로세스나 현재 환경에만 영향을 미칩니다.파일에는 저장되지 않습니다.임시 진단, 컨테이너/서비스 환경 내 주입용.

장기적으로 사용할 매개변수는 GUI 작업이나 CLI 명령어에 넣고, APP_JAVA_OPTS는 임시로 덮어쓰는 용도로 사용하는 것이 권장됩니다. 생성 스크립트를 직접 수정한 경우 변경 사항을 배포 설정에 기록해 두어야 하며, 다음에 재패키징할 때 다시 적용해야 합니다.

2. GUI에서 설정합니다.

  1. 입력 페이지에서 Advanced — customise the options yourself를 선택합니다. 간단 모드의 경우 최종 페이지에서 **Customize…**를 클릭하여 고급 설정으로 진입할 수 있습니다.
  2. Common options 내에서 JVM startup options를 찾습니다.
  3. 각 줄에 하나의 완전한 매개변수를 입력합니다. 예:
-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
-Dspring.profiles.active=prod
  1. 최종 매개변수 요약을 확인한 후 보호 작업을 실행합니다.

이러한 매개변수들은 자동으로 생성된 run.sh 및 run.bat에 기록됩니다. macOS의 run.command는 run.sh로 연결되므로 동일한 매개변수가 사용됩니다. Tomcat 매개변수는 또한 bin/catalina.sh 및 bin/catalina.bat의 시작 경로에도 포함됩니다. Library Encryption은 아카이브만 생성하고 시작 스크립트는 생성하지 않으므로 이 설정은 제공되지 않습니다.

GUI의 JVM 시작 옵션들

3. CLI에서 설정합니다.

각 매개변수마다 --jvm-option를 한 번씩 사용해야 하며, 여러 JVM 매개변수를 하나의 값으로 합치면 안 됩니다.

p4j javaapp app.jar dist \
  --jvm-option -Xms512m \
  --jvm-option -Xmx2g \
  --jvm-option -Dfile.encoding=UTF-8

Spring Boot:

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

Tomcat:

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

공백이나 특수 문자가 포함된 단일 매개변수는 전체를 한 블록으로 인용해야 합니다:

--jvm-option '-Dexample.message=hello world'

인코더는 매개변수의 경계를 기준으로 shell 스크립트와 batch 스크립트에 각각 이스케이프 처리를 수행합니다.

4. macOS / Linux: 스크립트를 직접 수정합니다.

일반 Java 및 Spring Boot 애플리케이션의 경우 출력 디렉토리에 있는 run.sh를 편집합니다. run.command는 단지 run.sh를 참조할 뿐이므로 중복으로 수정할 필요가 없습니다.

JVM_OPTS=(...)와 그 뒤에 존재할 수 있는 JVM_OPTS+=(...)를 찾아, APP_JAVA_OPTS에서 판단하기 전에 한 줄을 추가합니다:

JVM_OPTS+=("-Xms512m" "-Xmx2g" "-Dfile.encoding=UTF-8")
if [ -n "${APP_JAVA_OPTS:-}" ]; then
  # ...
fi

Spring Boot/JavaFX가 이미 생성한 --add-opens, --module-path, --add-modules 매개변수는 삭제하지 마십시오.

Tomcat의 경우 bin/catalina.sh를 편집하고, run_java() 내의 JVM_OPTS=(...) 뒤에 내용을 추가합니다:

run_java() {
  JVM_OPTS=(...)
  JVM_OPTS+=("-Xms1g" "-Xmx2g")
  # ...
}

이 변경 사항은 run.sh의 프론트엔드 실행과 bin/startup.sh의 백그라운드 시작에 모두 영향을 미칩니다.

5. Windows: 스크립트를 직접 수정합니다.

일반 Java 및 Spring Boot 애플리케이션의 출력 디렉터리를 수정하는 run.bat 파일을 편집합니다. 생성된 set "JVM_OPTS=..." 줄을 찾아, APP_JAVA_OPTS의 판단 부분 이전에 다음 내용을 추가합니다:

set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g -Dfile.encoding=UTF-8"
if defined APP_JAVA_OPTS set "JVM_OPTS=%JVM_OPTS% %APP_JAVA_OPTS%"

기존의 JVM_OPTS 내용은 그대로 유지하고, Spring Boot/JavaFX에 필요한 내부 매개변수는 삭제하지 마십시오.

Windows Tomcat을 백그라운드에서 실행합니다.

bin\catalina.bat 파일을 편집하여, 기존의 set "JVM_OPTS=..." 내용 뒤에 다음 내용을 추가합니다:

set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"

이 작업은 run.bat 또는 bin\catalina.bat run에 영향을 미칠 수 있습니다.

Windows Tomcat을 백그라운드에서 시작합니다.

bin\startup.bat는 PowerShell을 사용하여 백그라운드 프로세스를 생성합니다. 가장 간단한 영구적인 수정 방법은 catalina.bat를 호출하기 전에 APP_JAVA_OPTS를 설정하는 것입니다:

@echo off
set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
call "%~dp0catalina.bat" start %*
exit /b %ERRORLEVEL%

프론트엔드와 백엔드를 모두 지원하면서도 두 곳의 스크립트를 별도로 관리하지 않으려면, GUI 또는 CLI를 통한 --jvm-option를 사용하여 Tomcat 패키지를 재생성하는 것이 우선적입니다.

6. 임시로 APP_JAVA_OPTS를 사용합니다.

macOS / Linux

APP_JAVA_OPTS="-Xms512m -Xmx2g" ./run.sh

Tomcat:

APP_JAVA_OPTS="-Xms1g -Xmx2g" ./bin/startup.sh

Windows CMD

현재 CMD 세션에서 설정되며(이후 명령들도 이 설정을 계속 상속함), set APP_JAVA_OPTS=를 사용하여 삭제할 수 있습니다.

set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
run.bat

로컬 스코프 내에서만 적용되며, 실행 후 원래 환경으로 복원됩니다.

setlocal
set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
call run.bat
endlocal

Tomcat:

set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
bin\startup.bat

Windows PowerShell

$env:APP_JAVA_OPTS = '-Xms512m -Xmx2g'
.\run.bat
Remove-Item Env:APP_JAVA_OPTS

7. 파라미터의 순서 및 주의 사항

  • 툴이 생성하는 런타임에 반드시 필요한 파라미터가 앞에 오고, GUI/CLI를 통해 설정된 파라미터가 그 뒤에 추가되며, APP_JAVA_OPTS가 마지막에 추가됩니다.
  • 일부 JVM 파라미터의 경우 뒤에 오는 값이 앞의 값을 덮어쓰지만, 모든 파라미터에서 중복이 허용되는 것은 아닙니다. 중복 파라미터를 통한 덮어쓰기에 의존하는 것은 피해야 합니다.
  • APP_JAVA_OPTS는 공백으로 구분되므로 공백이 포함된 복잡한 단일 파라미터에는 적합하지 않습니다. 이러한 파라미터의 경우 GUI, --jvm-option를 사용하거나 스크립트 배열을 직접 편집하는 것이 더 좋습니다.
  • JVM 매개변수는 메인 클래스나 -jar 앞에 위치해야 하며, 애플리케이션 매개변수는 run.sh/run.bat 명령어 뒤에 배치해야 합니다.
  • 힙 크기를 수정한 후에는 컨테이너의 메모리 제한, 운영 체제의 사용 가능한 메모리, 그리고 실제 부하를 고려하여 검증을 진행해야 합니다.
  • 재패키징을 수행하면 시작 스크립트가 재작성되지만, 수동으로 수정한 내용은 자동으로 병합되지 않습니다.