Установка iQBot в Docker

Инструкция описывает запуск iQBot в Docker Compose. Требования к ресурсам — в разделе Требования к серверам iQBot, установка без контейнеров — в разделе Установка iQBot на Linux.

Что входит в поставку

Образ	Что внутри
iqbot-platform:<версия>	Ядро, Studio, консоль администрирования, а также NLU и Messaging: их исполняемые файлы лежат внутри образа в каталоге /app/bin, ядро запускает их само. Образ рассчитан на Linux x64.
iqbot-nlu:<версия>	Те же NLU и языковой сервер отдельным образом. Нужен для запуска языкового сервера.
iqbot-platform/duckling	Duckling: системные сущности (время, числа, суммы, e-mail). Необязателен.

Образы и файлы языковых моделей запрашивайте в службе технической поддержки: support@iqstore.ru. Контейнеру платформы дополнительные порты не нужны: наружу открывается только порт 3000.

Состав стека

Для работы нужны три контейнера и один необязательный:

• postgres: база данных. В ней хранятся боты (при IQB_IQBFS_STORAGE=database), диалоги и модели NLU.
• lang: языковой сервер. Он читает файлы языковых моделей из каталога на хосте.
• iqbot: платформа. Внутри этого контейнера ядро запускает NLU и Messaging.
• duckling (по желанию): извлечение дат, чисел и сумм из фраз. Если он не нужен, уберите сервис и задайте IQB_MODULE_NLU_DUCKLINGENABLED: "false".

Файл docker-compose.yml

Значения в угловых скобках <> замените своими. Положите файлы языковых моделей (iqbot.ru.100.bin и iqbot.ru.bpe.model) в каталог ./lang-data рядом с файлом compose.

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: iqbot
      POSTGRES_PASSWORD: <пароль-базы-данных>
      POSTGRES_DB: iqbot
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  lang:
    image: iqbot-nlu:<версия>
    command: ["lang", "--port", "3150", "--host", "0.0.0.0", "--langDir", "/data/lang"]
    volumes:
      - ./lang-data:/data/lang
    restart: unless-stopped

  duckling:
    image: <реестр>/iqbot-platform/duckling:latest
    restart: unless-stopped

  iqbot:
    image: iqbot-platform:<версия>
    ports:
      - "3000:3000"
    environment:
      IQB_DATABASE_URL: postgres://iqbot:<пароль-базы-данных>@postgres:5432/iqbot
      IQB_IQBFS_STORAGE: database
      IQB_PRODUCTION: "true"
      IQB_EXTERNAL_URL: https://bot.example.com
      IQB_ADMIN_EMAIL: admin@example.com
      IQB_ADMIN_PASSWORD: <стойкий-пароль-администратора>
      IQB_MODULE_NLU_LANGUAGESOURCES: '[{"endpoint":"http://lang:3150"}]'
      IQB_MODULE_NLU_DUCKLINGURL: http://duckling:8000
    depends_on:
      - postgres
      - lang
      - duckling
    restart: unless-stopped

volumes:
  pgdata:

Что делают переменные платформы:

Переменная	Назначение
IQB_DATABASE_URL	Подключение к PostgreSQL. В продуктивном режиме обязательна: без неё платформа не запустится.
IQB_IQBFS_STORAGE=database	Боты и конфигурация хранятся в базе, а не в файлах контейнера. При PostgreSQL действует само, строку можно опустить.
IQB_PRODUCTION	Продуктивный режим.
IQB_EXTERNAL_URL	Внешний адрес, по которому пользователи открывают платформу.
IQB_ADMIN_EMAIL, IQB_ADMIN_PASSWORD	Создают учётную запись администратора при первом запуске. В продуктивном режиме без них первый администратор не создаётся вовсе.
IQB_MODULE_NLU_LANGUAGESOURCES	Адрес языкового сервера для NLU. Значение — JSON. Имя lang в адресе — это имя сервиса в compose.
IQB_CONFIG_HTTPSERVER_SOCKETTRANSPORTS	Необязательная. Значение '["polling"]' отключает WebSocket: нужно, если прокси перед платформой не пропускает заголовки Upgrade, см. Диагностика.
IQB_MODULE_NLU_DUCKLINGURL	Адрес сервиса Duckling, здесь имя сервиса в compose. Без Duckling уберите сервис и задайте IQB_MODULE_NLU_DUCKLINGENABLED: "false".

Платформа слушает порт 3000 на всех сетевых интерфейсах контейнера, поэтому дополнительная настройка адреса для проброса порта не нужна. Остальные настройки описаны в разделе Конфигурация iQBot.

Запуск и проверка

docker compose up -d
docker compose ps

Первый запуск занимает несколько минут: языковому серверу нужно 10–15 секунд на каждый язык, а платформа создаёт таблицы в базе. Проверьте состояние компонентов запросом с хоста:

curl http://localhost:3000/status

Все компоненты должны быть в состоянии up:

{"core":"up","database":"up","messaging":"up","nlu":"up","nluVersion":"2.0.0","duckling":"up","assets":"up"}

Для мониторинга используйте GET /health и GET /metrics, см. Мониторинг.

Затем откройте http://localhost:3000/admin/, войдите под учётной записью администратора и проверьте в разделе «Языки», что русский язык установлен, а в разделе «Готовность к продуктиву», что нужные пункты отмечены. Если языковой файл не найден или его нет, в разделе «Языки» язык не появится, а рядом с ботом отобразится предупреждение.

HTTPS

Образ не обрабатывает сертификаты. Поставьте перед контейнером iqbot обратный прокси с HTTPS (NGINX, Caddy, Traefik или балансировщик облака) и задайте IQB_EXTERNAL_URL с адресом https://.... См. Безопасность iQBot.

Прокси должен пропускать WebSocket: по нему Studio, консоль и веб-чат (эмулятор в Studio) получают события. В NGINX добавьте в location / строки

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

а в http или перед server директиву map $http_upgrade $connection_upgrade { default upgrade; '' close; }, если используете $connection_upgrade. Без этого WebSocket не открывается, и клиенты переходят на обычные запросы (long polling): всё работает, но медленнее и с большей нагрузкой. Если за несколькими узлами стоит балансировщик, ему нужны «липкие» сессии, см. Кластер с распределением нагрузки.

Обновление

1. Сделайте резервную копию базы данных, см. Резервное копирование и обновление.
2. Замените тег образа iqbot-platform (и iqbot-nlu, если он меняется) на новую версию.
3. Один раз запустите обновлённый стек с переменной IQB_AUTO_MIGRATE: "true" в окружении iqbot, чтобы платформа выполнила необходимые миграции, затем уберите её.
4. Выполните docker compose up -d и проверьте /status и работу одного бота.

Если Messaging и NLU нужны в отдельных контейнерах

По умолчанию контейнер iqbot запускает NLU и Messaging внутри себя, и для большинства установок это правильно: узел остаётся самодостаточным. Когда и зачем их выносят, описано в разделе Размещение компонентов требований к серверам.

Если решили выносить: NLU запускается из образа iqbot-nlu командой nlu --port 3200 --languageURL http://lang:3150, а ядру указывают его адрес в nlu.json ("nluServer": {"autoStart": false, "endpoint": "http://nlu:3200"}). Для внешнего Messaging ядру задают IQB_MESSAGING_ENDPOINT и IQB_MESSAGING_ADMIN_KEY, а у самого Messaging обязательны его собственные переменные ADMIN_KEY (то же значение), DATABASE_URL и рекомендуется ENCRYPTION_KEY; доставка событий в ядро настраивается дополнительно. Если каналы связи идут через iQChannels, внешний Messaging не нужен.