Chatballs

Chatballs

ИИ-платформа клиентской поддержки

ИИ-платформа, которая ведёт диалоги с клиентами вместо вас: отвечает в мессенджерах, почте и на сайте и передаёт сотрудникам только сложные вопросы.

English version

Self-hosted Docker Compose Bring your own model License: AGPL-3.0

--- ## Содержание - [Что это](#что-это) - [Установка](#установка) - [Требования](#требования) - [Шаг 1. Запуск](#шаг-1-запуск) - [Шаг 2. Мастер первого запуска](#шаг-2-мастер-первого-запуска) - [Шаг 3. Настройка в интерфейсе](#шаг-3-настройка-в-интерфейсе) - [Виджет на сайте](#виджет-на-сайте) - [Звонки через relay (опционально)](#звонки-через-relay-опционально) - [Внешнее хранилище файлов (опционально)](#внешнее-хранилище-файлов-опционально) - [Обновление](#обновление) - [Функции](#функции) - [Решение проблем](#решение-проблем) - [Лицензия](#лицензия) --- ## Что это Chatballs берёт на себя первую линию общения с клиентами. ИИ-агент отвечает по вашей базе знаний в Telegram, MAX, электронной почте и в чате на сайте. Когда агент не уверен в ответе или клиент просит человека, диалог уходит вашим сотрудникам вместе с уведомлением. Платформа ставится на ваш сервер одной командой. Данные клиентов остаются у вас. ИИ-модель вы подключаете сами по своему ключу и сами задаёте бюджет. --- ## Установка ### Требования | | | |---|---| | **Сервер** | Linux, x86_64 | | **ПО** | Docker и плагин Docker Compose | | **Порты** | 80 и 443 открыты | | **Relay для звонков (опционально)** | Выделенный публичный IP, порт 3478 и диапазон UDP 49160–49999 | Домен на старте не нужен. Установка открывается по IP-адресу сервера, домен задаётся позже в настройках. ### Шаг 1. Запуск Скачайте `compose.yaml` со страницы релиза и поднимите стек: ```bash curl -fsSL https://github.com/dartdavros/chatballs/releases/latest/download/compose.yaml -o compose.yaml ``` ```bash docker compose up -d --wait ``` Больше ничего настраивать не нужно. Файла `.env` у продукта нет: секреты установки генерируются при первом запуске и хранятся в томе Docker. Всё остальное настраивается в интерфейсе. Что происходит при первом запуске: 1. Генерируются секреты установки: ключ подписи, пароли ролей базы данных, ключ шифрования, секрет TURN. 2. Поднимаются PostgreSQL с pgvector и Redis. 3. Выполняются миграции базы. 4. Стартуют приложение, фоновый воркер, фронтенд и шлюз Caddy. ### Шаг 2. Мастер первого запуска Откройте в браузере `http:///`. Мастер попросит: - название организации; - имя, почту и пароль владельца; - поставить ли демо-данные, чтобы посмотреть продукт на примере. После этого вы сразу оказываетесь в системе как владелец. ### Шаг 3. Настройка в интерфейсе Всё дальнейшее делается в разделе **Настройки**. | Раздел | Что сделать | |---|---| | **Платформа** | Укажите домен установки. Шлюз сам выпустит сертификат Let's Encrypt и переведёт работу на HTTPS. Здесь же задаётся исходящая почта по SMTP: она нужна для приглашений сотрудников и восстановления паролей. | | **Интеграции** | Подключите провайдера ИИ-моделей: OpenRouter, любой OpenAI-совместимый сервис или локальную модель. Для первого знакомства есть демо-провайдер, которому не нужен ключ. Затем подключите точки входа: бота Telegram, бота MAX, почтовый ящик по IMAP/SMTP или веб-виджет для сайта. | | **Агенты** | Создайте ИИ-агента: кто он, как говорит, по каким правилам работает. Выберите модель и дневной бюджет. Прикрепите статьи из базы знаний. | | **Сотрудники** | Пригласите команду по почте, распределите роли и группы. | На главном экране есть чек-лист запуска: создать агента, подключить точку входа, пригласить сотрудников. ### Виджет на сайте После создания веб-виджета вставьте на сайт один тег: ```html ``` Чат откроется в изолированном окне поверх сайта. ### Звонки через relay (опционально) Аудио- и видеозвонки работают напрямую между браузерами. Если клиенты или сотрудники сидят за строгим NAT или корпоративным файрволом, включите TURN-relay: ```bash COMPOSE_PROFILES=calls CHATBALLS_CALL_TURN_REALM=<домен> CHATBALLS_TURN_EXTERNAL_IP=<публичный IP> CHATBALLS_TURN_LISTENING_IP= docker compose up -d --wait ``` Relay слушает выделенный IP, чтобы порт 443 не конфликтовал с веб-шлюзом. Сертификат для TURN-over-TLS кладётся в каталог, заданный переменной `CHATBALLS_TURN_CERTS_DIR`. Адреса TURN затем указываются в **Настройки → Коммуникации**. ### Внешнее хранилище файлов (опционально) По умолчанию файлы хранятся в томе Docker. В **Настройки → Хранилище** можно переключить установку на любое S3-совместимое хранилище. Уже загруженные файлы переносятся автоматически. ### Обновление Скачайте `compose.yaml` нового релиза поверх старого и повторите запуск: ```bash docker compose pull && docker compose up -d --wait ``` Миграции выполняются автоматически. Секреты и данные остаются в томах. --- ## Функции ### ИИ-агент отвечает клиентам сам Настраивается за минуты: кто он, как говорит, по каким правилам работает. Отвечает только по вашим знаниям и не выдумывает. Если данных нет, честно говорит об этом и предлагает позвать сотрудника. ### Умная передача человеку Когда агент не находит ответа или клиент просит живого сотрудника, диалог сразу уходит операторам с уведомлением. У каждого диалога три режима: отвечает ИИ, отвечает сотрудник, пауза. ### Все каналы в одном окне Telegram, MAX, электронная почта и чат на сайте попадают в единый список диалогов. Сотрудник видит, откуда пришёл клиент, и отвечает в том же канале. ### База знаний с семантическим поиском Статьи, категории, импорт из файлов, вложения. Агент находит нужное по смыслу, а не только по совпадению слов. Если провайдер не даёт эмбеддинги, поиск работает по тексту без потери функциональности. ### Публичный центр помощи Портал с вашими статьями на своём домене и в своём оформлении. Категории, ревизии статей, оценка полезности от читателей. Агент отвечает по тем же статьям: правка статьи сразу меняет ответы бота. ### Чат на сайте одним тегом Виджет ставится одной строкой кода и работает в изолированном окне. Голосовые сообщения, файлы, звонки. Ограничение по доменам и защита от злоупотреблений настраиваются в интерфейсе. ### Аудио- и видеозвонки из чата Клиент и сотрудник созваниваются прямо из диалога без сторонних сервисов. Работает в веб-виджете, Telegram и MAX. Для сложных сетей есть relay. ### Рабочее место оператора Приоритеты, цветные метки, заметки к диалогу, назначение на сотрудника, шаблоны ответов. Голосовые сообщения с расшифровкой по кнопке. Файлы и картинки. Уведомление звуком о новом сообщении. ### Единая карточка клиента Один человек из разных каналов собирается в один профиль. Дубли сливаются вручную с указанием причины и возможностью отката. Список клиентов выгружается в CSV. ### Команда и доступы Роли владельца, администратора и сотрудника. Приглашения по почте. Группы видимости: сотрудник видит диалоги своих групп и те, где он ответственный. Двухфакторная защита по TOTP. Полный журнал действий с фильтрами. ### Уведомления сотрудникам в мессенджер Ждущие диалоги и новые сообщения приходят сотруднику в Telegram или MAX. Привязка делается из профиля одноразовым кодом. ### Свой сервер и своя ИИ-модель Ставится одной командой, данные остаются у вас. Подключаете любого провайдера ИИ-моделей по своему ключу: OpenRouter, OpenAI-совместимый сервис, локальная модель. Дневной бюджет на агента в долларах, учёт токенов и стоимости по каждому вызову. ### Защита данных клиентов Телефоны, адреса почты и длинные числовые идентификаторы вырезаются из текста перед отправкой в ИИ-модель. Токены интеграций, пароли SMTP, ключи S3 и секреты TOTP хранятся в базе в зашифрованном виде. --- ## Решение проблем
Стек не поднимается: порт 80 или 443 занят Шлюз публикует порты 80 и 443. Освободите их или привяжите шлюз к конкретному IP через переменную `CHATBALLS_WEB_LISTENING_IP`.
Установка открывается по IP, но не по HTTPS Это нормально до того, как задан домен. Укажите домен в **Настройки → Платформа**. Убедитесь, что DNS-запись домена ведёт на сервер, а порты 80 и 443 доступны снаружи: без этого сертификат не выпустится.
После смены домена сертификат не выписывается Сертификаты выпускаются по требованию, при первом обращении к домену. Откройте домен в браузере и подождите несколько секунд. Если не помогло, посмотрите журнал шлюза: ```bash docker compose logs gateway ```
Мастер первого запуска говорит «Первый запуск уже выполнен» Организация уже создана. Войдите по адресу установки под учётной записью владельца. Если пароль утерян, воспользуйтесь восстановлением по почте: для этого должна быть настроена исходящая почта.
Приглашения и письма не уходят Проверьте SMTP в **Настройки → Платформа**. Там есть кнопка отправки тестового письма. Типичные причины: не тот порт, выключенный TLS, пароль приложения вместо пароля учётной записи.
Агент не отвечает клиентам Проверьте по порядку: 1. Агент в статусе **Активен**, а не **Черновик**. 2. У агента выбран провайдер ИИ-моделей. Без него ответ невозможен. 3. Провайдер в **Интеграциях** имеет статус **Подключено**. Нажмите проверку, чтобы обновить статус. 4. Не исчерпан дневной бюджет агента. Заблокированные вызовы видны в учёте ИИ. 5. Диалог не переведён в режим **Оператор** или **Пауза**.
Интеграция в статусе «Ошибка» Откройте интеграцию и нажмите проверку. Для ботов частая причина: неверный токен или недоступный прокси. Для почты: неверные параметры IMAP или SMTP. Ошибки интеграций также приходят уведомлением.
Сообщения из Telegram или MAX не приходят Фоновый воркер опрашивает ботов. Проверьте, что он запущен: ```bash docker compose ps worker ``` ```bash docker compose logs worker ```
Звонки не соединяются Между браузерами звонок идёт напрямую. Если одна из сторон за строгим NAT, нужен relay: включите профиль `calls` и укажите адреса TURN в **Настройках**. Проверьте, что на файрволе открыты порт 3478 и диапазон UDP 49160–49999. Убедитесь, что relay слушает отдельный IP и не пересекается с веб-шлюзом по порту 443.
Миграции падают с ошибкой «must be owner of table» Права на объекты схемы принадлежат другой роли. Нормализуйте владение и повторите миграции: ```bash docker compose exec -T postgres psql -v ON_ERROR_STOP=1 -U chatballs_bootstrap -d chatballs -f /chatballs-reassign-ownership.sql ``` ```bash docker compose run --rm init ```
Файлы не загружаются или не открываются При локальном хранении файлы лежат в томе `chatballs-media`. Проверьте свободное место на диске. При S3 откройте **Настройки → Хранилище**: там отображается последняя ошибка подключения и статус переноса.
Виджет не появляется на сайте Проверьте, что виджет в статусе **Опубликован**, а домен сайта добавлен в список разрешённых. Ключ в атрибуте `data-widget-key` должен совпадать с ключом из настроек виджета.
Как проверить, что всё работает ```bash docker compose ps ``` Все сервисы должны быть в состоянии `healthy` или `running`. Готовность приложения проверяется по адресу `/api/v1/health/ready/`.
Не удаляйте том с секретами В томе `chatballs-secrets` лежит ключ шифрования. Без него станут нечитаемы токены интеграций, пароли SMTP, ключи S3 и секреты двухфакторной защиты. Включайте этот том в резервные копии вместе с базой и файлами.
Резервная копия Копируйте тома `chatballs-postgres`, `chatballs-media` и `chatballs-secrets`. Для базы можно снять дамп: ```bash docker compose exec -T postgres pg_dump -U chatballs_bootstrap chatballs > backup.sql ```
--- ## Лицензия Chatballs распространяется по лицензии [GNU Affero General Public License v3.0](LICENSE). Продукт можно свободно использовать, менять и ставить у себя. Если вы меняете его и предоставляете другим как сервис, изменения нужно опубликовать под той же лицензией.