Проектирование и развертывание тестовых стендов с помощью Docker и Docker Compose

Основы Docker и архитектура локального тестового стенда

Разработка новой функции заняла два часа, а попытка запустить проект локально, чтобы её протестировать — половину рабочего дня. Сначала выяснилось, что на машине установлена не та версия Node.js. Затем локальный сервер баз данных отказался принимать подключения из-за забытого пароля. Когда базу удалось поднять, оказалось, что бэкенд ищет кэш в Redis, которого на компьютере вообще нет. Эта ситуация — классический симптом отсутствия стандартизированного локального тестового стенда. Умение запустить один готовый образ через терминал решает проблему изоляции одного приложения, но современные проекты редко состоят из одного компонента.

Переход от использования одиночных контейнеров к проектированию полноценных сред требует смены парадигмы. Мы перестаем мыслить категориями «как запустить этот скрипт» и начинаем мыслить категориями «как описать инфраструктуру, в которой этот скрипт будет жить, общаться с соседями и сохранять данные».

От изолированных контейнеров к системной архитектуре

Базовый навык работы с Docker обычно ограничивается императивными командами: загрузить образ, пробросить порт, запустить процесс. Это отлично работает для утилит или разовых задач. Но тестовый стенд — это не просто набор запущенных программ. Это точная, масштабируемая и, главное, воспроизводимая копия боевой среды (production) или её логически завершенной части, развернутая на локальной машине разработчика.

Архитектура классического веб-проекта включает минимум три слоя:

!Схема архитектуры локального тестового стенда

В контексте локального стенда эти компоненты должны не просто работать одновременно. Они обязаны находиться в едином изолированном пространстве имен, иметь возможность обращаться друг к другу по понятным именам (а не по динамически меняющимся IP-адресам) и быть защищенными от влияния процессов хост-машины.

Стенд выступает абстракцией над операционной системой разработчика. Независимо от того, использует ли инженер macOS, Windows или Linux, внутри стенда Backend всегда найдет базу данных по адресу db:5432, а Frontend сможет отправить запрос к API, не задумываясь о том, какие еще проекты сейчас запущены на ноутбуке.

Проблема императивного подхода

Чтобы осознать ценность инструментов оркестрации, необходимо посмотреть на процесс ручного создания многокомпонентной среды. Представим, что мы хотим развернуть описанную выше трехзвенную архитектуру, используя только базовый CLI Docker.

Сначала потребуется создать изолированную сеть, чтобы контейнеры могли общаться: docker network create ecom_test_network

Затем нужно запустить базу данных, подключив её к этой сети и передав переменные окружения для инициализации: docker run -d --name ecom_db --network ecom_test_network -e POSTGRES_USER=admin -e POSTGRES_PASSWORD=secret postgres:15

После этого запускается бэкенд. Ему нужно передать строку подключения к базе, пробросить порты наружу для отладки и также подключить к сети: docker run -d --name ecom_backend --network ecom_test_network -p 8080:8080 -e DB_HOST=ecom_db -e DB_PASS=secret my_backend_image:latest

И, наконец, фронтенд: docker run -d --name ecom_frontend --network ecom_test_network -p 3000:80 my_frontend_image:latest

Этот императивный подход (последовательность команд «сделай это, затем сделай то») обладает критическими недостатками при проектировании стендов:

Для решения этих проблем архитектура стенда должна описываться декларативно. Инженер должен зафиксировать желаемое конечное состояние системы («мне нужны три сервиса, связанные такой-то сетью»), а инструмент оркестрации (Docker Compose) возьмет на себя вычисление разницы между текущим состоянием и желаемым, самостоятельно выполнив нужные API-вызовы к демону Docker.

Жизненный цикл стенда и управление состоянием

Один из главных принципов Docker — эфемерность (ephemerality) контейнеров. Контейнер должен быть готов к уничтожению и пересозданию в любой момент. В контексте тестового стенда это свойство является одновременно и главным преимуществом, и главным вызовом.

Преимущество заключается в том, что мы можем мгновенно сбросить состояние системы. Если в процессе тестирования данные были повреждены или база заполнена мусором, достаточно пересоздать контейнеры — и через несколько секунд у нас снова кристально чистая среда.

Вызов же состоит в том, что некоторые данные мы хотим сохранять между перезапусками стенда. Например, разработчик наполнил локальную базу тестовыми товарами и хочет, чтобы они остались доступны завтра, после перезагрузки компьютера. Для управления состоянием в архитектуре стенда применяются два механизма монтирования:

Грамотная архитектура стенда четко разделяет: код приложения пробрасывается через bind mounts для удобства разработки, а данные инфраструктурных сервисов сохраняются в named volumes для надежности.

