Skip to content

Настройка ​

Руководство по локальной настройке nxs-anomaly.

Если нужно понять, какие сущности создаются при seed-demo, как связаны алерты, группы, цепочки эскалации и уведомления, см. DOMAIN_MODEL.md.

Требования ​

  • Go 1.27
  • Node.js 22.12+ — только для локальной разработки frontend
  • Docker или доступный экземпляр PostgreSQL 14+
  • DSN PostgreSQL в переменной NXS_ANOMALY_DB_DSN

Локальная разработка ​

Запустить PostgreSQL:

bash
docker run --rm --name nxs-anomaly-postgres \
  -e POSTGRES_DB=nxs_anomaly \
  -e POSTGRES_USER=nxs_anomaly \
  -e POSTGRES_PASSWORD=nxs_anomaly \
  -p 127.0.0.1:5432:5432 \
  postgres:17-alpine

В другом терминале:

bash
export NXS_ANOMALY_DB_DSN='postgres://nxs_anomaly:nxs_anomaly@127.0.0.1:5432/nxs_anomaly?sslmode=disable'
export NXS_ANOMALY_BOOTSTRAP_ADMIN_USERNAME=admin
export NXS_ANOMALY_BOOTSTRAP_ADMIN_PASSWORD='pick a password'

# Запустить API сервер — миграции применятся автоматически
go run ./cmd/nxs-anomaly serve

На пустой базе seed-demo (без --force) добавит демо-пользователей, расписание и интеграцию — см. CLI-справочник ниже; для первого запуска это не обязательный шаг, а способ посмотреть форму продукта.

Docker Compose ​

bash
cp .env.example .env   # обязательные POSTGRES_PASSWORD и bootstrap admin — см. .env.example
docker compose up --build

.env не коммитится (.gitignore); без него docker compose up откажет сразу, назвав отсутствующую переменную, а не подставит пароль по умолчанию.

Сервисы:

СервисОписание
postgresPostgreSQL 17, данные на именованном volume pgdata
appAPI сервер (NXS_ANOMALY_START_SCHEDULER=false)
workerBackground-worker (цикл каждые 5 сек), проба /ready на :8081
frontendnginx со SPA и same-origin proxy, http://localhost:3100

pgdata переживает обычный down/up; down -v удаляет volume — это осознанный способ начать с чистого листа, а не побочный эффект перезапуска.

Проверить работоспособность:

bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8081/ready   # проба самого worker — см. «Диагностика» ниже
curl http://127.0.0.1:8080/metrics

CLI-справочник ​

bash
# API сервер
go run ./cmd/nxs-anomaly serve
go run ./cmd/nxs-anomaly serve --no-scheduler   # без встроенного планировщика
go run ./cmd/nxs-anomaly serve --port 9090       # другой порт

# Worker
go run ./cmd/nxs-anomaly run-worker              # постоянный цикл
go run ./cmd/nxs-anomaly run-worker --once       # один цикл и выйти

# Данные
go run ./cmd/nxs-anomaly seed-demo --force       # сброс + демо-данные
go run ./cmd/nxs-anomaly print-state             # дамп всех коллекций из БД в JSON

# Просмотр
go run ./cmd/nxs-anomaly history                 # история групп
go run ./cmd/nxs-anomaly history --limit 50 --severity critical
go run ./cmd/nxs-anomaly alerts                  # список алертов
go run ./cmd/nxs-anomaly notifications           # список уведомлений

# Эскалации и проверки
go run ./cmd/nxs-anomaly run-escalations         # один проход эскалаций
go run ./cmd/nxs-anomaly healthcheck             # проверить /health

Конфигурация базы данных ​

