Версия: Последняя

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

Обзор

Платформа iQChannels поставляется в виде Docker-образа из реестра вендора:

registry.iqstore.ru/iqchannels:<тег>

Тег образа передаёт вендор. Перед установкой уточните у вендора актуальный тег сборки, соответствующий вашей лицензии. Не используйте тег latest без согласования с вендором: он может указывать на новую мажорную версию, требующую предварительной миграции данных.

Типовой состав установки:

Компонент	Где разворачивается
iQChannels — сервер приложения и веб-интерфейс	Docker-контейнер из `registry.iqstore.ru/iqchannels`
СУБД: PostgreSQL 12+ или MS SQL Server 2016+	Внешний сервер (в контейнер не входит)
Redis 8.2+	Внешний сервер (в контейнер не входит)

Внутри контейнера приложение расположено в папке /iqchannels:

bin — бинарные файлы приложения и скрипты управления;
config — конфигурационные файлы;
migrations — файлы миграций баз данных;
static — статические файлы (JavaScript, CSS, изображения);
var/run, var/log, var/upload — pid-файлы, логи и загружаемый пользователями контент.

Требования к ресурсам серверов — на странице «Требования к серверам IQChannels».

Что понадобится

Docker Engine 20.10+ и Docker Compose (подкоманда docker compose);
доступ с сервера до registry.iqstore.ru (порт 443);
учётная запись реестра — выдаётся вендором вместе с тегом сборки;
развёрнутые и доступные по сети СУБД и Redis;
свободные порты 3001 и 3002 для публикации контейнера.

Структура каталогов на сервере

Рекомендуемая раскладка:

/opt/iqchannels/
├── docker-compose.yml
├── .env                       # версия (тег) образа
├── config/
│   └── config.yaml            # конфигурация платформы
└── var/                       # внешние данные контейнера
    ├── log/                   # логи
    ├── run/                   # pid-файлы
    └── upload/                # загружаемые пользователями файлы

Важно. Папка var должна монтироваться в контейнер как внешний том. В var/upload хранятся вложения из истории сообщений: если не подключить этот том, при удалении контейнера (например, при обновлении версии) файлы будут безвозвратно потеряны.

Создайте структуру каталогов:

sudo mkdir -p /opt/iqchannels/config /opt/iqchannels/var/log /opt/iqchannels/var/run /opt/iqchannels/var/upload
cd /opt/iqchannels

Шаг 1. Авторизация в реестре

Войдите в реестр вендора учётной записью, выданной вендором:

docker login registry.iqstore.ru

Проверьте, что образ скачивается (подставьте тег, переданный вендором):

docker pull registry.iqstore.ru/iqchannels:<ТЕГ>

Шаг 2. Файл `.env`

В папке /opt/iqchannels создайте файл .env с версией образа:

IQC_TAG=<ТЕГ>

Так обновление версии сводится к смене одной строки в этом файле.

Шаг 3. Файл конфигурации `config.yaml`

Создайте config/config.yaml. Минимальный пример — PostgreSQL + Redis:

db:
  type: postgres
  connect: host=<адрес-сервера-БД> port=5432 dbname=iqchannels user=iqchannels password=<пароль> sslmode=disable
  max_idle: 4   # максимум неиспользуемых соединений в пуле
  max_open: 12  # максимум открытых соединений в пуле

redis:
  mode: single              # single | sentinel | cluster
  addr: <адрес-сервера-Redis>:6379

# Порты HTTP-серверов (по умолчанию 3001 и 3002) и CORS:
# httpd1:                      # API клиентских приложений
#   listen: ":3001"
#   allowed_origins:
#     - https://chat.example.ru
# httpd2:                      # веб-интерфейс и API операторов
#   listen: ":3002"

files:
  upload_path: "/iqchannels/var/upload"   # каталог для хранения загружаемых файлов
  max_file_size_mb: 32                     # максимальный размер вложения, МБ

Вариант для MS SQL Server:

db:
  type: mssql
  connect: sqlserver://sa:<пароль>@<адрес-сервера-БД>:1433?database=iqchannels
  max_idle: 4
  max_open: 12

Для MS SQL Server требуется уровень совместимости БД не ниже 130 (SQL Server 2016+). Подробнее — в «Требованиях к серверам».

Примечания:

Указывайте адрес БД и Redis явно (host=..., addr: ...). Внутри контейнера localhost указывает на сам контейнер, а не на сервер. Если СУБД или Redis развёрнуты на том же физическом сервере, что и контейнер, используйте IP сервера в docker-сети или host.docker.internal (см. extra_hosts в compose-файле ниже).
Для кластерной установки с Redis Sentinel используйте mode: sentinel — пример конфигурации приведён на странице «Установка в режиме кластера». Точный формат секции redis для вашей версии сверяйте с эталонным config.yaml из поставки.
Полный перечень настроек с комментариями — в эталонном config.yaml внутри поставки и в разделе «Настройки».
При необходимости хранения вложений в отдельном сетевом каталоге смонтируйте его на сервере и укажите путь в files.upload_path.

Шаг 4. Файл `docker-compose.yml`

