Сервер и эксплуатация
Локальный Telegram Bot API
Запуск собственного сервера telegram-bot-api и подключение бота через TELEGRAM_API_URL
По умолчанию бот обращается к публичному серверу Telegram https://api.telegram.org. Вы можете развернуть собственный сервер telegram-bot-api и направить бота на него через переменную окружения TELEGRAM_API_URL.
Зачем это нужно
Заголовок раздела «Зачем это нужно»- Большие файлы — публичный API ограничивает загрузку до 20 МБ, скачивание до 20 МБ. Локальный сервер поднимает лимиты до 2 ГБ.
- Локальные файлы — локальный сервер отдаёт скачанные файлы прямым путём на диске, без повторной загрузки по сети.
- Скорость и независимость — нет общего rate-лимита публичного API, меньше задержек, работа при недоступности
api.telegram.orgнапрямую. - Webhook и polling на своей инфраструктуре.
Получение api_id и api_hash
Заголовок раздела «Получение api_id и api_hash»Локальный сервер требует ключей приложения Telegram (не путать с токеном бота):
- Войдите на my.telegram.org под своим аккаунтом.
- Откройте API development tools.
- Создайте приложение — получите
api_id(число) иapi_hash(строка).
Запуск сервера
Заголовок раздела «Запуск сервера»Docker Compose
Заголовок раздела «Docker Compose»Добавьте сервис в docker-compose.yml рядом с ботом:
services: telegram-bot-api: image: aiogram/telegram-bot-api:latest environment: TELEGRAM_API_ID: "1234567" TELEGRAM_API_HASH: "abcdef0123456789abcdef0123456789" TELEGRAM_LOCAL: 1 # режим локальных файлов (прямые пути на диске) volumes: - telegram-bot-api-data:/var/lib/telegram-bot-api ports: - "8081:8081" restart: unless-stopped
volumes: telegram-bot-api-data:telegram-bot-api \ --api-id=1234567 \ --api-hash=abcdef0123456789abcdef0123456789 \ --local \ --http-port=8081Отвязка бота от облака Telegram (обязательно)
Заголовок раздела «Отвязка бота от облака Telegram (обязательно)»Перед первым подключением к локальному серверу вызовите метод logOut на облачном API (именно на api.telegram.org, не на локальном сервере):
curl -X POST https://api.telegram.org/bot<TELEGRAM_TOKEN>/logOut# {"ok":true,"result":true}- Замените
<TELEGRAM_TOKEN>на ваш токен изTELEGRAM_TOKEN. - После
logOutподождите ~10 минут. Если в ответ пришёл429 Too Many Requests— выждите указанное вretry_afterвремя и повторите. - Только после успешного
logOutзапускайте бота сTELEGRAM_API_URL.
Подключение бота
Заголовок раздела «Подключение бота»Укажите адрес локального сервера в переменной окружения бота:
TELEGRAM_API_URL=http://telegram-bot-api:8081- Внутри Docker-сети — имя сервиса:
http://telegram-bot-api:8081. - На том же хосте —
http://127.0.0.1:8081. - Без слеша в конце не обязательно — он обрезается автоматически.
Если переменная пуста или не задана, бот использует https://api.telegram.org (поведение по умолчанию).
При старте в логах появится строка подтверждения:
Telegram bot using custom API server url=http://telegram-bot-api:8081Проверка
Заголовок раздела «Проверка»- Перезапустите контейнер бота после установки
TELEGRAM_API_URL. - Убедитесь, что в логах есть строка
Telegram bot using custom API server. - Проверьте доступность сервера:
curl http://127.0.0.1:8081/# Ответ "Unauthorized" — нормально: сервер жив, токен в запросе не переданЧтобы вернуться на публичный API, бота нужно так же отвязать — но теперь от локального сервера:
-
Остановите бота.
-
Вызовите
logOutна локальном сервере:curl -X POST http://127.0.0.1:8081/bot<TELEGRAM_TOKEN>/logOut -
Удалите
TELEGRAM_API_URL(или оставьте пустым) и перезапустите бота — он снова подключится кapi.telegram.org.
Частые проблемы
Заголовок раздела «Частые проблемы»| Симптом | Причина / решение |
|---|---|
getMe ... unexpected end of JSON input при старте |
Бот не отвязан от облака. Вызовите logOut на api.telegram.org (см. раздел выше). |
| Бот не стартует, ошибки сети | Неверный TELEGRAM_API_URL или сервер недоступен из сети контейнера. Проверьте имя сервиса и порт. |
logOut вернул 429 |
Telegram ограничивает частоту. Подождите время из retry_after и повторите. |
| Файлы не читаются | При TELEGRAM_LOCAL=1 том с файлами не примонтирован в контейнер бота по тому же пути. |
| Хочу обойти только блокировку | Используйте TELEGRAM_PROXY_URL вместо локального сервера. |