Доступ к localhost из Docker

Хостовая машина с Docker-контейнером и локальными соединениями

Быстрые ссылки

The Easy Option
Connecting to the Host Network
Accessing the Host With the Default Bridge Mode
Дополнительные советы и отладка

Введение

При работе с Docker вы обычно контейнеризуете сервисы стека и используете сетевые интерфейсы контейнеров для их взаимодействия. Иногда нужно, чтобы контейнер обратился к сервису, запущенному на самой хост-машине (то есть к localhost или 127.0.0.1 хоста). Эта статья описывает доступные методы, их плюсы и минусы, а также практические приёмы для отладки и безопасности.

Important: в тексте под «хостом» понимается физическая или виртуальная машина, на которой запущен Docker Engine или Docker Desktop.

The Easy Option

Docker Desktop (версии 18.03+ для Windows и macOS) поддерживает алиас host.docker.internal, который внутри контейнера резолвится в адрес хоста. Это самый простой способ для локальной разработки.

localhost и 127.0.0.1 внутри контейнера указывают на сам контейнер.
host.docker.internal указывает на внешнюю хост-машину.

Пример: если на хосте запущен MySQL на порту 3306, контейнер может подключиться к

host.docker.internal:3306

На Linux можно добавить похожую запись вручную с помощью флага –add-host при запуске контейнера:

docker run -d --add-host host.docker.internal:host-gateway my-container:latest

Флаг –add-host добавляет строку в /etc/hosts контейнера. Значение host-gateway поддерживается в современных версиях Docker Engine и сопоставляет host.docker.internal с реальным шлюзом хоста. При желании можно использовать своё имя вместо host.docker.internal.

Важно: если вы используете контейнеризованные приложения в продакшене, не полагайтесь на host.docker.internal — это удобный инструмент для локальной разработки.

Подключение через сетевой режим host

Docker поддерживает сетевой режим host, при котором контейнер использует сетевой стек хоста. В этом случае localhost внутри контейнера — это localhost хоста.

Запуск контейнера с сетевым режимом host:

docker run -d --network=host my-container:latest

В Docker Compose для сервиса указывается:

services:
  my-service:
    image: my-container:latest
    network_mode: host

Плюсы:

Контейнер может обращаться к localhost хоста напрямую.
Нулевая дополнительная маршрутизация: чуть меньшая задержка при сетевых вызовах.

Минусы и риски:

Нарушается сетевая изоляция между контейнерами и хостом.
Любые порты контейнера будут доступны на хосте, даже без -p.
Повышается риск конфликтов портов между контейнерами и хостом.
На некоторых платформах (например, Docker Desktop на Mac) поведение может отличаться.

Важно: host mode не поддерживается на Docker Desktop для macOS/Windows так же, как на Linux — проверяйте документацию и поведение вашей платформы.

Доступ к хосту в режиме bridge (по умолчанию)

По умолчанию Docker создает мостовую сеть docker0. Хост часто представлен в этой сети IP-адресом вроде 172.17.0.1. Вы можете определить текущий IP хоста в мостовой сети командой на хосте:

ip addr show docker0

В выводе найдите строку inet — это IP-адрес хоста в сети docker0. Затем из контейнера подключайтесь к этому IP вместо localhost.

Типичный сценарий

Демон MySQL слушает 127.0.0.1 и 127.0.1.1 — контейнер не сможет подключиться к нему по адресу docker0, если сервис привязан только к localhost.
Решение: настроить сервис, чтобы он слушал на 0.0.0.0 (все интерфейсы) или явно на IP docker0.

Ограничения:

Некоторые сервисы по умолчанию слушают только на 127.0.0.1, поэтому их нужно перенастроить.
На системах с несколькими сетевыми интерфейсами IP-адрес docker0 может отличаться.

Проверка соединения и отладка

Команды, которые помогут проверить доступность хоста из контейнера:

Проверка резолвинга и ping (если разрешён):

ping -c 3 host.docker.internal

Проверка порта с помощью curl или netcat:

curl -v http://host.docker.internal:8080/

