Установка Telegram Agent — Макс Пастухов

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

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

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

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

Приложение экономно расходует ресурсы сервера. В простое процессор не нагружается: планировщик публикаций и выгрузка статистики не опрашивают базу по таймеру, а просыпаются, когда появляется работа. Через 15 минут без активности освобождается занятая память — поисковый индекс и служебные данные; при новом задании всё поднимается само. Поэтому Telegram Agent спокойно соседствует с другими сервисами на одном сервере.

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

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

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

Docker Compose

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

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

volumes:
  telegram-agent-data-ru:
  telegram-agent-config-ru:

После запуска интерфейс будет доступен на порту 3998: http://localhost:3998.

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

Второй том — папка настроек /project/apps/telegram. Приложение держит там своё настроенное вами — каналы, источники, шаблоны, расписание — обычными читаемыми файлами (подробнее — в разделе «Хранение данных»).

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

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

Переменная	Назначение	По умолчанию
`TELEGRAM_APP_BRAND`	бренд и язык интерфейса: `pastukhov` (русский) или `xedant` (английский)	`xedant`
`TELEGRAM_APP_DATA`	папка данных приложения (в контейнере — `/apps/telegram`)	`/apps/telegram`
`TELEGRAM_APP_CONFIG_FOLDER`	папка настроек — читаемых файлов YAML (в контейнере — `/project/apps/telegram`)	`/project/apps/telegram`
`TELEGRAM_APP_LOGIN`	логин первого пользователя (пароль — SHA-256-хэш в `TELEGRAM_APP_PASSWORD`)	— (саморегистрация)
`TELEGRAM_APP_PASSWORD`	SHA-256-хэш пароля, не сам пароль: `echo -n "ваш-пароль" \| sha256sum`	—
`AGENT_LICENSE`	лицензионный ключ (или путь к файлу с ним) — та же переменная, что и у Pastukhov Agent	— (без чата с агентом)
`AGENT_API_URL`	адрес Pastukhov Agent для чата с агентом	— (кнопки «Вызвать агента» скрыты)
`AGENT_API_KEY`	API-ключ Pastukhov Agent	—
`TELEGRAM_APP_HASH`	SHA-256-хэш машинного ключа: по нему сервер управления MultiAgent получает доступ администратора к внешнему API	—
`TELEGRAM_APP_BASE_PATH`	размещение в подпапке первого уровня (например, `/telegram`)	—
`TELEGRAM_APP_DATABASE`	строка подключения PostgreSQL; пустое значение — встроенная SQLite	SQLite (`/apps/telegram/data.db`)
`TELEGRAM_APP_CLICKHOUSE_URL`	адрес ClickHouse — отдельной базы для долгого хранения статистики каналов; пусто — выгрузка выключена	—
`TELEGRAM_APP_SSL`	самоподписанный HTTPS: `auto` — включить (для прямого адреса вида `telegram.ваш-домен`); рядом `TELEGRAM_APP_SSL_PORT` и `TELEGRAM_APP_SSL_DOMAINS`	— (только HTTP)
`TELEGRAM_APP_DOCS_FOLDER`	папка документов проекта — туда попадают файлы, вставленные в чат с агентом	`/project/docs` (в контейнере — `/apps/telegram/docs`)
`TELEGRAM_APP_SEARCH_INDEX_FOLDER`	папка поискового индекса по каналам, постам, авторам и комментариям	`/apps/telegram/search-index`
`TELEGRAM_APP_ERROR_REPORTING`	`0` — выключить автоматические отчёты об ошибках	отчёты включены

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

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

Хранение данных

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

/apps/telegram/data.db — база данных SQLite (когда не используется PostgreSQL);
/apps/telegram/sessions/ — сессии подключённых Telegram-аккаунтов;
/apps/telegram/media/ — загруженные медиафайлы;
/apps/telegram/keys/ — ключ подписи входа (JWT);
/apps/telegram/auth/ — ключи защиты данных;
/apps/telegram/docs/ — файлы, вставленные в чат с агентом;
/apps/telegram/search-index/ — индекс полнотекстового поиска по каналам, постам, авторам и комментариям: лежит на диске и переиспользуется между запусками, поэтому поиск работает сразу после перезапуска;
/apps/telegram/.pastukhov/license.txt — активированный лицензионный ключ (у бренда xedant — папка .xedant).

Настройки живут отдельно — в томе /project/apps/telegram, обычными читаемыми файлами: settings.yml (настройки приложения), bots.yml и accounts.yml (боты и Telegram-аккаунты), по файлу на источник и канал в папках sources/ и channels/ (вместе со слотами расписания и шаблонами постов), categories.yml, tags.yml, routers.yml, routing-rules.yml, taggers.yml, commenting-projects.yml, commenting-targets.yml, comment-templates.yml. Это удобно: папку с настройками можно скопировать на другой сервер или положить в git, а правка файла вручную подхватывается на ходу. Если файл испорчен, приложение продолжает работать с последней удачной версией настроек.

Оба тома обязательны: без них при первом же docker compose down вы потеряете базу, сессии аккаунтов, медиа и настройки.

Первый вход

Откройте интерфейс в браузере и зарегистрируйтесь первым пользователем — вы станете администратором. Либо войдите под логином, заданным переменными окружения (в переменной — хэш, при входе вводите сам пароль) или выданным в консоли контейнера. Сразу после входа можно сменить язык и тему интерфейса.

Настройка после запуска

Сначала подключите ботов — токены создаются в @BotFather за минуту и проверяются автоматически — и (по желанию) личные Telegram-аккаунты по номеру телефона и коду. Затем подключите каналы: через бота достаточно имени и токена, через аккаунт — выбрать из списка ваших каналов. Подробнее — в разделе Каналы.

Чат с агентом включается переменными AGENT_API_URL и AGENT_API_KEY: появляются кнопки «Вызвать агента» на страницах канала и очереди и панель чата. Подробнее — в разделе Агент.

Лицензия

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

Docker CLI с файлом .env

Можно запустить Telegram Agent и без compose — командой docker run, сохранив переменные окружения в файле .env:

# .env
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:80
TELEGRAM_APP_DATA=/apps/telegram
TELEGRAM_APP_CONFIG_FOLDER=/project/apps/telegram
TELEGRAM_APP_BRAND=pastukhov
TELEGRAM_APP_LOGIN=admin
TELEGRAM_APP_PASSWORD=sha256-хэш-пароля
# опционально: чат с агентом через Pastukhov Agent
# AGENT_API_URL=
# AGENT_API_KEY=
# опционально: лицензионный ключ (в образе лицензии нет)
# AGENT_LICENSE=

docker run -d \
  --name telegram-agent-ru \
  --env-file .env \
  -p 3998:80 \
  -v telegram-agent-data-ru:/apps/telegram \
  -v telegram-agent-config-ru:/project/apps/telegram \
  --sysctl fs.inotify.max_user_watches=524288 \
  --sysctl fs.inotify.max_user_instances=512 \
  --restart unless-stopped \
  maxpastukhov/telegram-agent:latest

Флаг --env-file считывает все переменные из файла. Отдельные значения можно переопределить дополнительными флагами -e после него, например -e TELEGRAM_APP_BRAND=xedant.

← Вернуться на главную раздела Telegram Agent