Быстрый старт

Этот раздел нужен, чтобы быстро поднять рабочий контур NPPWEB локально и понять, как проверить платформу не по одному сервису, а end-to-end.

Что вы поднимаете

NPPWEB состоит из нескольких независимых, но связанных репозиториев:

Репозиторий	Роль
infra	Docker Compose-контур и env-конфигурация
contracts	общие GraphQL и event-схемы
scrape-helper	сбор данных из внешних источников
processing-worker	нормализация raw-потока и ingest
npp-backend	доменная модель, GraphQL API, отчёты, аналитика
npp-web	интерфейс пользователей, аналитиков и администраторов

Основные источники, которые сейчас предусмотрены в платформе:

• easuz
• eis
• eis_contracts
• eis_contracts_223
• rnp
• fedresurs
• fns
• gistorgi

Что нужно заранее

• Docker Desktop или Docker Engine с Compose plugin;
• Node.js 20+;
• свободные порты 3000, 3001, 8080, 15672, 9000, 9001;
• доступ к государственным площадкам напрямую или через proxy-контур;
• понимание, что часть источников может зависеть от внешних ограничений и не всегда стабильно отвечает из локального контура.

Самый короткий способ поднять всё

cd infra
cp .env.example .env
docker compose --env-file .env -f docker-compose.yml -f docker-compose.apps.yml up -d --build

Альтернатива:

make up

После этого в норме должны подняться:

• postgres
• redis
• rabbitmq
• minio
• minio-init
• backend-api
• processing-worker
• scraper-service
• frontend

Опционально:

• xray-proxy, если активирован профиль proxy

Где что открывать

Что	URL
frontend	http://localhost:8080
GraphQL backend	http://localhost:3000/graphql
backend health	http://localhost:3000/api/health
backend ready	http://localhost:3000/api/health/ready
scraper control-plane	http://localhost:3001/api/runtime-status
RabbitMQ management	http://localhost:15672
MinIO console	http://localhost:9001

Минимальный smoke-check

1. Проверить compose-статусы

cd infra
docker compose --env-file .env -f docker-compose.yml -f docker-compose.apps.yml ps

Что обычно считается нормой:

• postgres, rabbitmq, minio, backend-api, frontend — healthy
• processing-worker, scraper-service — Up
• minio-init — Exited (0)

2. Проверить backend

curl http://localhost:3000/api/health
curl http://localhost:3000/api/health/ready

3. Проверить scraper runtime

curl http://localhost:3001/health
curl http://localhost:3001/api/runtime-status

4. Проверить frontend

curl -I http://localhost:8080

Локальные учётные записи

Если backend-api поднят с seed-данными из infra, обычно доступны:

• admin@admin.ru / 12345678
• analyst@admin.ru / 12345678
• user@admin.ru / 12345678

Как проверить, что конвейер реально работает

Одного факта, что контейнеры “живы”, недостаточно. Важнее убедиться, что данные проходят весь путь:

1. scrape-helper делает запуск источника.
2. Публикуются raw-события.
3. processing-worker забирает raw-сообщения и делает нормализацию.
4. npp-backend принимает ingest.
5. npp-web показывает закупки, source runs и аналитику без пустого GraphQL-ответа.

Нормальный end-to-end запуск в NPPWEB означает не просто “контейнеры поднялись”, а следующее:

• у scraper-service есть активные источники;
• в RabbitMQ появляются raw-сообщения;
• processing-worker их подтверждает без массового роста retry/DLQ;
• backend создаёт или обновляет доменные сущности;
• frontend открывает ролевые экраны без пустых ответов и ошибок авторизации.

Практический сценарий

1. Откройте frontend и войдите под ANALYST или ADMIN.
2. Проверьте, что открываются dashboard, analytics, procurements.
3. Посмотрите jobs или административный экран запусков.
4. Подтвердите, что есть актуальные SourceRun.
5. Если нужно, триггерните один источник вручную и посмотрите, как меняются статусы.

Ручной запуск конкретного источника

