ermnvldmr.com/services/docs/content/ru/apex/concepts/compositions.md

title, description, weight

title	description	weight
Композиции и общее ядро	Ядровая композиция на основе include, профили, сети и наслоение окружения.	15

Среда выполнения узла объявляется как композиции: по одному docker-compose-проекту на сервис в каталоге compositions/<project>/, плюс ядровая композиция — граничные и инфраструктурные сервисы, необходимые каждому узлу. Ядро располагается в «commons» и потребляется каждым узлом через тонкую обёртку, поэтому его определение написано один раз и версионируется вместе с фреймворком.

Обёртка include

Файл compositions/apex/docker-compose.yml каждого узла состоит из трёх строк:

name: apex
include:
  - ../../commons/compositions/apex/docker-compose.yml

Общий файл полностью параметризован через ${APEX_*} и не содержит относительных хостовых путей — каждое монтирование разрешается через переменные, которые движок экспортирует при вызове, поэтому один и тот же файл корректен на каждом узле.

Структурное исключение — узел, которому действительно нужно изменить ядровой сервис, например опубликовать дополнительный хостовый порт, — наслаивает переопределение через форму include со списком путей вместо редактирования общего файла:

name: apex
include:
  - path:
      - ../../commons/compositions/apex/docker-compose.yml
      - ./traefik.override.yml

Note

Директива include: требует Docker Compose v2.20 или новее.

Ядровые сервисы и профили

Ядровая композиция определяет общий набор сервисов флота. Всегда включённые сервисы:

• traefik — граничный обратный прокси и якорь сети direct (всегда .10 в подсети узла). Он завершает TLS через DNS-челлендж, обнаруживает бэкенды через docker-метки и выставляет свою панель управления на FQDN узла за списком разрешённых IP анклава.
• socket-proxy — отфильтрованный прокси для docker-сокета; traefik читает состояние контейнеров через него и никогда не обращается к сокету напрямую.

Опциональные сервисы, управляемые через compose-профили, которые узел включает в COMPOSE_PROFILES (задаётся в apex.env):

Профиль	Сервис	Роль
xray	xray	Прокси-край с host-network для анклава.
adguard	adguard	DNS-фильтрация с использованием сетевого пространства имён traefik; маршрутизируется по /adguard на FQDN узла.
alloy	alloy	Понодовый агент наблюдаемости (Grafana Alloy). Собирает метрики хоста и контейнеров, а также логи journal и контейнеров и проталкивает их исходящим потоком в центральные Prometheus и Loki (см. Концепция: Модель безопасности). Его hostname контейнера установлен в APEX_NODE_HOST, и это значение проставляет метки node и instance на каждой метрике и потоке логов.
manual	resticontainer	Одноразовый исполнитель резервного копирования, управляемый метками (ghcr.io/deytenit/resticontainer) — никогда не запускается через up; вызывается действием backup/run, которое обнаруживает намерение резервного копирования для каждого сервиса из compose-меток restic.*.

Сети

Ядровая композиция владеет тремя сетями узла; сервисные композиции ссылаются на них по ключу с external: true.

Сеть	Тип	Назначение
direct	bridge, подсеть = APEX_SUBNET	Сеть со статическими якорными IP; якорь каждого проекта удерживает здесь фиксированный адрес (см. Концепция: Схема адресации флота).
enclave	bridge, internal: true	Бэкенд-сеть обратного прокси; traefik достигает помеченных сервисов здесь.
socket	bridge, internal: true	Несёт только трафик traefik ↔ socket-proxy.

Внутри проекта соседние контейнеры обычно присоединяются к сетевому пространству имён якоря (network_mode: service:<anchor>) вместо самостоятельного подключения к сетям.

Наслоение окружения

Значения достигают композиции из трёх слоёв в порядке возрастания приоритета:

1. .env — незакоммиченные секреты, символьная ссылка в хранилище уровня 1 (учётные данные APEX_RESTIC_*, токены APEX_TRAEFIK_*, блок UID/GID).
2. apex.env — закоммиченные несекретные скалярные значения (APEX_TRAEFIK_DIRECT_IP, APEX_RESTIC_REPOSITORY, COMPOSE_PROFILES, опциональный APEX_RESTIC_COMPRESSION).
3. Экспорты движка — идентичность APEX_* и пути уровней из ctx.vars(), внедряемые в окружение процесса действиями оркестрации и потому выигрывающие у обоих файлов.

Критические переменные несут маркеры ?error в общем файле, поэтому отсутствующий секрет громко проваливает загрузку конфигурации композиции вместо запуска неправильно настроенного контейнера.

Оркестрация

apex compose <action> управляет каждой композицией на узле:

• Порядок — сначала ядровой проект (он владеет сетями), затем каждая сервисная композиция в алфавитном порядке; down разворачивает последовательность.
• Env-файлы — для каждого проекта .env и apex.env передаются как --env-file, если они присутствуют.
• up подразумевает -d; любые дополнительные аргументы передаются в docker compose.
• --dry-run печатает каждую команду с её рабочим каталогом вместо выполнения — принимается в любом месте командной строки.

---

См. также:

• Концепция: Схема адресации флота
• Руководство: Добавление сервисной композиции
• Справочник: Переменные окружения