Оркестрация запуска и разрешение зависимостей

Многоконтейнерная система — это не просто набор независимых процессов. Между ними существуют строгие временные и логические зависимости.

Если в нашем стенде бэкенд запустится на долю секунды раньше, чем база данных будет готова принимать подключения, приложение упадет с ошибкой Connection refused. Простого указания порядка старта недостаточно: процесс PostgreSQL внутри контейнера может запуститься быстро, но ему потребуется еще несколько секунд на инициализацию системных таблиц и применение стартовых скриптов.

!Пошаговый запуск зависимых сервисов тестового стенда

Архитектура надежного стенда учитывает разницу между состоянием «контейнер запущен» и «сервис готов к работе». Для этого внедряются механизмы проверок работоспособности (healthchecks).

Вместо того чтобы надеяться на удачные тайминги, система проектируется так:

Такой подход гарантирует, что стенд поднимется корректно на любой машине, независимо от мощности процессора и скорости работы диска. Слабый ноутбук просто будет дольше выполнять инициализацию базы, но бэкенд гарантированно дождется её завершения.

Сценарии использования: зачем нам воспроизводимость

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

Изоляция Feature-веток. Представим, что разработчик переключается между двумя ветками в Git. В ветке feature-A добавлена новая таблица в базу данных, а в ветке feature-B используется старая схема. Если разработчик использует локально установленную базу данных, переключение веток превращается в кошмар с ручным откатом миграций. При использовании Docker-стенда каждая ветка может поднимать свою собственную, полностью изолированную копию базы данных со своим набором данных. Переключение контекста происходит моментально.

Интеграционное тестирование. Стенд, описанный декларативно, может быть запущен не только на ноутбуке разработчика, но и на сервере непрерывной интеграции (CI). Когда код отправляется в репозиторий, CI-сервер поднимает точно такой же стенд, прогоняет по нему автоматические тесты и затем уничтожает его. Поскольку архитектура среды идентична локальной, ситуация «тесты падают в CI, но проходят локально» практически исключается.

Безопасные эксперименты с инфраструктурой. Разработчику нужно проверить, как поведет себя приложение, если обновить версию базы данных с 13 до 15. В традиционной среде это рискованная операция, требующая резервного копирования. В архитектуре Docker-стенда достаточно изменить одну цифру в конфигурации (версию образа), перезапустить стенд и провести тесты. Если что-то пошло не так — изменение откатывается за секунды.

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

Анатомия Dockerfile: создание кастомных образов для Frontend и Backend

Если взять исходный код приложения размером в 50 килобайт и написать для него наивный, линейный скрипт сборки контейнера, на выходе можно получить образ весом в 1.5 гигабайта, который будет собираться по десять минут при каждом изменении одной строчки кода. Разница между тяжеловесным, медленным монолитом и молниеносно собирающимся микросервисом кроется не в самом коде, а в понимании того, как Docker читает, кэширует и исполняет инструкции.

Слоистая архитектура и механизм кэширования

Docker-образ не является монолитным файлом. Это стопка доступных только для чтения слоев (layers), наложенных друг на друга. Каждый слой представляет собой дельту — набор изменений файловой системы, произошедших в результате выполнения одной инструкции в Dockerfile.

Ключевые инструкции, создающие новые слои — это RUN, COPY и ADD. Остальные инструкции (например, ENV, EXPOSE, WORKDIR) создают промежуточные метаданные и практически не увеличивают физический размер образа, но влияют на его конфигурацию.

При выполнении команды docker build демон Docker анализирует каждую инструкцию и проверяет, есть ли уже в локальном кэше точно такой же слой, созданный ранее. Для инструкций RUN проверяется совпадение самой текстовой команды. Для COPY и ADD дополнительно вычисляются контрольные суммы копируемых файлов.

Если Docker находит совпадение, он использует слой из кэша (вывод CACHED в логах сборки). Но как только контрольная сумма файла изменилась или команда была модифицирована, кэш инвалидируется.

!Структура слоев Docker-образа и механизм инвалидации кэша

Главное правило слоистой архитектуры: инвалидация кэша на любом слое автоматически уничтожает кэш для всех последующих слоев. Если вы изменили базовый образ в первой строке или скопировали изменившийся файл во второй, все инструкции ниже будут выполняться с нуля, даже если они сами по себе не менялись. Именно это правило диктует порядок написания инструкций: от самых редко изменяемых к самым часто изменяемым.

Контекст сборки и невидимый враг производительности

