Проверка системы

Около 6 мин

Проверка системы

В Stormbpmn Enterprise встроены автоматические проверки окружения: база данных, лицензия, адрес приложения, почта, файловое хранилище, выгрузка в PDF и остальные внешние сервисы. Они показывают, что подключено неверно, до того, как с этим столкнутся пользователи, и подсказывают, что исправить.

Что это даёт

Администратор видит причину сбоя на понятном языке и ссылку на нужный раздел документации.
Настройку нельзя завершить «вслепую»: пока есть красная проверка, мастер не пустит дальше.
Служба поддержки получает отчёт, по которому видно состояние инсталляции.

Где найти

Проверки доступны администратору с полными правами в двух местах:

Мастер первоначальной настройки (онбординг администратора), шаг «Проверка системы». Мастер открывается при первом входе в новую инсталляцию.
Админка → вкладка «Состояние системы» после завершения настройки. Если последняя проверка нашла ошибки, прошла давно (более 7 суток) или система обновилась до новой версии, на вкладке появляется отметка «Требует внимания» и предложение проверить систему заново.

Проверки запускаются при открытии страницы и по кнопке «Проверить снова». Все проверки идут параллельно; каждая ограничена по времени (10 секунд, для Gotenberg — 40 секунд). Если сервис не ответил за это время, проверка получает статус «Ошибка» с пометкой «не ответил за N с».

Статусы

Статус	Что означает	Блокирует завершение настройки
OK («Работает»)	Проверка пройдена	Нет
WARN («Предупреждение»)	Работает, но настройка выглядит подозрительно: скорее всего, опечатка или неудачный выбор	Нет
FAIL («Ошибка»)	Функция не работает или не будет работать	Да
SKIPPED («Не настроено»)	Необязательный сервис не подключён, проверять нечего	Нет

У каждой проверки есть краткое объяснение причины, подсказка, что исправить, ссылка «Как настроить» на раздел документации и (где это уместно) кнопка «Открыть настройку». Если для проверки есть технические подробности, их можно развернуть по ссылке «Подробнее». Рядом с настройкой указано, откуда взято значение: переменная окружения, настройка приложения или значение по умолчанию.

Какие проверки выполняются

Проверка	Что делает	Типичные причины красного статуса
База данных	Запрашивает версию PostgreSQL, кодировку базы и список расширений	База недоступна (неверный адрес, логин или пароль, сеть между контейнерами); не установлены расширения `vector`, `pg_trgm`, `pgcrypto`, `uuid-ossp`, `hstore`; кодировка базы не `UTF8`. Требования — в разделе «Требования к PostgreSQL»
Лицензия	Проверяет, что лицензионный ключ принят и привязан к этой инсталляции	Не задан `LICENSE_KEY_V2` или ключ не читается; ключ выпущен без привязки к инсталляции или для другой инсталляции; не удалось вычислить код активации. См. «Диагностика и восстановление»
Адрес приложения	Проверяет настройку `baseUrl`: по ней строятся ссылки в письмах и по ней Gotenberg открывает приложение	`baseUrl` не задан (Ошибка). Если страница администратора открыта по другому адресу, чем указан в `baseUrl`, — Предупреждение: за прокси так бывает, но чаще это опечатка
Почта (SMTP)	Подключается к SMTP-серверу (и авторизуется, если включена авторизация), письмо не отправляет. Для провайдера, отличного от SMTP (например, ListMonk), проверка не выполняется — они проверяются в собственном кабинете	Не задан `EMAIL_PROVIDER=smtp` или `SMTP_HOST`, `SMTP_PORT`, `SMTP_FROM`; сервер недоступен из контейнера Stormbpmn; неверные `SMTP_USERNAME` и `SMTP_PASSWORD`; сервер требует другой порт или шифрование
Файловое хранилище (S3)	Проверяет запись, чтение и удаление пробного файла в бакетах загрузок и импортов (и в общем бакете пользователей при `S3_SINGLE_USERS_BUCKET=true`). Если бакет создаётся на каждого пользователя, проверяет и право на создание бакетов. Затем проверяется доступ из браузера (см. ниже)	Остался адрес-заглушка вместо `S3_ENDPOINT`; неверные ключи доступа; нет прав на бакеты; бакет не существует; шлюз S3 вернул не те данные, что записаны
Выгрузка в PDF (Gotenberg)	Три шага: адрес не является публичным демо-сервисом; Gotenberg отвечает на запрос проверки состояния; Gotenberg открывает страницу приложения и возвращает PDF	Указан публичный демо-сервис `demo.gotenberg.dev`; контейнер Gotenberg не запущен или `GOTENBERG_URL` недоступен из контейнера Stormbpmn; Gotenberg жив, но не видит приложение по адресу `baseUrl` или `gotenbergOverrideBaseUrl` (другая docker-сеть, DNS, самоподписанный сертификат)
Диаграммы PlantUML	Отправляет на сервер пробную диаграмму и ждёт ответ с картинкой в формате SVG	Остался адрес-заглушка вместо `PLANTUML_SERVER`; сервер недоступен; сервер ответил ошибкой или вернул не SVG
Симуляции (DES)	Запрашивает у сервиса DES его ограничения	Не задан `DES_BASE_URL` при наличии модуля в лицензии; контейнер DES не запущен или недоступен из контейнера Stormbpmn
Голосовой ввод (storm-media)	Проверяет, что сервис распознавания отвечает	Задан адрес `stormMediaBaseUrl`, но пуст токен `stormMediaToken`; сервис недоступен из контейнера Stormbpmn (адрес указывается как корень сервиса, без `/v1`)
ИИ-модель (LLM)	Проверяет настройки языковой модели без запроса к ней; живой запрос — по отдельной кнопке	Не включена настройка `bpmnAiCompletion` или не указан адрес модели при наличии ИИ-модуля в лицензии; адрес не является URL

