Nginx 리버스 프록시 502 에러 해결 방법

두 가지 웹서비스 AAA 서비스와 BBB 서비스를 Docker Compose로 구성하여 운용 중이었으며, 각각 Python Flask, Next.js로 작성된 두 서비스는 서로 유기적으로 설계되어있어서 (로그인 세션 공유 등) Nginx의 리버스 프록시를 사용하여 다음과 같은 라우팅을 설정했습니다:
/, /service1, /service2 경로 → BBB 서비스 (포트 3000)
나머지 모든 경로 → AAA 서비스 (포트 8000)
그러나 BBB 서비스로 라우팅되는 경로들에서 502 Bad Gateway 에러가 발생했고 이를 해결하는 과정에서 알게 된 내용에 대해 포스팅합니다."

원인 분석

1. Nginx 로그 확인

Nginx 로그를 확인해보니 다음과 같은 에러가 반복적으로 발생했습니다:

connect() failed (111: Connection refused) while connecting to upstream

이는 Nginx가 BBB 서비스에 연결할 수 없다는 것을 의미합니다.

2. 컨테이너 상태 확인

Docker 컨테이너들의 상태를 확인해보니

BBB 서비스 컨테이너는 정상적으로 실행 중
포트 매핑도 정상적으로 되어 있음 (3000:3000)
컨테이너 로그에서 서버가 정상적으로 시작되었다는 메시지 확인

3. 네트워크 설정 확인

BBB 서비스 컨테이너의 네트워크 설정을 확인해보니:

{
    "Ports": {
        "3000/tcp": [
            {
                "HostIp": "0.0.0.0",
                "HostPort": "3000"
            }
        ]
    }
}

문제의 원인

문제의 핵심은 BBB 서비스(Next.js)의 바인딩 주소였습니다. 기본적으로 Next.js는 localhost:3000으로만 바인딩되어 있어서, Docker 컨테이너 내부의 다른 서비스(Nginx)에서 접근할 수 없었습니다.

해결 방법

BBB 서비스의 package.json 파일에서 start 스크립트를 수정했습니다:

{ "scripts": { "start": "next start -H 0.0.0.0"  // 변경 전: "next start"  }}

H 0.0.0.0 옵션을 추가하여 Next.js 서버가 모든 네트워크 인터페이스에 바인딩되도록 했습니다.

적용 및 결과

변경 후 Docker 컨테이너를 재시작했습니다:

docker-compose down
docker-compose up -d

이제 BBB 서비스가 0.0.0.0:3000으로 바인딩되어 Nginx가 접근할 수 있게 되었고, 502 에러가 해결되었습니다.

결론

Docker 컨테이너 간 통신에서는 서비스가 0.0.0.0으로 바인딩되어야 합니다.
Next.js와 같은 웹 서버를 Docker 환경에서 사용할 때는 호스트 바인딩 설정을 확인해야 합니다.
Nginx의 502 에러는 종종 업스트림 서버의 접근성 문제와 관련이 있습니다.

참고: Nginx 설정

문제 해결 후의 Nginx 설정은 다음과 같습니다:

upstream bbb {
    server aaa:3000;
}

location /challenges {
    proxy_pass <http://visualizer>;
    proxy_redirect off;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $server_name;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}