Процесс сборки начинается с того, что Docker CLI упаковывает текущую директорию (build context) и отправляет ее демону Docker. Демон может находиться на той же машине, а может быть удаленным сервером.

Если в корне проекта лежит папка node_modules весом 800 МБ или скрытая директория .git с историей коммитов на 2 ГБ, CLI послушно запакует их и отправит демону, прежде чем выполнит первую строчку Dockerfile. Это приводит к зависанию сборки на этапе Sending build context to Docker daemon.

Для решения этой проблемы используется файл .dockerignore. Его синтаксис идентичен .gitignore, но цель иная: он указывает демону, какие файлы и директории вообще не должны попасть в контекст сборки.

!Процесс отправки контекста сборки и фильтрация файлов

Правильно настроенный .dockerignore выполняет три функции:

Базовый .dockerignore для любого веб-проекта должен включать:

Проектирование Backend-образа: управление зависимостями

Рассмотрим процесс создания Dockerfile для типичного Backend-сервиса на Node.js (Express). Наша задача — написать инструкции так, чтобы изменение бизнес-логики (файлов с кодом) не приводило к переустановке всех библиотек.

Разберем критические узлы этой конфигурации:

Выбор базового образа (FROM). Использование node:20-alpine вместо стандартного node:20 кардинально снижает размер образа (в среднем с 1 ГБ до 150 МБ). Alpine Linux — это минималистичный дистрибутив, использующий musl libc вместо glibc. Меньше размер — быстрее скачивание образа из реестра и меньше поверхность для потенциальных уязвимостей (attack surface).

Рабочая директория (WORKDIR). Инструкция WORKDIR /app не просто создает папку /app, но и делает ее текущей для всех последующих инструкций RUN, COPY, CMD. Использование RUN mkdir /app && cd /app является антипаттерном, так как каждая инструкция RUN запускается в новом изолированном shell-окружении. Смена директории через cd в одном RUN не сохранится для следующего.

Раздельное копирование (COPY). Это классический паттерн оптимизации. Сначала мы копируем только package.json и package-lock.json (шаг 3), а затем устанавливаем зависимости (шаг 4). Исходный код мы копируем только на пятом шаге. Если разработчик изменит контроллер в src/index.js, слои 1-4 возьмутся из кэша, потому что package.json не изменился. Сборка займет доли секунды. Если бы мы написали COPY . . до RUN npm ci, любое изменение в коде инвалидировало бы кэш, заставляя Docker заново скачивать сотни мегабайт пакетов из интернета.

Строгая установка (RUN npm ci). В отличие от npm install, команда npm ci (clean install) строго следует версиям, зафиксированным в package-lock.json, и не обновляет их в процессе установки. Это гарантирует абсолютную воспроизводимость тестового стенда: образ, собранный сегодня, будет иметь те же версии транзитивных зависимостей, что и образ, собранный через месяц.

Проектирование Frontend-образа: раздача статики

Frontend-приложения (React, Vue, Angular) в скомпилированном виде представляют собой набор статических файлов: HTML, CSS и минифицированный JavaScript. Им не нужна среда выполнения Node.js в production-контейнере. Для их раздачи используется легковесный веб-сервер, например, Nginx.

На данном этапе мы предполагаем, что сборка статики (npm run build) производится на хост-машине, а Docker лишь упаковывает готовый результат. Перенос самого процесса компиляции внутрь Docker требует механизма многоэтапных сборок (multi-stage builds), который мы подробно разберем в следующих главах.

Директория /usr/share/nginx/html — это стандартный путь, откуда Nginx отдает статические файлы. Инструкция EXPOSE 80 не публикует порт на хост-машину автоматически. Это декларация намерений, документация для разработчика и для оркестратора (Docker Compose), сообщающая, что процесс внутри контейнера прослушивает 80-й порт. Фактический проброс портов (publish) настраивается при запуске контейнера.

Флаг daemon off; в инструкции CMD критически важен. По умолчанию Nginx запускается как фоновый процесс (демон). Если главный процесс, запущенный инструкцией CMD, завершается или уходит в фон, Docker считает, что контейнер выполнил свою работу, и останавливает его. Указание daemon off; заставляет Nginx работать на переднем плане (foreground), удерживая контейнер в активном состоянии.

Разграничение CMD и ENTRYPOINT

В обоих примерах мы использовали CMD для запуска процесса. Однако в Dockerfile есть родственная инструкция ENTRYPOINT. Их часто путают, что приводит к непредсказуемому поведению контейнеров при передаче аргументов из командной строки.

Обе инструкции определяют, что произойдет при старте контейнера, но работают по-разному при попытке переопределить их через docker run <image> <аргументы>.

