---
title: "Docker 컨테이너에서 Mac localhost 서비스에 연결 · Kilobat 가이드"
url: "https://kilobat.app/ko/guides/localhost-from-container"
description: "컨테이너 안에서 localhost는 컨테이너를 뜻합니다. Mac에서 실행 중인 데이터베이스, API 또는 모델 서버에 접근하려면 host.docker.internal을 사용하세요."
---

개발자

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

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

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

## 증상

- 컨테이너의 앱이 `localhost:5432` 또는 유사한 포트에서 “connection refused” 오류를 받습니다.
- 같은 URL이 Mac의 Safari 또는 터미널에서는 작동합니다.
- 개발 컨테이너에서 Mac의 모델 서버나 API에 연결할 수 없습니다.

## 가능한 원인

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

## 확인 방법

1. 서비스가 Mac에서 작동하는지 확인하세요. 8000을 사용하는 포트로 바꾸세요.

   ```
   curl http://localhost:8000
   ```
2. Mac 서비스가 수신하는 주소를 확인합니다.

   ```
   lsof -nP -iTCP:8000 -sTCP:LISTEN
   ```

   출력 `*:8000`은(는) 모든 주소를, `127.0.0.1:8000`은(는) 루프백 주소만을 뜻합니다.
3. 이미지에 wget이 있으면 컨테이너 내부에서 호스트 이름을 테스트하세요.

   ```
   docker exec my-container wget -qO- http://host.docker.internal:8000
   ```

## 해결 방법

1. 컨테이너에서 `localhost` 대신 `host.docker.internal`을 사용하세요. Docker Desktop과 OrbStack은 모두 이 이름을 지원합니다.
2. 앱 구성에서 주소를 설정하세요. 예를 들어 환경 변수에 설정할 수 있습니다.

   ```
   docker run -e API_URL=http://host.docker.internal:8000 my-image
   ```
3. OrbStack에서는 대신 호스트 네트워킹을 사용할 수 있습니다. 그러면 컨테이너에서 Mac 서비스에 `localhost`로 접근할 수 있습니다.

   ```
   docker run --net host my-image
   ```
4. 그래도 연결되지 않으면 macOS 방화벽 설정을 확인하세요. [macOS 방화벽이 들어오는 연결을 차단함](https://kilobat.app/ko/guides/macos-firewall-incoming)을 참조하세요.

## Kilobat 사용

1. Kilobat의 검사는 컨테이너가 아닌 Mac에서 실행됩니다. `--context container`를 추가하면 컨테이너에서 실행할 명령을 얻을 수 있습니다.

   ```
   kilobat why http://localhost:8000 --context container
   ```
2. 호스팅된 서비스가 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가 있습니다.

## 출처

- [Docker 문서: Docker Desktop의 네트워킹 방법 살펴보기](https://docs.docker.com/desktop/features/networking/networking-how-tos/)
- [OrbStack 문서: 컨테이너 네트워킹](https://docs.orbstack.dev/docker/network)
- [OrbStack 문서: 호스트 네트워킹](https://docs.orbstack.dev/docker/host-networking)
- lsof(8), macOS 27.2와 함께 설치된 매뉴얼 페이지

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

## 관련 가이드

- [Mac에서 Docker 컨테이너에 연결할 수 없음](https://kilobat.app/ko/guides/docker-container-from-mac): Mac의 Docker는 Linux 가상 머신에서 컨테이너를 실행합니다.
- [macOS 방화벽이 들어오는 연결을 차단합니다](https://kilobat.app/ko/guides/macos-firewall-incoming): macOS 방화벽은 다른 컴퓨터가 Mac으로 시작하는 연결을 제어합니다.
- [한 사이트 또는 API에 연결되지 않는 이유 찾기](https://kilobat.app/ko/guides/recipes/why-cant-it-connect): 인터넷은 작동하지만 한 주소에 연결할 수 없을 때 Kilobat이 각 계층을 차례로 확인합니다.
- [Mac에서 포트가 이미 사용 중인 경우](https://kilobat.app/ko/guides/port-already-in-use): 한 TCP 포트와 주소에서는 하나의 프로세스만 수신 대기할 수 있습니다.