폐쇄망(Internal Network) 환경에서 Maven 빌드 시 발생하는 PKIX path building failed 오류처리방안

폐쇄망(Internal Network) 환경에서 Maven 빌드 시 발생하는 PKIX path building failed 오류처리방법

작성자:

폐쇄망(Internal Network) 환경에서 Maven 빌드 시 발생하는 PKIX path building failed 오류는 Maven이 중앙 저장소(Maven Central)에 접속하려 하지만, 보안 장비(방화벽, Proxy, SSL 검사 등)의 인증서를 Java가 신뢰하지 못해서 발생하는 전형적인 문제입니다.

폐쇄망에서는 외부 인터넷 접속이 불가능하므로, 이를 해결하기 위한 가장 근본적인 방법은 내부망에 Nexus(Private Repository)를 구축하는 것입니다.

1. 대응 방안 개요

  1. Nexus 서버 구축: 내부망의 특정 서버에 Sonatype Nexus 설치.

  2. Artifact 반입: 인터넷이 되는 환경에서 필요한 라이브러리를 다운로드하여 폐쇄망 Nexus로 복사/업로드.

  3. Maven 설정(settings.xml): 모든 라이브러리 요청이 외부가 아닌 내부 Nexus를 향하도록 설정.

  4. SSL 인증서 등록 (선택 사항): 만약 Nexus를 HTTPS로 운영하거나 프록시 서버를 경유해야 할 경우 Java Truststore에 인증서 등록.

2. 로컬 환경에 Nexus 서버 구축 방법

① Nexus 설치 (CentOS/Ubuntu 또는 Windows)

  1. Sonatype 공식 홈페이지에서 Nexus Repository Manager OSS 버전을 다운로드합니다. (폐쇄망이므로 파일은 USB 등으로 반입)

  2. 압축 해제: tar -xvf nexus-x.x.x.tar.gz

  3. 실행:

    • Linux: ./nexus-x.x.x/bin/nexus start

    • Windows: nexus.exe /run

  4. 접속: 브라우저에서 http://localhost:8081 접속 (기본 계정: admin / 비밀번호는 초기 실행 시 특정 파일에 저장됨)

② Nexus 저장소 설정

  • Proxy Repository: 외부 저장소 캐싱용 (폐쇄망에서는 사용 불가)

  • Hosted Repository: 직접 빌드한 JAR 또는 외부에서 가져온 JAR를 저장하는 용도.

  • Group Repository: 여러 저장소를 하나로 묶어서 제공 (주로 이것을 사용).

3. 폐쇄망으로 라이브러리 반입 방법 (가장 중요)

인터넷이 안 되는 폐쇄망 Nexus에 어떻게 라이브러리를 채울 것인가가 핵심입니다.

방법 A: 의존성 통째로 복사 (추천)

  1. 인터넷이 되는 PC에서 동일한 프로젝트를 준비합니다.

  2. mvn dependency:go-offline 명령어를 실행하여 모든 라이브러리를 로컬(~/.m2/repository)에 다운로드합니다.

  3. .m2/repository 폴더 전체를 압축하여 폐쇄망으로 옮깁니다.

  4. 폐쇄망 Nexus 서버의 Storage 경로(기본적으로 sonatype-work/nexus3/blobs)에 직접 넣거나, Nexus 관리자 화면의 ‘Upload’ 기능을 이용하여 주요 라이브러리를 업로드합니다.

방법 B: Maven Artifact Bulk Import 스크립트 이용

  • Nexus API나 별도의 스크립트를 사용하여 .m2/repository에 있는 파일들을 Nexus Hosted Repository로 일괄 업로드합니다.

4. Maven 설정 (settings.xml) 변경

개발자 PC의 conf/settings.xml 또는 ~/.m2/settings.xml을 수정하여 Nexus를 바라보게 합니다.

Xml

<settings>
  <mirrors>
    <mirror>
      <id>internal-nexus</id>
      <name>Internal Nexus Repository</name>
      <!-- Nexus의 Group Repository URL 입력 -->
      <url>http://[NEXUS_IP]:8081/repository/maven-public/</url>
      <mirrorOf>*</mirrorOf> <!-- 모든 요청을 Nexus로 강제 전환 -->
    </mirror>
  </mirrors>

  <profiles>
    <profile>
      <id>nexus-profile</id>
      <repositories>
        <repository>
          <id>central</id>
          <url>http://central</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>nexus-profile</activeProfile>
  </activeProfiles>
</settings>

5. PKIX path building failed 오류 해결 (SSL 인증서 문제)

폐쇄망(Internal Network) 환경에서 Maven 빌드 시 발생하는 PKIX path building failed 오류처리방안

만약 Nexus를 구축했음에도 이 에러가 계속 난다면, 이는 Maven이 Nexus에 접속할 때 사용하는 HTTPS 인증서를 Java가 신뢰하지 못하기 때문입니다. (또는 여전히 외부로 나가려 시도 중일 때)

해결책: Java Keystore에 인증서 등록

  1. 브라우저로 Nexus URL 접속 -> 주소창 자물쇠 클릭 -> 인증서 내보내기 (예: nexus.cer)

  2. 명령프롬프트(관리자 권한)에서 Java의 cacerts 파일에 인증서 추가:

    Bash

    keytool -importcert -keystore "C:\Program Files\Java\jdk-xx\lib\security\cacerts" -storepass changeit -file nexus.cer -alias nexus_internal

  3. Maven 재실행.

6. 요약

  1. 환경 확인: 폐쇄망이므로 외부 repo.maven.apache.org 접속은 무조건 실패합니다.

  2. Nexus 구축: 내부 서버에 Nexus를 띄우고 8081 포트를 오픈합니다.

  3. 데이터 이관: 외부에서 다운로드한 .m2/repository의 내용을 Nexus로 이관합니다.

  4. 설정 강제: settings.xml의 <mirrorOf>*</mirrorOf> 설정을 통해 Maven이 절대 밖으로 나가지 않고 Nexus만 바라보게 합니다.

  5. 빌드: mvn package 실행 시 Nexus에서 라이브러리를 가져오는지 확인합니다.