핵심 요약
Jenkins 서비스 자체가 시작하지 않으면 Jenkinsfile보다 systemd 상태와 로그, 컨트롤러가 실제 사용하는 Java 버전을 먼저 확인해야 합니다.
검수 범위
현재 Jenkins LTS별 지원 Java 버전이 달라질 수 있으므로 고정 버전을 단정하지 않고 공식 지원표를 확인하도록 검수했습니다.
Jenkins 관리자 화면이 열리지 않고 서비스 자체가 failed 상태라면 Jenkinsfile 문법보다 컨트롤러 프로세스의 시작 로그를 먼저 봐야 합니다. Jenkins Pipeline은 Groovy와 유사한 DSL을 사용하지만 Jenkins 컨트롤러는 Java에서 실행되며, 지원 Java 버전은 Jenkins 릴리스에 따라 달라집니다.
서비스 문제와 Pipeline 문제 구분
- 서비스 문제: 관리자 화면이 열리지 않고 systemd에서 Jenkins가 시작하지 못함
- Pipeline 문제: Jenkins 화면은 열리지만 특정 Job의 stage 또는 step이 실패함
첫 번째 상황에서 Jenkinsfile을 되돌려도 서비스 시작 문제는 해결되지 않는 경우가 많습니다. 반대로 특정 Pipeline만 실패한다면 해당 빌드 로그, Jenkinsfile, 플러그인과 빌드 도구를 확인합니다.
첫 진단 명령
sudo systemctl status jenkins
sudo journalctl -u jenkins -b --no-pager
java -version
sudo systemctl cat jenkins로그에서 첫 번째 원인 메시지를 찾습니다. UnsupportedClassVersionError, 지원되지 않는 Java 안내, 포트 충돌, 권한 오류, 설정 파일 구문 오류는 접근 방법이 서로 다릅니다. 마지막 줄만 보지 말고 서비스가 시작된 시점부터 확인하는 편이 좋습니다.
Java 버전은 고정 숫자로 단정하지 않기
예전 Jenkins LTS에서 Java 17이 지원됐다고 해서 현재 릴리스도 같은 것은 아닙니다. 2026년의 일부 Jenkins 릴리스는 Java 21 또는 25를 요구합니다. 설치된 Jenkins 버전을 확인한 뒤 Jenkins 공식 Java 지원표에서 정확히 대응되는 런타임을 선택하세요.
jenkins --version 2>/dev/null || true
java -version패키지 설치 방식에 따라 Jenkins 버전 확인 명령과 설정 위치가 다를 수 있습니다. 공식 설치 문서와 배포판 패키지 정보를 함께 확인합니다.
터미널 Java와 서비스 Java가 다를 수 있음
터미널에서 java -version이 올바르게 보여도 systemd 서비스가 별도의 JAVA_HOME이나 실행 경로를 사용할 수 있습니다. systemctl cat jenkins와 서비스 환경 설정을 확인하고, 실제 Jenkins 프로세스가 어떤 Java를 사용하는지 로그에서 확인합니다. 여러 JDK가 설치된 서버에서는 이 차이가 자주 원인이 됩니다.
지원 Java로 변경한 뒤 확인
서버와 Jenkins 릴리스에 맞는 JDK를 설치하고 서비스 설정을 변경했다면 systemd 설정을 다시 읽고 Jenkins를 시작합니다.
sudo systemctl daemon-reload
sudo systemctl restart jenkins
sudo systemctl status jenkins정상 실행 후에는 관리자 화면 접속만 보지 말고 대표 Pipeline을 한 번 실행합니다. 컨트롤러용 Java와 Android Gradle 빌드에 사용하는 JDK는 요구 버전이 다를 수 있으므로 두 환경을 별도로 기록해야 합니다.
Groovy를 별도 설치해야 하는가
일반적인 Jenkins Pipeline 사용을 위해 운영체제에 groovy 명령을 별도로 설치하는 것이 서비스 시작 문제의 해결책은 아닙니다. Declarative와 Scripted Pipeline은 Jenkins Pipeline 하위 시스템이 제공하며 일반 Groovy와 완전히 같은 실행 환경도 아닙니다. Pipeline 문법 오류는 Job 실행 로그와 Pipeline 문법 문서에서 확인합니다.
업그레이드 전 남길 기록
- 현재 Jenkins와 플러그인 버전
- 컨트롤러와 agent가 사용하는 Java 버전
- Android Gradle Plugin과 Gradle이 요구하는 JDK
- 서비스 설정 파일과 즉시 되돌릴 방법
- 업그레이드 뒤 실행할 대표 Pipeline 목록
로그의 실제 오류와 공식 지원표를 먼저 맞추면 Groovy, Jenkinsfile, Java를 한꺼번에 변경하는 일을 피할 수 있고 원인도 명확하게 남길 수 있습니다.
Java 외에 함께 확인할 시작 실패
로그에 Java 호환 오류가 없다면 8080 포트가 이미 사용 중인지, Jenkins 홈과 로그 디렉터리를 서비스 계정이 읽고 쓸 수 있는지, 디스크 공간이 남아 있는지 확인합니다. 포트 충돌과 파일 권한 문제는 JDK를 바꿔도 해결되지 않습니다. 원인 메시지를 기준으로 한 계층만 변경하세요.
변경 전 복구 지점
Jenkins와 플러그인 업그레이드, Java 전환 전에는 Jenkins 홈의 지원되는 백업 방법과 서비스 설정을 확인합니다. 단순히 폴더를 실행 중에 복사하면 일관성이 보장되지 않을 수 있습니다. 조직의 백업 절차로 복구 가능성을 확인한 뒤 변경하고, 문제가 생기면 여러 버전을 연속 설치하기보다 마지막 정상 조합으로 되돌릴 수 있어야 합니다.
검증 기준과 참고 자료
이 글은 2026-09-08에 아래 공식 문서와 공개 기술 문서를 기준으로 내용과 용어를 다시 검수했습니다. 제품 버전과 기기 제조사에 따라 화면 이름은 달라질 수 있으므로 실제 화면과 공식 문서를 함께 확인하세요.