| Инструкция | Назначение | Поведение при передаче аргументов в docker run | | :--- | :--- | :--- | | CMD | Задает команду и аргументы по умолчанию. | Аргументы из CLI полностью заменяют значение CMD. | | ENTRYPOINT | Задает неизменяемый исполняемый файл контейнера. | Аргументы из CLI добавляются в конец к ENTRYPOINT. |

Рассмотрим пример образа утилиты для пинга:

Если запустить этот образ без аргументов (docker run my-ping), Docker объединит инструкции и выполнит ping localhost. Если пользователь передаст аргумент (docker run my-ping google.com), переданная строка заменит CMD, но ENTRYPOINT останется неизменным. Итоговой командой станет ping google.com. Контейнер начинает вести себя как полноценная CLI-утилита.

Для Backend и Frontend сервисов в тестовом стенде обычно достаточно использовать CMD, так как мы редко передаем им динамические аргументы при запуске. ENTRYPOINT чаще применяется в инфраструктурных контейнерах (например, скрипты инициализации баз данных), где контейнер должен жестко выполнять одну программу, принимая лишь конфигурационные флаги.

Создание правильных Dockerfile для каждого компонента системы — это фундамент. Мы получили неизменяемые, оптимизированные артефакты — образы Frontend и Backend. Однако сами по себе они изолированы. Чтобы Frontend смог отправлять API-запросы к Backend, а Backend — записывать данные в базу, их необходимо объединить в единую топологию. Именно эту задачу решает декларативное описание инфраструктуры через оркестратор.

Синтаксис и структура Docker Compose для декларативного описания сервисов

Запуск одного контейнера с базой данных через интерфейс командной строки требует передачи десятка флагов: проброс портов, монтирование томов, задание паролей через переменные окружения, указание сети. Команда docker run быстро разрастается до трехсот символов. Ошибка в одном символе приводит к падению контейнера. Когда тестовый стенд состоит из Frontend-приложения, Backend-API и СУБД, ручной запуск превращается в хрупкий процесс, зависящий от человеческого фактора. Docker Compose решает эту проблему, переводя инфраструктуру из императивных команд в декларативный текстовый файл, который становится единым источником истины для всего проекта.

От CLI к YAML: анатомия конфигурации

Основой декларативного подхода выступает файл docker-compose.yml. Он пишется на языке разметки YAML, где структура и вложенность определяются отступами (строго пробелами, обычно по два на каждый уровень).

Корневым элементом любого тестового стенда является блок services. В терминологии Compose «сервис» — это абстракция над одним или несколькими идентичными контейнерами. Каждый ключ внутри блока services задает имя сервиса, которое в дальнейшем будет использоваться как сетевое имя хоста (DNS) для связи контейнеров друг с другом.

Любой флаг, который передается в команду docker run, имеет свой строгий эквивалент в синтаксисе Compose.

!Маппинг флагов Docker CLI в синтаксис Docker Compose

Вместо того чтобы держать в памяти порядок запуска и набор флагов, инженер описывает желаемое состояние. Если необходимо изменить порт, редактируется одна строка в файле, после чего Compose сам вычисляет дельту изменений и пересоздает только затронутый контейнер.

Описание сервисов: сборка и готовые образы

При формировании тестового стенда компоненты делятся на два типа: внешние зависимости (базы данных, брокеры сообщений, кэши), которые берутся в готовом виде из реестра, и собственные приложения (Frontend, Backend), которые необходимо собирать из исходного кода.

Для запуска готового образа используется директива image. Она указывает демону Docker, какой репозиторий и тег необходимо скачать.

Для собственных приложений, чьи Dockerfile мы подготавливали ранее, применяется блок build. Он указывает Compose, что перед запуском контейнера необходимо инициировать процесс сборки. Блок build требует указания контекста сборки — директории, файлы которой будут отправлены демону Docker.

Директивы image и build могут работать совместно. Если указать их обе в одном сервисе, Compose соберет образ по инструкциям из build, но присвоит результату сборки имя и тег, указанные в image. Это полезно для кэширования локальных сборок и их последующей отправки в удаленный реестр без дополнительных команд тегирования.

Проброс конфигурации и данных

Поведение контейнеров настраивается через переменные окружения. В Compose за это отвечает блок environment. Синтаксис поддерживает два формата: словарь (пары ключ-значение через двоеточие) и список (строки с символом равенства).

Формат словаря предпочтительнее, так как он позволяет передавать булевы значения и числа без риска их неверной интерпретации парсером YAML:

