도커 포트 포워딩 기본 가이드 필요합니다.

---

로컬에서 간단한 웹 앱 테스트용으로 도커 컨테이너를 띄우는 작업을 반복 중입니다.
컨테이너 내부에서 서비스가 돌아가긴 하는데, 외부에서 접속하거나 로컬 PC의 다른 서비스와 연동할 때마다 포트 매핑이나 네트워크 설정 부분에서 막힙니다.
이게 처음이라 개념 자체가 어렵게 느껴집니다.

혹시 도커를 처음 접하는 입장에서, 가장 최소한의 기능(예: 웹 서버 띄우고 로컬 브라우저에서 접속)을 구현하기 위한 가장 직관적인 네트워크 연결 방법 같은 게 있을까요?
복잡한 브릿지나 오버레이 같은 건 일단 배제하고, 정말 기본 셋업만 간략하게 설명해주실 분 계실까요?

안녕하세요.
도커 포트 포워딩 때문에 막히셨군요.
저도 처음에 이거 만질 때 정말 헷갈렸던 부분이거든요.
특히 '내부에서 돌아가는 것'이랑 '외부에서 접근하는 것'의 차이를 체감하기 전까지는 포트 개념 자체가 벽처럼 느껴지더라고요.
너무 걱정 마세요.
질문자님이 원하시는 '가장 최소한의 기본 셋업' 위주로 최대한 실전 위주로 설명드릴게요.
복잡한 네트워크 구성은 잠시 잊으셔도 됩니다.
일단 결론부터 말씀드리면, 가장 기본적이고 직관적인 방법은 -p 또는 --publish 옵션을 사용하는 겁니다.
이게 90% 이상의 간단한 테스트 환경에서는 정답이라고 보시면 됩니다.
--- ### 1.
도커 포트 포워딩, 왜 필요한가?
(개념 잡기) 우선 이 개념을 딱 한 문장으로 정리하면 이렇습니다.
'도커 컨테이너'는 격리된 가상 공간이에요.
컨테이너 안에서 웹 서버(예: Nginx, Node.js 등)를 띄웠다고 가정해 봅시다.
이 서버가 아무리 잘 돌아가도, 컨테이너라는 '방' 안에 갇혀 있으면 바깥세상(호스트 PC, 즉 질문자님 컴퓨터)에서는 그 존재 자체를 못 감지해요.
그래서 "이 방의 80번 문(포트)을 열어서, 바깥세상 사람들이 들어올 수 있게 해줘!"라고 명시적으로 알려줘야 하는 과정이 바로 **포트 포워딩(Port Forwarding)**입니다.
쉽게 비유하자면, * 호스트 PC (질문자님 컴퓨터): 아파트 건물 입구.

