• 목록

컨테이너 안에서는 웹 서버가 실행되는데 브라우저에서는 열리지 않는 일이 있습니다. 설정 파일에 80과 8080이 함께 적혀 있어 어느 번호로 접속할지 헷갈리기도 합니다.

이때 포트 번호를 무작정 바꾸기보다 요청이 출발하는 위치와 도착하는 위치를 구분하면 문제 범위를 좁힐 수 있습니다. 일반적인 Docker 브리지 네트워크와 포트 게시를 기준으로 기본 개념을 정리합니다.

host 네트워크 등 다른 구성에는 그대로 적용되지 않을 수 있습니다.

AI 생성 삽화 · 개념 이해를 위한 AI 연출 이미지이며 실제 시스템 구성도나 측정 결과가 아닙니다.

핵심 정리
호스트 포트는 호스트 쪽 접속 입구이고 컨테이너 포트는 내부 프로그램이 연결을 받는 위치입니다. 포트 게시 설정, 프로그램의 수신 주소, 실제 접속 주소를 한 경로로 연결해서 확인합니다.

1. 포트 번호 옆에 장소를 함께 적습니다

8080이라는 숫자만 메모하면 그것이 개발 PC의 포트인지 컨테이너 안의 포트인지 알 수 없습니다. 연결 문제를 조사할 때는 호스트의 8080, 웹 컨테이너의 80처럼 위치를 붙입니다.

가상의 개발 환경에 웹 컨테이너 두 개가 있다고 가정하겠습니다. 각 컨테이너 안에서 같은 포트 번호를 사용하더라도 서로 분리된 네트워크 공간일 수 있습니다.

반면 호스트의 같은 주소와 같은 포트를 두 프로그램이 동시에 차지하려 하면 충돌할 수 있습니다. 숫자가 같다는 이유로 같은 연결 지점을 뜻한다고 생각하면 이 차이가 사라집니다.

메모에 출발 프로그램, 접속 주소, 전달 대상까지 한 줄씩 적으면 어디서 번호가 바뀌는지 확인하기 쉽습니다.

2. 포트 게시를 전달 관계로 읽습니다

Docker 공식 문서의 포트 게시 형식은 호스트 쪽 포트와 컨테이너 쪽 포트를 구분합니다. 예를 들어 127.0.0.1:8080:80이라는 게시 설정은 호스트의 루프백 주소에 있는 8080을 컨테이너의 80으로 연결하는 의미입니다.

이미지의 EXPOSE 설명만으로 호스트 포트가 자동 게시되지는 않습니다. 이 기본 관계를 파악한 뒤에는 실제 실행된 설정을 확인합니다.

예전 메모에는 8080이라고 적혀 있어도 현재 실행은 다른 번호일 수 있기 때문입니다. 브라우저 주소를 바꿀 때도 내부 프로그램의 수신 포트를 먼저 바꾸는 일이 필요한지 따져 봅니다.

접속 입구를 바꾸는 요구와 프로그램의 내부 설정을 바꾸는 요구는 서로 다른 변경입니다.

3. localhost는 요청을 보내는 쪽에서 해석합니다

일반적인 분리된 컨테이너 네트워크에서 localhost를 내 컴퓨터 전체를 가리키는 공통 이름으로 생각하면 혼동이 생깁니다. 호스트의 브라우저와 컨테이너 안의 프로그램은 서로 다른 네트워크 문맥에서 주소를 사용합니다.

Docker 네트워킹 문서는 컨테이너의 네트워크와 이름 해석 설정을 별도로 설명합니다. 가상의 웹 컨테이너가 다른 데이터 저장 컨테이너에 연결하려는데 자신의 localhost를 사용했다고 가정해 봅니다.

이때 확인할 것은 비밀번호보다 먼저 연결 대상의 위치일 수 있습니다. 같은 네트워크에서 사용할 서비스 이름이나 연결 주소를 구성에 맞게 확인해야 합니다.

호스트에서 성공한 주소를 내부 프로그램 설정에 그대로 복사해도 된다는 가정은 피하는 편이 좋습니다.

4. 포트 전달 뒤에 실제 수신 프로그램이 있어야 합니다

주소를 올바르게 적었어도 전달 대상에서 연결을 받는 프로그램이 없다면 원하는 응답은 나오지 않습니다. 가상의 웹 서버가 설정 파일에서는 80을 쓰도록 되어 있는데 실행 옵션에서 다른 포트를 선택했다고 생각해 봅니다.

포트 게시만 고쳐 가며 재시작하면 변경 이력이 복잡해지고 원인을 놓치기 쉽습니다. 프로그램 로그와 실제 수신 설정을 먼저 비교합니다.

수신 주소가 컨테이너 외부에서 들어오는 연결을 받을 수 있는 주소인지도 구성에 맞게 확인합니다. 단순히 프로세스가 존재한다는 기록과 웹 요청을 받을 준비가 끝났다는 기록을 나누면 도움이 됩니다.

시작 중 오류가 났는데 셸이나 다른 프로세스만 남아 있는 경우도 조사 범위에 포함할 수 있습니다.

5. 호스트에서 성공한 다음 바깥 경로를 확인합니다