services:
  iqchannels:
    image: registry.iqstore.ru/iqchannels:${IQC_TAG}
    container_name: iqchannels
    restart: unless-stopped
    ports:
      - "3001:3001"   # API клиентских приложений
      - "3002:3002"   # веб-интерфейс и API операторов
    volumes:
      - ./config/config.yaml:/iqchannels/config/config.yaml:ro
      - ./var:/iqchannels/var
    extra_hosts:
      # нужно, если СУБД или Redis запущены на самом сервере:
      - "host.docker.internal:host-gateway"

Альтернатива — режим network_mode: host (контейнер использует сеть хоста напрямую, порты публиковать не нужно, а localhost в config.yaml указывает на сам сервер). Выбирайте один вариант: либо ports + extra_hosts, либо network_mode: host.

Шаг 5. Запуск

docker compose up -d

Миграции базы данных выполняются автоматически при старте контейнера: команда run применяет их до запуска серверов. Отдельный шаг миграции не требуется. При первом запуске и после смены версии в логах будут строки вида Migrating... → Applying migration ...; при актуальной схеме этот этап проходит без сообщений.

Отдельная команда migrate остаётся доступной и применяется по желанию — например, чтобы выполнить миграции в окне обслуживания до подъёма новой версии:

docker compose run --rm iqchannels migrate

Проверьте, что платформа запустилась:

docker compose ps
docker compose logs -f iqchannels

В логах должны появиться строки запуска HTTP-серверов (с вашими портами из config.yaml):

INFO  httpd2/server.go  TCP server listening on 0.0.0.0:9000
INFO  httpd1/server.go  HTTP listening to :3001
INFO  httpd2/server.go  HTTP listening to :3002

Откройте веб-интерфейс по адресу: http://<адрес-сервера>:3002/

Далее перейдите к настройке приложения — раздел «Настройки».

Альтернатива: запуск без Docker Compose

Если Compose недоступен, платформу можно запустить отдельными командами docker run из той же папки /opt/iqchannels. Миграции базы данных применятся автоматически при старте.

Запуск контейнера в фоновом режиме:

docker run -d \
    --name=iqchannels \
    -p 3001:3001 -p 3002:3002 \
    -v /opt/iqchannels/config/config.yaml:/iqchannels/config/config.yaml \
    -v /opt/iqchannels/var:/iqchannels/var \
    --restart=unless-stopped \
    registry.iqstore.ru/iqchannels:<ТЕГ> \
    run

При необходимости миграции можно выполнить отдельно (например, в окне обслуживания):

docker run -it --rm \
    -v /opt/iqchannels/config/config.yaml:/iqchannels/config/config.yaml \
    -v /opt/iqchannels/var:/iqchannels/var \
    registry.iqstore.ru/iqchannels:<ТЕГ> \
    migrate

Остановка и удаление контейнера:

docker stop iqchannels
docker rm iqchannels

Внимание. Перед docker rm убедитесь, что папка /iqchannels/var примонтирована как внешний том, иначе загруженные пользователями файлы будут удалены вместе с контейнером.

Обновление версии

Предполагается, что установка выполнена по шагам выше и текущая версия запущена из /opt/iqchannels.

Получите у вендора тег новой сборки.

Сделайте резервные копии:

# вложения и логи
tar -czf /backup/var-$(date +%F).tgz -C /opt/iqchannels var

# дамп PostgreSQL
pg_dump -h <адрес-БД> -U iqchannels iqchannels > /backup/iqchannels-$(date +%F).sql

Для MS SQL Server используйте штатные средства (BACKUP DATABASE).

Остановите текущий контейнер:
```
docker compose down
```
Укажите новый тег в .env:
```
IQC_TAG=<НОВЫЙ_ТЕГ>
```
Скачайте образ:
```
docker compose pull
```
Запустите платформу: миграции новой версии применятся автоматически при старте.
```
docker compose up -d
docker compose logs -f iqchannels
```
Дождитесь в логах строк HTTP listening to :3001 и HTTP listening to :3002 и убедитесь, что контейнер не уходит в цикл перезапуска.
Убедитесь, что история сообщений и вложения открываются в веб-интерфейсе, после чего старый образ можно удалить:
```
docker image prune
```

Диагностика

Симптом	Что проверить
Контейнер циклически перезапускается, в логах `panic` / `Failed to execute ...sql`	Ошибка миграции: схема БД расходится с историей миграций (объект создан или изменён вручную). Сохраните лог, восстановите БД из бэкапа и обратитесь к вендору
Контейнер перезапускается, в логах ошибки подключения к БД	Доступность СУБД с сервера, строка `connect` в `config.yaml`, правильный `host=` (не `localhost`)
Ошибки `redis` в логах	Доступность Redis 8.2+, секция `redis` в `config.yaml`, для sentinel — совпадение `master_name`
Вложения не открываются в истории	Примонтирован ли том `var`, путь в `files.upload_path`
Веб-интерфейс недоступен	Публикация портов (`3002`), правила firewall

Логи платформы:

docker compose logs --tail 200 iqchannels

Логи приложения также пишутся в /opt/iqchannels/var/log.

Обзор​

Что понадобится​

Структура каталогов на сервере​

Шаг 1. Авторизация в реестре​

Шаг 2. Файл .env​

Шаг 3. Файл конфигурации config.yaml​

Шаг 4. Файл docker-compose.yml​

Шаг 5. Запуск​

Альтернатива: запуск без Docker Compose​

Обновление версии​

Диагностика​