Установка в Docker-контейнере¶

В инструкции приведены шаги по установке решения ПроAPI Защита с помощью Docker Compose.

Компоненты¶

Консоль управления (manager) – веб-интерфейс для управления нодами, настройки политик безопасности и мониторинга системы.
Фильтрующая нода (node) – компонент для валидации и фильтрации трафика по спецификации OpenAPI.

Требования¶

Docker Engine версии 24+
Docker Compose plugin
Linux-сервер с архитектурой linux/amd64
Доступ к registry.webmonitorx.ru
Лицензионный ключ APIFW_LICENSE_KEY
DNS-имя или IP для Консоли управления
Открытый TCP-порт от Ноды (node) к Консоли управления
Целевой адрес проксирования очищенного трафика от Ноды

Известные ограничения¶

Использование localhost для связи Фильтующая нода → Консоль управления
Укажите в переменной WMX_AGENT_API_HOST реальный адрес сервера с Консолю управления (например, manager.example.com или IP). Даже если Консоль управления и Нода работают на одном сервере, внутри контейнера localhost указывает на сам контейнер, а не на сервер.
Настройка адреса защищаемого бэкенда upstream в конфигурации Фильтрующей ноды
Обязательно проверьте файл node/conf/nginx/wmx.nginx.conf перед запуском Ноды – в нём необходимо задать адрес защищаемого API.
Проверка доступа к внешним реестрам
Пакет использует образы не только из основного реестра registry.webmonitorx.ru, но и из публичных реестров (clickhouse/clickhouse-server, nginx:1.29-alpine-slim). Убедитесь, что с вашего сервера есть сетевой доступ к этим реестрам.

Порядок установки¶

Установите Консоль управления.
Войдите в интерфейс Консоли управления.
Создайте ноду и получите токен регистрации – registration token.
Настройте адрес защищаемого приложения в конфигурации Фильтрующей ноды.
Установите Фильтрующую ноду.
Проверьте регистрацию ноды и передачу данных.

Обратите внимание

Если запустить Фильтрующую ноду до получения токена, регистрация завершится ошибкой.

Инициализация данных (`seed data`)¶

seed-data — это отдельная инициализация данных Консоли управления в PostgreSQL. Используйте её только если в вашей сборке отключён bootstrap через миграции.

Что делает seed-data:

Инициализирует базовые данные Консоли управления.
Создаёт или переиспользует Cуперадминистратора и тенанта.
Добавляет дефолтные конфигурации и приложение.

Когда использовать seed-data:

При первом запуске Консоли управления, если вы не хотите хранить пароль bootstrap-пользователя в миграциях.
Если WMX_AUTHN_SEED_* отключён.
Для отдельной инициализации дефолтных конфигураций.

Предварительные условия
Убедитесь, что миграции PostgreSQL Консоли управления выполнены.

Запустите seed-data через контейнер

Если PostgreSQL опубликован на host-порт, выполните:

  docker run --rm \
  -e WMX_PG_HOST=host.docker.internal \
  -e WMX_PG_PORT=5433\
  -e WMX_PG_USER=apifw \
  -e WMX_PG_PASSWORD=12345\
  -e WMX_PG_DB_NAME=api_fw_manager \
  -e WMX_USER_EMAIL=admin@example.com \
  -e WMX_USER_PASSWORD='ChangeMe123!'\
  -e WMX_USER_NAME='Bootstrap Admin'\
  -e WMX_USER_COMPANY='Default Company'\
  registry.webmonitorx.ru/api-firewall/seeder:<tag>

Для запуска в той же Docker-сети, что и Консоль управления, выполните:

  docker run --rm \
  --network api-fw-manager-v2 \
  -e WMX_PG_HOST=pg \
  -e WMX_PG_PORT=5432 \
  -e WMX_PG_USER=discovery \
  -e WMX_PG_PASSWORD=12345 \
  -e WMX_PG_DB_NAME=discovery \
  -e WMX_PG_CONNECTION_EXTRAS='sslmode=disable' \
  -e WMX_USER_EMAIL='admin@example.com' \
  -e WMX_USER_PASSWORD='ChangeMe123!' \
  -e WMX_USER_NAME='Bootstrap Admin' \
  -e WMX_USER_COMPANY='Default Company' \
  registry.webmonitorx.ru/api-firewall/seeder:2.0.3