Если переменных много, их выносят в отдельный файл (обычно .env), который подключается через директиву env_file. Это изолирует секреты от логики развертывания и предотвращает случайный коммит паролей в систему контроля версий.

Для управления состоянием используется блок volumes. Синтаксис внутри сервиса выглядит как строка источник:цель. Если источником выступает абсолютный или относительный путь на хост-машине (./src:/app/src), Compose создает Bind Mount. Это критически важно для Frontend и Backend в режиме разработки: изменения в коде на хосте мгновенно отражаются внутри контейнера, позволяя работать механизмам hot-reload.

Если источником выступает произвольное имя (pg_data:/var/lib/postgresql/data), Compose использует Named Volume. Однако, в отличие от Bind Mount, именованные тома требуют явного объявления в корне файла docker-compose.yml, на одном уровне с services.

Управление порядком запуска и Healthchecks

В многослойной архитектуре порядок старта компонентов имеет решающее значение. Backend-приложение не сможет успешно инициализировать пул подключений, если база данных еще не готова принимать запросы.

Базовая директива depends_on устанавливает порядок запуска. Если сервис backend зависит от сервиса database, Compose сначала отправит команду на старт контейнера с БД, и только потом — контейнера с API.

Однако стандартный depends_on таит в себе ловушку. Он считает зависимость выполненной в момент, когда процесс внутри контейнера-зависимости просто запустился. Базе данных PostgreSQL требуется несколько секунд на выделение памяти, проверку файлов и открытие порта. Backend стартует за миллисекунды, пытается подключиться к еще инициализирующейся БД, получает отказ соединения и падает с ошибкой (классический race condition).

Для решения этой проблемы декларативный синтаксис расширяется механизмом проверок работоспособности — healthcheck. Эта директива описывает команду, которую Docker будет периодически выполнять внутри контейнера, чтобы понять, готов ли сервис к реальной работе.

В этом примере используется встроенная утилита pg_isready. Docker будет вызывать ее каждые 5 секунд. Если команда вернет нулевой код выхода (успех), контейнер получит статус healthy.

Теперь директиву depends_on в зависимом сервисе необходимо перевести в расширенный формат, указав условие condition: service_healthy:

!Разрешение зависимостей при старте тестового стенда

При такой конфигурации Compose запустит базу данных, поставит запуск бэкенда на паузу и будет ждать, пока healthcheck базы данных не завершится успехом. Только после получения статуса healthy начнется сборка и запуск API.

Сетевой доступ: Ports против Expose

Для доступа к стенду с хост-машины (например, чтобы открыть Frontend в браузере) необходимо пробросить порты. Блок ports принимает массив строк в формате порт_хоста:порт_контейнера.

Строка "3000:80" означает, что трафик, поступающий на 3000 порт компьютера разработчика, будет перенаправлен на 80 порт внутри контейнера frontend. Кавычки здесь обязательны: без них YAML-парсер может интерпретировать значения вроде 60:60 как время в шестнадцатеричном формате, что приведет к непредсказуемому поведению.

Важно различать директиву ports в Compose и инструкцию EXPOSE в Dockerfile. ports физически открывает сокет на хост-машине и маршрутизирует трафик. EXPOSE (или аналогичная директива expose в Compose) носит исключительно информационный характер, документируя, на каком порту приложение слушает входящие соединения внутри виртуальной сети.

Внутри тестового стенда контейнерам не нужны проброшенные на хост порты для общения друг с другом. Backend обращается к базе данных напрямую по порту 5432, даже если директивы ports в сервисе database нет вообще. Compose автоматически создает изолированную виртуальную сеть для всех сервисов, описанных в файле.

Сборка и управление стендом

Объединив описанные блоки, мы получаем файл, который исчерпывающе описывает архитектуру из трех узлов: базы данных, бэкенда и фронтенда.

Для запуска всей инфраструктуры используется команда docker compose up. Флаг -d (detach) переводит процесс в фоновый режим, освобождая терминал. При выполнении этой команды Compose читает YAML-файл, создает необходимые сети и тома, собирает образы из исходного кода, выстраивает граф зависимостей на основе depends_on и healthcheck, после чего запускает контейнеры в строгой последовательности.

Если конфигурация стенда меняется (например, добавлена новая переменная окружения), повторный вызов docker compose up -d не приведет к перезапуску всего стенда. Compose проанализирует текущее состояние демона Docker, вычислит разницу и пересоздаст только тот контейнер, конфигурация которого изменилась.

Для остановки стенда с удалением контейнеров и виртуальных сетей применяется docker compose down. Если необходимо также очистить именованные тома (сбросить состояние базы данных до нуля), добавляется флаг -v.

