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). Собирает метрики хоста и контейнеров, а также логи systemd 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: выводит каждую команду с её рабочим каталогом без выполнения; поддерживается в любом месте командной строки.

---

См. также:

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