Обязательные и необязательные сервисы

Сервисы DES, storm-media и языковая модель необязательны, поэтому по умолчанию:

если адрес или ключи не заданы, проверка получает статус «Не настроено» и ничего не блокирует;
если адрес задан, сервис проверяется, и недоступность считается ошибкой.

Из этого правила есть исключение: если модуль входит в лицензию, подключение обязательно. Вы получили лицензию на этот модуль, поэтому незаполненные настройки считаются ошибкой, а не «не настроено»:

Имитационное моделирование (DES). Обязательно, если модуль выдан подписанным ключом LICENSE_KEY_V2. У старых ключей LICENSE_KEY (v1) признака модуля нет, поэтому для них подключение DES не требуется.
ИИ-модуль. Обязателен, если в активной лицензии включены AI-функции: должны быть включены bpmnAiCompletion и заданы адрес, токен и модель.

Сервис storm-media (голосовой ввод) в лицензии отдельным модулем не выделен и проверяется только при заданном адресе.

Проверка файлового хранилища из браузера

Сервер Stormbpmn может работать с S3 по внутреннему адресу S3_ENDPOINT, а браузер пользователя открывает файлы по ссылкам, которые вы выдаёте наружу. Если внешний адрес недоступен, на сервере всё работает, а у пользователей не открываются вложения и изображения.

Поэтому после успешной проверки S3 система кладёт в бакет загрузок пробную картинку, а страница администратора пытается открыть её из браузера по временной ссылке (она действует 10 минут). Если картинка не открылась, показывается сообщение «браузер не может открыть файлы из хранилища».

Что делать: проверьте переменную S3_EXTERNAL_ENDPOINT — это адрес, по которому браузер открывает ссылки на файлы. Если она не задана, используется S3_ENDPOINT. Адрес должен открываться с компьютеров пользователей (учтите HTTPS, имя хоста и CORS). Подробнее: «S3-хранилище для файлов».

Проверка языковой модели: платный запрос

Автоматическая проверка модели только сверяет настройки: адрес, токен и имя модели. Она может показать предупреждение:

адрес указан с /v1 (укажите корень шлюза, версию API приложение дописывает само);
не задан токен bpmnAiCompletionToken (подойдёт только шлюз без авторизации).

Эти случаи не блокируют настройку: приложение само убирает /v1, а шлюз без авторизации — допустимый вариант.

Чтобы убедиться, что модель действительно отвечает, нажмите «Проверить модель (платный запрос)». Система отправит модели короткий запрос с коротким ответом, за него провайдер возьмёт плату, поэтому автоматически он не выполняется. Модель собирается теми же настройками и тем же каналом, что и в чате, так что проверяется именно то, что будет работать у пользователей. Ограничение по времени — 20 секунд. Настройки модели описаны в статье «Настройка AI-ассистента».

Тестовое письмо

Проверка почты только подключается к SMTP-серверу. Чтобы убедиться, что письма доходят, введите адрес и нажмите «Отправить тестовое письмо». Письмо отправляется сразу, а не через очередь, поэтому причина отказа SMTP видна на месте. Успешная отправка заменяет результат проверки почты: доставленное письмо считается более сильным доказательством, чем просто подключение.

Как исправлять ошибки

Откройте карточку красной проверки, прочитайте причину и подсказку, при необходимости разверните «Подробнее».
Если значение задаётся переменной окружения, исправьте её в .env и перезапустите контейнер Stormbpmn: изменения в .env применяются только после перезапуска.
После перезапуска откройте страницу снова. В мастере настройки вы вернётесь на шаг «Проверка системы»: мастер продолжит с этого шага, начинать заново не нужно.
Если значение задаётся настройкой приложения (например, baseUrl или stormMediaBaseUrl), нажмите «Открыть настройку» — откроется админка с найденной настройкой, а перезапуск не нужен.
Нажмите «Проверить снова».