Декларативное описание инфраструктуры устраняет разрыв между тем, как система должна работать в теории, и тем, как она запускается на практике. Файл docker-compose.yml становится исполняемой документацией. Любой новый разработчик, подключившийся к проекту, может клонировать репозиторий и поднять точную копию сложного тестового стенда одной командой, не вникая в сотни строк скриптов инициализации.

Сетевое взаимодействие и механизмы линковки контейнеров в общей среде

Разработчик настраивает Frontend-приложение, которое должно запрашивать данные у Backend-сервиса. Оба контейнера успешно запущены через Docker Compose. В коде Frontend указан адрес API: http://localhost:8080. При попытке сделать запрос приложение моментально падает с ошибкой ECONNREFUSED. Этот сценарий — самая частая причина фрустрации при проектировании тестовых стендов. Проблема заключается не в упавшем сервере, а в фундаментальном непонимании того, где именно пролегает граница сети каждого контейнера и как работает встроенная система разрешения имен.

Встроенный DNS и сеть по умолчанию

Когда выполняется запуск проекта, Docker Compose не просто поднимает набор изолированных процессов. До старта первого контейнера оркестратор неявно создает виртуальную сеть типа bridge. Имя этой сети формируется по шаблону <имя_директории_проекта>_default. Все сервисы, описанные в конфигурации, автоматически подключаются к этой сети, получая собственные внутренние IP-адреса.

Однако полагаться на IP-адреса в эфемерных средах нельзя. При каждом пересоздании контейнера (например, после изменения переменных окружения) Docker может выдать ему новый IP-адрес из пула подсети. Чтобы контейнеры могли надежно находить друг друга, Docker использует встроенный DNS-сервер, который всегда доступен внутри любого контейнера по зарезервированному адресу 127.0.0.11.

Этот DNS-сервер динамически обновляет записи при старте и остановке контейнеров. В качестве доменного имени выступает название сервиса из корневого блока конфигурации. Если в файле описан сервис с именем payment_gateway, любой другой контейнер в этой же сети может отправить запрос на http://payment_gateway, и внутренний DNS прозрачно преобразует это имя в актуальный IP-адрес.

!Процесс разрешения имени сервиса через внутренний DNS Docker

Важно понимать, что это разрешение имен работает исключительно внутри виртуальной сети Docker. Хост-машина (ваш ноутбук или сервер) ничего не знает о существовании домена payment_gateway.

Анатомия ловушки localhost

Возвращаясь к ошибке ECONNREFUSED, необходимо разделить два принципиально разных контекста выполнения кода: внутри контейнера и снаружи (на хост-машине).

Термин localhost (или IP-адрес 127.0.0.1) всегда указывает на loopback-интерфейс той среды, в которой выполняется процесс.

!Схема маршрутизации: запросы из браузера на хосте против запросов между контейнерами

Эта архитектурная особенность требует особой внимательности при разработке современных веб-приложений, особенно использующих Server-Side Rendering (SSR). В SSR-фреймворках (например, Next.js или Nuxt) код выполняется в двух разных средах:

Для решения этой проблемы в конфигурацию стенда внедряют две разные переменные окружения. Например, INTERNAL_API_URL=http://backend:8080 для серверных запросов и PUBLIC_API_URL=http://localhost:8080 для клиентских.

Изоляция сред через пользовательские сети

Сеть default удобна для простых проектов, но при масштабировании стенда принцип наименьших привилегий требует сетевой изоляции. Нет никаких причин, по которым Frontend-сервер должен иметь сетевой доступ к контейнеру с базой данных. Если Frontend будет скомпрометирован, злоумышленник получит прямую видимость СУБД.

Docker Compose позволяет декларативно описывать кастомные сети и управлять тем, какой сервис к какой сети подключен.

Рассмотрим архитектуру из трех компонентов: Nginx (балансировщик/статика), Node.js (API) и PostgreSQL (база данных). Логично разделить их на две сети:

Для реализации этой топологии необходимо добавить корневой блок networks и явно указать принадлежность каждого сервиса:

В этой конфигурации контейнер api оснащается двумя виртуальными сетевыми интерфейсами. Он может общаться как с frontend, так и с db. Однако попытка сделать ping db из контейнера frontend завершится ошибкой разрешения имени, так как они находятся в непересекающихся сетях, и DNS-сервер сети public_net не содержит записей о сервисах из private_net.

Продвинутая маршрутизация: Aliases и интеграция внешних сетей

Иногда возникает потребность, чтобы один и тот же контейнер был доступен по разным доменным именам. Это актуально при рефакторинге микросервисов, когда старый код обращается к legacy-users-api, а новый ожидает auth-service. Вместо дублирования контейнеров используется механизм сетевых алиасов (aliases).