Рекомендуем хранить тег seeder вместе с APIFW_TAG окружения Консоли.

Переменные окружения

Переменная	Обязательность	Описание
WMX_PG_HOST	да	Сервер PostgreSQL
WMX_PG_PORT	да	Порт PostgreSQL
WMX_PG_USER	да	Пользователь PostgreSQL
WMX_PG_PASSWORD	да	Пароль PostgreSQL
WMX_PG_DB_NAME	да	Имя базы данных Консоли управления
WMX_PG_CONNECTION_EXTRAS	нет	Доп. параметры (например, sslmode=disable)
WMX_USER_EMAIL	только если нет Суперадминистатора	Email bootstrap-пользователя
WMX_USER_PASSWORD	только если нет Суперадминистатора	Пароль bootstrap-пользователя
WMX_USER_NAME	нет	Полное имя (по умолчанию email)
WMX_USER_COMPANY	нет	Название тенанта (по умолчанию Default Company)

Примечание

WMX_USER_EMAIL — автоматически очищается от лишних пробелов и приводится к нижнему регистру.
WMX_USER_PASSWORD — используется только для создания нового пользователя. Если пользователь уже существует, пароль не меняется.
Пароль сохраняется в зашифрованном виде (bcrypt-хэш), а созданному пользователю будет предложено сменить пароль при первом входе (флаг requires_password_change = true).
Если в системе уже есть активный суперадминистратор — переменные WMX_USER_EMAIL и WMX_USER_PASSWORD игнорируются. В этом случае seeder использует существующего пользователя и только добавляет недостающие дефолтные конфиги и приложение для его тенанта.
Проверьте результат

Успешный запуск завершается сообщением:
```
"msg": "seed data completed"
```
Если активный суперадминистратор отсутствует, а переменные WMX_USER_EMAIL и WMX_USER_PASSWORD не заданы, seeder завершится с ошибкой:
```
"msg": "seed user email and password are required"
```
В этом случае укажите эти переменные и запустите seeder повторно.

Установка Консоли управления¶

Разместите на сервере (например, /opt/proapi/manager) содержимое каталога manager.
Подготовьте файл .env:
```
cd /opt/proapi/manager
cp env.example .env
```
Заполните обязательные переменные:
```
APIFW_TAG=2.0.0 (пример)
APIFW_UI_TAG=2.0.0 (пример)
POSTGRES_TAG=16-alpine3.23
CLICKHOUSE_TAG=24-alpine
APIFW_LICENSE_KEY=ваш_ключ
API_BASE_URL=http://manager.example.com:3001/api
UI_PORT=3001 (пример)
API_PORT=7777 (пример)
```
APIFW_TAG — тег образов backend-компонентов Консоли управления. Обновляйте значение в документации при каждом релизе.

APIFW_UI_TAG — тег образа веб-интерфейса Консоли управления. Обновляйте значение в документации при каждом релизе.

APIFW_LICENSE_KEY — лицензионный ключ

API_BASE_URL — адрес API, видимый браузером пользователя.

UI_PORT — внешний порт интерфейса.

API_PORT — внешний TCP-порт API Консоли управления для discovery-agent.

Если интерфейс открывается через reverse proxy, в API_BASE_URL укажите внешний адрес, например:
```
API_BASE_URL=https://proapi.customer.example/api
```
Настройте WMX_AUTHN_SEED_*

По умолчанию механизм seed-пользователя отключён. Оставьте значение:
```
WMX_AUTHN_SEED_USER=false
```
Для первичного входа используйте учётные данные, указанные при старте системы.

Выполните авторизацию в registry:

docker login registry.webmonitorx.ru
# введите логин и пароль

Запустите Консоль управления:
```
cd /opt/proapi/manager
docker compose config >/dev/null
docker compose pull
docker compose up -d
```
Первый запуск может занять несколько минут из‑за инициализации базы данных и миграций.
Проверьте Консоль управления:

