컨테이너를 다시 빌드한 후 리버스 프록시에서 502 오류가 발생하는 이유는 무엇인가요?

Eva Wong 는 테크니컬 라이터 이자 상주 메이커 로 ZimaSpace에서 활동합니다. 평생 기술을 사랑해 온 그녀는 홈랩과 오픈 소스 소프트웨어에 열정을 품고 있으며, 복잡한 기술 개념을 누구나 이해하기 쉬운 실습 가이드로 풀어내는 데 전문성을 갖추고 있습니다. Eva는 셀프 호스팅이 어렵고 부담스러운 일이 아니라 즐거워야 한다고 믿습니다. 그녀는 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 어려움을 풀어내고, 첫 NAS를 조립하는 것부터 Docker 컨테이너를 능숙하게 다루는 것까지 도전하도록 돕습니다.

재빌드된 업스트림에 유효한 연결을 더 이상 열 수 없으면 리버스 프록시에서 컨테이너 재빌드 후 502 오류가 발생합니다.

재빌드로 컨테이너가 교체되거나, 새 주소가 할당되거나, Docker 네트워크에서 분리되거나 네트워크 이름이 바뀌거나, 노출 포트가 변경되거나, 구성이 불완전한 상태로 복원되거나, 애플리케이션이 준비되기 전에 프록시가 시작될 수 있습니다. 올바른 원인 파악은 프록시 오류 로그에서 시작해 프록시부터 컨테이너까지 정확한 업스트림 주소를 추적하는 것입니다. 오류가 잠시 사라질 때까지 두 서비스를 재시작하는 방식은 피하세요.

502가 업스트림 연결 실패로 발생했는지 확인

문제가 발생한 도메인에 한 번 요청하고 타임스탬프, 프록시 상태, 업스트림 주소, 전체 오류 메시지를 기록하세요. 연결 거부, 호스트를 찾을 수 없음, 시간 초과, 연결 재설정, TLS 핸드셰이크 실패, 잘못된 응답을 구분하세요.

502는 프록시가 사용할 수 있는 업스트림 응답을 받지 못했다는 뜻이지만, 오류 세부 정보에 따라 대상이 없거나, 연결할 수 없거나, 수신 대기 중이 아니거나, 잘못된 프로토콜을 사용 중일 수 있습니다. 최신 NGINX 문제 해결 가이드에 따르면 컨테이너를 재빌드한 뒤 이름 확인이나 구성을 새로 고칠 때까지 프록시가 이전 백엔드 주소를 사용할 수 있습니다.

로그에 기록된 업스트림 이름, 주소, 포트, 프로토콜을 사용해 프록시 호스트나 프록시 컨테이너에서 애플리케이션에 직접 요청을 보내세요. 직접 요청도 같은 방식으로 실패한다면 공개 DNS나 인증서를 변경하지 말고 프록시와 컨테이너 사이를 조사하세요.

재빌드 전후 업스트림 대상 비교

재빌드된 컨테이너 이름, 서비스 이름, 내부 IP, 노출 포트, 게시 포트, 네트워크 별칭, 연결된 네트워크를 확인하세요. 프록시 구성 및 마지막으로 작동했던 대상으로 삼아 비교하세요.

nginx-proxy 문제 사례에서는 재빌드로 애플리케이션 컨테이너 IP가 바뀌었는데도 프록시가 계속 연결할 수 없는 컨테이너 업스트림으로 요청을 보낸 상황을 설명합니다. 공개 도메인은 그대로였지만 내부 업스트림 주소만 바뀌었습니다.

컨테이너 IP보다 안정적인 Compose 서비스 이름이나 네트워크 별칭을 사용하세요. IP를 고정으로 지정했다면 재빌드된 서비스에 실제로 해당 IP가 할당되었는지, 다른 컨테이너가 그 주소를 사용하고 있지는 않은지 확인하세요.

프록시와 앱이 여전히 Docker 네트워크를 공유하는지 확인

