Веб-приложения и домены

Эта страница — для тех, кто публикует веб-сервис вместе с ботом: API, мини-приложение, панель, приём вебхуков Telegram и т.п.
Нужна база про 0.0.0.0, Reverse Proxy и PORT? Начните со статьи Работа с доменами и портами.
Здесь — практические сценарии: вебхук, деплой, типовые ошибки и диагностика.
Опция «Использовать домен» в дополнительных настройках бота

Когда читать эту страницу

  • Вы уже включили опцию «Использовать домен» и публикуете веб-сервис.
  • Нужна настройка webhook URL и проверка маршрутов в приложении.
  • Пытаетесь разобраться с 502/504, 404 и запуском HTTP-обёртки.

Что даёт включение домена

  • Запросы из интернета приходят на ваш домен по HTTPS (порт 443).
  • Платформа маршрутизирует трафик в ваш контейнер на выбранный внутренний порт приложения.
  • Для Telegram-бота можно указать вебхук на URL вида https://ваш-домен/... — Telegram будет слать обновления на этот адрес.

Что проверить перед деплоем

  • Включена опция «Использовать домен».
  • Веб-сервер слушает 0.0.0.0 и читает порт из PORT.
  • Порт в настройках бота совпадает с портом, который реально слушает приложение.
  • После смены домена/порта выполнен повторный деплой.
Подробно про устройство трафика и портов: Работа с доменами и портами.

Автоматический поддомен (bothost.tech)

При выборе автоматического домена для веб-интерфейса поддомен формируется из идентификатора бота. Символы подчёркивания в имени поддомена заменяются на дефисы, чтобы имя соответствовало правилам DNS (в имени хоста не должно быть _). Пример: bot-1774542086-5810-user.bothost.tech вместо bot_1774....

Кастомный домен

Если вы подключаете свой домен, в DNS нужно настроить запись на IP, который выдаст поддержка (обычно это центральный сервер платформы). После проверки сертификатов запросы пойдут по той же схеме, что и для *.bothost.tech.

Вебхук Telegram и путь в приложении

  • Вебхук задаётся URL вида https://ваш-домен/webhook (или другой путь — как настроите в коде).
  • Ваше приложение должно реализовать HTTP-обработчик на этом пути (например, POST для Telegram).
  • Если по корню / открывается 404, это не всегда ошибка: многие боты не отдают страницу на /, а принимают только /webhook.

Рекомендуемый минимум для webhook-бота

  • Приложение слушает 0.0.0.0 на PORT из переменных окружения.
  • Есть endpoint POST /webhook (или ваш путь, но он должен совпадать с URL в Telegram).
  • Endpoint быстро отвечает 200 OK (Telegram ожидает быстрый ответ; тяжёлую обработку лучше выносить в фон).
  • В логах видно факт приёма апдейта (например, update_id, chat_id, размер payload).

Пошаговая настройка webhook

    • Включите домен в настройках бота и сделайте деплой.
    • Убедитесь, что приложение отвечает по https://ваш-домен/health (или по вашему health-пути).
    • Настройте webhook в Telegram на https://ваш-домен/webhook.
    • Отправьте сообщение боту в Telegram.
    • Проверьте, что:
- в логах контейнера есть входящий webhook-запрос, - бот обработал апдейт (например, ответил в чат), - нет цикла рестартов контейнера. Пример минимального тестового проекта: bothost-tech/bothost_testwebhook.

Установка и проверка webhook через браузер

Если нужно быстро проверить webhook без терминала, можно использовать прямые ссылки Telegram Bot API:
  • Без secret token:
- https://api.telegram.org/bot<ТОКЕН>/setWebhook?url=https://<твой-домен>/webhook
  • С secret token:
- https://api.telegram.org/bot<ТОКЕН>/setWebhook?url=https://<твой-домен>/webhook&secret_token=<твой_секрет> После установки webhook откройте:
  • https://api.telegram.org/bot<ТОКЕН>/getWebhookInfo
Проверьте, что:
  • поле url заполнено вашим адресом https://<твой-домен>/webhook,
  • нет ошибок в last_error_message,
  • pending_update_count не растёт бесконечно.
Пример успешной проверки (бот ответил в Telegram): Пример успешной проверки webhook

Что обычно ломает webhook

  • Указан один путь в Telegram, а в коде слушается другой (/webhook vs /telegram/webhook).
  • Бот слушает 127.0.0.1 вместо 0.0.0.0.
  • Порт в коде не совпадает с PORT/internal_port.
  • Веб-сервер запускается медленно или падает при старте из-за исключения.
  • В обработчике нет ответа 200, из-за чего Telegram повторяет доставку.

Быстрая диагностика

  • Откройте https://ваш-домен/health: если ответа нет, сначала чините запуск приложения/порт.
  • Откройте https://ваш-домен/ и https://ваш-домен/webhook:
- 404 на / допустим, - для /webhook важно, чтобы POST обрабатывался вашим приложением.
  • Сверьте URL webhook в Telegram и фактический маршрут в коде.
  • Проверьте последние логи контейнера: старт сервера, порт, входящие POST-запросы, traceback.

Полезно для надёжности

  • Добавьте проверку секретного токена webhook (X-Telegram-Bot-Api-Secret-Token).
  • Делайте идемпотентную обработку апдейтов (на случай повторной доставки).
  • Логируйте ошибки обработки отдельно от access-логов HTTP.

Как работает деплой с доменом

  • Бот должен слушать 0.0.0.0 на порту из переменной PORT (не хардкодьте порт в коде).
  • Traefik маршрутизирует трафик с домена именно на этот внутренний порт контейнера.
  • Если в репозитории уже есть HTTP-сервер (например, aiohttp, FastAPI, Flask, HTTPServer из stdlib), приложение запускается напрямую — дополнительная обёртка не нужна.
  • Если HTTP-сервера в репозитории нет, но домен указан, платформа автоматически добавляет FastAPI-обёртку и запускает бота как subprocess, чтобы домен и health-check работали корректно.

Частые проблемы

504 Gateway Timeout / «не доходит» трафик

Часто это не Telegram, а несовпадение порта в настройках и в приложении, либо сетевые настройки на ноде. Проверьте: порт в панели = порт в коде, приложение слушает 0.0.0.0, контейнер в статусе Up, не в цикле перезапусков.

«Не могу открыть файл /app/http_wrapper.py»

Если включена опция HTTP-обёртки, платформа ожидает в образе сгенерированный файл обёртки. Если образ собран без этого шага или код монтируется с хоста без этого файла — контейнер не запустится. Для полноценного веб-приложения лучше поднимать свой сервер (FastAPI, Express и т.д.) и не полагаться только на обёртку.

404 на / или /health

Маршрутизация до контейнера может работать, а маршрута в приложении нет — тогда ответ 404 идёт от вашего кода. Добавьте нужный endpoint или проверьте путь вебхука.

Рекомендации для продакшена

  • Явно задайте обработчики для путей, которые использует вебхук и браузер.
  • Логируйте старт сервера и порт, на котором слушаете.
  • После смены порта или домена сделайте повторный деплой, чтобы настройки и образ совпали.
Связанные материалы: домены и порты, переменные окружения. Если используете собственную сборку, см. также: кастомный Dockerfile.