• 도커 컨테이너: 그 건물 안에 있는 특정 세대.
• 컨테이너 내부 포트 (예: 80): 그 세대 안의 실제 가구 배치 공간 (서비스가 돌아가는 곳).
• 포트 매핑 (-p 아파트 입구에서 특정 호실로 연결되는 '직통 엘리베이터'를 설치하는 행위.
  --- ### ️ 2.
  가장 기본적인 테스트 환경 설정 (실습 위주) 질문자님처럼 웹 앱 테스트용으로 가장 많이 쓰시는 시나리오를 기준으로 설명드릴게요.
  가장 많이 쓰는 명령어는 docker run -d -p [호스트 포트]:[컨테이너 포트] [이미지명] 형태입니다.
  예시 시나리오: * 띄우려는 웹 앱이 내부적으로 3000번 포트에서 서비스한다고 가정합니다.
• 로컬 PC 브라우저에서 http://localhost:8080 으로 접속하고 싶습니다.
  실행 명령어: bash docker run -d --name my-web-test -p 8080:3000 nginx:latest 위 명령어 해석 (이 부분이 핵심입니다): 1.
  docker run -d: 컨테이너를 백그라운드(-d)로 실행해줘.

--name my-web-test: 컨테이너 이름은 my-web-test로 해줘.
(관리 편의용) 3.
-p 8080:3000: 이게 포트 매핑입니다. * 8080 (앞쪽): 호스트 포트 (Host Port).
질문자님 컴퓨터의 포트 번호입니다.
외부에서 접근할 때 사용할 문 번호예요.

• : (콜론): 구분자.
• 3000 (뒤쪽): 컨테이너 포트 (Container Port).
  컨테이너 내부에서 실제로 웹 서버가 듣고 있는 포트 번호입니다.

nginx:latest: 사용할 이미지 이름입니다.
접속 방법: 이렇게 실행했다면, 질문자님의 브라우저에서 http://localhost:8080 으로 접속하면, 도커가 8080 포트로 들어온 트래픽을 받아서 컨테이너 내부의 3000 포트로 쏴주는 역할을 자동으로 수행합니다.
실전 팁 1: 포트 충돌 주의점 만약 로컬 PC의 8080 포트에 이미 다른 프로그램(예: 다른 웹 서버, VS Code의 일부 기능 등)이 사용 중이라면, 도커는 "이미 점유된 포트"라며 오류를 낼 겁니다.
이럴 땐 간단하게 호스트 포트만 바꿔주세요.
예: -p 8081:3000 로 하면, 로컬 브라우저에서 http://localhost:8081 로 접속하면 됩니다.
--- ### 3.
상황별 추가 설명 및 주의사항 질문자님께서 "가장 직관적인 방법"을 원하셨으니, 이 기본 매핑 외에 알아두면 좋을 몇 가지 케이스를 추가로 설명드릴게요.

3.1.

여러 포트를 열어야 할 때 (매핑 여러 개) 만약 하나의 컨테이너가 웹(80)이랑 관리자 API(5000) 두 개를 동시에 열고 있다면, -p 옵션을 여러 번 사용하면 됩니다.
bash docker run -d -p 80:80 -p 5000:5000 my-app-image # 호스트 80 -> 컨테이너 80, 호스트 5000 -> 컨테이너 5000 이때도 원칙은 같습니다.
호스트 포트:컨테이너 포트 순서입니다.

3.2.

컨테이너 내부 포트가 정해져 있지 않을 때 (Docker Compose 사용 시) 만약 docker-compose.yml 파일을 사용하게 되면, 포트 매핑은 ports: 섹션에서 명시합니다.
yaml version: '3.8' services: web: image: my-web-image ports: - "8080:3000" # 호스트:컨테이너 Compose를 쓰면 명령어가 길어지는 것보다 YAML 파일로 관리하는 게 훨씬 체계적이라, 나중에 여러 서비스 연동할 때는 이 방법을 쓰는 게 표준입니다.
하지만 지금은 -p 옵션만 익히셔도 충분해요!

3.3.

권한 문제 (가끔 발생하는 실수) 가끔 포트 80이나 443처럼 낮은 번호의 포트를 매핑하려고 할 때 권한 문제로 실패하는 경우가 있습니다.
이건 운영체제(OS) 레벨의 제약사항이라 도커 자체의 문제가 아닐 때가 많습니다.
팁: 테스트 목적으로는 1024 이상의 높은 포트 번호(예: 8080, 8888 등)를 호스트 포트로 사용하는 게 가장 안전합니다.
--- ### 🧐 4.
종합 정리 및 디버깅 체크리스트 혹시 연결이 안 될 때, 아래 순서대로 점검해보시면 99% 해결됩니다.
Step 1: 컨테이너 내부 확인 (가장 먼저!) * docker logs [컨테이너 이름] 을 실행해서 로그를 확인하세요.

• 혹시 웹 서버가 시작되면서 "Listening on port 3000" 같은 메시지가 나오는지 확인하세요.
• ️ 중요: 서버가 정말 그 포트에서 리스닝 중인지, 아니면 다른 포트로 띄웠는지 확인하는 게 최우선입니다.
  (예: 3000이 아니라 8000으로 띄웠을 수도 있습니다.) Step 2: 도커 포트 확인 * docker ps 를 실행하세요.
• 실행 중인 컨테이너 목록과 함께 PORTS 항목이 정확히 내가 원하는 매핑(0.0.0.0:8080->3000/tcp)으로 찍혀 있는지 확인하세요.
• 만약 매핑이 안 되어 있다면, 컨테이너를 중지하고(docker stop) 포트 옵션만 확인하며 다시 실행(docker run...) 해보세요.
  Step 3: 로컬 방화벽 확인 (흔한 함정) * 만약 위 두 단계가 완벽해도 접속이 안 된다면, **질문자님 PC의 방화벽(Windows Defender 등)**이 도커나 해당 포트를 막고 있을 가능성이 있습니다.
• 이 경우, 해당 포트(예: 8080)에 대한 인바운드(Inbound) 규칙을 임시로 열어줘야 할 수도 있습니다.
  (테스트용이므로 잠시만 열어보세요.) --- 결론적으로, 질문자님이 반복적으로 할 작업이라면, docker run -d -p [로컬 포트]:[내부 포트] [이미지] 이 패턴만 익히시고, 접속할 때는 항상 http://localhost:[로컬 포트] 로 접근하시면 됩니다.
  처음에는 이 '방'과 '직통 엘리베이터' 개념이 헷갈리지만, 몇 번 반복하다 보면 명령어 자체가 손에 익으면서 자연스럽게 이해하게 되실 거예요.
  화이팅입니다!
  궁금한 거 있으면 언제든지 다시 질문 주세요.