Для локальной диагностики удобно использовать control API scraper-service.

Пример ручного старта eis:

curl -X POST http://localhost:3001/api/source-runs \
  -H 'content-type: application/json' \
  -d '{"sourceCodes":["eis"]}'

Пример запуска нескольких источников:

curl -X POST http://localhost:3001/api/source-runs \
  -H 'content-type: application/json' \
  -d '{"sourceCodes":["eis","rnp","fns"]}'

Это удобно, когда нужно понять, пустой экран вызван общим контуром или конкретным адаптером.

Как проверить очереди и транспортный слой

Для локальной отладки полезно сразу смотреть не только логи, но и состояние очередей.

Пример:

curl -u app:app http://localhost:15672/api/queues/%2F/source.raw.v1
curl -u app:app http://localhost:15672/api/queues/%2F/source.raw.retry.v1
curl -u app:app http://localhost:15672/api/queues/%2F/source.raw.dlq.v1
curl -u app:app http://localhost:15672/api/queues/%2F/source.normalized.v1

Интерпретация обычно такая:

• source.raw.v1 растёт и быстро уменьшается: worker успевает обрабатывать поток;
• source.raw.retry.v1 растёт: есть transient-проблемы, чаще всего ingest или инфраструктура;
• source.raw.dlq.v1 растёт: есть poison messages или сломана нормализация;
• source.normalized.v1 пополняется: события дошли до стадии успешной нормализации.

Когда нужен proxy

Часть государственных площадок может быть недоступна напрямую.

В этом случае обычно нужно:

1. создать infra/xray-local/config.json на основе config.example.json;
2. включить COMPOSE_PROFILES=proxy;
3. указать HTTP_PROXY и HTTPS_PROXY=http://xray-proxy:8080;
4. не забыть про корректный NO_PROXY для внутренних сервисов.

Для Fedresurs отдельно важно помнить:

• стабильный production-сбор больше не стоит строить на публичном HTML;
• нужен официальный API;
• для него требуются FEDRESURS_API_LOGIN и FEDRESURS_API_PASSWORD.

Если хотите запускать сервисы по отдельности

Backend

cd npp-backend
npm install
npm run db:setup
npm run start:dev

Frontend

cd npp-web
npm install
npm run dev

Scraper

cd scrape-helper
npm install
npm run start:dev

Worker

cd processing-worker
npm install
npm run start:dev

Полезная диагностика через логи

cd infra
docker compose --env-file .env -f docker-compose.yml -f docker-compose.apps.yml logs backend-api processing-worker scraper-service frontend

Для живого наблюдения:

docker compose --env-file .env -f docker-compose.yml -f docker-compose.apps.yml logs -f scraper-service processing-worker backend-api

Что особенно полезно искать:

• в scraper-service:
  • loaded enabled sources
  • source run started
  • raw event published
• в processing-worker:
  • raw event validated
  • normalized event created
  • published normalized event
  • retry scheduled
  • message dead-lettered
• в backend-api:
  • ошибки ingest;
  • ошибки auth/session;
  • проблемы Prisma и БД.

Частые первые проблемы

Симптом	Что смотреть первым
frontend не открывается	контейнер frontend, health backend, переменные Nuxt
GraphQL ошибки	backend-api logs, миграции, seed, auth
запуски есть, но новых закупок нет	scraper-service, processing-worker, RabbitMQ, ingest token
источник завершился успешно, но нашёл 0	фильтры источника, доступ к площадке, relevance-логика
артефакты не появляются	MinIO, minio-init, S3_* переменные

Минимальный принцип чтения проблем

Если после запуска что-то “не работает”, лучше идти не хаотично, а по фиксированному порядку:

1. docker compose ps
2. health / ready backend
3. runtime-status scraper-service
4. очереди RabbitMQ
5. логи processing-worker
6. GraphQL API
7. frontend

Так почти всегда быстрее видно, в каком именно слое сломался поток.

Что читать дальше

• Архитектура
• Аналитический контур
• Карта репозиториев
• Диагностика и Runbook