Установка Чатбот-агента

Не хотите читать всё это?

Просто скиньте в любой ИИ-чат (Claude, ChatGPT и т.д.) ссылку на https://pastukhov.com/agents/chatbot/install.md или на https://pastukhov.com/llms.txt и попросите сгенерировать конфигурационные файлы и команды. Он прочитает документацию, задаст несколько вопросов о вашей настройке и выдаст готовую конфигурацию. Экономьте время — пусть модель читает за вас.

Вы также можете связаться со мной через Telegram — я всегда рад помочь. И это не просто вежливость — мне действительно нравится общаться с единомышленниками, особенно если вы так же увлечены программированием, как и я.

Чатбот-агент — программа для создания чатботов с ИИ, которую вы запускаете на своём сервере. Разворачивается одним Docker-контейнером, все данные хранятся в постоянных томах: /apps/chatbot — база, медиатека и базы знаний, /project/apps/chatbot — файлы ботов и скрипты. Своя база данных не нужна: встроенная SQLite работает из коробки, PostgreSQL подключается по желанию.

Минимальные требования

Достаточно любого Linux-хоста с Docker (например, недорогого VPS). Всё остальное уже встроено в образ:

веб-сервер приложения (ASP.NET Core 9 runtime);
база данных SQLite — работает без настройки;
эмулятор Telegram — можно собирать и проверять ботов, не создавая настоящего бота и не подключаясь к мессенджеру;
для чата с ИИ-агентом понадобится адрес и ключ вашего Pastukhov Agent — но это необязательно: без них всё работает, кроме этого чата.

Приложение экономно расходует ресурсы сервера. В простое процессор не нагружается: фоновые обработчики не опрашивают базу по таймеру, а просыпаются, когда появляется работа. Через 15 минут без активности освобождается занятая память — снимки поиска по базам знаний, кэш аналитики и другие служебные данные; при новом запросе всё поднимается само. Поэтому Чатбот-агент спокойно соседствует с другими сервисами на одном сервере. Настраивать ничего не нужно; при желании срок задаётся в файле settings.yml в папке настроек — в блоке memory поле idleTrimMinutes (0 выключает уборку).

Docker Compose

Создайте файл compose.yml и запустите docker compose up -d:

services:
  chatbotagent-ru:
    image: maxpastukhov/chatbot-agent:min-latest
    container_name: chatbotagent-ru
    ports:
      - "3979:80"
    volumes:
      - chatbotagent-data-ru:/apps/chatbot
      - chatbotagent-config-ru:/project/apps/chatbot
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_URLS=http://+:80
      - CHATBOT_APP_BRAND=pastukhov
      - CHATBOT_APP_DATA=/apps/chatbot
      - CHATBOT_APP_CONFIG_FOLDER=/project/apps/chatbot
      # Необязательная связка с Pastukhov Agent (без этих строк чат с агентом скрыт):
      # - AGENT_API_URL=https://адрес-вашего-агента
      # - AGENT_API_KEY=ключ-вашего-агента
      # Размещение в подпапке первого уровня (например, /chatbot):
      # - CHATBOT_APP_BASE_PATH=/chatbot
    restart: unless-stopped
    sysctls:
      fs.inotify.max_user_watches: "524288"
      fs.inotify.max_user_instances: "512"

volumes:
  chatbotagent-data-ru:
  chatbotagent-config-ru:

После запуска интерфейс будет доступен на порту 3979: http://<адрес-сервера>:3979.

Две строки sysctls повышают системные лимиты отслеживания изменений файлов — они нужны, чтобы правки сценария и скриптов подхватывались мгновенно, без перезапуска. Без них на больших проектах часть изменений может не дойти до приложения.

Переменные окружения

Настройки приложения передаются переменными окружения — так удобно задать их один раз в compose.yml и менять без правки кода:

Переменная	Назначение	По умолчанию
`CHATBOT_APP_BRAND`	бренд и язык интерфейса: `pastukhov` (русский) или `xedant` (английский)	`xedant`
`CHATBOT_APP_DATA`	папка постоянных данных (в контейнере — `/apps/chatbot`)	`/apps/chatbot`
`CHATBOT_APP_DB`	строка подключения PostgreSQL; пустое значение — встроенная SQLite	SQLite (`/apps/chatbot/data.db`)
`CHATBOT_APP_BASE_PATH`	размещение в подпапке первого уровня (например, `/chatbot`)	— (работа в корне домена)
`CHATBOT_APP_LOGIN`	логин готового пользователя; вместе с паролем ниже создаёт администратора при старте	— (саморегистрация)
`CHATBOT_APP_PASSWORD`	строчная SHA-256-сумма пароля, не сам пароль	—
`AGENT_API_URL`	адрес Pastukhov Agent для чата с ИИ-агентом	— (чат с агентом скрыт)
`AGENT_API_KEY`	ключ доступа к вашему Pastukhov Agent	—
`AGENT_LICENSE`	лицензионный ключ, чтобы не вводить его руками в интерфейсе	— (лицензии в образе нет)
`CHATBOT_APP_HASH`	SHA-256 hex ключа управления: по нему ИИ-агент управляет ботами по API; пусто — выключено	— (управление по API выключено)
`CHATBOT_APP_CONFIG_FOLDER`	папка файлов ботов (настройки и сценарии в формате YAML)	`/project/apps/chatbot`
`CHATBOT_APP_SCRIPTS_FOLDER`	папка скриптов ботов на Python	`/project/apps/chatbot/scripts`
`CHATBOT_APP_PYTHON`	какая программа Python выполняет ваши скрипты (если не задана, берётся из окружения скриптов)	из окружения скриптов
`CHATBOT_APP_VENV`	папка отдельного окружения Python для библиотек скриптов	`/apps/chatbot/venv`
`CHATBOT_APP_DOCS_FOLDER`	папка документов для файлового менеджера	`/project/docs`
`CHATBOT_APP_SSL`	самоподписанный HTTPS: `auto` — включить; рядом `_SSL_PORT` и `_SSL_DOMAINS`	— (только HTTP)
`JWT_SECRET_KEY`	секрет для подписи сессий входа (в MultiAgent задаётся автоматически)	ключ в `/apps/chatbot/keys`
`SSO_PROXY_TOKEN`	вход через внешний SSO-прокси (в MultiAgent задаётся автоматически)	— (выключено)
`CHATBOT_APP_ERROR_REPORTING`	`0` — выключить отправку сведений об ошибках	— (отправка всё равно выключена: адрес приёма не задан)