Приоритет при определении подключения:

  1. NXS_ANOMALY_DB_DSN — полный DSN (рекомендуется):

    bash
    export NXS_ANOMALY_DB_DSN='postgres://user:password@host:5432/dbname?sslmode=disable'
  2. Отдельные переменные (fallback):

    bash
    export NXS_ANOMALY_DB_HOST=127.0.0.1
    export NXS_ANOMALY_DB_PORT=5432
    export NXS_ANOMALY_DB_NAME=nxs_anomaly
    export NXS_ANOMALY_DB_USER=nxs_anomaly
    export NXS_ANOMALY_DB_PASSWORD=nxs_anomaly
    export NXS_ANOMALY_DB_SSLMODE=disable   # для production: require или строже

Параметры пула:

bash
export NXS_ANOMALY_DB_POOL_MAX=10   # максимум соединений (по умолчанию 10); worker'у нужно ≥ 3 (LISTEN + блокировка шарда + транзакция), иначе не стартует
export NXS_ANOMALY_API_READ_CONCURRENCY=5  # одновременных чтений API на процесс (по умолчанию половина пула); остальное — приёму и записи
export NXS_ANOMALY_DB_POOL_MIN=1    # минимум idle-соединений (по умолчанию 1)
export NXS_ANOMALY_DB_POOL_MAX_CONN_LIFETIME_SECONDS=3600  # макс. возраст соединения (1ч); шеддинг после failover/через LB
export NXS_ANOMALY_DB_POOL_MAX_CONN_IDLE_SECONDS=1800      # макс. простой соединения (30м)
export NXS_ANOMALY_DB_POOL_HEALTHCHECK_SECONDS=60          # период health-probe пула (1м)
export NXS_ANOMALY_DB_STATEMENT_TIMEOUT_SECONDS=30         # statement_timeout на каждое соединение (0=выкл); миграции освобождены через SET LOCAL
export NXS_ANOMALY_DB_CONNECT_MAX_WAIT_SECONDS=0           # retry подключения к БД на старте до N сек (0=fail-fast); рекомендуется >0 для serve/run-worker в k8s

NXS_ANOMALY_DB_STATEMENT_TIMEOUT_SECONDS=0 не отправляет statement_timeout вовсе. За PgBouncer это обязательно: он отвергает startup-параметры, которых нет в ignore_startup_parameters, и сервис не может подключиться. NXS_ANOMALY_DB_POOL_MIN=0 не держит idle-соединений.

PostgreSQL за PgBouncer. Поддерживается прямое подключение или PgBouncer в режиме session (pool_mode = session). Режимы transaction и statement не поддерживаются, и ни NXS_ANOMALY_DB_STATEMENT_TIMEOUT_SECONDS=0, ни больший пул этого не меняют: сервис опирается на состояние сессии:

  • миграции идут под сессионным pg_advisory_lock, с SET statement_timeout = 0 и RESET вокруг них на том же соединении;
  • worker держит сессионный pg_try_advisory_lock на шард, пока работа под ним идёт через другие соединения пула;
  • worker держит одно соединение с постоянным LISTEN для пробуждений (при его потере он опрашивает базу, но у блокировок выше запасного пути нет);
  • запросы используют кэшированные prepared statements pgx.

В режиме session каждое соединение сервиса занимает серверное соединение на всё время жизни, поэтому PgBouncer рассчитывают на сумму NXS_ANOMALY_DB_POOL_MAX по всем репликам API и worker'а (default_pool_size и max_client_conn) и задают NXS_ANOMALY_DB_STATEMENT_TIMEOUT_SECONDS=0 или добавляют statement_timeout в ignore_startup_parameters. Для prepared statements в режиме session ничего настраивать не нужно. Поддержка transaction pooling потребует перевести координацию на транзакционные блокировки или аренды и держать слушателя и миграции на отдельном прямом соединении — это GitHub #55.

0 принимается только там, где выше сказано, что он значит. Для размера пула, возраста и простоя соединения, периода health-probe (…_POOL_MAX, …_MAX_CONN_LIFETIME_SECONDS, …_MAX_CONN_IDLE_SECONDS, …_HEALTHCHECK_SECONDS), для HTTP-таймаутов и NXS_ANOMALY_SESSION_TTL_SECONDS минимум — 1: для драйвера БД и HTTP-сервера 0 значит не «выкл», а «закрывать каждое соединение» или «без таймаута». Значение, которое не разбирается или ниже минимума, заменяется значением по умолчанию, и на старте пишется invalid_setting с именем переменной.

