Local Telegram Bot API: преимущества, ограничения стандартного API и настройка через Docker

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

🚀 Основные преимущества Local Bot API

1. Увеличенные лимиты на работу с файлами

Для разработчиков, чьи боты активно работают с медиа, локальный API-сервер открывает новые возможности:

• Загрузка файлов до 2 ГБ:
  В отличие от стандартного Bot API, который ограничивает размер загружаемых файлов 50 МБ, локальный сервер позволяет работать с файлами до 2000 МБ (2 ГБ). Это идеально для ботов, обрабатывающих видео, аудио или другие крупные медиафайлы.

• Скачивание файлов без ограничений:
  Локальный API позволяет скачивать файлы с серверов Telegram без ограничений по размеру (до 2000 МБ), в то время как стандартный API ограничивает скачивание файлов до 20 МБ.

• Использование локального пути для загрузки:
  Локальный API-сервер поддерживает указание локального пути или схемы URI file:// для загрузки файлов, что исключает необходимость передачи файлов через HTTP-запросы.

2. Снижение сетевых задержек (Latency)

Локальный сервер API может существенно улучшить производительность:

• Уменьшение задержки:
  Запросы от вашего бота сначала отправляются на ваш локальный API-сервер, а затем перенаправляются на серверы Telegram.
  Если ваш бот и API-сервер находятся в одной сети или географически близко, это позволяет сократить сетевую задержку, обеспечивая более быструю обработку запросов.

3. Гибкость и повышенные лимиты для Webhook

Использование локального API-сервера расширяет возможности настройки вебхуков:

• Поддержка HTTP:
  В отличие от стандартного Bot API, где требуется использование HTTPS, локальный сервер позволяет использовать HTTP для вебхуков, что упрощает настройку в некоторых сценариях.

• Любой IP и порт:
  Вы можете настроить вебхуки на любой локальный IP-адрес и любой порт, что обеспечивает гибкость в конфигурации сервера.

• Больше одновременных подключений:
  Параметр max_webhook_connections на локальном сервере можно поднять до 100 000 (по умолчанию в режиме --local — 100). У стандартного API допустимы значения от 1 до 100, по умолчанию 40, а вебхук принимается только по HTTPS на портах 443, 80, 88 или 8443.

4. Ускоренный доступ к файлам

В режиме --local метод getFile возвращает абсолютный локальный путь к файлу (file_path) и не требует отдельного скачивания. Чтобы бот мог прочитать такой файл, у него должен быть доступ к каталогу данных сервера — например, общий том Docker.

Все преимущества из этого раздела работают только при запуске сервера с флагом --local. Без него локальный сервер ведёт себя как облачный: те же лимиты на файлы и те же требования к вебхукам.

🛑 Ограничения стандартного Telegram Bot API

🛠 Настройка Local Bot API через Docker

1. Подготовка к запуску

Перед началом убедитесь, что у вас установлены Docker и Docker Compose, и у вас есть API ID и API Hash, полученные на my.telegram.org.

Создайте файл .env:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

2. Конфигурация Docker Compose

Файл docker-compose.yml:

services:
  telegram-bot-api:
    build: ./telegram-bot-api-builder
    container_name: telegram-local-api
    restart: unless-stopped
    environment:
      TELEGRAM_API_ID: ${TELEGRAM_API_ID}
      TELEGRAM_API_HASH: ${TELEGRAM_API_HASH}
    ports:
      - "127.0.0.1:8081:8081"
    volumes:
      - tgdata:/var/lib/telegram-bot-api
    command:
      - --local
      - --http-port=8081
      - --dir=/var/lib/telegram-bot-api
      - --temp-dir=/tmp/telegram-bot-api

volumes:
  tgdata:

Что важно в этой конфигурации:

• --local включает локальный режим: файлы до 2000 МБ, вебхуки по HTTP на любом порту, локальные пути в getFile. Без этого флага сервер работает с теми же ограничениями, что и облачный.
• TELEGRAM_API_ID и TELEGRAM_API_HASH сервер читает из переменных окружения сам, поэтому передавать их ещё и аргументами --api-id и --api-hash не нужно.
• Порт опубликован только на 127.0.0.1. Сервер принимает запросы по одному токену бота без других проверок, открывать его в интернет не следует. Если бот работает в том же Compose-проекте, он обращается к серверу по имени сервиса, http://telegram-bot-api:8081, и публиковать порт наружу не нужно вовсе.
• Строка version: в начале файла устарела: современный Docker Compose её игнорирует и выводит предупреждение.

3. Dockerfile

Файл telegram-bot-api-builder/Dockerfile:

# ---------- Stage 1: Build ----------
FROM ubuntu:24.04 AS builder

ARG DEBIAN_FRONTEND=noninteractive
# Ветка или коммит для сборки; для воспроизводимости укажите хеш коммита:
# --build-arg TELEGRAM_BOT_API_REF=<commit>
ARG TELEGRAM_BOT_API_REF=master

# Зависимости сборки из официальной инструкции (gperf обязателен)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      make git zlib1g-dev libssl-dev gperf cmake g++ ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Репозиторий клонируется рекурсивно: TDLib подключён как подмодуль
WORKDIR /src
RUN git clone --recursive https://github.com/tdlib/telegram-bot-api.git . && \
    git checkout "${TELEGRAM_BOT_API_REF}" && \
    git submodule update --init --recursive

# Сборка
RUN mkdir -p build && cd build && \
    cmake -DCMAKE_BUILD_TYPE=Release .. && \
    cmake --build . --target telegram-bot-api -j"$(nproc)"

# Сжимаем бинарник (уменьшаем размер)
RUN strip /src/build/telegram-bot-api || true