프록시와 애플리케이션에 연결된 네트워크를 나열하고, 둘이 사용자가 정의한 네트워크를 하나 이상 공유하는지 확인하세요. 호스트 포트를 게시해도 격리된 다른 Docker 네트워크에서 컨테이너 이름에 자동으로 접근할 수 있는 것은 아닙니다.

Docker 네트워킹 사례에서는 종속 서비스를 적절한 네트워크로 옮기자 반복되던 502 응답이 즉시 사라졌습니다. 이는 모든 컨테이너가 계속 실행 중이어도 업스트림 경로에 접근할 수 없을 수 있음을 보여 줍니다.

서비스 간 연결이 재빌드 후에도 유지되도록 일회성 명령이 아닌 Compose를 통해 연결하세요. 스택을 다시 만든 후 프록시 컨테이너 내부에서 DNS 이름 확인과 업스트림 포트를 테스트하세요.

내부 리스너 포트와 바인딩 주소를 확인하세요

애플리케이션이 프록시에서 사용하는 포트와 컨테이너 네트워크에서 접근 가능한 주소에서 수신 대기하는지 확인하세요. 호스트에 공개된 포트와 컨테이너 내부의 수신 포트를 혼동하지 마세요.

앱이 루프백 이외의 주소에 바인딩된 후에야 프록시가 연결할 수 있습니다. 자체 컨테이너 내부에서 127.0.0.1로 수신하는 서비스는 로컬 상태 확인 명령이 성공하더라도 프록시에서 사용할 수 없습니다.

애플리케이션 로그, 소켓 목록, 프록시 컨테이너에서 직접 보낸 요청 하나를 확인하세요. 포트에서 연결을 거부하면 재시도나 프록시 시간 제한을 늘리기 전에 앱 리스너 또는 구성을 수정하세요.

컨테이너 시작이 아닌 애플리케이션 준비 완료까지 기다리세요

재빌드된 컨테이너가 실행 중이어도 마이그레이션, 데이터베이스 복구, 캐시 준비 또는 구성 생성이 계속 진행되어 애플리케이션이 요청을 수락하지 못할 수 있습니다. 최초 502 발생 시각을 상태 확인 및 시작 로그와 비교하세요.

Grist 문제 해결 논의에서는 Docker 아키텍처, 환경 설정, 상위 서비스의 준비 상태가 함께 작용해 재빌드 후에도 컨테이너 측 502 오류가 지속될 수 있음을 보여 줍니다.

의미 있는 상태 확인을 추가하고, 프록시나 종속 서비스가 단순히 프로세스의 존재 여부가 아니라 클라이언트에 필요한 작업이 완료될 때까지 기다리도록 하세요. 영구적으로 실패한 앱이 단순히 느리게 시작하는 것처럼 보이지 않도록 재시도 횟수를 제한하세요.

프록시 이름 확인을 새로 고치고 안정적인 경로를 재구축하세요

서비스 이름, 네트워크, 포트, 상태가 올바른지 확인한 후 프록시를 다시 로드하거나 재생성하세요. 프록시가 시작 시에만 이름을 확인한다면, 지원되는 런타임 이름 확인 기능이나 예측 가능한 재시작 순서를 설정하세요.

ZimaSpace에서 실패한 컨테이너 종속 항목을 격리하는 워크플로는 상위 컨테이너가 정상 상태를 유지하지 않고 반복적으로 종료될 때 참고할 수 있는 진단 방법입니다.

프록시가 재빌드 후 서비스 이름을 확인하고, 의도한 내부 포트에 연결하며, 시작이 완료될 때까지 기다린 뒤, 수동으로 IP를 수정하지 않아도 도메인을 제공해야 복구가 완료된 것입니다. 검증 후에는 임시 직접 IP 대상과 문서화되지 않은 네트워크 연결을 제거하세요.

지원 및 팁

더 읽어보기

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.