Проверьте контейнеры:
```
docker compose ps
```
- Убедитесь, что присутствуют контейнеры:
  apifw-postgres, apifw-click, server, node-api, discovery-api, bg-worker, backend-nginx, authn, userm, apigw, triggers, auditlog, ui.
  Обратите внимание, что одноразовые миграционные контейнеры (pg_migrations, ch_migrations, auditlog-migrations) могут иметь статус Exited (0) – это нормально.
Проверьте APIGW:
```
curl -i http://127.0.0.1:7777/healthz
```
Ожидаемый результат: HTTP 200.
Проверьте интерфейс: откройте http://<manager-host>:3001 и выполните вход.

Если интерфейс не открывается, проверьте логи:
```
docker compose logs --tail=100 apifw-manager-ui apilb apigw authn
```

Создание токена ноды¶

Откройте раздел Ноды.
Нажмите Создать ноду.
Укажите имя ноды.
Скопируйте выданный токен.
Вставьте скопированный токен в node/.env в переменную:
```
WMX_AGENT_API_REG_TOKEN=...
```
Если нода уже создана, можно перевыпустить токен в карточке ноды.

Установка фильтрующей ноды¶

Разместите на сервере (например, /opt/proapi/node) содержимое каталога node:
```
cd /opt/proapi/node
cp env.example .env
```
Заполните следующие переменные в файле .env:
```
APIFW_TAG=2.0.0 (пример)
APIFW_MODULE_TAG=v2.0.4 (пример)
WMX_AGENT_API_REG_TOKEN=ваш_токен
NODE_PORT=8090 (пример)
WMX_AGENT_API_HOST=manager.example.com
WMX_AGENT_API_PORT=7777 (пример)
```
- APIFW_TAG – тег базового образа Фильтрующей ноды. Обновляйте значение в документации при каждом релизе.
- APIFW_MODULE_TAG – тег модуля Фильтрующей ноды. Обновляйте значение в документации при каждом релизе.
- WMX_AGENT_API_REG_TOKEN – токен из интерфейса Консоли управления.
- NODE_PORT – внешний порт фильтрующей ноды.
- WMX_AGENT_API_HOST – DNS/IP сервера с manager (не localhost).
- WMX_AGENT_API_PORT – API порт manager (обычно 7777).
Обратите внимание: не указывайте localhost в WMX_AGENT_API_HOST.
Настройте адрес защищаемого API:

Отредактируйте файл node/conf/nginx/wmx.nginx.conf. Найдите строку:
```
  proxy_pass http://host.docker.internal:8080;
```
Замените её на адрес вашего защищаемого приложения.

Примеры:

Защищаемое приложение на том же сервере, порт 8080: proxy_pass http://host.docker.internal:8080;
Защищаемое приложение на другом сервере: proxy_pass http://api-backend.customer.local:8080;
Защищаемое приложение по HTTPS: proxy_pass https://api-backend.customer.local:8443;

Обратите внимание: нода должна проксировать очищенный трафик в указанное защищаемое приложение.

Войдите в registry (повторно).

Если Нода запускается на отдельном сервере, выполните:
```
docker login registry.webmonitorx.ru
```
Запустите ноду:

 cd /opt/proapi/node
 docker compose config >/dev/null
 docker compose pull
 docker compose up -d

Проверьте ноду:

Проверьте статус контейнеров:
```
docker compose ps
```
Убедитесь, что запущены сервисы: apistore, api-fw-nginx (контейнер Ноды), discovery-agent (контейнер agent).
Проверьте логи регистрации:
```
docker compose logs --tail=100 discovery-agent
```
Ожидаемые сообщения:
- node registration start
- set client id
- node successfully registered
При повторном запуске с существующим volume shared_config возможно сообщение:
- node already registered and valid, skipping registration
Если появляются ошибки failed to register node instance, проверьте:
- Токен ноды (возможно, неверный или отозван).
- WMX_AGENT_API_HOST (должен указывать корректный адрес).
- Сетевую доступность между Нодой и Консолью управления по настроенному TCP-порту.

Проверка работоспособности системы¶

После запуска обеих частей выполните следующие шаги:

Откройте интерфейс: http://<manager-host>:3001.
Выполните curl http://<manager-host>:7777/healthz — ожидайте HTTP 200.
Убедитесь, что нода отображается зарегистрированной в интерфейсе.
Отправьте тестовый запрос к ноде: curl -i http://<node-host>:8090/ — должен прийти ответ бэкенд, а не 502.
Проверьте появление данных о ноде и трафике в интерфейсе.

