[docker] 🐳 Docker 컨테이너에서 로컬 데이터베이스가 연결되지 않는 이유 (localhost 이슈)

Docker에서 개발을 하다 보면, 컨테이너에서 로컬에 있는 데이터베이스에 접속하려 할 때 localhost 또는 127.0.0.1을 사용해도 연결이 안 되는 경우가 있다.

초반에 도커를 접하게 되는경우에서는 도커의 개념을 명확하게 인지한 상태가 아니라면 네트워크의 연결 부분에서 문제를 직면하게 되는 경우가 많을텐데 이런경우에 대해서 내가 직면했던 상황과 해결내용을 작성해보았다.

처음 접하는 사람에겐 당황스러울 수 있는 문제인데, 사실 이건 Docker의 네트워크 구조를 이해하면 쉽게 풀 수 있다.

Docker 컨테이너는 기본적으로 호스트와 분리된 독립 네트워크 안에서 동작한다. 그래서 컨테이너 내부에서 localhost를 사용하면 호스트가 아니라 컨테이너 자기 자신을 바라보게 된다. 이게 DB 연결이 안 되는 핵심.
만약, 정말 localhost의 환경을 사용하겠다면 해당 도커컨테이너 내부에 연결을 하고자 하는 DB를 설치 및 작동하면 된다.

⸻

❓ 문제 상황

컨테이너 안에서 DB에 접속할 때 아래처럼 localhost를 쓴다:

DB_HOST=127.0.0.1
또는
DB_HOST=localhost

그런데 DB 연결 오류가 발생한다.

이유는 간단하다.

💥 localhost는 컨테이너 내부를 가리킨다

localhost 또는 127.0.0.1은 항상 자기 자신(=로컬 루프백)을 가리킨다.
Docker 컨테이너 내부에서 이걸 쓰면, 호스트(내 컴퓨터)가 아니라 컨테이너 자체를 바라보게 된다.

즉, 컨테이너 안에 MySQL 같은 DB가 설치되어 있지 않다면, 당연히 접속이 안 된다.

🧠 컨테이너는 호스트와 격리된 네트워크에서 동작한다는 사실을 기억하자.

✅ 해결 방법

1. Mac 또는 Windows (Docker Desktop 사용자)

👉 host.docker.internal 사용

Docker Desktop은 host.docker.internal이라는 특수 DNS를 지원해서
컨테이너에서 호스트 OS로 접속할 수 있게 해준다.

DB_HOST=host.docker.internal

2. Linux 사용자

리눅스에서는 host.docker.internal이 기본적으로 작동하지 않는다.
대신 아래 두 가지 방법을 사용할 수 있다.

👉 A. 호스트 IP 직접 입력하기

ip addr show docker0  # 또는 ifconfig

# 예를 들어 ip주소를 확인했을때 주소가 123.45.6.7가 나온다면
DB_HOST=172.17.0.1

컨테이너는 이 주소를 통해 호스트에 접근할 수 있다.

👉 B. host 네트워크 모드 사용

docker run --network host ...

이렇게 하면 컨테이너가 호스트의 네트워크를 그대로 사용하게 된다.
즉, 127.0.0.1로도 연결이 가능해진다.

⚠️ 하지만 이 방식은 보안 이슈나 포트 충돌 위험이 있으니, 개발환경에서만 사용하는 걸 추천.

✏️ 마무리

Docker를 쓸 때 가장 많이 헷갈리는 포인트 중 하나가 바로 네트워크 분리 구조다.
이 구조를 이해하고 나면, localhost 문제가 왜 생기는지도 명확해진다.

환경에 따라 접근 방법은 달라지니, 본인의 OS에 맞는 방법을 사용하자!