Kafka (опционально) ​

Для включения аналитического стриминга через Kafka задайте:

bash
export KAFKA_BROKERS=kafka:9092
export KAFKA_TOPIC_ALERTS=nxs-anomaly.alerts  # по умолчанию
export KAFKA_BATCH_SIZE=100                    # по умолчанию

Per-integration топик настраивается через API (kafka_topic в теле PUT /api/v1/integrations/{id}).

Прочие env vars ​

ПеременнаяПо умолчаниюОписание
NXS_ANOMALY_ALERT_GROUP_TTL_DAYS30Архивация resolved alert_groups старше N дней
NXS_ANOMALY_CHATOPS_MESSAGES_TTL_DAYS30Архивация chatops_messages старше N дней
NXS_ANOMALY_DEAD_LETTER_WEBHOOK_URL—URL для fire-and-forget уведомления о permanently failed notifications
NXS_ANOMALY_PUBLIC_URL—Публичный адрес этой инсталляции. Нужен для кнопок Mattermost: их callback идёт на абсолютный URL
NXS_ANOMALY_MATTERMOST_ACTION_SECRET—Секрет, которым аутентифицируется нажатие кнопки в Mattermost (свои callback'и он не подписывает)
NXS_ANOMALY_SLACK_SIGNING_SECRET—Signing secret Slack: им проверяются и слэш-команды, и нажатия кнопок
NXS_ANOMALY_NOTIFY_ON_RESOLVEfalsetrue — сообщать о закрытии алерта тем, кого он разбудил. Получатели берутся из самой группы, а не из расписания: это те, кто получил уведомление, а не те, кто дежурит сейчас. Отправляется один раз на группу
NXS_ANOMALY_NOTIFICATION_MAX_RETRIES3Максимум retry для уведомлений
NXS_ANOMALY_NOTIFICATION_RETRY_DELAYS1,5Задержки retry в минутах
NXS_ANOMALY_WEBHOOK_TIMEOUT_SECONDS5Timeout исходящих HTTP-webhook запросов
NXS_ANOMALY_NOTIFICATION_DELIVERY_CONCURRENCY8Параллельных provider-вызовов на цикл доставки/ретраев (<1 — последовательно)
NXS_ANOMALY_WORKER_CYCLE_TIMEOUT_SECONDS— (выкл)Общий дедлайн одного worker-цикла; 0/не задан — без ограничения (большой бэклог доставки легитимно может быть долгим)
NXS_ANOMALY_WORKER_HEARTBEAT_URL—URL внешнего dead-man's switch (healthchecks.io, Cronitor, push-монитор Uptime Kuma). Worker делает на него GET после успешного цикла, не чаще раза в минуту; перестал приходить пинг — упал worker, его база или сеть. См. ALERTING_RULES.md
NXS_ANOMALY_NOTIFICATION_CLAIM_TIMEOUT_SECONDS300TTL claim'а доставки: уведомление в delivering/retrying дольше N сек возвращается reaper'ом в очередь. Должен превышать худшее время цикла, иначе reaper перехватит активную доставку → дубль. При <= WORKER_CYCLE_TIMEOUT сервис логирует claim_timeout_too_small на старте
NXS_ANOMALY_REOPEN_ACKED_ON_NEW_ALERTfalsetrue — новый алерт на подтверждённой группе возвращает её в open и проводит цепочку с нулевого шага. По умолчанию повторный firing подтверждение не снимает — ALERT_PROCESSING.md §3.1
NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKSfalse (в Helm-чарте true)true — блокировать исходящие webhook/issue-запросы на приватные/loopback/link-local адреса (SSRF-защита)
NXS_ANOMALY_TRUSTED_PROXIES— (в Helm-чарте приватные диапазоны)CIDR прокси, чьему X-Forwarded-For верить. Клиент — ближайший адрес вне этих диапазонов. Лимит попыток входа считается по адресу клиента: за недоверенным прокси он общий для всех, и несколько неверных паролей блокируют вход всем. Клиент, который сам находится внутри доверенного диапазона (VPN, офисная сеть, соседний под), выбирает себе адрес сам — поэтому неудачные входы дополнительно тратят бюджет на аккаунт: десять попыток с пополнением двенадцать в минуту, и его заголовком не обойти. Если API доступен из приватной сети, сузьте список до реально используемых прокси
NXS_ANOMALY_DELIVERY_PROXY_URL—Прокси для всей исходящей доставки: http/https/socks5/socks5h/tcp (прозрачный релей вида HAProxy mode tcp). Для сетей, где провайдер напрямую недоступен — PROXY.md
NXS_ANOMALY_DELIVERY_PROXY_<КАНАЛ>_URL—Прокси для одного канала (TELEGRAM, SLACK, MATTERMOST, WEBHOOK, CHATOPS, MOBILE, ISSUE, EMAIL, CALL). direct — отправлять этот канал напрямую в обход общего прокси. email и call — только socks5/tcp
NXS_ANOMALY_DELIVERY_NO_PROXY—Хосты в обход прокси (синтаксис NO_PROXY: хост или домен, домен покрывает поддомены)
NXS_ANOMALY_HTTP_READ_HEADER_TIMEOUT_SECONDS5Таймаут чтения заголовков запроса (защита от slowloris)
NXS_ANOMALY_HTTP_READ_TIMEOUT_SECONDS15Таймаут чтения всего запроса
NXS_ANOMALY_HTTP_WRITE_TIMEOUT_SECONDS30Таймаут записи ответа
NXS_ANOMALY_HTTP_IDLE_TIMEOUT_SECONDS60Таймаут keep-alive idle-соединения
NXS_ANOMALY_API_KEY—Единый admin API-ключ для /api/v1/* (для автоматизации)
NXS_ANOMALY_API_KEYS—Несколько ключей с ролью: tok1:admin,tok2:viewer. Роли: admin/editor/responder/viewer
NXS_ANOMALY_BOOTSTRAP_ADMIN_USERNAME—Break-glass админ: создаётся или повышается при каждом старте
NXS_ANOMALY_BOOTSTRAP_ADMIN_PASSWORD—Его пароль, применяется заново при каждом старте
NXS_ANOMALY_SESSION_TTL_SECONDS43200Абсолютное время жизни веб-сессии (12 ч)
NXS_ANOMALY_SESSION_COOKIE_SECUREtruefalse — только для локальной разработки по HTTP
NXS_ANOMALY_ALLOW_ANONYMOUSfalsetrue — открыть API без аутентификации (только локальная разработка)
NXS_ANOMALY_TEAM_SCOPINGfalsetrue — ограничить пользователя объектами его команд и объектами без команды
NXS_ANOMALY_AUDIT_RETENTION_DAYS0Удалять события аудита старше N дней; 0 — хранить всё
NXS_ANOMALY_NOTIFICATION_RETENTION_DAYS0Удалять завершённые уведомления старше N дней
NXS_ANOMALY_DELIVERY_ATTEMPT_RETENTION_DAYS0Удалять записи о попытках доставки старше N дней
NXS_ANOMALY_WEB_SESSION_RETENTION_DAYS0Удалять web-сессии старше N дней (в них IP и User-Agent)
NXS_ANOMALY_BLOCKED_CHANNELS—Каналы, запрещённые на уровне инсталляции, через запятую
NXS_ANOMALY_EGRESS_ALLOWLIST—Разрешённые адресаты исходящей доставки: хосты и/или CIDR
NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS_EXCEPT—Приватные адресаты, которые SSRF-гейт пропускает: хосты, суффиксы .domain, CIDR; loopback и link-local — никогда. См. SECURITY_PROFILE.md

| NXS_ANOMALY_ANALYTICS_PSEUDONYMISE | false | true — дайджест вместо user_id/team_id в аналитике |

| NXS_ANOMALY_OIDC_* | — | Вход через OIDC-провайдера; полный список — API.md |

| LOG_LEVEL | info | Уровень логирования: debug/info/warn/error. debug включает диагностические логи (escalation_skipped, delivery_attempt и др.) | | LOG_FORMAT | text | Формат логов: text или json |

Полная карта персональных данных, сроков хранения и процедур экспорта/удаления — DATA_INVENTORY.md.

Язык и часовой пояс интерфейса ​

SPA содержит каталоги ru-RU и en-US. До входа язык выбирается по настройкам браузера и сохраняется в localStorage; после входа выбор записывается также в профиль пользователя через PUT /api/v1/auth/preferences. Пустой locale означает «следовать браузеру». timezone — IANA-имя, например Asia/Novosibirsk; неизвестная зона отклоняется с HTTP 400.

Язык не задаётся переменной окружения всей инсталляции: это личная настройка. Времена расписания всегда вычисляются в timezone расписания, а отображаются в выбранной локали.

Безопасность ​

  • Аутентификация обязательна: без настроенных учётных данных /api/v1/* отклоняет все запросы. Открыть API можно только явно — NXS_ANOMALY_ALLOW_ANONYMOUS=true, и сервер предупреждает об этом при каждом старте.

  • Пользователи: вход по логину/паролю, сессия в HttpOnly-куке SameSite=Strict. Пароли — PBKDF2-HMAC-SHA256, 600 000 итераций, соль на пользователя; токен сессии хранится хешем, поэтому дамп БД не содержит рабочих сессий. Смена или сброс пароля, снятие роли и удаление пользователя завершают все его сессии.

  • Первый вход: NXS_ANOMALY_BOOTSTRAP_ADMIN_USERNAME + _PASSWORD. Пара применяется при каждом старте, поэтому она же — путь восстановления при забытом пароле; после настройки обычных учёток её стоит убрать.

  • API-ключи (автоматизация): X-API-Key или Authorization: Bearer, сравнение constant-time. Роль ключа ограничивает методы (403 при нехватке прав). Если запрос несёт и куку сессии, и ключ, побеждает сессия — в аудите останется человек, а не общий ключ.

  • SSO: authorization code + PKCE, проверка подписи id_token по JWKS, а также issuer/audience/exp/nonce. Алгоритмы none и HS-семейство отвергаются. Refresh-токены не используются: провайдер один раз подтверждает личность, дальше работает собственная сессия сервиса.

  • Профиль production — решение, а не умолчание. Под профилем production чарт отказывается рендериться, пока NXS_ANOMALY_TEAM_SCOPING не задан явно ("true" или "false"): незаданное значение приложение читает как выключенное, то есть каждый оператор видит и может разбудить всех, и нигде об этом не сказано. values-production.yaml ставит "true". Отчёт /readiness содержит проверку «Team boundaries are decided»: при выключенном скоупинге — предупреждение с прямой формулировкой последствий, при включённом — блокер, перечисляющий интеграции и расписания без команды (они видны всем, то есть это дыра ровно в той границе, которую кто-то включил). Чего скоупинг не покрывает: API-ключи глобальны.

  • Team scoping (NXS_ANOMALY_TEAM_SCOPING=true): объект без команды виден всем; объект команды — её участникам; пользователь без команд видит только объекты без команды. Админы, API-ключи и worker не ограничиваются. Уведомления скоупятся через денормализованный integration_id; delivery-attempts наследуют команду своего уведомления, поэтому скоупленному вызывающему обязателен notification_id; история (GET /api/v1/history) ограничивается на запросе групп — она инлайнит уведомления и попытки доставки, а уведомление несёт контакт человека, поэтому ограничивать её позже означало бы, что строки уже прочитаны.

  • Сессии: GET /api/v1/auth/sessions показывает, где пользователь залогинен, DELETE /api/v1/auth/sessions/{id} завершает конкретную (только свою), DELETE /api/v1/users/{id}/sessions — админский «разлогинить везде» (веб-сессии и подключённые телефоны) без сброса пароля.

  • API-ключи: запись в NXS_ANOMALY_API_KEYS без :role теперь даёт viewer, а не admin (сервер предупреждает на старте). NXS_ANOMALY_API_KEY по-прежнему admin — это и есть явный scope, записанный в имени переменной.

  • Аудит: GET /api/v1/audit (только admin), страница /audit в UI. Каждое событие несёт request_id — тот же, что в заголовке X-Request-ID и в access-логе, поэтому «всё, что сделал один запрос» — это один фильтр. Таблица append-only на уровне триггера; записываются имена изменённых полей, но не значения, чтобы секреты не появились во втором месте.

  • SSRF: NXS_ANOMALY_BLOCK_PRIVATE_WEBHOOKS=true запрещает доставку на приватные диапазоны (включая cloud metadata 169.254.169.254). Включайте в multi-tenant средах, где конфиг интеграций задаётся не доверенными операторами.

  • Probes: используйте /live для k8s livenessProbe (не трогает БД) и /health или /ready для readinessProbe (DB ping). Полная справка по API — API.md.

Smoke-тест ​

Создать демо-данные и найти ключ интеграции:

bash
go run ./cmd/nxs-anomaly seed-demo --force
go run ./cmd/nxs-anomaly print-state

Отправить webhook-алерт:

bash
curl -X POST "http://127.0.0.1:8080/integrations/v1/webhook/<key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "CPU high",
    "labels": {
      "alertname": "CPUHigh",
      "service": "api",
      "severity": "critical"
    }
  }'

Отправить payload Alertmanager:

bash
curl -X POST "http://127.0.0.1:8080/integrations/v1/alertmanager/<key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "receiver": "platform",
    "status": "firing",
    "groupLabels": {"alertname": "HighLatency"},
    "commonLabels": {"service": "api", "severity": "critical"},
    "commonAnnotations": {"summary": "API latency is high"},
    "externalURL": "https://alertmanager.example.com",
    "alerts": [{
      "status": "firing",
      "labels": {"alertname": "HighLatency", "service": "api", "severity": "critical"},
      "annotations": {"summary": "API latency is high"},
      "startsAt": "2026-05-17T01:00:00Z",
      "endsAt": "0001-01-01T00:00:00Z",
      "generatorURL": "https://prometheus.example.com/graph",
      "fingerprint": "abc123"
    }]
  }'

Посмотреть группы алертов:

bash
curl http://127.0.0.1:8080/api/v1/alert-groups

Диагностика ​

Проверить подключение к БД:

bash
go run ./cmd/nxs-anomaly healthcheck

Ответ /health содержит:

json
{
  "status": "ok",
  "db_ok": true,
  "version": "dev",
  "uptime_seconds": 42,
  "worker_cycles_completed": 8,
  "last_worker_cycle_at": "2026-05-17T12:00:00Z"
}

При статусе degraded, db_ok: false и наличии поля db_error — проблема в подключении к PostgreSQL.

worker_cycles_completed в этом ответе — счётчик процесса app, а не факт, что worker жив: при NXS_ANOMALY_START_SCHEDULER=false планировщик крутится на worker, и здесь это поле навсегда останется нулём. Проверяйте сам worker — run-worker --worker-addr :8081 и curl :8081/ready: то же поле там плюс worker_stalled, если цикл завис.

Если Docker-сборка падает из-за зависимостей — убедиться, что vendor/ актуален:

bash
go mod tidy
go mod vendor
docker build -t nxs-anomaly:local .

nxs-anomaly · Documentation