fix, feat, doc: massive build system refactorion, bug fixes and apex documentation (#19)

2026-07-12 01:57:40 +03:00
1 parent e8b42c60c2
commit 91f5245823
@@ -0,0 +1,87 @@
+---
+title: Композиции и общее ядро
+description: Ядровая композиция на основе include, профили, сети и наслоение окружения.
+weight: 15
+---
+
+Среда выполнения узла объявляется как [композиции](/apex/glossary#compositions): по одному docker-compose-проекту на сервис в каталоге `compositions/<project>/`, плюс [ядровая композиция](/apex/glossary#core-composition) — граничные и инфраструктурные сервисы, необходимые каждому узлу. Ядро располагается в [«commons»](/apex/glossary#commons) и потребляется каждым узлом через тонкую обёртку, поэтому его определение написано один раз и версионируется вместе с фреймворком.
+
+## Обёртка include {#include}
+
+Файл `compositions/apex/docker-compose.yml` каждого узла состоит из трёх строк:
+
+```yaml {filename="compositions/apex/docker-compose.yml"}
+name: apex
+include:
+  - ../../commons/compositions/apex/docker-compose.yml
+```
+
+Общий файл полностью параметризован через `${APEX_*}` и не содержит относительных хостовых путей — каждое монтирование разрешается через переменные, которые [движок](/apex/glossary#engine) экспортирует при вызове, поэтому один и тот же файл корректен на каждом узле.
+
+Структурное исключение — узел, которому действительно нужно изменить ядровой сервис, например опубликовать дополнительный хостовый порт, — наслаивает переопределение через форму include со списком путей вместо редактирования общего файла:
+
+```yaml {filename="compositions/apex/docker-compose.yml"}
+name: apex
+include:
+  - path:
+      - ../../commons/compositions/apex/docker-compose.yml
+      - ./traefik.override.yml
+```
+
+> [!NOTE]
+> Директива `include:` требует Docker Compose v2.20 или новее.
+
+## Ядровые сервисы и профили {#core-services}
+
+Ядровая композиция определяет общий набор сервисов флота. Всегда включённые сервисы:
+
+- **traefik** — граничный обратный прокси и якорь сети `direct` (всегда `.10` в подсети узла). Он завершает TLS через DNS-челлендж, обнаруживает бэкенды через docker-метки и выставляет свою панель управления на FQDN узла за списком разрешённых IP [анклава](/apex/glossary#enclave).
+- **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 (см. [Концепция: Модель безопасности](/apex/concepts/security-model#observability)). Его `hostname` контейнера установлен в `APEX_NODE_HOST`, и это значение проставляет метки `node` и `instance` на каждой метрике и потоке логов. |
+| `manual` | resticontainer | Одноразовый исполнитель резервного копирования, управляемый метками (`ghcr.io/deytenit/resticontainer`) — никогда не запускается через `up`; вызывается действием `backup/run`, которое обнаруживает намерение резервного копирования для каждого сервиса из compose-меток `restic.*`. |
+
+## Сети {#networks}
+
+Ядровая композиция владеет тремя сетями узла; сервисные композиции ссылаются на них по ключу с `external: true`.
+
+| Сеть | Тип | Назначение |
+|---|---|---|
+| `direct` | bridge, подсеть = `APEX_SUBNET` | Сеть со статическими [якорными IP](/apex/glossary#anchor-ip); якорь каждого проекта удерживает здесь фиксированный адрес (см. [Концепция: Схема адресации флота](/apex/concepts/addressing)). |
+| `enclave` | bridge, `internal: true` | Бэкенд-сеть обратного прокси; traefik достигает помеченных сервисов здесь. |
+| `socket` | bridge, `internal: true` | Несёт только трафик traefik ↔ socket-proxy. |
+
+Внутри проекта соседние контейнеры обычно присоединяются к сетевому пространству имён якоря (`network_mode: service:<anchor>`) вместо самостоятельного подключения к сетям.
+
+## Наслоение окружения {#env-layering}
+
+Значения достигают композиции из трёх слоёв в порядке возрастания приоритета:
+
+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_*` и пути [уровней](/apex/glossary#tier) из `ctx.vars()`, внедряемые в окружение процесса действиями оркестрации и потому выигрывающие у обоих файлов.
+
+Критические переменные несут маркеры `?error` в общем файле, поэтому отсутствующий секрет громко проваливает загрузку конфигурации композиции вместо запуска неправильно настроенного контейнера.
+
+## Оркестрация {#orchestration}
+
+`apex compose <action>` управляет каждой композицией на узле:
+
+- **Порядок** — сначала ядровой проект (он владеет сетями), затем каждая сервисная композиция в алфавитном порядке; `down` разворачивает последовательность.
+- **Env-файлы** — для каждого проекта `.env` и `apex.env` передаются как `--env-file`, если они присутствуют.
+- **`up`** подразумевает `-d`; любые дополнительные аргументы передаются в `docker compose`.
+- **`--dry-run`** печатает каждую команду с её рабочим каталогом вместо выполнения — принимается в любом месте командной строки.
+
+---
+
+**См. также:**
+
+- [Концепция: Схема адресации флота](/apex/concepts/addressing)
+- [Руководство: Добавление сервисной композиции](/apex/guides/service-composition)
+- [Справочник: Переменные окружения](/apex/reference/environment)