Nexus Repository 유형 및 Spring Boot 연동

Nexus에 Proxy, Hosted, Group이라는 저장소 유형이 있는데, 각각 왜 존재하고 Spring Boot에서는 어떤 URL을 써야 할까요?

Nexus Repository 는 용도별로 네 가지 유형(Proxy, Hosted, Group, Virtual)을 제공합니다. 이 유형들을 이해해야 pom.xml과 settings.xml을 올바르게 설정할 수 있습니다.

Repository 유형

Proxy Repository

Proxy Repository는 Maven Central 같은 ** 외부 공개 저장소의 캐싱 프록시** 역할을 합니다.

개발자가 외부 라이브러리를 요청하면, Nexus가 먼저 캐시에서 확인하고, 없으면 외부 저장소에서 다운로드하여 캐시에 저장한 뒤 응답합니다. 이후 동일한 라이브러리 요청은 캐시에서 바로 제공됩니다.

Proxy Repository를 사용하면 외부 저장소 장애나 네트워크 불안정 상황에서도 이미 캐싱된 라이브러리는 정상적으로 사용할 수 있습니다. 또한 개발 서버가 외부망에 접근할 수 없는 폐쇄망 환경에서 필수적입니다.

Hosted Repository

Hosted Repository는 ** 팀에서 직접 개발한 아티팩트를 저장하고 배포하는 사설 저장소 **입니다. Version Policy에 따라 Release용과 Snapshot용으로 분리하여 운영합니다.

Version Policy

Release와 Snapshot을 분리하는 이유는 명확합니다. Release 저장소에는 검증이 완료된 안정 버전만 올라가므로, 운영 환경에서 실수로 개발 중인 불안정한 버전을 참조하는 사고를 방지할 수 있습니다.

Group Repository

Group Repository는 Proxy와 Hosted 저장소를 하나의 URL로 묶어주는 가상 저장소 입니다.

Group이 없다면, 개발자는 pom.xml에 외부 라이브러리를 받기 위한 Proxy URL과 내부 라이브러리를 받기 위한 Hosted URL을 각각 등록해야 합니다. Group Repository를 사용하면 하나의 URL만 등록하면 됩니다.

[개발자의 Maven 요청]
        │
        ▼
  ┌─────────────┐
  │  Group Repo │  ← 단일 URL로 접근
  │  (maven-    │
  │   public)   │
  └──────┬──────┘
         │
    ┌────┴─────┐
    ▼          ▼
┌────────┐ ┌────────┐
│ Proxy  │ │ Hosted │
│ (Maven │ │(Release│
│Central)│ │/Snap)  │
└────────┘ └────────┘

Nexus 설치 시 기본 생성되는 maven-public이 바로 Group Repository입니다. 일반적으로 이 URL 하나만 pom.xml에 등록하면 됩니다.

Virtual Repository

Virtual Repository는 Maven 1 형식과 Maven 2 형식 간의 변환을 위해 존재했던 레거시 유형입니다. 현재는 Maven 2(및 3) 형식이 표준이므로, 새로운 환경에서는 사용할 일이 거의 없습니다.

Spring Boot와 Nexus 연동

Nexus 연동은 크게 두 가지 흐름으로 나뉩니다.

1. 라이브러리를 받으려면 → settings.xml (인증) + pom.xml의 <repositories> (저장소 URL)
2. ** 내부 라이브러리를 배포하려면** → pom.xml의 <distributionManagement> (배포 대상 URL)

1단계: Maven settings.xml에 인증 정보 등록

Nexus 저장소에 접근하려면 인증이 필요합니다. 인증 정보는 프로젝트 파일(pom.xml)이 아닌 ** 로컬 Maven 설정 파일 **에 작성하여 보안을 유지합니다.

<!-- ~/.m2/settings.xml -->
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                         http://maven.apache.org/xsd/settings-1.0.0.xsd">

     <servers>
        <!-- Nexus 서버 인증 정보 -->
        <server>
          <id>nexus-releases</id>        <!-- pom.xml의 repository id와 반드시 일치해야 함 -->
          <username>deployer</username>   <!-- Nexus 계정 -->
          <password>deployer123</password><!-- Nexus 비밀번호 -->
        </server>
        <server>
          <id>nexus-snapshots</id>
          <username>deployer</username>
          <password>deployer123</password>
        </server>
     </servers>
</settings>

<server> 의 <id> 값은 이후 pom.xml에서 사용하는 <repository>의 <id>와 정확히 일치해야 합니다. 이 값이 다르면 Maven이 인증 정보를 찾지 못해 401 Unauthorized 오류가 발생합니다.

설정 후, IntelliJ에서 Settings → Build, Execution, Deployment → Build Tools → Maven → User settings file 경로를 ~/.m2/settings.xml로 지정합니다.

2단계: pom.xml에 저장소 URL 등록 (라이브러리 다운로드)

Nexus에서 라이브러리를 받아오려면 <repositories>에 저장소 URL을 등록합니다.

<!-- pom.xml -->
<repositories>
    <!-- Nexus Group Repository (Proxy + Hosted를 포함하는 단일 URL) -->
    <repository>
        <id>nexus-releases</id>
        <name>Nexus Release Repository</name>
        <url>https://nexus.example.com/repository/maven-public/</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Group Repository URL을 사용하면, Maven이 하나의 URL로 외부 라이브러리(Proxy)와 내부 라이브러리(Hosted) 모두를 받아올 수 있습니다.

3단계: pom.xml에 배포 설정 추가 (내부 라이브러리 배포)

팀에서 개발한 라이브러리를 Nexus에 배포하려면 <distributionManagement>를 설정합니다. mvn deploy 명령 실행 시 이 설정에 따라 아티팩트가 업로드됩니다.

<!-- pom.xml -->
<distributionManagement>
    <!-- Release 버전 배포 저장소 -->
    <repository>
        <id>nexus-releases</id>   <!-- settings.xml의 server id와 매칭 -->
        <url>https://nexus.example.com/repository/maven-releases/</url>
    </repository>

    <!-- Snapshot 버전 배포 저장소 -->
    <snapshotRepository>
        <id>nexus-snapshots</id>  <!-- settings.xml의 server id와 매칭 -->
        <url>https://nexus.example.com/repository/maven-snapshots/</url>
    </snapshotRepository>
</distributionManagement>

Maven은 pom.xml의 <version> 값에 -SNAPSHOT 접미사가 있으면 <snapshotRepository>로, 없으면 <repository>로 배포합니다.

# 배포 실행
mvn deploy

연동 시 자주 발생하는 문제

주의할 점

settings.xml과 pom.xml의 id 불일치

가장 흔한 실수입니다. settings.xml의 <server><id>와 pom.xml의 <repository><id>가 한 글자라도 다르면 Maven이 인증 정보를 찾지 못해 401 Unauthorized가 발생합니다. 복붙할 때 공백이 포함되지 않았는지 확인합니다.

Release 저장소에 동일 버전 재배포

Release 저장소는 한 번 배포한 아티팩트를 덮어쓸 수 없습니다. 동일 버전(1.0.0)을 다시 배포하면 405 Method Not Allowed가 발생합니다. 수정이 필요하면 반드시 버전 번호를 올려야 합니다.

정리