Обратите внимание: CHATBOT_APP_PASSWORD содержит не пароль, а его строчную SHA-256-сумму — «отпечаток», по которому пароль восстановить нельзя. Получить её можно командой echo -n вашпароль | sha256sum. При входе приложение считает сумму от введённого пароля и сравнивает с заданной. Так же устроен и ключ управления: в CHATBOT_APP_HASH попадает не сам ключ, а его сумма в шестнадцатеричном виде — её считает та же команда sha256sum.

Где хранятся данные

Все постоянные данные переживают пересоздание контейнера. Данные приложения лежат в томе /apps/chatbot:

/apps/chatbot/data.db — база данных SQLite (когда не используется PostgreSQL);
/apps/chatbot/auth/ — ключи защиты данных;
/apps/chatbot/keys/ — ключ подписи сессий входа;
/apps/chatbot/bot-media/<бот>/ — медиатека ботов: картинки и файлы из диалогов;
/apps/chatbot/kb/ — файлы баз знаний (документы, по которым отвечает ИИ);
/apps/chatbot/venv/ — окружение Python, в котором выполняются ваши скрипты (библиотеки для них перечисляются в файле scripts-requirements.txt в корне папки настроек);
/apps/chatbot/.pastukhov/license.txt — активированный лицензионный ключ (у бренда xedant — папка .xedant).

Файлы ботов и скрипты живут отдельно — в томе /project/apps/chatbot: настройки и сценарии в папке bots/, свои скрипты на Python — в scripts/. Это тот же каталог, что в проекте разработчика, поэтому папку бота можно скопировать туда целиком.

Тома обязательны: без них при первом же docker compose down вы потеряете базу, медиатеку, базы знаний и файлы ботов. И важное преимущество: всё это обычные файлы — их видно, можно скопировать и перенести на другой сервер.

Первый вход

Откройте интерфейс в браузере. Пока в базе нет ни одного пользователя, форма регистрации открыта сама — первый зарегистрировавшийся становится администратором. Если логин и пароль заданы переменными окружения, входите под ними (в переменной — сумма, при входе вводите сам пароль). Сессия входа живёт 90 дней. Сразу после входа можно сменить язык и тему интерфейса в настройках. Подробнее — в разделе Начало работы.

Что сделать после запуска

Создайте первого бота — имя и токен из @BotFather. Если настоящего бота пока нет, это не помеха: тестового бота можно собрать и проверить прямо на встроенном эмуляторе. Затем соберите сценарий в студии и проверьте его: подробности — в разделах Боты, Студия сценариев и Эмулятор.

При желании подключите Pastukhov Agent — тогда появляется чат с ИИ-агентом, которому можно поручать правки словами. Подробнее — в разделе Чат с ИИ-агентом.

Запуск без Compose

Можно запустить приложение и одной командой docker run:

docker run -d \
  --name chatbotagent-ru \
  -p 3979:80 \
  -v chatbotagent-data-ru:/apps/chatbot \
  -v chatbotagent-config-ru:/project/apps/chatbot \
  -e CHATBOT_APP_BRAND=pastukhov \
  -e CHATBOT_APP_DATA=/apps/chatbot \
  -e CHATBOT_APP_CONFIG_FOLDER=/project/apps/chatbot \
  --sysctl fs.inotify.max_user_watches=524288 \
  --sysctl fs.inotify.max_user_instances=512 \
  --restart unless-stopped \
  maxpastukhov/chatbot-agent:min-latest

Остальные переменные окружения можно передать файлом через флаг --env-file .env — так удобнее, когда настроек много.

Установка через Pastukhov MultiAgent

Если у вас несколько серверов и приложений, удобнее ставить Чатбот-агент из Pastukhov MultiAgent: продукт есть в списке новых агентов. MultiAgent сам поднимает контейнер, выдаёт постоянный адрес и HTTPS, подключает базу PostgreSQL и общий том документов, а также связывает приложение с выбранным ИИ-агентом — вручную ничего прописывать не нужно. Порт по умолчанию — 6050. Подробнее — на странице MultiAgent.

Лицензия

Лицензионный ключ активируется в диалоге лицензии или передаётся переменной AGENT_LICENSE при запуске. Готовой лицензии в образе нет: свежий контейнер стартует без неё. Без лицензии работает всё — боты, студия, эмулятор, проверка, база знаний, операторы, чат-комната, виджет, рассылки и аналитика. Лицензия нужна только для отправки сообщений в чат с ИИ-агентом. Подробнее — на странице Лицензирование.

← Вернуться на главную раздела Чатбот-агент