MikrotikManager/docs/netflow-agent.md

Автоматическое подключение NetFlow

mmapp-netflow-agent управляет только wg-flow на том же Debian/Ubuntu-хосте, где работает Docker Engine. Используются WireGuard ядра Linux и обычный Docker с root-правами. Rootless Docker и Docker Desktop не поддерживаются этим режимом.

Production-состав

С Compose deploy/docker-compose.cdn-mm.yml и дополнением агента работают семь контейнеров:

Контейнер	Назначение
cdn-mm-traefik	HTTPS и маршрутизация
cdnmanager	CDN Manager
mmapp-frontend	Интерфейс MM
mmapp-backend	API, настройка MikroTik и приём IPFIX
mmapp-postgres	Настройки и потоки
mmapp-updater	Существующее обновление контейнеров MM
mmapp-netflow-agent	Применение пиров WireGuard на хосте

Собственный systemd-сервис не нужен. Стандартный wg-quick@wg-flow поднимает интерфейс до Docker: backend публикует IPFIX только на его адресе.

flowchart TB
  User[Пользователь] -->|HTTPS| Proxy[Traefik]
  subgraph Host[Production Linux]
    subgraph Docker[Docker Compose]
      Proxy --> Frontend[frontend]
      Proxy --> CDN[CDN Manager]
      Frontend -->|API| Backend[backend + IPFIX collector]
      Backend --> PG[PostgreSQL]
      Backend <-->|HTTP через Unix socket bind mount| Agent[netflow-agent: host network + NET_ADMIN]
      Updater[updater] -.-> Backend
      Updater -.-> Frontend
    end
    Agent -->|atomic write| Conf[wg-flow.conf]
    Agent -->|wg syncconf| WG[wg-flow: интерфейс хоста]
    Conf --> Boot[wg-quick при загрузке]
    Boot --> WG
    WG -->|Docker UDP bind на WG-IP| Backend
  end
  Backend -->|RouterOS API| Router[MikroTik]
  Router <-->|WireGuard: внутри IPFIX| WG

Агент не обрабатывает потоки: при остановке/пересоздании контейнера интерфейс и приём IPFIX продолжают работать. NET_ADMIN вместе с host network позволяет управлять сетью хоста; API ограничено фиксированным интерфейсом и структурированными настройками. Агент не получает Docker socket, privileged, корневую ФС хоста, право загрузки модулей или TCP API.

Однократная установка

1. Обновить MM до версии с агентом. Образ агента должен быть опубликован CI в том же реестре; production-хост должен быть авторизован через docker login.

2. В «Сбор данных → NetFlow» создать ключи хоста, открыть «Файлы хоста» и скачать install-netflow-agent.sh из вкладки «Агент Docker».

3. Выполнить на Linux-хосте:

   sudo bash install-netflow-agent.sh /opt/cdn-mm
   

   Файл содержит приватный ключ. Хранить его как секрет, не коммитить. При необходимости образ можно задать явно:

   sudo MM_NETFLOW_AGENT_IMAGE=git.shx.one/denozord/mikrotikmanager-netflow-agent:VERSION \
     bash install-netflow-agent.sh /opt/cdn-mm
   

4. В MM обновить состояние хоста и применить настройки. Затем подключать jump-host из раздела трафика: пиры применяются автоматически без перезапуска WG.

Альтернатива из checkout: скачать wg-flow.conf из MM и выполнить sudo bash deploy/netflow-agent/install.sh /absolute/path/wg-flow.conf /opt/cdn-mm 4739. Третий аргумент — фактический IPFIX-порт из настроек.

Установщик сначала проверяет конфигурацию и Compose. Он сохраняет существующие пиры и делает резервную копию конфигурации; при несовпадении ключа, адреса или порта останавливается. Hooks, SaveConfig и нестандартные параметры wg-quick требуют ручной проверки и не принимаются. Интерфейс должен иметь IPv4 /24; пиры MM получают собственные /32 в этой сети.

