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

Эта страница — для тех, кто публикует веб-сервис вместе с ботом: API, мини-приложение, панель, приём вебхуков Telegram и т.п. Базовые понятия о доменах и портах см. также в статье Работа с доменами и портами.

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

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

Как устроен трафик (кратко)

    • Пользователь или Telegram открывает https://ваш-поддомен.bothost.tech (или ваш кастомный домен).
    • DNS указывает на центральный сервер платформы — там завершается TLS (сертификат).
    • Дальше запрос проксируется на ноду, где крутится ваш контейнер, и попадает в приложение на нужном порту.
Вам не нужно открывать порты вручную на сервере: наружу доступны только стандартные 80/443 у прокси; ваше приложение слушает порт внутри контейнера.

Порт приложения: два важных поля

  • Порт в панели / internal_port — это тот порт, на который смотрит прокси внутри Docker. Он должен совпадать с тем, на чём реально слушает ваше приложение.
  • Переменная PORT в контейнере обычно выставляется платформой в то же значение.
Если вы поменяли только PORT в переменных окружения, но не обновили порт в настройках бота, прокси будет стучаться «не туда» — часто это 502 или 504 Gateway Timeout. Рекомендация: в коде читать порт из PORT и слушать 0.0.0.0: 
import os
port = int(os.getenv("PORT", "3000"))
# uvicorn / flask / etc. — host="0.0.0.0", port=port
Подробнее про 0.0.0.0 и примеры — в доменах и портах.

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

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

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

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

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

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

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

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

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

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

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

404 на / или /health

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

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

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