# или
nc -vz host.docker.internal 3306

Просмотр /etc/hosts внутри контейнера:

docker exec -it  cat /etc/hosts

Узнать IP docker0 на хосте:

ip addr show docker0

Типичные ошибки и причины:

connection refused — сервис не слушает на том интерфейсе.
timeout — сетевой маршрут не доступен или firewall блокирует.
name resolution failure — не добавлен host.docker.internal в /etc/hosts.

Когда это не работает

Counterexamples / когда методы не подходят:

Сервис на хосте строго привязан к 127.0.0.1 и его нельзя изменить — тогда bridge-путь не сработает, а host network может помочь, если платформа его поддерживает.
В средах CI/CD или кластерах Kubernetes host.docker.internal обычно недоступен — следует использовать сервисы внутри сети кластера или каталоги сервисов.
Если контейнер запущен с ограничениями безопасности (например, seccomp/profile), доступ к сетевым ресурсам может быть ограничен.

Альтернативные подходы

Проксирование: поднять прокси внутри контейнера, который пересылает запросы на хост.
sidecar-подход: запустить вспомогательный контейнер в одной сети с основным сервисом и настроить маршрут через него.
Запуск тестовых сервисов прямо в контейнере (меньше зависимости от хоста).

Практическая шпаргалка команд

Запустить контейнер с добавленным хостом:

docker run -d --add-host host.docker.internal:host-gateway --name app my-container:latest

Запустить с сетевым режимом host:

docker run -d --network=host --name app my-container:latest

Docker Compose пример (host mode):

version: '3.8'
services:
  app:
    image: my-container:latest
    network_mode: host

Docker Compose с добавлением host.docker.internal (альтернативно):

version: '3.8'
services:
  app:
    image: my-container:latest
    extra_hosts:
      - "host.docker.internal:host-gateway"

Чек-листы по ролям

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

Убедиться, что используемый адрес — host.docker.internal (Windows/Mac) или IP docker0 (Linux).
Если сервис слушает только на localhost, изменить конфигурацию на 0.0.0.0 или IP docker0.
Добавить проверки в тестах, чтобы эмулировать доступ из контейнера.

DevOps / Системный администратор:

Проверить, что firewall не блокирует связь между контейнерами и хостом.
Настроить docker daemon для поддержки host-gateway, если нужно.
Документировать используемый подход в CI/CD и на серверах сборки.

QA / Тестировщик:

Тестировать поведение при разных сетевых режимах (bridge, host).
Проверять случаи отказа (connection refused, timeout).

Security:

Оценить риски host network и ограничения привилегий контейнера.
По возможности избегать host mode в production.

Критерии приёмки

Контейнер успешно подключается к сервису хоста по выбранному адресу.
Порт на хосте прослушивается и доступен из контейнера.
Отсутствует нежелательная экспозиция портов при использовании host network.
Безопасность: подтверждено, что режим не нарушает политики безопасности организации.

Краткий глоссарий

host.docker.internal — псевдоним, указывающий на хост-машину внутри контейнера (Windows/macOS, возможна настройка на Linux).
docker0 — мостовая сеть Docker по умолчанию на хосте.
host-gateway — специальный маркер в Docker для маппинга на шлюз хоста.

Безопасность и риски

Использование host network снимает сетевую изоляцию — это повышает риски атак и межпакетных конфликтов. Для продакшена предпочитайте изолированные сети и явную настройку маршрутов. При работе в локальной разработке взвесьте удобство против безопасности.

Резюме

Для локальной разработки на Windows и macOS используйте host.docker.internal.
На Linux можно эмулировать поведение через –add-host host.docker.internal:host-gateway или подключиться к IP docker0.
host network позволяет использовать localhost хоста напрямую, но ломает сетевую изоляцию и может создавать риски.
Для минимизации проблем в большинстве случаев используйте bridge mode и настраивайте сервисы так, чтобы они слушали на 0.0.0.0 или на IP docker0.

Важно: выбирайте подход в зависимости от требований к изоляции, безопасности и удобству разработки.