Локальный Telegram Bot API сервер: зачем и как его запустить

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

По умолчанию бот общается с Telegram через облачный Bot API на api.telegram.org. Этот сервер открыт — telegram-bot-api от команды TDLib — и его можно запустить у себя. Бот отправляет те же HTTP-запросы на ваш экземпляр, а тот общается с Telegram по MTProto.

С флагом --local сервер снимает ряд облачных ограничений:

• Загрузка файлов до 2000 МБ и скачивание файлов без облачного лимита на размер.
• Локальные пути: файл можно отправить по абсолютному пути или file:// URI, а getFile возвращает абсолютный путь на диске сервера вместо ссылки на скачивание.
• Гибкие webhook: обычный HTTP, любой порт, любой локальный IP и max_webhook_connections до 100000.

Код бота почти не меняется — это тот же Bot API, только с другим базовым URL. Полный список отличий — в официальной документации Bot API.

Когда это оправдано

• Бот работает с видео, архивами, бэкапами или большими документами.
• При высокой нагрузке вы упираетесь в лимит параллельных webhook-соединений облачного API.
• Бот и API-сервер в одной приватной сети, и публичный HTTPS-эндпоинт для webhook не нужен.

Для обычных ботов с текстом, кнопками и небольшими картинками облачный API проще и дешевле в поддержке.

Сборка и запуск в Docker

Понадобятся api_id и api_hash с my.telegram.org. Они идентифицируют ваше приложение, а не бота, поэтому храните их как секреты.

Multi-stage Dockerfile делает итоговый образ компактным. Учтите: компиляция TDLib требует много оперативной памяти — собирайте на машине с запасом или в CI.

FROM debian:bookworm-slim AS build
RUN apt-get update && apt-get install -y --no-install-recommends \
    git ca-certificates cmake g++ make gperf zlib1g-dev libssl-dev
RUN git clone --recursive https://github.com/tdlib/telegram-bot-api.git /src
WORKDIR /src/build
RUN cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX:PATH=/opt/tba .. \
 && cmake --build . --target install

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends zlib1g libssl3 ca-certificates \
 && rm -rf /var/lib/apt/lists/*
COPY --from=build /opt/tba/bin/telegram-bot-api /usr/local/bin/
EXPOSE 8081
ENTRYPOINT ["telegram-bot-api", "--local", "--dir=/var/lib/telegram-bot-api"]

Сервер берёт TELEGRAM_API_ID и TELEGRAM_API_HASH из переменных окружения и по умолчанию слушает порт 8081:

docker build -t telegram-bot-api .
docker run -d --name tba --restart unless-stopped \
  --env-file tba.env \
  -v tba-data:/var/lib/telegram-bot-api \
  -p 127.0.0.1:8081:8081 \
  telegram-bot-api

Две важные детали:

• getFile возвращает путь в файловой системе сервера, поэтому контейнер бота должен монтировать тот же volume по тому же пути, чтобы читать файлы.
• Укажите библиотеке новый базовый URL, например в grammY: new Bot(token, { client: { apiRoot: "http://tba:8081" } }). В aiogram, python-telegram-bot и других есть аналогичная настройка.

Перенос бота: logOut и close

Перед запуском на локальном сервере бота нужно разлогинить в облачном — иначе доставка обновлений не гарантирована.

1. Остановите процесс бота.
2. Вызовите logOut на облачном сервере:

curl "https://api.telegram.org/bot$BOT_TOKEN/logOut"

3. Запустите бота на локальном сервере и, если используете webhook, снова вызовите setWebhook — уже через локальный экземпляр.

После logOut залогиниться локально можно сразу, но вернуться на облачный сервер нельзя 10 минут. Планируйте переключение так, чтобы такое окно отката было приемлемым.

Чтобы перенести бота между двумя локальными серверами, сначала вызовите deleteWebhook, затем close на старом экземпляре. close возвращает ошибку 429 в первые 10 минут после запуска бота.

Компромиссы эксплуатации

Сервер принимает запросы с любым токеном бота, поэтому открытый наружу порт позволяет кому угодно пользоваться вашей инфраструктурой. Привязывайте его к localhost или внутренней сети и храните рабочую директорию на постоянном volume.