Если у вас есть простой тестовый эндпоинт на защищаемое приложение, проверьте его через ноду:
curl -i http://<node-host>:8090/ – должен прийти ответ от защищаемого приложения, а не ошибка Nginx.

Типовые команды¶

Быстрая проверка состояния Консоли управления¶

cd /opt/proapi/manager
docker compose ps
docker compose logs --tail=100

Быстрая проверка состояния Фильтрующей ноды¶

cd /opt/proapi/node
docker compose ps
docker compose logs --tail=100

Просмотр логов конкретного сервиса¶

Консоль:

docker compose logs -f apifw-manager-ui
docker compose logs -f apigw
docker compose logs -f authn
docker compose logs -f node-api

Нода:

docker compose logs -f discovery-agent
docker compose logs -f api-fw-nginx
docker compose logs -f apistore

Перезапуск отдельного сервиса¶

docker compose up -d apifw-manager-ui   # для Консоли
docker compose up -d api-fw-nginx       # для Ноды

Перечитывание конфигурации Фильтующей ноды¶

После изменения файла node/conf/nginx/wmx.nginx.conf:

cd /opt/proapi/node
docker compose up -d api-fw-nginx

Обновление версий образов¶

Измените теги в .env.

Выполните:

docker compose config >/dev/null
docker compose pull
docker compose up -d

Проверка получения конфигурации агентом от Консоли управления¶

docker exec node ls -la /wmx_config
docker exec node sh -c
'head -c 500 /wmx_config/api-config.json'

Если файл api-config.json появился – агент зарегистрировался и начал получать конфигурацию.

Проверка доступности защищаемого приложения Консоли управления¶

curl -i http://127.0.0.1:7777/healthz

Ожидаемый ответ: HTTP 200.

Остановка стенда¶

docker compose down

Полная остановка с удалением данных:¶

docker compose down -v

Сценарии обработки HTTP и HTTPS трафика¶

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

Сценарий 1. Передача обычного HTTP-трафик без шифрования¶

(Клиент → HTTP → нода → HTTP → бэкенд)

Самый простой вариант. Вы отправляете незашифрованный HTTP-запрос на ноду. Нода фильтрует трафик (проверяет на соответствие спецификации API) и передаёт его на бэкенд по HTTP. Бэкенд отвечает, нода возвращает ответ вам.

Когда использовать

В тестовых или изолированных средах, где шифрование не требуется.
Если Фильтрующая нода и бэкенд находятся в одной защищённой сети (например, внутри VPC).
Для первичной проверки работоспособности ноды.

Пример проверки
Отправьте GET-запрос на корневой путь:

curl -i http://<node-host>:8090/

Ожидаемый результат
Ответ вашего защищаемого приложения (например, HTML-страница, JSON или 200 OK). Если вместо ответа вы получаете 502 Bad Gateway — проверьте адрес защищаемого приложения в wmx.nginx.conf.

curl -i http://<node-host>:8090/health

Сценарий 2. Заголовок Host для виртуальных серверов бэкенда¶

(Клиент → HTTP → нода с подставленным Host → бэкенд)

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

Когда использовать

Если ваш бэкенд использует виртуальные серверы (например, api.customer.example и api.supplier.example на одном сервере).
Для тестирования маршрутизации без изменения DNS.

Пример запроса с явным указанием Host

curl -i http://<node-host>:8090/api/v1/orders \
  -H 'Host: api.customer.example'

Пояснение параметров

-H 'Host: api.customer.example' – подменяет заголовок Host, заставляя бэкенд думать, что запрос пришёл на указанное доменное имя.

Ожидаемый результат
Бэкенд возвращает данные, соответствующие именно этому виртуальному сервеу. Если заголовок Host не будет соответствовать ни одному из настроенных виртуальных серверов, бэкенд может вернуть ошибку 400 или 404.

Сценарий 3. POST-запрос с JSON-данными через ноду¶

(Клиент → HTTP POST JSON → нода → бэкенд)

Вы отправляете POST-запрос с телом в формате JSON → нода проверяет структуру JSON на соответствие схеме API (описано в спецификации OpenAPI) и передаёт запрос бэкенд.