Создаются:

• data/netflow-wireguard/wg-flow.conf и binding.json с правами 0600;
• ссылка /etc/wireguard/wg-flow.conf на постоянную конфигурацию;
• docker-compose.netflow-agent.yml, не заменяющий пользовательский override;
• drop-in /etc/systemd/system/docker.service.d/mm-netflow.conf для порядка запуска wg-quick → Docker;
• общий каталог data/netflow-agent-socket для Unix-сокета, подключённый в backend только для чтения. Bind mount сохраняет этот режим при пересоздании backend существующим updater.

Установщик однократно пересоздаёт backend и не перезапускает Docker или Traefik. Он не изменяет firewall хоста. Существующий публичный или несовместимый IPFIX bind в Compose нужно исправить перед повторным запуском. Не публиковать IPFIX на 0.0.0.0.

Эксплуатация

При следующих операциях Compose сохранять все файлы дополнений:

cd /opt/cdn-mm
docker compose -f docker-compose.yml -f docker-compose.override.yml \
  -f docker-compose.netflow-agent.yml up -d

Если docker-compose.override.yml отсутствует, убрать соответствующий -f. Установщик печатает команду для фактического набора файлов. Образ агента обновляется явно через Compose; существующий updater не включает его в автоматические цели. При пересоздании backend updater сохраняет его mounts.

Просмотр: GET /api/traffic/flow/host-status, право mm:traffic:read. Повторное применение: POST /api/traffic/flow/host-reconcile, право mm:traffic:write. Статус не содержит приватных/preshared ключей. lastHandshakeAt — Unix seconds или null; факт применения настроек не означает handshake или получение IPFIX. Время последнего IPFIX-пакета в панели относится ко всему коллектору.

Подключения и изменения настроек сериализуются PostgreSQL advisory lock. После рестарта backend повторно применяет сохранённые пиры. При конфликте или недоступности агента приложение и текущий приём продолжают работать. Если MikroTik уже настроен, но хост не применён, результат подключения содержит ok: false, stage: host-pending, hostError: нажать «Применить настройки хоста». При ошибке во время настройки роутера повторить подключение; его изменения не откатываются автоматически.

Агент сохраняет сторонние persistent и runtime-only пиры, проверяет пересечения AllowedIPs, атомарно записывает конфигурацию и применяет её через wg syncconf. При сбое восстанавливает предыдущий файл и runtime; сбой восстановления сообщается отдельно. Добавление/обновление пиров не меняет адреса, маршруты и интерфейс.

Первая версия не удаляет туннели. Адрес коллектора, префикс и порты закреплены установкой: изменение требует согласования настроек MM, WG и Compose вручную и повторного запуска установщика. Автоматическая смена адреса или ротация ключа не выполняется. Другие установки могут продолжать пользоваться ручным экспортом без FLOW_AGENT_SOCKET.

Проверки

npm --prefix backend run test:netflow-settings
npx playwright test -c playwright.netflow-agent.config.ts
python3 -m unittest discover -s deploy/netflow-agent -p 'test_*.py' -v
bash -n deploy/netflow-agent/install.sh
docker build --target test -t mm-netflow-agent-test deploy/netflow-agent
docker run --rm --cap-drop ALL --cap-add NET_ADMIN --read-only --tmpfs /tmp \
  -e FLOW_AGENT_KERNEL_TEST=1 --entrypoint python3 mm-netflow-agent-test \
  -m unittest discover -s /app -p test_agent.py -v

Последняя проверка использует отдельное сетевое пространство контейнера, проверяет настоящий kernel WireGuard, сохранение стороннего пира и неизменность интерфейса. Она не заменяет приёмку на стенде с двумя MikroTik: handshake/IPFIX от каждого, сохранение первого соединения при добавлении второго, перезапуск агента/backend и холодная загрузка Linux-хоста с проверкой UDP bind.