Диагностика и устранение неполадок

С чего начать

1. Проверьте состояние компонентов. Запрос не требует авторизации:

   curl http://localhost:3000/status

   В ответе для каждого компонента указано его состояние:

   {"core":"up","database":"up","messaging":"up","nlu":"up","nluVersion":"2.0.0","duckling":"n/a","lang":"up","languages":["en","ru"],"languagesLoading":[],"assets":"up","redis":"n/a","ready":true,"draining":false}

   Поле	Что проверяет
   core	Ядро платформы
   database	Подключение к PostgreSQL: up или error
   messaging	Сервис Messaging: up или down
   nlu	Сервер NLU: up или down. Поле nluVersion показывает его версию
   duckling	Duckling: up, down или n/a, если он отключён в настройках NLU
   lang	Языковой сервер, опрошенный напрямую: up, down или n/a, если адрес не задан. Поля languages и languagesLoading перечисляют загруженные и ещё загружаемые языки
   assets	Наличие файлов консоли (/admin) и веб-чата (/lite): up или down
   redis, cluster	Redis и число узлов в режиме кластера
   ready, draining	Узел смонтировал ботов; узел завершает работу

   /status отвечает кодом 200, пока узел готов, даже если один из компонентов недоступен: это ответ для человека. Системе мониторинга нужен GET /health: он отвечает 503 и перечисляет причины, когда компонент не работает, см. Мониторинг. Версию ядра отдаёт запрос GET /version. Те же состояния видны на цветных плашках в заголовке консоли и в верхней панели Studio.

2. Посмотрите журнал платформы.

   • Консоль: journalctl -u iqbot -f для службы systemd, docker compose logs -f iqbot для Docker.
   • Раздел «Журналы» в консоли администрирования и пункт «Посмотреть журнал» у конкретного бота.
   • Файлы журналов, если включён параметр logs.fileOutput.enabled.

3. Проверьте раздел «Готовность к продуктиву» и раздел «Языки»: они показывают самые частые ошибки конфигурации.

Таймауты и возврат на страницу входа

Признаки: действия в консоли и Studio зависают, появляется сообщение «Сервер не ответил за 20 с», страница возвращается к форме входа, в консоли браузера net::ERR_TIMED_OUT у /status, а в журнале платформы ошибок нет. Ошибка WebSocket connection ... failed в консоли браузера причиной не является: так выглядит проба перехода с обычных запросов на WebSocket, когда прокси его не пропускает. Платформа продолжает работать на обычных запросах.

Сначала выясните, отвечает ли сам сервер. На хосте, мимо прокси:

docker inspect iqbot --format 'перезапусков={{.RestartCount}} OOM={{.State.OOMKilled}} запущен={{.State.StartedAt}}'
docker stats --no-stream
free -m
while true; do curl -o /dev/null -s -w '%{time_total} %{http_code}\n' http://localhost:3000/status; sleep 2; done