Когда использовать

Для создания ресурсов (например, новый пользователь).
Для отправки структурированных данных, которые должны соответствовать строгой схеме.
Для проверки правил валидации.

Пример POST-запроса через ноду:

curl -i http://<node-host>:8090/api/v1/orders \
  -H 'Host: api.customer.example' \
  -H 'Content-Type: application/json' \
  -d '{ "order_id": "123", "amount": 100}'

Параметры

-H 'Content-Type: application/json' – бэкенд указывает, что тело запроса 2 JSON.

-d '{ ... }' 2 тело запроса. Замените пример на свои поля, соответствующие спецификации API.

-H 'Host: ...' – как в сценарии 2, укажите нужный виртуальный сервер.

Ожидаемый результат

Если JSON соответствует спецификации, нода передаст его бэкенд, и вы получите ответ (обычно 201 Created или 200 OK).

Если JSON невалиден (например, отсутствует обязательное поле или неправильный тип данных), нода может вернуть ошибку 400 Bad Request с пояснением, не передавая запрос в бэкенд.

Сценарий 4. HTTPS снаружи, HTTP внутри (внешний reverse proxy)¶

(Клиент → HTTPS → внешний reverse proxy → HTTP → нода → бэкенд)

Это рекомендуемый способ работы с HTTPS в текущем пакете. Вы ставите внешний reverse proxy (например, Nginx, HAProxy, балансировщик от облачного провайдера), который принимает HTTPS-трафик от пользователей, завершает TLS, а затем передаёт уже расшифрованный HTTP-трафик на ноду. Нода в этом случае не работает с HTTPS напрямую — она получает обычный HTTP-запрос.

Почему это предпочтительно

