Spring Boot 포트 번호 변경 & 충돌 해결 가이드 (8080 포트가 사용 중일 때)

안녕하세요. IT 기술 블로거입니다.

Spring Boot를 실행했는데 Web server failed to start. Port 8080 was already in use. 라는 에러 메시지를 보신 적 있으신가요? 개발자라면 누구나 한 번쯤 겪어봤을 포트 충돌 문제입니다.

Spring Boot의 내장 톰캣(Tomcat)은 기본적으로 8080 포트를 사용합니다. 하지만 이미 다른 프로세스가 이 포트를 쓰고 있거나, 여러 개의 마이크로서비스를 동시에 띄워야 한다면 포트 번호를 변경해야 합니다.

오늘은 가장 기초적인 설정 파일 수정부터, 커맨드 라인 인자, 그리고 테스트를 위한 랜덤 포트 할당까지 Spring Boot 포트 제어의 모든 것을 정리해 드립니다.

1. 설정 파일(application.yml)에서 변경하기

가장 정석적이고 영구적인 방법입니다. application.yml (또는 .properties) 파일에 server.port 속성을 정의하면 됩니다.

server:
  port: 9090

만약 properties를 사용한다면:

server.port=9090

이렇게 설정하고 재시작하면, 이제 애플리케이션은 9090번 포트에서 요청을 기다립니다.

2. 실행 시점에 변경하기 (일시적 변경)

이미 빌드된 JAR 파일을 받았는데 포트를 바꿔야 하거나, 임시로 다른 포트에서 띄워보고 싶을 때 유용합니다. 코드를 수정하고 다시 빌드할 필요가 없습니다.

2.1. 커맨드 라인 인자 (Command Line Arguments)

가장 우선순위가 높은 방법입니다. 설정 파일의 값보다 우선 적용됩니다.

java -jar my-app.jar --server.port=8081

2.2. 시스템 프로퍼티 (System Properties)

-D 옵션을 사용합니다.

java -Dserver.port=8082 -jar my-app.jar

2.3. 환경 변수 (Environment Variables)

도커(Docker)나 쿠버네티스(Kubernetes) 환경에서 매우 자주 사용됩니다. Spring Boot는 SERVER_PORT라는 환경 변수를 자동으로 매핑해 줍니다.

export SERVER_PORT=8083
java -jar my-app.jar

3. 랜덤 포트 사용하기 (테스트 환경 꿀팁)

CI/CD 파이프라인에서 자동화 테스트를 돌릴 때, 고정된 포트를 쓰면 동시에 여러 빌드가 돌 때 충돌이 날 수 있습니다. 이때 랜덤 포트 기능을 사용하면 운영체제가 사용 가능한 포트를 자동으로 할당해 줍니다.

설정 값을 0으로 지정하면 됩니다.

server:
  port: 0

로그를 확인해보면 Tomcat started on port(s): 54321 (http) 처럼 임의의 포트가 할당된 것을 볼 수 있습니다.

테스트 코드에서 할당된 포트 알아내기

랜덤 포트로 실행되면 포트 번호를 미리 알 수 없습니다. 이때 @LocalServerPort 어노테이션을 사용합니다.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class MyControllerTest {

    @LocalServerPort
    private int port;

    @Test
    void testHello() {
        String url = "http://localhost:" + port + "/hello";
        // RestTemplate 등을 이용해 요청 전송
        System.out.println("테스트 수행 중인 포트: " + port);
    }
}

4. 프로그래밍 방식으로 변경하기 (Configuration)

드물지만, 특정 로직에 따라 포트를 동적으로 결정해야 한다면 자바 코드로 설정할 수도 있습니다. WebServerFactoryCustomizer를 구현하면 됩니다.

@Component
public class ServerPortCustomizer implements WebServerFactoryCustomizer<ConfigurableWebServerFactory> {

    @Override
    public void customize(ConfigurableWebServerFactory factory) {
        // 예: 특정 조건에 따라 포트 변경
        int customPort = 8085; 
        factory.setPort(customPort);
    }
}

하지만 이 방법은 설정 파일 방식보다 우선순위가 낮거나 관리가 어려울 수 있어, 특수한 상황이 아니라면 권장하지 않습니다.

5. 포트 충돌 시 확인 방법

포트를 변경하기 전에 누가 내 포트를 쓰고 있는지 확인하고 싶다면?

Windows

netstat -ano | findstr :8080
taskkill /F /PID <PID번호>

Mac / Linux

lsof -i :8080
kill -9 <PID번호>

결론

Spring Boot에서 포트를 변경하는 방법은 상황에 따라 다양합니다.

1. 기본 설정: application.yml의 server.port
2. 배포/운영 유연성: java -jar 실행 시 --server.port 또는 환경 변수 사용
3. 테스트 격리: server.port=0 (랜덤 포트)

이 세 가지 패턴만 숙지하고 있다면, 단일 서버 배포든 MSA 환경이든 포트 문제로 골머리를 앓는 일은 없을 것입니다.

다음 글에서는 애플리케이션의 블랙박스를 들여다보는 창, “Spring Boot 로그 설정”에 대해 알아보겠습니다. System.out.println은 이제 그만! 제대로 된 로깅 전략을 세워봅시다.