Docker에서 docker ps로 확인했을 때 컨테이너 상태는 **Up(Running)**인데,
외부(브라우저, curl)에서 서비스 접속이 안 되는 경우가 있다.

이 문제는 컨테이너가 “죽었는지”의 문제가 아니라,
대부분 네트워크 리스닝 구조 또는 포트 매핑 설정 문제다.

---

증상 (The Phantom Service) #

docker ps

CONTAINER ID   IMAGE     STATUS         PORTS
abcd1234       my-app    Up 10 minutes  0.0.0.0:8080->8080/tcp

현상

• 컨테이너는 정상 실행 중 (Up)
• 포트도 정상적으로 바인딩된 것처럼 보임

문제

• curl localhost:8080 또는 브라우저 접속 시
  Connection refused / 무한 로딩 발생

---

원인 1: Localhost(127.0.0.1) 바인딩 (가장 흔함) #

이 케이스가 **전체의 80~90%**다.

컨테이너 내부 애플리케이션이 127.0.0.1로만 리스닝하고 있으면,
외부(호스트)에서는 절대 접근할 수 없다.
컨테이너의 localhost는 컨테이너 자신일 뿐이다.

확인 방법 (컨테이너 내부) #

docker exec -it <container_name> ss -nltp
# 또는 netstat -nltp

LISTEN 0 128 127.0.0.1:8080   <-- 문제 확정 (외부 접속 불가)
LISTEN 0 128 0.0.0.0:8080     <-- 정상 (외부 접속 가능)

참고
Alpine / Distroless 이미지처럼 ss, netstat, curl조차 없는 경우도 많다.
이 경우에는 애플리케이션 시작 로그나
application.yml, nginx.conf 등 설정 파일에서 바인딩 주소를 직접 확인해야 한다.

해결책 #

애플리케이션 리스닝 주소를 변경한다.

• 변경 전: 127.0.0.1, localhost
• 변경 후: 0.0.0.0 (또는 ::)

---

원인 2: 포트 불일치 (Port Mismatch) #

Docker 포트 노출(-p)과 실제 애플리케이션 포트가 다른 경우다.

흔한 실수 #

docker run -p 8080:8080 my-app

Docker는 컨테이너의 8080으로 트래픽을 보낸다.
하지만 실제 앱은 3000번 포트에서 리스닝 중이라면?

확인 및 해결 #

docker exec -it <container> ss -nltp

LISTEN 0 128 0.0.0.0:3000

# 포트 매핑 수정 후 재실행
docker run -p 8080:3000 my-app

---

원인 3: 내부 접속은 되는데 외부만 안 됨 #

컨테이너 내부에서는 접속되는데,
호스트나 외부에서는 접속이 안 된다면 네트워크 문제다.

내부 테스트 #

docker exec -it <container> curl localhost:8080

• 성공 → 애플리케이션 정상, 네트워크/방화벽 문제
• 실패 → 애플리케이션 자체가 비정상 또는 Hang 상태

체크 포인트 #

• 호스트 방화벽 (ufw, firewalld)
• 클라우드 환경 보안 그룹 (AWS SG 등)
• 특정 사설 IP로만 바인딩되어 있는지 여부

---

원인 4: Docker 네트워크 설정 문제 #

커스텀 네트워크(User-defined bridge)를 사용하는 경우,
외부 접근이 의도적으로 차단된 구조일 수 있다.

확인 #

docker inspect <container> | grep -i network

• bridge vs user-defined network 확인
• 외부 노출이 필요한 컨테이너인지 점검

---

로그에서 반드시 확인할 패턴 #

docker logs <container>

자주 나오는 결정적 로그:

• Listening on 127.0.0.1
  → 원인 1번 확정
• Bind failed: Address already in use
  → 포트 충돌, 앱 자체 미기동
• 서비스 시작 로그 자체가 없음
  → 초기화 중 Hang / 크래시

Tip.
이런 상황을 빠르게 식별하려면
Dockerfile 또는 docker-compose에 HEALTHCHECK를 설정하는 것이 좋다.
접속 불가 시 Up (unhealthy)로 표시되어 문제 인지가 훨씬 빠르다.

---

핵심 요약 #

• Running은 프로세스 생존 상태일 뿐, 서비스 가용성을 의미하지 않는다
• 가장 먼저 확인할 것:
  1. 리스닝 주소 (127.0.0.1 vs 0.0.0.0)
  2. 포트 매핑과 실제 앱 포트 일치 여부
• 경량 이미지에서는 명령어보다 로그와 설정 파일이 더 중요하다

이 순서대로 보면,
Docker “Running인데 접속 안 됨” 문제는 대부분 10분 안에 끝난다.

🛠 마지막 수정일: 2025.12.23