Нода по умолчанию слушает только порт 80 (HTTP).
Вынос TLS-терминации на отдельный компонент упрощает управление сертификатами (их автоматическое обновление через Let's Encrypt).
Reverse proxy может выполнять дополнительные задачи: балансировку, ограничение частоты запросов, логирование.

Когда использовать

Всегда для production-сред, где требуется HTTPS.
Если у вас уже есть внешний балансировщик или Ingress-контроллер (например, в Kubernetes).

Пример конфигурации внешнего Nginx перед нодой
Создайте файл конфигурации (например, /etc/nginx/sites-available/api-gateway):

server {
    listen 80;
    server_name api.customer.example;
    return 301 https://$host$request_uri;   # перенаправляем HTTP на HTTPS
}

server {
    listen 443 ssl http2;
    server_name api.customer.example;

    ssl_certificate /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/privkey.pem;

    location / {
        proxy_pass http://<node-host>:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Пояснение директив

ssl_certificate и ssl_certificate_key – пути к сертификату и ключу.

proxy_set_header X-Forwarded-Proto https – сообщает ноде (и бэкенду), что исходное соединение было HTTPS. Некоторые приложения используют этот заголовок для генерации абсолютных ссылок.

proxy_pass http://<node-host>:8090 – передача трафика на ноду по HTTP.

Проверка снаружи

curl -I https://api.customer.example

Ожидаемый результат
Ответ от вашего бэкенд. Сертификат должен быть валидным.

Сценарий 5. HTTPS-соединение ноды с бэкендом¶

(Клиент (HTTP или HTTPS) → нода → HTTPS → бэкенд)

Защищаемое приложение принимает трафик только по HTTPS, требуя шифрования на своём уровне. Настройте ноду так, чтобы она устанавливала HTTPS-соединение с бэкенд.

Когда использовать

Если бэкенд развёрнут в облаке и требует TLS для всех запросов.
Если корпоративные политики безопасности требуют сквозного шифрования до самого бэкенда.

Настройка: в файле node/conf/nginx/wmx.nginx.conf укажите proxy_pass с протоколом https://.

Пример конфигурации

location / {
proxy_pass https://api-backend.customer.local:8443;
proxy_ssl_server_name on;
proxy_set_header Host api-backend.customer.local;
proxy_set_header X-Real-IP $remote_addr;
}

Пояснение директив

proxy_ssl_server_name on — включает указание имени сервера при установке TLS-соединения (SNI). Необходимо, если бэкенд использует виртуальные серверы.

proxy_set_header Host ... — задаёт заголовок Host, который ожидает бэкенд (часто совпадает с именем сервера в сертификате).

Особый случай: бэкенд с самоподписанным сертификатом (только для тестов).

Добавьте в конфигурацию:

proxy_ssl_verify off;

Предупреждение

Никогда не отключайте проверку сертификатов в production. Это делает соединение уязвимым для атак man-in-the-middle.

Пример проверки (вы → Нода → HTTPS backend)
Вы можете обращаться к ноде как по HTTP, так и через внешний reverse proxy по HTTPS (сценарий 4 + сценарий 5). Сам запрос остаётся прежним:

curl -i http://<node-host>:8090/api/v1/orders

Ожидаемый результат
Нода успешно устанавливает TLS-соединение с бэкенд, передаёт запрос и возвращает ответ.

Сценарий 6. HTTPS напрямую на ноду (без внешнего прокси)¶

(Клиент → HTTPS → нода → бэкенд (HTTP или HTTPS))

Вы настраиваете саму ноду так, чтобы она принимала HTTPS-трафик, самостоятельно завершала TLS и затем (опционально) передавала его на бэкенд по HTTP или HTTPS.

Когда использовать

В простых установках, где нет отдельного reverse proxy.
Если ваша инфраструктура требует, чтобы шлюз (нода) сам работал по HTTPS.

Отредактируйте node/conf/nginx/wmx.nginx.conf: добавьте второй блок server, слушающий порт 443 с SSL, сертификаты и volume mounts.

Обратите внимание

Быстрее и безопаснее поставить внешний reverse proxy перед нодой.

Выбор сценария: таблица решений¶

Ситуация	Рекомендуемый сценарий
Тестирование в локальной сети, HTTPS не требуется	1
Бэкенд различает домены по Host header	2
Вы отправляете JSON, нужна проверка схемы	3
Production, требуется HTTPS для пользователей, нода без HTTPS	4
Бэкенд принимает только HTTPS	5
Нет возможности поставить внешний reverse proxy, нужно всё в одном контейнере	6 (с оговорками)

Устранение неполадок¶

Интерфейс не открывается¶

Проверьте:

docker compose ps
docker compose logs --tail=100 apifw-manager-ui apilb
Свободен ли порт 3001

`curl http://<manager-host>:7777/healthz` не отвечает¶

Проверьте:

Контейнер backend-nginx
Контейнер apigw
Логи apilb, apigw, authn, userm

`discovery-agent` не регистрируется¶

Проверьте:

Токен ноды
WMX_AGENT_API_HOST
TCP-доступность порта API Консоли управления
Логи discovery-agent

Через ноду идёт 502 Bad Gateway¶

Наиболее вероятная проблема в адресе защищаемого приложения wmx.nginx.conf.

Проверьте:

Правильный ли host/port бэкенд.
Доступен ли бэкенд с сервера, где работает нода.
Не осталось ли значение по умолчанию, которое не подходит.

HTTPS снаружи работает, а бэкенд за нодой нет¶

Проверьте:

Где завершается TLS (внешний proxy/Ingress или сама нода).
Правильно ли указан proxy_pass.
Нужен ли proxy_ssl_server_name on.
Не мешает ли проверка сертификата бэкенду.

Пример установки на Timeweb (домен example.ru)¶

Целевая конфигурация

https://example.ru → внешний Nginx → Нода → бэкенд (127.0.0.1:8080)
https://manager.example.ru → внешний Nginx → интерфейс Консоли управения
https://manager.example.ru/api/... → внешний Nginx → API Консоли управления

Внутри виртуальной машины:

Консоль управления слушает порты 3001 и 7777
Фильтрующая нода слушает порт 8090

DNS в Timeweb
* Создайте A-записи:
example.ru → публичный IP виртуальной машины
manager.example.ru → публичный IP виртуальной машины
Открытые порты на виртуальной машине
Откройте порты: 80, 443, 7777.
Для демо-стенда можно открыть все порты.
Размещение каталогов
```
/opt/proapi/manager
/opt/proapi/node
```
Заполнение manager/.env
```
APIFW_TAG=2.0.0
APIFW_UI_TAG=2.0.0
POSTGRES_TAG=16-alpine3.23
CLICKHOUSE_TAG=24-alpine

APIFW_LICENSE_KEY=_PUT_LICENSE_HERE_

API_BASE_URL=https://manager.example.ru/api
UI_PORT=3001 (пример)
API_PORT=7777 (пример)
```
APIFW_TAG — тег образов backend-компонентов Консоли управления.

APIFW_UI_TAG — тег образа веб-интерфейса Консоли управления.

Заполнение node/.env

APIFW_TAG=2.0.0 (пример)
APIFW_MODULE_TAG=v2.0.4 (пример)

WMX_AGENT_API_REG_TOKEN=_PUT_NODE_REG_TOKEN_HERE_
NODE_PORT=8090
WMX_AGENT_API_HOST=manager.example.ru
WMX_AGENT_API_PORT=7777 (пример)

APIFW_TAG — тег базового образа Фильтрующей ноды.

APIFW_MODULE_TAG — тег модуля Фильтрующей ноды.

Настройка адрес защищаемого приложения для example.ru
Если бэкенд на той же витуальной машине на порту 8080, в node/conf/nginx/wmx.nginx.confоставьте:
```
proxy_pass http://host.docker.internal:8080;
```

Внешний Nginx перед Консолью управления и Нодой
Используйте пример конфигурации/etc/nginx/sites-enabled/default:

server {
    listen 80;
    server_name example.ru www.example.ru manager.example.ru;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.ru www.example.ru;

    ssl_certificate /etc/letsencrypt/live/example.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.ru/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}


server {
    listen 443 ssl http2;
    server_name manager.example.ru;

    ssl_certificate /etc/letsencrypt/live/example.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.ru/privkey.pem;

    location /api/ {
        proxy_pass http://127.0.0.1:7777;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}

Получение сертификата Let's Encrypt
Установите Nginx, certbot и получите сертификат:

apt update
apt install -y nginx certbot python3-certbot-nginx
certbot --nginx -d example.ru -d www.example.ru -d manager.example.ru

Проверка после запуска
Выполните команды:
```
curl -i http://127.0.0.1:7777/healthz   # Консоль управаления
curl -i http://127.0.0.1:8090/          # Нода
curl -I https://example.ru
curl -I https://manager.example.ru
```
Если https://example.ru открывается и отсутствует ошибка 502, базовая схема работает правильно.

Установка в Docker-контейнере¶

Компоненты¶

Требования¶

Известные ограничения¶

Порядок установки¶

Инициализация данных (seed data)¶

Установка Консоли управления¶

Создание токена ноды¶

Установка фильтрующей ноды¶

Проверка работоспособности системы¶

Типовые команды¶

Быстрая проверка состояния Консоли управления¶

Быстрая проверка состояния Фильтрующей ноды¶

Просмотр логов конкретного сервиса¶

Перезапуск отдельного сервиса¶

Перечитывание конфигурации Фильтующей ноды¶

Обновление версий образов¶

Проверка получения конфигурации агентом от Консоли управления¶

Проверка доступности защищаемого приложения Консоли управления¶

Остановка стенда¶

Полная остановка с удалением данных:¶

Сценарии обработки HTTP и HTTPS трафика¶

Сценарий 1. Передача обычного HTTP-трафик без шифрования¶

Сценарий 2. Заголовок Host для виртуальных серверов бэкенда¶

Сценарий 3. POST-запрос с JSON-данными через ноду¶

Сценарий 4. HTTPS снаружи, HTTP внутри (внешний reverse proxy)¶

Сценарий 5. HTTPS-соединение ноды с бэкендом¶

Сценарий 6. HTTPS напрямую на ноду (без внешнего прокси)¶

Выбор сценария: таблица решений¶

Рекомендации по избежанию ошибок¶

Устранение неполадок¶

Интерфейс не открывается¶

curl http://<manager-host>:7777/healthz не отвечает¶

discovery-agent не регистрируется¶

Через ноду идёт 502 Bad Gateway¶

HTTPS снаружи работает, а бэкенд за нодой нет¶

Пример установки на Timeweb (домен example.ru)¶

Инициализация данных (`seed data`)¶

`curl http://<manager-host>:7777/healthz` не отвечает¶

`discovery-agent` не регистрируется¶