Локальный сервер Telegram Bot API: свой сервер для работы с большими файлами

Большинство Telegram-ботов работают, отправляя запросы на api.telegram.org, и обычно этого достаточно. Но как только бот начинает работать с файлами, появляются ограничения: согласно официальной документации, через стандартный Bot API бот может скачивать файлы только до 20 МБ и отправлять только до 50 МБ. Для бота, который принимает видео, архивы или большие PDF, это серьёзное препятствие. У Telegram есть решение с открытым кодом — запустить сервер Bot API на своём собственном сервере.

Что даёт локальный сервер

Исходный код сервера Telegram Bot API опубликован в репозитории tdlib/telegram-bot-api. При запуске в режиме --local бот получает ряд расширенных возможностей. Основные отличия, перечисленные в документации:

Скачивание файлов без ограничения по размеру и отправка файлов до 2000 МБ.
Отправка файла по локальному пути на сервере через URI file://, без повторной загрузки по HTTP.
getFile возвращает абсолютный путь к файлу на сервере вместо ссылки для скачивания.
Webhook на любом порту и локальном IP, а также возможность использовать обычный HTTP.

Важно понимать, что бот по-прежнему работает через сеть Telegram. Локальный сервер лишь переносит посредника между ботом и Telegram на вашу машину, а сообщения и файлы доходят до пользователей через Telegram, как и раньше.

Реальный пример: бот видеостудии

Допустим, небольшая видеостудия из Ферганы хочет принимать от клиентов видео со свадеб и мероприятий через бота. Клиенты отправляют с телефона файлы по 300–800 МБ, а бот должен принять их и положить на диск команды монтажа. Со стандартным Bot API бот не сможет скачать такой файл, и вызов getFile вернёт ошибку. После установки локального сервера файл попадает прямо на диск сервера, и бот просто перемещает его как обычный файл. Для такого решения понадобится VPS, потому что на обычном shared-хостинге нельзя скомпилировать собственную программу и держать её постоянно работающим сервисом.

Получение api_id и api_hash

Локальный сервер подключается к Telegram от своего имени, поэтому ему нужны идентификаторы приложения. Их выдают на сайте my.telegram.org: войдите со своим аккаунтом Telegram и откройте раздел «API development tools». Вы получите два значения: числовой api_id и строку api_hash. Они так же секретны, как токен бота: не публикуйте их в открытых репозиториях и храните только в конфигурации на сервере.

Компиляция на сервере

Инструкции в официальном репозитории содержат команды для разных систем. Для Ubuntu или Debian процесс выглядит примерно так. Компиляция может потребовать много оперативной памяти и занять несколько десятков минут; на небольших VPS полезно временно добавить swap или воспользоваться рекомендациями для систем с малым объёмом памяти из официальной документации.

sudo apt-get update
sudo apt-get install -y make git zlib1g-dev libssl-dev gperf cmake g++
git clone --recursive https://github.com/tdlib/telegram-bot-api.git
cd telegram-bot-api
rm -rf build && mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=/usr/local ..
cmake --build . --target install
telegram-bot-api --help

Существуют и Docker-образы, подготовленные сообществом, — они экономят время на сборку. Но они не официальные, поэтому перед использованием проверьте источник и то, как регулярно они обновляются.

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

Сервер должен работать постоянно и подниматься после перезагрузки. Для этого создадим отдельного пользователя, каталог для файлов и сервис systemd. Параметр --http-port задаёт порт, который слушает сервер, а --dir — каталог, где хранятся файлы и рабочие данные.

sudo useradd -r -s /usr/sbin/nologin tgapi
sudo mkdir -p /var/lib/telegram-bot-api
sudo chown tgapi:tgapi /var/lib/telegram-bot-api

# /etc/systemd/system/telegram-bot-api.service
[Unit]
Description=Telegram Bot API local server
After=network.target

[Service]
User=tgapi
EnvironmentFile=/etc/telegram-bot-api.env
ExecStart=/usr/local/bin/telegram-bot-api --local --http-port=8081 \
  --http-ip-address=127.0.0.1 --dir=/var/lib/telegram-bot-api
Restart=always

[Install]
WantedBy=multi-user.target

Запишите в файл /etc/telegram-bot-api.env строки TELEGRAM_API_ID=... и TELEGRAM_API_HASH=... — сервер умеет читать эти переменные окружения. Затем запустите его командой sudo systemctl enable --now telegram-bot-api. Порт 8081 не должен быть открыт наружу, иначе любой, кто знает токен, сможет отправлять запросы через ваш сервер.

Перевод бота на локальный сервер

Если бот раньше работал через официальный сервер, перед переходом нужно вызвать метод logOut на api.telegram.org. Согласно документации, после этого бота какое-то время — около 10 минут — нельзя снова подключить к официальному серверу, так что планируйте переход заранее.

curl "https://api.telegram.org/bot<TOKEN>/logOut"

Дальше достаточно поменять адрес API в коде бота. Например, в aiogram 3 это делается так:

from aiogram import Bot
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer

session = AiohttpSession(
    api=TelegramAPIServer.from_base("http://127.0.0.1:8081", is_local=True)
)
bot = Bot(token=TOKEN, session=session)

Не забывайте о диске и безопасности

В локальном режиме скачанные файлы остаются в каталоге --dir и сами не удаляются. В примере с видеостудией диск может заполниться за несколько недель, поэтому напишите скрипт, который переносит обработанные файлы в другое место и регулярно чистит старые. Чтобы процесс бота мог читать эти файлы, оба сервиса нужно включить в одну группу или правильно настроить права на каталог. Время от времени обновляйте и сам сервер: когда в Telegram Bot API появляются новые методы, в локальный сервер они приходят с новой версией.