Алиасы задаются на уровне подключения сервиса к конкретной сети:

Теперь любой контейнер в сети private_net может отправить запрос на http://legacy-users-api или http://v1-auth, и оба запроса будут маршрутизированы в один и тот же контейнер auth.

Другой граничный случай — необходимость связать текущий тестовый стенд с базой данных, которая уже запущена в рамках совершенно другого проекта Compose. По умолчанию Compose изолирует проекты, добавляя префикс имени директории к сетям. Чтобы подключиться к сети, созданной извне, используется директива external.

Если в другом проекте была создана сеть shared_database_net, в текущем стенде ее можно объявить следующим образом:

При запуске такого стенда Docker не будет пытаться создать сеть заново. Он найдет существующую сеть с точным именем shared_database_net и подключит к ней сервисы, у которых она указана в конфигурации. Если сеть не существует, процесс запуска прервется с ошибкой. Это гарантирует, что стенд не запустится в неполном или некорректном состоянии при отсутствии критически важных внешних зависимостей.

Инструменты диагностики сетевых аномалий

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

Первый уровень проверки — инспекция самой сети. Выполнение команды docker network inspect <имя_сети> возвращает JSON-объект, содержащий массив Containers. В нем перечислены все контейнеры, фактически подключенные к сети в данный момент, с их текущими внутренними IP-адресами и MAC-адресами. Это позволяет убедиться, что оркестратор действительно поместил сервисы в единое широковещательное пространство.

Второй уровень — проверка связности изнутри контейнера. Поскольку проблема localhost часто сбивает с толку, тестировать доступность Backend-сервиса нужно не с хост-машины, а из среды того сервиса, который инициирует запрос.

Используя команду docker compose exec <имя_сервиса> <команда>, можно запустить утилиту внутри работающего контейнера. Например, docker compose exec frontend curl -v http://api:3000/health покажет весь процесс разрешения имени api встроенным DNS-сервером и попытку установки TCP-соединения. Если curl сообщает Could not resolve host, проблема кроется в конфигурации сетей. Если соединение устанавливается, но возвращается HTTP-ошибка, сеть функционирует штатно, а причину следует искать в логике самого приложения.

Понимание этих механизмов превращает файл конфигурации из набора магических строк в прозрачную карту инфраструктуры, где каждый маршрут предсказуем, а зоны ответственности сервисов строго разграничены на сетевом уровне.

Оптимизация многоэтапной сборки и подготовка стенда к деплою

Исходный код современного Frontend-приложения весит несколько мегабайт, но размер каталога node_modules с инструментами сборки, линтерами и компиляторами легко превышает гигабайт. Если упаковать всё это в Docker-образ, размер итогового контейнера составит 1.5–2 ГБ. В условиях CI/CD, где образы собираются, пушатся в реестр и скачиваются на серверы десятки раз в день, передача таких объемов данных становится критическим узким местом. Более того, наличие компиляторов и исходников внутри production-окружения экспоненциально увеличивает поверхность атаки (attack surface).

Решение этой проблемы лежит в изоляции среды сборки от среды выполнения.

Многоэтапные сборки (Multi-stage builds)

Многоэтапная сборка позволяет использовать несколько инструкций FROM в одном Dockerfile. Каждая инструкция FROM начинает новую стадию сборки с чистой базовой файловой системы. Ключевая особенность механизма заключается в возможности выборочно копировать артефакты из одной стадии в другую, оставляя промежуточные слои (исходники, кэши пакетов, инструменты сборки) за бортом финального образа.

!Схема передачи артефактов между этапами сборки

Оптимизация Frontend-сервиса

Для Frontend-приложений (React, Vue, Angular) типичный жизненный цикл состоит из установки зависимостей, компиляции TypeScript/SCSS и минификации кода. На выходе получается набор статических файлов (HTML, CSS, JS), для раздачи которых нужен только легковесный веб-сервер.

Реализация через multi-stage build выглядит следующим образом:

В этом сценарии финальный образ базируется на nginx:alpine и весит около 20–30 МБ. В нем нет ни Node.js, ни исходного кода приложения, ни менеджера пакетов. Директива COPY --from=builder извлекает только директорию /app/dist из первой стадии. Все слои стадии builder кэшируются локально демоном Docker для ускорения будущих сборок, но не включаются в экспортируемый образ.

Оптимизация Backend-сервиса (TypeScript/Node.js)

Для Backend-приложений логика немного отличается: серверу выполнения все еще нужен Node.js (runtime), но не нужны инструменты сборки (TypeScript-компилятор, типы) и dev-зависимости.