То же curl повторите с адресом, который видят пользователи (https://<ваш-адрес>/status).

Что видно	Причина	Что делать
перезапусков растёт, OOM=true, или uptimeSeconds в /status снова мал, а в журнале платформы нет ни ошибки, ни остановки	Процесс завершает система при нехватке памяти: сигнал SIGKILL не оставляет записей. Пока контейнер поднимается, запросы зависают.	Освободите память или добавьте её, см. Требования к серверам. Языковой сервер держит около 1,3 ГБ на каждый язык: уберите модели языков, которые боты не используют. Проверьте dmesg -T, ищите Killed process.
Контейнер не перезапускался, но в журнале платформы есть [nlu], [studio] или [messaging] The process exited unexpectedly (signal SIGKILL)	Внутри контейнера платформы работают ещё три процесса. Если системе не хватило памяти, она останавливает самый крупный из них, а не весь контейнер: перезапуск контейнера не происходит. Платформа запускает такой процесс заново (не более двух раз подряд; процесс, проработавший десять минут, считается здоровым). Пока он поднимается, запросы к нему обрываются по таймауту.	Освободите память, см. выше.
Сразу после запуска запросы обрываются по таймауту, через минуту всё работает	Запуск занимает время: процесс ядра открывает порт, потом отвечает 503 на /status и /health, пока не смонтирует ботов, а NLU, Messaging и Studio запускаются следом и в это время нагружают процессор и память. Прокси без проверки готовности направляет пользователей на узел сразу. После перезапуска все открытые вкладки подключаются одновременно. Если языковой сервер ещё загружает язык (10–15 секунд на язык), NLU не может обучаться и распознавать.	Направляйте трафик на узел только после 200 от /health (проверка готовности в прокси или балансировщике). Для lang в compose добавьте проверку и depends_on с condition: service_healthy. Закладывайте на запуск запас процессора и памяти.
Плашка «NLU» красная, хотя процесс NLU запущен; быстрые запросы ждут несколько секунд	Сервер NLU жив, но не отвечает: загружает модели после запуска или вытеснен в своп. Платформа ждёт его не дольше 2 секунд в /status и 5–15 секунд в остальных запросах и показывает nlu: down, пока он не ответит.	Дождитесь окончания загрузки. Если состояние держится, не хватает памяти или процессора, см. выше.
Перезапусков нет, но free -m показывает почти всю память занятой и своп растёт, curl отвечает с задержкой в секунды	Узел упирается в память и своп.	То же: освободите память, остановите посторонние контейнеры, не размещайте на узле лишнего.
curl на localhost:3000 отвечает быстро, а через адрес пользователей медленно или с 502/504	Проблема в обратном прокси, балансировщике или сети.	Смотрите журнал прокси: upstream timed out, 499, 502, 504. Проверьте proxy_read_timeout (не меньше 60 с для long polling) и доступность узла из прокси.
Всё отвечает быстро, но в браузере запросы долго стоят в очереди (вкладка Network, колонка Stalled)	Браузер держит не больше шести соединений на адрес при HTTP/1.1. Без WebSocket каждая вкладка с Studio, эмулятором и консолью постоянно занимает по соединению запросом long polling, и обычным запросам не остаётся места.	Включите на прокси HTTP/2 (listen 443 ssl http2) или WebSocket (Upgrade и Connection). Пока этого нет, закройте лишние вкладки и задайте IQB_CONFIG_HTTPSERVER_SOCKETTRANSPORTS='["polling"]'.
После каждого перезапуска всех выбрасывает на страницу входа	Ключ подписи токенов (appSecret) хранится в конфигурации, а конфигурация и каталог данных не в постоянном хранилище: после перезапуска ключ создаётся заново, старые токены перестают подходить.	Храните конфигурацию в базе (IQB_IQBFS_STORAGE=database, по умолчанию при PostgreSQL) или смонтируйте каталог данных как том.
База данных отвечает медленно	Платформа не может проверить пользователя и отвечает 503. Пользователя при этом не выбрасывает на страницу входа: действие надо повторить.	Проверьте docker stats у PostgreSQL, число соединений и диск.

Чтобы такие случаи замечать сразу, поставьте оповещение на resets(process_uptime_seconds[1h]) > 0, см. Мониторинг.

Платформа не запускается

Симптом	Причина и решение
Предупреждение Configured port 3000 is already in use. Using next port available	Порт занят другим процессом. Платформа выбрала ближайший свободный, проверьте, на каком порту она слушает, и освободите нужный или задайте порт переменной PORT.
Предупреждение External URL is not configured	Не задан IQB_EXTERNAL_URL. Задайте внешний адрес, иначе ссылки и ресурсы будут некорректными.
Предупреждение You are running iQBot as a privileged user	Платформа запущена от root. Запускайте её под отдельным пользователем.
Платформа просит задать IQB_APP_DATA_PATH	У пользователя нет домашнего каталога. Задайте переменную IQB_APP_DATA_PATH с путём к каталогу данных.
Messaging завершается с сообщением ADMIN_KEY is not set	Внешнему Messaging не задан ключ администратора. Задайте ADMIN_KEY, он должен совпадать с IQB_MESSAGING_ADMIN_KEY на ядре. Когда Messaging запускает ядро, ключ задаётся автоматически.
Messaging завершается с сообщением ENCRYPTION_KEY must be 32 bytes	Ключ шифрования должен быть ровно 32 байта в base64, например openssl rand -base64 32.
Данные ботов пропали после пересоздания контейнера	Не заданы IQB_DATABASE_URL и IQB_IQBFS_STORAGE=database: платформа работала с локальным SQLite внутри контейнера.
Платформа перезапускается сама	Ядро перезапускает себя после сбоя до IQB_MAX_SERVER_REBOOT раз (по умолчанию 5). Причину ищите в журнале перед перезапуском. Автоперезапуск отключается переменной IQB_DISABLE_AUTO_RESTART.

Вход и доступ

Симптом	Причина и решение
Нет учётной записи администратора	Не заданы IQB_ADMIN_EMAIL и IQB_ADMIN_PASSWORD, а регистрация ещё не пройдена. Откройте страницу консоли и создайте учётную запись в форме первого запуска. Переменные работают только на пустой установке.
Учётная запись заблокирована	После 5 неудачных попыток вход блокируется на 15 минут. Подождите или сбросьте пароль в разделе «Пользователи».
Пользователь не видит нужный раздел	Права роли. Проверьте роль в разделе «Роли»: доступ к модулю задаётся правом module.<имя>.
В консоли красный значок «Конфигурация устарела»	Файл конфигурации изменён, а платформа ещё не перезапущена. Перезапустите сервер кнопкой в диалоге.
Пользователь потерял телефон с приложением-аутентификатором	Администратор в разделе «Пользователи» выбирает «Сбросить второй фактор»; войти можно и по одному из кодов восстановления, которые показывались при подключении.
На странице входа нет ссылки «Забыли пароль?»	Не настроена почта платформы: вкладка «Почта» в «Настройках сервера» или раздел mail главного конфига.
Вход через Keycloak или LDAP не работает	Причины и сообщения разобраны в разделе Аутентификация и единый вход; в журнале ищите sign-in failed и the directory is not available.
Проверочное письмо не доходит	Проверьте строку подключения (smtp:// или smtps://, порт, логин), сертификат сервера и правила файрвола; текст ошибки показывает кнопка «Отправить проверочное письмо».

NLU и языки

Симптом	Причина и решение
В разделе «Языки» красная плашка «Языковой сервер недоступен» (в ответе API ошибка Could not get language info: connect ECONNREFUSED)	Языковой сервер не запущен, был остановлен системой при нехватке памяти (см. следующую строку) или адрес в nlu.json (languageSources) указан неверно. Плашка показывает адрес, по которому платформа ищет сервер. Запустите сервер и нажмите «Проверить снова».
Языковой сервер завершается сообщением Killed	Системе не хватило памяти: на каждый язык нужно около 1,3 ГБ при размерности векторов 100 и около 4 ГБ при 300, см. Требования к серверам iQBot.
У бота предупреждение «Бот использует языки, которые не включены в системе NLU»	Для языка бота нет модели на языковом сервере. Положите файлы модели в каталог языкового сервера и перезапустите его.
В журнале No model found for the following languages	Для этого языка у бота нет обученной модели NLU. Запустите обучение в Studio, если языковой сервер доступен.
Модели не обучаются	Проверьте, что языковой сервер доступен (см. выше), что NLU в /status в состоянии up и что хватает памяти. Причина последней неудачи показана в Studio в окне «Результат обучения», а в журнале платформы есть строка failed on the NLU server с типом ошибки.
Обучение дошло до конца, а потом снова появилась кнопка «Обучить»; /status показывает nlu: up, lang: down	Языковой сервер остановился во время обучения. Чаще всего его завершила система из-за нехватки памяти: ищите Killed в журнале языкового сервера и OOMKilled в docker inspect. NLU помнит языки и после этого, поэтому только поле lang и плашка «Языки» показывают проблему. Запустите языковой сервер, освободите память и повторите обучение.
В журнале was interrupted, окно «Обучение прервано»	Сервер NLU остановился или перезапустился, не закончив обучение. Дождитесь, когда nlu в /status снова станет up, и запустите обучение заново.
Окно «Процесс обучения в NLU аварийно завершился»	Рабочий процесс обучения был убит: обычно не хватило памяти. Освободите память узла и повторите. Если вместе с ним упал языковой сервер, сначала дождитесь зелёной плашки «Языки».
Эмулятор в Studio открывается белым окном, в консоли браузера WebSocket failed и Timeout to acquire VISITOR ID	Обратный прокси не пропускает WebSocket. Платформа переключается на обычные запросы (long polling), плашка «Сокеты» в Studio при этом жёлтая. Включите заголовки Upgrade и Connection в прокси; при нескольких узлах включите ещё и «липкие» сессии, см. Установка в режиме кластера.
Бот отвечает «не понял» на очевидную фразу	Проверьте, что обучение NLU завершено. Если фраза подходит сразу под два ответа с близкой уверенностью (например QnA и намерение), платформа отбрасывает оба: это управляется параметром decisionMinMargin, см. Конфигурация iQBot. В панели отладки Studio у события видно решение и его причину.

Messaging и подключение к iQChannels

Симптом	Причина и решение
messaging: down в /status	Messaging не запущен: смотрите журнал ядра. При внешнем Messaging проверьте IQB_MESSAGING_ENDPOINT и доступность адреса.
Боты не монтируются, в журнале бота ошибка 401	При внешнем Messaging не совпадают IQB_MESSAGING_ADMIN_KEY на ядре и ADMIN_KEY на Messaging.
Бот не отвечает iQChannels	Проверьте шаги подключения в разделе «Подключение к iQChannels» руководства пользователя: учётную запись, платформу в сегменте и связь бота с пользователем iQChannels.

Что передать в техническую поддержку

Что в диагностическом отчёте

Отчёт — текстовый файл для службы поддержки. Его разделы:

Раздел	Что показывает
General	Версии платформы, Node.js, NLU, Studio и Messaging; время работы и память процесса; часовой пояс и время сервера; права на запись и свободное место на диске (при малом остатке строка помечена LOW)
Environment Variables	Переменные окружения платформы (IQB_*, EXPOSED_* и системные); пароли, токены и ключи скрыты
Connectivity	Подключение к базе данных: тип, версия, размер; подключение к Redis в кластере
Network Connections	Duckling, языковой сервер, шлюзы ИИ-агента (по умолчанию и каждый профиль), провайдер единого входа (OpenID Connect или LDAP) и почтовый сервер. Доступ в интернет не проверяется
Connection to Services	Studio, Messaging и NLU по всем адресам сервера
Server Health	Тот же ответ, что у /health и /status: готовность, состояние компонентов, узлы кластера, очередь запросов диалога; защищены ли метрики токеном
Authentication	Метод входа платформы, второй фактор, сброс пароля по почте, саморегистрация, число учётных записей по стратегиям и сколько из них с включённым вторым фактором
iQBot Config, Module Configuration	Главная конфигурация и настройки модулей (модули с настройками по умолчанию — одной строкой)
Bot (по разделу на каждого бота)	Статус, языки, режим ответов на вопросы внутри процесса, число процессов, намерений и файлов содержимого, последнее изменение из журнала, настройки бота
Database Tables, Migration History	Таблицы базы с приблизительным числом строк в самых больших, история миграций

Секреты скрываются по имени поля (пароль, токен, ключ, сертификат, bindCredentials, clientSecret) и в адресах с паролем (postgres://user:пароль@host). Параметр IQB_DIAG_INCLUDE_PASSWORDS=true отключает скрытие: не отправляйте такой отчёт.

Если решить вопрос самостоятельно не удалось, пришлите на support@iqstore.ru:

1. Диагностический отчёт. Нажмите «Подготовьте диагностический отчет» в разделе «Готовность к продуктиву» или выполните ./iqbot diag. Что в отчёте, см. ниже.
2. Версию платформы: ./iqbot version.
3. Ответ /status.
4. Фрагмент журнала вокруг момента ошибки (около 100 строк).
5. Описание: что делали, что ожидали и что получили, на каком боте и в какое время.