Модель Compose: проект, сеть и сервисы, находящие друг друга по имени

Проект — это namespace

Файл Compose описывает один проект, и имя проекта (по умолчанию имя каталога или -p) — это префикс на всём, что Compose создаёт: контейнерах, сетях, томах, метках. Этот namespace и делает compose up и compose down идемпотентными — Compose ищет ресурсы по метке com.docker.compose.project, а не угадывает, поэтому повторный up сверяется с существующим проектом, а не плодит дубли. Две копии одного репозитория в двух каталогах дают два независимых проекта с двумя сетями и двумя томами БД, без коллизий. Модель — это сходимость к желаемому состоянию, а не скрипт: ты объявляешь набор сервисов, которые хочешь видеть запущенными, а up сравнивает это с тем, что есть, и делает минимум изменений — стартует недостающее, пересоздаёт изменённое, оставляет совпадающее. Поэтому правка образа одного сервиса и повторный up пересоздают именно этот контейнер, а не весь стек.

# compose.yaml — всё локальное окружение как данные
services:
  api:
    build: .
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app   # "db" — DNS-имя
      REDIS_URL: redis://cache:6379
    ports:
      - "8080:8080"
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data   # именованный том переживает `down`
  cache:
    image: redis:7

volumes:
  pgdata:

Сервисы находят друг друга по имени, а не по IP

Когда ты запускаешь compose up, Compose создаёт для проекта сеть по умолчанию (с именем <project>_default) и подключает к ней каждый сервис. В этой сети Docker поднимает встроенный DNS-сервер, и каждый сервис разрешается по имени сервиса — api достаёт Postgres по хосту db, порт 5432, без единого IP в конфиге. Это главная причина, по которой вики из команд run исчезает: хрупкой частью ручной оркестрации всегда была сшивка контейнеров по адресам, а адреса меняются при каждом перезапуске. DNS по имени сервиса делает связи стабильными и читаемыми. Два момента кусаются на senior-уровне: DNS-имя — это ключ сервиса, и container_name его не меняет — переопредели имя контейнера, и DNS-запись всё равно db. И опубликованный маппинг ports: ("8080:8080") нужен, чтобы хост достучался до контейнера; трафик между сервисами идёт прямо на порт контейнера через сеть проекта и вовсе не требует записи ports:. Частая ошибка — публиковать порт БД на хост, «чтобы API мог достучаться» — API достучится по имени через сеть в любом случае; публикация лишь открывает БД твоему ноутбуку.

Именованные тома — это долговечный слой

Контейнеры одноразовы; данные под ними — обычно нет. Именованный том (pgdata выше) — это управляемый Compose, привязанный к проекту объект хранения, переживающий пересоздание контейнера: compose up после смены образа пересоздаёт контейнер db, но заново монтирует тот же pgdata, так что локальная база сохраняет строки. Острые края — это разрушающие команды: обычный compose down удаляет контейнеры и сеть по умолчанию, но сохраняет именованные тома, а compose down -v их удаляет — этот флаг и есть разница между «перезапустить стек» и «стереть локальную базу». Анонимные тома (голый путь без имени) — ловушка: они создаются заново при каждом пересоздании и осиротевают, поэтому сервис, который должен хранить данные, но использует анонимный том, тихо их теряет на следующем up. Дай тому имя, смонтируй его в путь данных — и down/up можно гонять весь день безопасно.