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-адрес и любой порт, что обеспечивает гибкость в конфигурации сервера.

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

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

Метод getFile возвращает абсолютный локальный путь (file_path), что позволяет избежать дополнительных запросов на скачивание файлов, если они уже доступны на вашем сервере.

🛑 Ограничения стандартного 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:

version: "3.8"
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:
      - "8081:8081"
    volumes:
      - tgdata:/var/lib/telegram-bot-api
    command:
      - --api-id=${TELEGRAM_API_ID}
      - --api-hash=${TELEGRAM_API_HASH}
      - --http-port=8081
      - --dir=/var/lib/telegram-bot-api

volumes:
  tgdata:

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=v7.2
ARG TELEGRAM_BOT_API_REF=master

RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      build-essential g++ cmake git \
      libssl-dev zlib1g-dev ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Клонируем и фиксируемся на нужной ревизии
WORKDIR /src
RUN git clone https://github.com/tdlib/telegram-bot-api.git . --depth 1 --branch ${TELEGRAM_BOT_API_REF}

# Сборка
RUN mkdir -p build && cd build && \
    cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local .. && \
    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

# Минимальные зависимости рантайма:
# libssl3 для Ubuntu 24.04, zlib, сертификаты для исходящих запросов
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      libssl3 zlib1g ca-certificates curl && \
    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 && \
    chown -R telegram-bot-api:telegram-bot-api /var/lib/telegram-bot-api

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

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

# Healthcheck: простой HTTP-пинг локального порта
ENV HEALTH_PORT=8081
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -fsS "http://127.0.0.1:${HEALTH_PORT}/" >/dev/null || exit 1

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

# Параметры (api-id, api-hash, порты, директории) передаются через docker-compose:
#   command: ["--api-id=...", "--api-hash=...", "--http-port=8081", "--dir=/var/lib/telegram-bot-api"]
ENTRYPOINT ["/usr/local/bin/telegram-bot-api"]

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

• Актуальная база — Ubuntu 24.04 с libssl3.
• Параллельная сборка и strip бинарника для уменьшения размера.
• HEALTHCHECK для мониторинга контейнера.
• Безопасный непривилегированный пользователь.
• Возможность задать тег сборки TELEGRAM_BOT_API_REF для воспроизводимости.

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

docker-compose up -d

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

http://localhost:8081

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

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

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

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

Python (python-telegram-bot)

from telegram.ext import Updater
updater = Updater(token='YOUR_TOKEN', base_url='http://localhost:8081')

Node.js (node-telegram-bot-api)

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_TOKEN', { baseUrl: 'http://localhost:8081' });

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

curl -X POST \
  http://localhost:8081/bot<YOUR_TOKEN>/setWebhook \
  -d '{"url": "http://your_server_ip:8081/bot<YOUR_TOKEN>"}'

💡 Резюме

Local Telegram Bot API — мощное решение для:

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

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

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

Настройка через Docker обеспечивает воспроизводимость, простое обновление и безопасность изоляции. Dockerfile — оптимальный вариант для стабильной и лёгкой сборки Telegram Bot API в продакшене.

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

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

---