Здесь используется три этапа. Разделение этапов компиляции и установки production-зависимостей позволяет максимально эффективно использовать кэш слоев: если изменился только исходный код, но не package.json, этап deps будет взят из кэша мгновенно. Инструкция USER node переключает выполнение процесса с прав root на непривилегированного пользователя, что является обязательным стандартом безопасности для production-окружений.

Разделение конфигураций: Overrides

При подготовке стенда к деплою возникает конфликт интересов. Для локальной разработки требуются Bind Mounts (чтобы изменения в коде сразу отражались в контейнере без пересборки), открытые порты отладки и переменные окружения для тестирования. В CI/CD или production-среде код должен быть жестко запечен в образ (никаких Bind Mounts), а порты часто закрыты обратным прокси-сервером.

Docker Compose решает эту проблему через механизм слияния файлов (merge). По умолчанию, если в директории присутствуют файлы docker-compose.yml и docker-compose.override.yml, Compose автоматически читает оба и объединяет их.

Базовый docker-compose.yml должен описывать production-ready состояние стенда:

А файл docker-compose.override.yml добавляет или переопределяет параметры исключительно для локальной разработки:

При запуске docker compose up на машине разработчика применятся оба файла: включится hot-reload (через volumes), пробросится порт и установится режим development. В CI/CD пайплайне файл переопределения игнорируется (или не копируется на сервер), и стенд запускается в строгом изолированном режиме на основе базового файла.

Изоляция тестовых инструментов: Profiles

Тестовый стенд часто включает сервисы, которые не нужны для постоянной работы приложения, но требуются для специфичных задач. Например, контейнер с E2E-тестами (Cypress/Playwright) или графический интерфейс для базы данных (pgAdmin). Запускать их по умолчанию — значит впустую тратить ресурсы процессора и памяти.

Механизм Profiles позволяет группировать сервисы и запускать их только по явному требованию.

При стандартной команде docker compose up -d запустятся только api и db. Сервисы с указанными профилями будут проигнорированы. В CI/CD пайплайне для запуска тестов используется команда с указанием профиля: docker compose --profile testing up --abort-on-container-exit. Флаг --abort-on-container-exit заставит Compose остановить весь стенд и вернуть код возврата (exit code) тестового контейнера, как только он завершит работу. Это идеальный паттерн для автоматизированного тестирования. Для локальной отладки базы данных разработчик может выполнить docker compose --profile debug up -d pgadmin.

Квотирование ресурсов и защита от OOM

В локальной среде контейнеры могут потреблять все доступные ресурсы хост-машины. В production или CI/CD (где на одном сервере работают десятки контейнеров) неконтролируемое потребление ресурсов одним сервисом приведет к деградации или падению всего узла. Например, утечка памяти в Backend-приложении может заставить операционную систему начать убивать критические системные процессы.

Для предотвращения этого в Compose используется блок deploy.resources.

Параметр limits устанавливает жесткую верхнюю границу. cpus: '0.50' означает, что контейнеру разрешено использовать максимум 50% времени одного ядра процессора. Если приложение попытается использовать больше, ядро Linux (через механизм cgroups) начнет принудительно ограничивать процессорное время (throttling), что приведет к замедлению работы сервиса, но спасет соседние контейнеры.

!Потребление памяти и OOM Killer

Ограничение памяти (memory: 512M) работает жестче. Если процесс внутри контейнера попытается выделить память сверх установленного лимита, операционная система вызовет механизм OOM Killer (Out Of Memory Killer). Процесс будет немедленно завершен сигналом SIGKILL. Контейнер остановится, и, если настроена политика restart: always, Docker попытается запустить его заново.

Параметр reservations является мягким ограничением. Он сообщает оркестратору (или Docker-демону), сколько ресурсов гарантированно требуется контейнеру для нормальной работы. Это критически важно при деплое в кластеры (например, Docker Swarm), чтобы планировщик мог найти узел с достаточным количеством свободных ресурсов.

Грамотно спроектированный тестовый стенд — это не просто набор связанных контейнеров. За счет многоэтапных сборок он минимизирует время передачи данных по сети и исключает попадание уязвимых инструментов в конечный артефакт. Разделение конфигураций через overrides позволяет разработчикам иметь гибкую среду с hot-reload, не ломая при этом строгие правила запуска в CI/CD. А профилирование сервисов и жесткое квотирование ресурсов делают среду предсказуемой: тяжелые тесты запускаются только когда нужно, а утечки памяти локализуются в рамках одного контейнера, не затрагивая инфраструктуру.