개발자

컨테이너에서 Mac의 localhost에 연결할 수 없음

각 컨테이너에는 자체 네트워크 스택이 있습니다. 컨테이너에서 localhost은 Mac이 아닌 컨테이너 자체를 가리킵니다.

적용 대상: 현재 지원되는 macOS 버전의 Docker Desktop 및 OrbStack.확인일: 2026년 10월 29일

증상

localhost가 컨테이너를 가리킵니다. 컨테이너는 서비스가 수신 대기하지 않는 자체 네트워크 스택에서 서비스를 찾습니다.
호스트 주소가 변경됩니다. Docker 문서에 따르면 호스트 IP 주소는 변경됩니다. 대신 호스트에 사용할 수 있는 특수 이름을 제공합니다.
Mac의 방화벽. macOS 방화벽 또는 다른 방화벽 앱이 서비스로 들어오는 연결을 차단할 수 있습니다.

서비스가 Mac에서 작동하는지 확인하세요. 8000을 사용하는 포트로 바꾸세요.
```
curl http://localhost:8000
```
Mac 서비스가 수신하는 주소를 확인합니다.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
출력 *:8000은(는) 모든 주소를, 127.0.0.1:8000은(는) 루프백 주소만을 뜻합니다.
이미지에 wget이 있으면 컨테이너 내부에서 호스트 이름을 테스트하세요.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

컨테이너에서 localhost 대신 host.docker.internal을 사용하세요. Docker Desktop과 OrbStack은 모두 이 이름을 지원합니다.
앱 구성에서 주소를 설정하세요. 예를 들어 환경 변수에 설정할 수 있습니다.
```
docker run -e API_URL=http://host.docker.internal:8000 my-image
```
OrbStack에서는 대신 호스트 네트워킹을 사용할 수 있습니다. 그러면 컨테이너에서 Mac 서비스에 localhost로 접근할 수 있습니다.
```
docker run --net host my-image
```
그래도 연결되지 않으면 macOS 방화벽 설정을 확인하세요. macOS 방화벽이 들어오는 연결을 차단함을 참조하세요.

Kilobat의 검사는 컨테이너가 아닌 Mac에서 실행됩니다. --context container를 추가하면 컨테이너에서 실행할 명령을 얻을 수 있습니다.
```
kilobat why http://localhost:8000 --context container
```
호스팅된 서비스가 Mac에 요청을 보내는 경우 --context provider를 사용합니다. Kilobat은 localhost가 비공개 주소여서 해당 서비스가 접근할 수 없다고 알려줍니다.
```
kilobat why http://localhost:8000 --context provider
```

host.docker.internal이 Linux에서도 작동하나요?

이 페이지는 Mac을 다룹니다. Mac용 Docker Desktop과 OrbStack에서는 이 이름이 호스트로 확인됩니다.

컨테이너는 연결할 수 없는데 Safari는 서비스에 연결되는 이유는 무엇인가요?

Safari는 Mac에서 실행되므로 localhost는 Mac입니다. 컨테이너에는 자체 localhost가 있습니다.

2026년 10월 29일 확인했습니다.