Конфигурация iQBot
Платформа настраивается на трёх уровнях:
| Уровень | Где задаётся | Для чего |
|---|---|---|
| Переменные окружения | Файл .env рядом с исполняемым файлом iqbot, переменные контейнера или службы | Подключение к базе, режим работы, адреса сервисов, секреты |
Главный конфиг iqbot.config.json | data/global/iqbot.config.json | Сервер, безопасность, журналы, диалоги, события |
Настройки модулей, например nlu.json | data/global/config/<модуль>.json | NLU, базовые навыки, веб-чат, тестирование |
При IQBFS_STORAGE=database файлы конфигурации лежат в базе данных, а не на диске. Правятся они в консоли администратора в разделе «Редактор кода» (главный конфиг и глобальные настройки модулей доступны только супер-администратору) или командами pullfile и pushfile, см. Командная строка iQBot.
После изменения файла конфигурации в статусной строке консоли появляется красный значок шестерёнки «Конфигурация устарела» с кнопкой перезапуска сервера. Изменения вступают в силу после перезапуска.
Переменные окружения
У каждой переменной платформы есть имя с префиксом IQB_. Исторические имена без префикса (DATABASE_URL, CLUSTER_ENABLED, REDIS_URL и другие) принимаются по-прежнему, но в новых установках используйте имена с префиксом; если заданы оба, действует значение с IQB_.
Основные
| Переменная | Историческое имя | По умолчанию | Назначение |
|---|---|---|---|
IQB_DATABASE_URL | DATABASE_URL | SQLite, только вне продуктива | Строка подключения к PostgreSQL: postgres://пользователь:пароль@хост:5432/база. В продуктивном режиме обязательна: без PostgreSQL платформа не запустится (временный обход — IQB_ALLOW_SQLITE=true). |
IQB_IQBFS_STORAGE | IQBFS_STORAGE | database при PostgreSQL, иначе disk | Где лежат боты и файлы конфигурации: в базе или на диске узла. Для нескольких серверов нужен database. |
IQB_PRODUCTION | — | false | Продуктивный режим: скрывает трассировки стека и журналы отладки, требует PostgreSQL и учётную запись администратора из переменных ниже. Эквивалент ключа запуска --production. |
IQB_EXTERNAL_URL | EXTERNAL_URL | http://localhost:3000 | Внешний адрес платформы, по которому её открывают пользователи. |
IQB_PORT | PORT | 3000 | Порт ядра. Заменяет httpServer.port. |
IQB_HOST | — | все интерфейсы | Адрес, который слушает ядро. Заменяет httpServer.host. |
IQB_ADMIN_EMAIL, IQB_ADMIN_PASSWORD | — | не заданы | Создают учётную запись администратора при первом запуске. В продуктивном режиме без них страница входа не создаёт первого администратора (иначе им стал бы любой, кто открыл её первым); временный обход — IQB_ALLOW_OPEN_REGISTRATION=true. |
IQB_AUTO_MIGRATE | AUTO_MIGRATE | false | Автоматически выполнять миграции данных при обновлении. Эквивалент ключа --autoMigrate. |
IQB_APP_DATA_PATH | APP_DATA_PATH | $HOME/iqbot | Каталог для кэшей и служебных данных. Если у пользователя, от имени которого запущена платформа, нет домашнего каталога, платформа не стартует и просит задать эту переменную. |
IQB_ENABLED_MODULES | — | все модули платформы | JSON-массив имён включённых модулей. Переопределяет список по умолчанию. |
Кластер
| Переменная | Историческое имя | По умолчанию | Назначение |
|---|---|---|---|
IQB_CLUSTER_ENABLED | CLUSTER_ENABLED | false | Обмен между узлами через Redis: задания, инвалидация кэша, события realtime, блокировки. Не включает продуктивный режим и не нужен для схемы с резервным узлом. |
IQB_REDIS_URL | REDIS_URL | — | Адрес Redis: строка redis://[:пароль@]хост:порт[/база] или JSON-массив узлов Redis Cluster. |
IQB_REDIS_SCOPE | — | — | Префикс ключей и каналов, если один Redis обслуживает несколько установок. |
IQB_REDIS_OPTIONS | REDIS_OPTIONS | — | JSON с параметрами клиента ioredis, например пароль или TLS. |
IQB_CONVERSE_MAX_IN_FLIGHT | — | 100 | Сколько сообщений узел обрабатывает одновременно. Сверх лимита ответ 503 с Retry-After. 0 снимает лимит. |
IQB_DRAIN_TIMEOUT_MS | — | 15000 | Сколько узел ждёт завершения принятых сообщений при остановке, прежде чем выйти. |
Подробности — в разделе Кластер с распределением нагрузки.
Messaging и NLU
| Переменная | Историческое имя | Назначение |
|---|---|---|
IQB_MESSAGING_ENDPOINT | MESSAGING_ENDPOINT | Адрес внешнего Messaging. Если не задан, ядро запускает Messaging само. |
IQB_MESSAGING_ADMIN_KEY | MESSAGING_ADMIN_KEY | Ключ администратора внешнего Messaging, должен совпадать с ADMIN_KEY на стороне Messaging. |
IQB_MESSAGING_LOGGING_ENABLED | MESSAGING_LOGGING_ENABLED | Включает подробные журналы Messaging. |
IQB_MODULE_NLU_* | — | Настройки модуля NLU, см. ниже. |
Сеть и безопасность
| Переменная | Историческое имя | Назначение |
|---|---|---|
IQB_REVERSE_PROXY | REVERSE_PROXY | true, IP-адрес или имя хоста, если платформа стоит за обратным прокси. |
IQB_PROXY | — | Прокси для обращений платформы к внешним сервисам, например http://пользователь:пароль@хост:порт. |
IQB_HTTP_DISABLE_GZIP | — | Отключает сжатие ответов. |
IQB_DISABLE_SERVER_CONFIG | — | Отключает API serverConfig, которое может отдавать чувствительные данные. |
IQB_DISABLE_SERVER_DIAG | — | Отключает создание диагностического отчёта через API. Команда diag и переменная IQB_DIAG продолжают работать. |
IQB_METRICS_TOKEN | — | Если задан, GET /metrics требует заголовок Authorization: Bearer <токен>, см. Мониторинг. |
Надёжность и производительность
| Переменная | По умолчанию | Назначение |
|---|---|---|
IQB_DISABLE_AUTO_RESTART | false | Отключает автоматический перезапуск ядра после сбоя. |
IQB_MAX_SERVER_REBOOT | 5 | Максимальное число автоматических перезапусков. |
IQB_FAILSAFE | false | Не завершать процесс при неперехваченной ошибке. |
IQB_MAX_MEMORY_CACHE_SIZE | 1gb | Максимальный размер кэша в памяти процесса. |
IQB_IQBFS_MAX_FILE_SIZE | 100mb | Максимальный размер файла в хранилище IQBFS. |
IQB_IQBFS_UPLOAD_CONCURRENCY | 50 | Максимум одновременных загрузок в IQBFS. |
IQB_CODE_EDITOR_DISABLE_UPLOAD | false | Отключает загрузку файлов в редакторе кода. |
IQB_CODE_EDITOR_DISABLE_ADVANCED | false | Отключает расширенный режим редактора кода. |
Отладка
| Переменная | Назначение |
|---|---|
DEBUG | Области отладки, например iqbot:dialog:*,iqbot:nlu:*. |
IQB_DEBUG_IO | Включает замер времени обработки входящих и исходящих событий. |
IQB_DIAG | true запускает платформу в режиме диагностического отчёта вместо обычного запуска. |
IQB_DIAG_INCLUDE_PASSWORDS | true отключает скрытие паролей и секретов в отчёте. Такой отчёт нельзя отправлять в поддержку. |
Не отключайте песочницу
Переменные DISABLE_GLOBAL_SANDBOX, DISABLE_BOT_SANDBOX, DISABLE_TRANSITION_SANDBOX и DISABLE_CONTENT_SANDBOX выполняют код ботов вне изолированной среды. Это ускоряет работу, но снимает защиту. В продуктиве их включать не нужно.
Главный конфиг iqbot.config.json
Сервер читает главный конфиг при запуске. Если файл изменили, пока сервер работает, в правом нижнем углу консоли и Studio появляется красная шестерня. Подсказка по ней и окно, которое открывается по нажатию, перечисляют изменённые параметры по именам (например, mail.transport), без значений, чтобы пароли не попадали на экран. Изменения вступают в силу после перезагрузки сервера: кнопка «Перезагрузить сервер» в окне перезапускает процесс, страница обновится сама. Если вернуть файл к исходному виду, шестерня исчезнет. Тот же список отдаёт запрос GET /api/v2/admin/management/configHash в поле changedKeys.
Любой параметр главного конфига можно переопределить переменной окружения IQB_CONFIG_<ПУТЬ>: имя пути записывается заглавными буквами, точки заменяются подчёркиваниями. Например, httpServer.cors.enabled задаётся как IQB_CONFIG_HTTPSERVER_CORS_ENABLED=false, а decisionMinMargin как IQB_CONFIG_DECISIONMINMARGIN=0.1. Значение разбирается как JSON, поэтому числа, true/false и массивы задаются как обычно, остальное считается строкой.
Основные параметры. Время и размеры записываются в формате 10s, 25m, 2 weeks, 25mb.
Сервер
| Параметр | По умолчанию | Назначение |
|---|---|---|
httpServer.host | localhost | Значение localhost не ограничивает доступ: платформа слушает все интерфейсы. Чтобы слушать только локальный адрес, задайте 127.0.0.1. |
httpServer.port | 3000 | Порт ядра. Если порт занят, платформа выберет следующий свободный и напишет предупреждение. |
httpServer.externalUrl | не задан | Внешний адрес платформы, то же, что EXTERNAL_URL. |
httpServer.bodyLimit | 10mb | Максимальный размер тела запроса. |
httpServer.socketTransports | ["websocket","polling"] | Транспорты соединения в реальном времени (прогресс обучения, события Studio, эмулятор). Если обратный прокси не пропускает WebSocket, задайте IQB_CONFIG_HTTPSERVER_SOCKETTRANSPORTS='["polling"]': браузеры не будут пытаться открыть WebSocket и сразу работают через обычные запросы (long polling). Когда прокси начнёт пропускать WebSocket, уберите переменную. |
httpServer.cors.enabled | true | Политика CORS. По умолчанию разрешены запросы из любого источника. |
httpServer.cors.origin | не задан | Разрешённый источник. |
httpServer.rateLimit.enabled | false | Ограничение числа запросов с одного IP. |
httpServer.rateLimit.limit и limitWindow | 600 за 30s | Порог ограничения. Учитывает запросы админки, Studio и чата. |
httpServer.session.enabled | false | Серверные сессии. |
httpServer.headers | {"X-Powered-By": "iQBot"} | Заголовки, которые добавляются ко всем ответам. |
Безопасность и доступ
| Параметр | По умолчанию | Назначение |
|---|---|---|
superAdmins | заполняется при первом входе | Список супер-администраторов: адрес электронной почты и стратегия входа. Первый зарегистрированный пользователь добавляется автоматически. |
authStrategies | {"default": {"type": "basic"}} | Способы входа: базовая стратегия, OpenID Connect (oauth2), LDAP. Параметры каждого типа описаны в разделе Аутентификация и единый вход. |
authStrategies.default.options.twoFactor | off | Второй фактор базовой стратегии: off, optional, required. |
collaboratorsAuthStrategies | ["default"] | Метод входа платформы: первая стратегия списка — единственная, через которую можно войти; остальные элементы сохраняют лишь доступ ранее созданных пользователей к пространствам. |
externalAuth | выключена | Проверка конечных пользователей (клиентов чата) по JWT из внешней системы: enabled, ключ проверки подписи или адрес JWKS, допустимые алгоритмы. Данные из токена доступны ботам в event.credentials. |
branding.admin, branding.studio, branding.webchat | iQBot | Название во вкладке браузера (title), значок (favicon) и свой файл стилей (customCss) консоли, Studio и веб-чата. |
mail.transport, mail.from | не заданы | Исходящая почта платформы (ссылки для сброса пароля): строка SMTP или объект nodemailer и адрес отправителя. Задаются и на странице «Настройки сервера». |
authStrategies.default.options.maxLoginAttempt | 5 | Число неудачных попыток входа до блокировки. |
authStrategies.default.options.lockoutDuration | 15m | Длительность блокировки после неудачных попыток. |
authStrategies.default.allowSelfSignup | false | Разрешена ли самостоятельная регистрация. |
jwtToken.duration | 1h | Срок действия токена доступа к консоли и Studio. |
jwtToken.allowRefresh | true | Обновлять токен каждые 5 минут, пока пользователь в системе. |
jwtToken.useCookieStorage | false | Хранить токен в защищённом cookie, а не в localStorage браузера. |
allowServerReboot | true | Разрешить супер-администратору перезапускать сервер из консоли. В продуктиве рекомендуется отключить. |
fileUpload.maxFileSize | 25mb | Максимальный размер загружаемого медиафайла. |
fileUpload.allowedMimeTypes | изображения, аудио, видео, PDF | Разрешённые типы загружаемых файлов. |
Журналы и события
| Параметр | По умолчанию | Назначение |
|---|---|---|
logs.dbOutput.expiration | 2 weeks | Срок хранения журналов в базе данных. |
logs.fileOutput.enabled | false | Писать журналы в файлы, новый файл каждый день. |
logs.fileOutput.folder | ./ | Каталог файлов журнала. |
logs.fileOutput.maxFileSize | 10000 | Размер файла журнала в килобайтах, после которого начинается новый. |
eventCollector.enabled | true | Сохранять входящие и исходящие события в базе. Нужно ряду разделов Studio. |
eventCollector.retentionPeriod | 30d | Срок хранения событий. |
eventCollector.ignoredEventTypes | ["visit","typing"] | Типы событий, которые не сохраняются. |
botMonitoring.enabled | true | Накопление ошибок ботов для хука OnBotError. |
Диалог
| Параметр | По умолчанию | Назначение |
|---|---|---|
dialog.timeoutInterval | 25m | Через сколько без активности пользователь возвращается в начало процесса. |
dialog.sessionTimeoutInterval | 30m | Через сколько без активности сессия и её переменные удаляются. |
decisionMinMargin | 0.15 | Минимальный отрыв лучшего ответа от второго. Если разрыв меньше, оба отбрасываются и бот отвечает как на непонятную фразу. Значение 0 отключает проверку. |
noRepeatPolicy | false | Не повторять ответ бота, если он уже недавно его давал. |
autoRevision | false | Автоматически сохранять ревизию бота при изменении или смене стадии. |
botCategories | [] | Категории, в которых можно создавать ботов. |
showPoweredBy | true | Показывать подпись в веб-чате. |
additionalLanguages | [] | Дополнительные языки для перевода бота сверх установленных на языковом сервере. |
Настройки бота (bot.config.json)
Файл лежит в каталоге бота (data/bots/<бот>/bot.config.json) и правится в Studio в разделе «Настройка». Параметры, которых нет в интерфейсе:
| Параметр | По умолчанию | Назначение |
|---|---|---|
qna.disabled | false | Отключает базу вопросов-ответов бота. |
qna.answerInsideFlow | false | Отвечать на вопросы из базы знаний, пока процесс ждёт реплику клиента; процесс остаётся на том же звене. В Studio: переключатель «Вопросы-ответы внутри процесса». |
converse.timeout | 5s | Сколько ждать ответа бота на одно сообщение через Converse API; дольше — ответ 504. |
converse.bufferDelayMs | 100 | Пауза после ответа бота на запоздавшие реплики. |
Настройки модулей
Настройки модуля читаются слоями, каждый следующий слой перекрывает предыдущий:
- значения по умолчанию из схемы модуля;
- глобальный файл
data/global/config/<модуль>.json; - переменные окружения
IQB_MODULE_<МОДУЛЬ>_<ПАРАМЕТР>; - файл настроек конкретного бота
data/bots/<бот>/config/<модуль>.json.
Имя переменной окружения составляется из имени модуля и пути параметра заглавными буквами, всё, кроме букв и цифр, заменяется подчёркиванием. Значение разбирается как JSON. Примеры: IQB_MODULE_NLU_DUCKLINGENABLED=false, IQB_MODULE_NLU_LANGUAGESOURCES=[{"endpoint":"http://localhost:3150"}].
NLU (nlu.json)
| Параметр | По умолчанию | Назначение |
|---|---|---|
nluServer | {"autoStart": true} | Запускать ли NLU вместе с ядром. Чтобы подключиться к уже запущенному серверу: {"autoStart": false, "endpoint": "http://хост:3200"}. |
languageSources | [{"endpoint": "http://localhost:3150"}] | Адрес языкового сервера (и authToken, если сервер запущен с --authToken). Редактируется на странице «Настройки сервера». |
ducklingEnabled | true | Использовать Duckling для системных сущностей. Если Duckling не установлен, задайте false. |
ducklingURL | http://localhost:8000 | Адрес Duckling (образ iqbot-platform/duckling). |
modelCacheSize | 850mb | Размер кэша обученных моделей в памяти. |
maxTrainingPerInstance | 1 | Сколько обучений может идти одновременно. |
queueTrainingOnBotMount | false | Ставить ли в очередь обучение ботов, требующих его, при запуске. |
Базовые навыки (basic-skills.json)
| Параметр | По умолчанию | Назначение |
|---|---|---|
defaultGptUrl | http://127.0.0.1:8001/v1/chat/completions | Адрес языковой модели для звена «ИИ-агент» по умолчанию. |
defaultGptModel | Qwen3-8B | Название модели по умолчанию. |
gptProfiles, defaultGptProfile, defaultGptTimeoutMs | {}, "", 60000 | Профили шлюзов для звена «ИИ-агент», см. ИИ-агент на основе GPT. Редактируются на странице «Настройки сервера» консоли. |
transportConnectionString | <<change me>> | Подключение к почтовому серверу для звена отправки письма, строка в формате SMTP. |
defaultMaxAttempts | 3 | Число попыток при выборе варианта в звене «Выбор». |
Тестирование (testing.json)
| Параметр | По умолчанию | Назначение |
|---|---|---|
scenarioTimeout | 5000 | Сколько миллисекунд сценарий может ждать ответа бота, прежде чем считаться проваленным. |
Веб-чат (channel-web.json)
Основные параметры: recentConversationLifetime (по умолчанию 6 hours, время, в течение которого возвращающийся пользователь продолжает прежний разговор), startNewConvoOnTimeout (false), maxMessageLength (360), параметры загрузки файлов, в том числе в S3 (uploadsUseS3, uploadsS3Bucket и другие).