Add opt-in NPM and CrowdSec traffic map with selectable agent source

README.md

@@ -434,3 +434,71 @@ InErrors, InDroppedDma, AllocFails, SkbAllocFails и Restarts через ethtool
 
 Скрипт запускает тесты и создаёт в dist бинарник, SHA-256 и установочный архив,
 совместимые со встроенным обновлением из Gitea Releases.
+
+## Карта трафика NPM + CrowdSec (v0.20.0)
+
+Откройте **Настройки → Карта трафика**, включите страницу и выберите
+агент VM/LXC, где установлены Nginx Proxy Manager и CrowdSec. Например,
+`nginxproxymanager · VMID 102`. Необязательно выберите страну сервера для
+конечной точки линий на карте. Сохраните настройки: в шапке появится ссылка
+«Карта трафика», страница также доступна по `/traffic`.
+
+Функция **по умолчанию выключена**. Только выбранный агент получает команду
+включить сбор. При выключении или смене источника старый агент останавливает
+сбор после следующего успешного обычного отчёта; сервер сразу прекращает
+приём его событий. Выключенная страница и её API недоступны. Это глобальная
+настройка экземпляра Dashboard. Карта не создаёт общих алертов или писем.
+
+Агент автоматически обновляется вместе с Dashboard; для карты требуется
+v0.20.0 или новее. Он читает стандартные NPM access-логи из
+`/opt/npm/data/logs/*_access.log`, включая несжатые файлы ротации. Другой каталог
+задаётся переменной окружения службы `DASHBOARD_NPM_LOG_DIR`; значение `off`
+полностью запрещает сбор на конкретном агенте. Порт CrowdSec наружу открывать
+и новые API-ключи создавать не нужно: используется локальная команда
+`cscli alerts list --since 24h --limit 50 -o json` с существующими учётными
+данными машины. Права на логи и запуск cscli нужны службе агента.
+
+- Голубой: все записанные HTTP-запросы, включая обычные и локальные обращения.
+- Оранжевый: реальные (не simulated) срабатывания сценариев CrowdSec.
+- Розовый: решения CrowdSec, например ban или captcha. Это **не** счётчик
+  фактически отброшенных пакетов и не список действующих сейчас банов.
+- HTTP 401/403/502 сами по себе не считаются атакой или блокировкой.
+
+Карта показывает страны источников, живую ленту последних 100 событий,
+счётчики за последние 24 часа, уникальные IP HTTP-клиентов, график по минутам
+и средний req/s за последние 60 секунд. Есть фильтры типа события, домена и
+внешних IP, пауза и полный экран. Локальные адреса видны в ленте без страны.
+Все счётчики следуют выбранным фильтрам. Уникальный IP не равен человеку.
+
+Первое включение начинает чтение с конца логов, без импорта старых HTTP-запросов.
+Обычно обновление занимает несколько секунд; Nginx записывает запрос после
+его завершения. Это не карта открытых TCP-соединений. Позиции чтения и очередь
+до 500 событий сохраняются в `traffic-state.json` рядом с конфигом агента;
+повторы после обрыва связи устраняются на сервере. При переполнении очереди
+чтение ждёт отправки. Если за время длительного простоя логи уже сжаты или
+удалены, восстановить эти строки нельзя. Размер очереди чтения и ошибки
+парсинга отображаются на самой странице, без глобальных уведомлений.
+
+CrowdSec опрашивается каждые 15 секунд, до 50 последних alerts за 24 часа;
+при достижении лимита страница предупреждает о возможной неполноте истории.
+Связанный домен берётся из метаданных события, только если он однозначен.
+Новый ban не рисуется как новый запрос. Для наблюдения реально отброшенных
+firewall пакетов нужен отдельный источник: в этой версии его нет.
+
+В SQLite хранится до 24 часов и 200 000 событий; старые строки удаляются при
+приёме новых данных. Данные каждого выбранного агента фильтруются отдельно.
+Query string и fragment URL отбрасываются на агенте и повторно на сервере;
+заголовки, cookie и тела запросов не передаются. IP, домен и путь сохраняются.
+
+GeoIP работает локально: DB-IP Country Lite за октябрь 2026 встроена в бинарник,
+исходящие запросы с IP посетителей не выполняются. Координаты на карте — условные
+точки стран Natural Earth, а не точное местоположение посетителя. Дата базы
+видна внизу карты. Обновление базы требует нового релиза; автоматического
+скачивания нет. Лицензии и происхождение данных: `assets/NOTICE.md`.
+
+Локальный предпросмотр с явно обозначенными искусственными данными:
+
+```bash
+DASHBOARD_TRAFFIC_PREVIEW=1 go test -run '^TestTrafficPreview$' -timeout 30m
+# http://127.0.0.1:19105/traffic
+```