Кнопка «Скопировать отчёт для поддержки» формирует текстовый отчёт: версия и сборка, дата, адрес, результаты проверок и сведения о завершении настройки. Его можно отправить в поддержку.

Завершение настройки и красные проверки

Онбординг нельзя завершить, пока есть хотя бы одна проверка со статусом «Ошибка». Это решает сервер по последнему сохранённому отчёту (если он не старше 15 минут, иначе проверки запускаются заново), а не браузер: подменить результат на стороне страницы нельзя. Предупреждения и «Не настроено» завершению не мешают.

Кроме проверок, при завершении мастер просит указать:

дату последней проверки восстановления из резервной копии (она не может быть в будущем);
имя и email или телефон ответственного администратора;
подтверждение, что вы готовы присылать в поддержку HAR-файл, логи и тег версии при обращениях.

Обход проверок: `?skipChecks=1`

Если исправить ошибку сейчас нельзя (например, почтовый сервер подключат на следующей неделе), настройку можно завершить в обход. Для этого откройте мастер по адресу:

https://<ваш-адрес>/admin-onboarding?skipChecks=1

В этом режиме красные проверки не блокируют кнопку «Далее», а на странице появляется заметное предупреждение: «Проверки обойдены — это будет записано». Чтобы завершить настройку, нужно:

Описать причину: от 10 до 500 символов.
Подтвердить, что обращения по модулям с непройденными проверками не обслуживаются по SLA, пока проверки не исправлены.

Обход фиксируется

Сервер записывает в запись о завершении: кто завершил (email и идентификатор пользователя), когда, версию, список непройденных проверок, причину и подтверждение условия про SLA. Тот же факт попадает в журнал приложения (уровень предупреждения) и в телеметрию. Записанные значения нельзя изменить из админки.

Если ошибок нет, а мастер открыт с ?skipChecks=1, обход не понадобится, но факт запуска в этом режиме тоже будет записан.

Инсталляции, настроенные до обновления

Если онбординг был завершён до появления автопроверок, такая инсталляция считается прошедшей настройку: запись о завершении помечается как «настройка завершена до появления автопроверок» (legacy), мастер повторно не показывается. Состояние системы можно проверить в любой момент на вкладке админки «Состояние системы».

Что уходит в телеметрию

В вендорскую телеметрию (она отправляется вместе с остальными данными об инсталляции) добавляется раздел diagnostics. В нём два блока.

Последний прогон проверок:

Поле	Содержимое
`ranAt`	Время запуска
`ranBy`	Идентификатор запустившего пользователя в виде хэша
`ranByEmail`	Email запустившего администратора
`version`	Версия приложения
`checks`	Для каждой проверки: идентификатор, статус, сообщение, длительность в миллисекундах

Запись о завершении онбординга:

Поле	Содержимое
`completedAt`	Время завершения
`completedBy`	Идентификатор завершившего пользователя в виде хэша
`completedByEmail`	Email завершившего администратора
`bypassed`, `failedChecks`	Был ли обход и какие проверки были красными
`bypassReason`, `slaAcknowledged`	Причина обхода и подтверждение условия про SLA
`restoreTestedOn`	Дата последней проверки восстановления из резервной копии
`supportConfirmed`	Подтверждение готовности присылать материалы в поддержку
`responsibleContact`	Контакт ответственного администратора
`version`	Версия приложения
`legacy`	Настройка завершена до появления автопроверок

Email и контакты передаются осознанно

В отличие от остальной телеметрии, где пользователи обезличены, в этот раздел намеренно включены email администратора и контакт ответственного: поддержке нужно знать, с кем связаться по инсталляции и кто завершил настройку. Значения настроек, пароли, токены и ключи в телеметрию не попадают. Из сообщений проверок вырезаются логин и пароль в адресах.

Параметры (для администратора контейнера)

Сроки и таймауты проверок заданы в application.properties и обычно не меняются:

Параметр	Значение по умолчанию	Назначение
`storm.diagnostics.probe-timeout`	`10s`	Сколько ждём одну проверку
`storm.diagnostics.gotenberg-timeout`	`40s`	Таймаут проверки Gotenberg (дольше остальных: он рендерит страницу)
`storm.diagnostics.llm-timeout`	`20s`	Таймаут живого запроса к модели
`storm.diagnostics.report-max-age`	`15m`	Насколько свеж должен быть отчёт, чтобы завершить настройку без нового прогона
`storm.diagnostics.browser-probe-url-ttl`	`10m`	Срок действия ссылки на пробную картинку S3
`storm.diagnostics.stale-after`	`7d`	Через сколько отчёт считается устаревшим