Разработчикам

Контейнер не может подключиться к localhost на Mac

У каждого контейнера свой сетевой стек. В контейнере localhost — это сам контейнер, а не Mac.

Относится к: Docker Desktop и OrbStack в актуальных версиях macOS.Проверено: 29 октября 2026 г.

Симптомы

Приложение в контейнере получает ошибку «connection refused» на localhost:5432 или похожем порту.
Тот же URL открывается в Safari или Терминале на Mac.
Сервер модели или API на Mac недоступен из dev-контейнера.

localhost указывает на контейнер. Контейнер ищет сервис в собственном сетевом стеке, а там никто не слушает порт.
Адрес хоста меняется. В документации Docker сказано, что IP-адрес хоста меняется, и вместо него предлагается специальное имя хоста.
Брандмауэр на Mac. Брандмауэр macOS или другое приложение-брандмауэр может блокировать входящие подключения к сервису.

Убедитесь, что сервис работает на Mac. Замените 8000 на свой порт.
```
curl http://localhost:8000
```
Посмотрите, на каком адресе слушает сервис на Mac.
```
lsof -nP -iTCP:8000 -sTCP:LISTEN
```
Вывод *:8000 — все адреса. 127.0.0.1:8000 — только петлевой адрес (loopback).
Проверьте имя хоста изнутри контейнера, если в образе есть wget.
```
docker exec my-container wget -qO- http://host.docker.internal:8000
```

В контейнере используйте host.docker.internal вместо localhost. Это имя поддерживают и 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. В Docker Desktop для Mac и в OrbStack это имя указывает на хост.

Почему Safari видит сервис, а контейнер — нет?

Safari работает на Mac, поэтому localhost для него — это Mac. У контейнера свой localhost.

Источники проверены 29 октября 2026 г. Man-страницы — те, что установлены вместе с macOS; откройте любую командой man <name> в Терминале.