Сеть контейнеров: bridge, DNS по имени и ловушка localhost

За десять минут ты поймёшь, почему localhost врёт внутри контейнера, какой драйвер выбрать и как связать сервисы так, чтобы они не теряли друг друга после рестарта.

Драйверы: как контейнер вообще получает сеть

Контейнер стартует в своём network namespace — со своими интерфейсами, таблицей маршрутизации и localhost. Сетевой драйвер решает, как этот namespace соединяется со всем остальным. Драйвер ты выбираешь, создавая network или запуская контейнер.

Драйвер bridge — это умолчание. Docker создаёт на хосте приватный виртуальный коммутатор (docker0 для дефолтной сети) и подключает к нему каждый контейнер виртуальной ethernet-парой. Контейнеры получают внутренние IP в приватной подсети (часто 172.17.0.0/16), общаются друг с другом через этот bridge и достигают внешнего мира через NAT — хост маскирует их трафик за своим IP. Снаружи хоста эти IP контейнеров невидимы, пока ты не опубликуешь порт.

Драйвер host убирает изоляцию полностью: контейнер делит network namespace хоста. Нет отдельного IP контейнера, нет NAT и нет проброса портов — если приложение биндится на :8080, оно на :8080 хоста напрямую. Это самый быстрый вариант (нет bridge, нет хопа через NAT) и причина использовать его для чувствительных к задержке или высоконагруженных ворклоадов, но ты теряешь изоляцию и не можешь запустить два контейнера, которым нужен один порт.

Драйвер none даёт контейнеру namespace только с loopback — вообще без внешней связности, для полностью изолированной работы. overlay охватывает несколько хостов (сервисы Swarm, мультихостовые кластеры), туннелируя трафик контейнеров между демонами. macvlan выдаёт контейнеру собственный MAC-адрес, так что он выглядит физическим устройством в LAN, — для легаси-систем, которые этого ждут. Повседневная рабочая лошадка — bridge; остальное ситуативно.

docker run -d --name web nginx                 # дефолтный bridge
docker run -d --network host nginx             # делит стек хоста, -p не нужен
docker run -d --network none alpine sleep 1d   # только loopback, изолирован
docker network ls                              # bridge, host, none + созданные тобой

Дефолтный bridge против пользовательского bridge

Вот ключевой сеньорский момент, на котором держится хук. Существуют два вида bridge-сети, и они не равнозначны.

Дефолтный bridge (тот, что зовётся bridge, к которому подключается каждый контейнер, если не сказано иное) не имеет встроенного DNS. Контейнеры на нём достают друг друга только по сырому IP-адресу — что хрупко, потому что IP назначаются динамически и меняются между перезапусками. Старым обходом был устаревший флаг --link.

Пользовательский bridge — любая сеть, которую ты создаёшь сам — добавляет встроенный DNS-сервер. Контейнеры на нём резолвят друг друга по имени контейнера автоматически. Запусти db и api в одной пользовательской network — и api сможет подключиться к db:5432 без IP, без link, без конфига. Это service discovery, и это единственная причина всегда помещать связанные контейнеры в созданную тобой network, а не в дефолтный bridge.

docker network create appnet                              # пользовательский bridge
docker run -d --name db  --network appnet postgres:16
docker run -d --name api --network appnet my/api          # api достаёт db по имени "db"

Именно это делает за тебя docker compose: каждый проект Compose получает собственный пользовательский bridge, так что сервисы достают друг друга по имени сервиса из коробки. Руками network ты создаёшь редко, потому что Compose уже это сделал.

Публикация портов против общения внутри сети

Два контейнера в одной пользовательской network общаются напрямую на собственном порту контейнера — api бьёт в db:5432 независимо от того, опубликован ли 5432. Публикация — только про доступ к контейнеру снаружи Docker-сети, обычно с хоста или из интернета.

-p host:container (--publish) маппит порт хоста на порт контейнера через NAT bridge’а. -p 8080:80 значит «отправь хостовый :8080 в этот контейнерный :80». Ты публикуешь сервис, обращённый наружу (веб-сервер, API-шлюз), а внутренние сервисы вроде базы оставляешь без публикации — им не нужен хостовый порт, потому что их клиенты в той же network.

Частая путаница: EXPOSE в Dockerfile ничего не публикует. Это документация — метаданные, объявляющие, какой порт слушает приложение. Он не открывает ни одного хостового порта и не меняет файрвол. Только -p (или ports: в Compose) реально публикует; EXPOSE лишь сообщает читателям и инструментам намерение.

docker run -d --network appnet -p 8080:80 --name web my/web   # host:8080 → container:80
# у db НЕТ -p: с хоста недоступен, но web достаёт его на db:5432 внутри

Ловушка localhost

Теперь хук разрешается. Внутри контейнера localhost (127.0.0.1) — это собственный loopback контейнера, не хост и не какой-либо другой контейнер. У каждого контейнера свой loopback-интерфейс в своём namespace. Поэтому api, подключаясь к localhost:5432, спрашивает Postgres у самого себя, ничего слушающего не находит и получает ECONNREFUSED.

Фиксы следуют из всего сказанного выше:

• Чтобы достать другой контейнер, используй его имя в общей пользовательской network: db:5432. Никогда localhost, никогда захардкоженный IP.
• Чтобы достать сервис на самой хост-машине изнутри контейнера (например, базу, запущенную нативно на твоём ноутбуке), используй host.docker.internal — специальное DNS-имя, которое Docker резолвит в IP хост-машины. (host-сеть — другой путь: тогда localhost и есть хост, потому что отдельного namespace нет.) (host-сеть — другой путь: тогда localhost и есть хост, потому что отдельного namespace нет.)
• Чтобы достать контейнер с хоста, опубликуй порт через -p и подключайся к localhost:<hostPort> на хосте.

Вместе эти три правила означают одно: localhost — только «этот же контейнер», и без явного имени первый же рестарт в проде тихо ломает связку. В тот миг, когда ты пересекаешь границу контейнера, тебе нужно имя — db, api или host.docker.internal.