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

Как запустить Аэрозвено у себя, проверить здоровье сервисов и найти причину типовых сбоев.

Локальный запуск

Только расчёт и проверка (без сервера)

Нужны Python 3.12 и uv.

cd src/backend
uv sync --all-packages
uv run python proto-gen/generate_stubs.py     # gRPC-стабы

uv run python -m planner run --scenario scenarios/s01-simple.json \
  --objective makespan --out /tmp/plan-s01.json
uv run python -m validator check --scenario scenarios/s01-simple.json \
  --plan /tmp/plan-s01.json

Лимит расчёта в командной строке по умолчанию — 30 с. Валидатор печатает проверки и итог «ВЕРДИКТ: план допущен» либо список нарушений.

Весь контур в Docker Compose

docker-compose.yml в корне репозитория поднимает PostgreSQL, планировщик, валидатор и gateway (порт 3000):

docker compose up -d --wait
curl -s http://localhost:3000/healthz          # {"status":"ok"}
curl -s http://localhost:3000/api/fleet | head

Swagger UI — http://localhost:3000/api/docs.

Интерфейс в режиме разработки

Нужен Node.js 24.

cd src/frontend
npm install --legacy-peer-deps
npm run dev          # http://localhost:5173

Поднимаются оболочка :5173 и модули planner :5174, validator :5175, viewer3d :5176.

Проверки здоровья

Путь	Что проверяет
GET /healthz	процесс gateway жив
GET /readyz	доступны PostgreSQL, планировщик и валидатор; иначе 503 UPSTREAM_UNAVAILABLE
GET /status	версия, коммит сборки, время старта
GET /metrics	метрики Prometheus

У планировщика и валидатора те же пути на служебных портах 3001 и 3002.

Настройки

Только имена и назначение; значения секретов в документации не приводятся.

Сервис	Переменная	Назначение
gateway	DATABASE_URL, GATEWAY_PLANS_STORAGE	база и режим хранения (postgres или memory)
gateway	PLANNER_GRPC_ADDR, VALIDATOR_GRPC_ADDR, SERVICE_API_KEY	адреса и ключ внутренних сервисов
gateway	PLAN_CONCURRENCY (2), PLAN_QUEUE_LIMIT (20), PLAN_DEFAULT_TIME_LIMIT_S (300)	очередь и лимит расчёта
gateway	WEATHER_PROVIDER	прогноз ветра (open-meteo или выключен)
gateway	LLM_PROVIDER, OPENAI_MODEL, OPENAI_BASE_URL, OPENAI_API_KEY, ASSISTANT_*	чат-ассистент (см. Чат-ассистент)
planner	PLANNER_TURN_MODEL (arc / legacy)	модель разворотов
planner	PLANNER_PROFILE_MODEL (legacy / computed)	профиль взлёта и посадки
planner	PLANNER_ANGLE_SEARCH (full / probe), PLANNER_ANGLE_WORKERS	уточнение угла галсов и число процессов
planner, validator	PLANNER_DEM_DIR, VALIDATOR_DEM_DIR	каталог цифровой модели рельефа
validator	VALIDATOR_TURN_CHECKS (fail / warn)	блокируют ли допуск проверки разворотов G5-07, G5-08

Метрики

Gateway отдаёт, среди прочего: число HTTP-запросов и их длительность, число заданий расчёта по статусам, а для ассистента — запросы к языковой модели, их длительность и токены, число шагов, вызовов инструментов и оценок. Планировщик — длительность расчёта.

Типовые сбои

Симптом	Что проверить	Что сделать
/readyz отвечает 503	какой из сервисов недоступен (поле details)	поднять PostgreSQL, планировщик или валидатор
429 QUEUE_FULL	в очереди 20 заданий	повторить через Retry-After секунд
Расчёт завершился failed с GSD_UNREACHABLE	GSD недостижим ни одним бортом	ослабить GSD, сменить нагрузку или борт (пример — демо-сценарий s08)
План «нерешаемо», покрытие меньше 99 %	нераспределённые галсы и их причины	увеличить парк, ослабить ветер, расширить разрешённое пространство, убрать конфликтующую зону
409 PLAN_NOT_READY при выгрузке	статус расчёта	дождаться completed
422 при сохранении сценария	поле errors[]: путь поля и правило	привести документ к схеме (например, оборот — turnaround_time_min, в минутах)
В плане TERRAIN_UNKNOWN	подключена ли модель рельефа	задать PLANNER_DEM_DIR и VALIDATOR_DEM_DIR
Ассистент отвечает 503	GET /api/assistant/status	включить модель (LLM_PROVIDER=openai и ключ) или пользоваться кнопкой «Подобрать вариант»
Прогресс «стоит» на «Очереди»	расчёт идёт, стадии придут в конце	дождаться; время «Идёт М:СС» растёт