# ---------- Stage 2: Runtime ----------
FROM ubuntu:24.04

ARG DEBIAN_FRONTEND=noninteractive

# Минимальные зависимости рантайма:
# в Ubuntu 24.04 библиотека OpenSSL называется libssl3t64
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      libssl3t64 zlib1g ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Каталог данных + системный пользователь
RUN groupadd -r telegram-bot-api && \
    useradd  -r -g telegram-bot-api -d /var/lib/telegram-bot-api -s /sbin/nologin telegram-bot-api && \
    mkdir -p /var/lib/telegram-bot-api /tmp/telegram-bot-api && \
    chown -R telegram-bot-api:telegram-bot-api /var/lib/telegram-bot-api /tmp/telegram-bot-api

# Копируем бинарник
COPY --from=builder /src/build/telegram-bot-api /usr/local/bin/telegram-bot-api

# Порт по умолчанию (меняйте в docker-compose командой --http-port)
EXPOSE 8081

# Healthcheck: проверяем, что сервер принимает TCP-соединения на порту
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD bash -c 'exec 3<>/dev/tcp/127.0.0.1/8081' || exit 1

USER telegram-bot-api
WORKDIR /var/lib/telegram-bot-api

# Параметры передаются через docker-compose (command), ключи API — через переменные окружения
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

Особенности этой версии:

• Зависимости и git clone --recursive — как в официальной инструкции по сборке. Без gperf и без подмодуля TDLib сборка не пройдёт.
• База — Ubuntu 24.04; в рантайме нужен пакет libssl3t64.
• Параллельная сборка и strip бинарника для уменьшения размера.
• HEALTHCHECK проверяет, что порт принимает соединения. Проверка через curl -f на корневой адрес здесь не подходит: сервер отвечает на такой запрос ошибкой.
• Сервер работает от непривилегированного пользователя.
• Аргумент TELEGRAM_BOT_API_REF позволяет закрепить сборку на конкретном коммите.

4. Запуск сервера

docker compose up -d --build

После запуска сервер будет доступен по адресу:

http://localhost:8081

5. Проверка и регистрация бота

Если бот уже работал через облачный API, перед переходом на локальный сервер его нужно отключить от облака методом logOut. Иначе часть обновлений может продолжать уходить на серверы Telegram:

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

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

Затем проверьте локальный сервер:

curl http://localhost:8081/bot<YOUR_TOKEN>/getMe

Если видите JSON-ответ с именем бота — всё работает.

6. Использование в коде

Python (python-telegram-bot 20 и новее)

from telegram.ext import ApplicationBuilder

application = (
    ApplicationBuilder()
    .token("YOUR_TOKEN")
    .base_url("http://localhost:8081/bot")
    .base_file_url("http://localhost:8081/file/bot")
    .local_mode(True)
    .build()
)

Адрес указывается вместе с суффиксом /bot: по умолчанию библиотека обращается к https://api.telegram.org/bot. Класс Updater(token, base_url=...) из старых примеров относится к версии 13 и в текущих версиях так не работает. local_mode(True) нужен, когда сервер запущен с --local: тогда get_file() возвращает локальный путь, и библиотека не пытается скачивать файл.

Любой другой язык или библиотека

Bot API — обычный HTTP-интерфейс: достаточно заменить в клиенте адрес https://api.telegram.org на адрес своего сервера. Название параметра зависит от библиотеки, ищите в её документации base URL или API URL. Проверить работу можно без библиотеки:

curl -X POST "http://localhost:8081/bot<YOUR_TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Проверка локального сервера"}'

7. Настройка Webhook

curl -X POST "http://localhost:8081/bot<YOUR_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "http://bot:8443/telegram-webhook"}'

В url указывается адрес вашего бота — приложения, которое принимает обновления, а не адрес сервера Bot API. В примере бот запущен в том же Compose-проекте как сервис bot и слушает порт 8443. В режиме --local вебхук может быть на HTTP, на любом порту и на локальном адресе.

8. HTTPS и ошибка версии HTTP

Сервер Bot API принимает только HTTP-запросы. Если к нему нужно обращаться снаружи по HTTPS, перед ним ставят TLS-прокси — nginx, Caddy или HAProxy.

Сервер понимает только HTTP/1.0 и HTTP/1.1. На запросы по другой версии протокола он отвечает 505 HTTP Version Not Supported, а клиентские библиотеки превращают это в сообщения вроде «self hosted bot api instances only support HTTP/1.1». Причины обычно две:

• Клиент настроен на HTTP/2. В python-telegram-bot это параметр http_version="2" у запроса; по умолчанию используется "1.1", и его достаточно не менять. В других библиотеках отключите HTTP/2 для адреса локального сервера.
• Прокси обращается к серверу по HTTP/2. Между прокси и сервером Bot API должно быть HTTP/1.1. В nginx для этого задают proxy_http_version 1.1; в блоке location; HTTP/2 при этом можно оставить на стороне клиентов.

💡 Резюме

Local Telegram Bot API подходит для:

• работы с большими файлами (до 2 ГБ);
• уменьшения задержек;
• гибкой конфигурации вебхуков;
• высоконагруженных систем.

Стандартный API подходит для:

• небольших проектов;
• работы с файлами до 50 МБ;
• типовых HTTPS-вебхуков.

Сборка в Docker даёт воспроизводимый образ и простое обновление. Главное при переходе — запустить сервер с --local, вызвать logOut для облачного API и не публиковать порт сервера в интернет.

🔗 Полезные ссылки

• Официальный репозиторий Telegram Bot API
• Telegram API Tools (my.telegram.org)
• Документация Telegram Bot API
• Официальная инструкция по сборке
• Local Bot API Server в python-telegram-bot