연결을 시험할 때는 한 번에 인터넷 전체 경로를 확인하기보다 가까운 구간부터 나누면 원인 후보가 줄어듭니다. 컨테이너 프로그램 상태, 게시 설정, 호스트에서의 접속, 다른 기기에서의 접속 순으로 관찰할 수 있습니다.

호스트에서는 열리지만 다른 기기에서는 열리지 않는다면 두 요청이 같은 주소로 들어오는지 비교합니다. 로컬 전용 주소에 게시한 서비스를 외부에서 접속하려는 상황일 수도 있습니다.

네트워크나 방화벽의 범위를 바꾸기 전에 의도한 이용자가 누구인지 정해야 합니다. 개발 확인용 서비스를 공개하는 변경이 필요한지부터 판단합니다.

포트가 열린다는 사실은 로그인이나 권한 확인이 준비되었다는 의미가 아니므로 서비스의 접근 제어는 따로 확인합니다.

6. 오류 문구를 그대로 남겨 구간을 좁힙니다

접속이 안 된다는 설명에는 이름을 찾지 못한 경우, 연결이 거절된 경우, 기다리다 끝난 경우, HTTP 오류 응답을 받은 경우가 모두 들어갈 수 있습니다. 각 상황은 조사할 시작점이 다릅니다.

가상의 오류 기록에는 요청을 보낸 위치, 주소, 시간, 실제 메시지를 함께 남겨 봅니다. 웹 서버가 오류 페이지를 반환했다면 적어도 어떤 서버와는 HTTP 응답을 주고받았다는 관찰이 생깁니다.

반대로 주소를 해석하지 못했다면 애플리케이션 내부 처리부터 볼 이유는 적습니다. 오류를 임의로 번역해 한 단어로 줄이기보다 원문과 맥락을 보관하는 편이 협업에 유리합니다.

공유할 때는 인증 값이나 개인 정보가 주소에 포함되지 않았는지도 확인합니다.

7. 변경 전후의 경로를 짧게 문서화합니다

접속 문제를 해결한 뒤에는 성공한 명령 하나만 남기지 말고 어떤 관계가 바뀌었는지 적습니다. 예를 들어 호스트 입구를 다른 번호로 옮겼는지, 컨테이너의 수신 포트를 바로잡았는지 구분합니다.

팀원이 같은 이미지를 실행해도 실행 옵션이 다르면 접속 주소는 달라질 수 있습니다. 로컬 개발용 주소와 공동 테스트용 주소를 문서에서 나누어 표시하면 잘못된 복사를 줄일 수 있습니다.

설정 변경으로 공개 범위가 넓어졌다면 그것도 결과에 포함합니다. 마지막으로 새 환경에서 문서만 보고 같은 경로를 설명할 수 있는지 확인합니다.

포트 숫자를 암기하는 것보다 어느 공간에서 어느 프로그램으로 연결되는지 말할 수 있는 상태가 학습 목표입니다. 학습 노트에 두 개의 상자를 그리고 하나는 호스트, 하나는 컨테이너라고 적어 보는 방법도 있습니다.

각 상자 안에 프로그램이 연결을 받는 주소를 쓰고 바깥에서 들어오는 요청의 목적지를 연결합니다. 가상의 8080 입구와 80 수신 위치가 어디에 속하는지 이 그림으로 설명할 수 있으면 설정 문자열도 읽기 쉬워집니다.

다만 이 그림은 개념 정리용이며 모든 Docker 네트워크 모드의 실제 구현을 나타내는 것은 아닙니다. 환경이 바뀌면 적용한 네트워크 모드를 먼저 확인합니다.

팀에 질문할 때는 이 경로 메모와 현재 실행 옵션을 함께 전달하면 같은 숫자를 서로 다른 위치로 이해하는 일을 줄일 수 있습니다. 성공한 접속 시험도 어디서 수행했는지 반드시 남깁니다.

8. 자주 묻는 질문

Q1. 호스트와 컨테이너의 포트 번호는 같아야 하나요?

같을 필요는 없습니다. 호스트의 접속 입구와 컨테이너 내부 프로그램의 수신 위치를 연결하는 설정이 맞는지가 중요합니다.

Q2. EXPOSE를 적었는데 왜 접속되지 않나요?

EXPOSE는 사용 포트를 설명하는 정보이며 그 자체가 호스트 게시를 완료하지는 않습니다. 실제 실행 옵션과 게시 결과를 함께 확인합니다.

Q3. 다른 컨테이너도 localhost로 연결하나요?

일반적으로 분리된 네트워크 공간이라면 자기 자신을 가리키게 됩니다. 네트워크 공유 방식과 서비스 이름 등 해당 구성의 연결 방법을 확인해야 합니다.

Q4. 8080을 바꾸면 연결 문제가 해결되나요?

호스트 포트 충돌이라면 도움이 될 수 있지만 모든 원인에 해당하지는 않습니다. 프로그램 미실행이나 잘못된 수신 주소라면 그 부분을 먼저 바로잡아야 합니다.

참고 자료

• Docker 공식 문서: 포트 게시와 EXPOSE
• Docker 공식 문서: 네트워킹 개요