# Веб-приложения и домены Эта страница — для тех, кто публикует **веб-сервис** вместе с ботом: API, мини-приложение, панель, приём вебхуков Telegram и т.п. > Нужна база про `0.0.0.0`, Reverse Proxy и `PORT`? Начните со статьи [Работа с доменами и портами](domains-and-ports). > Здесь — практические сценарии: вебхук, деплой, типовые ошибки и диагностика.  ## Когда читать эту страницу - Вы уже включили опцию **«Использовать домен»** и публикуете веб-сервис. - Нужна настройка webhook URL и проверка маршрутов в приложении. - Пытаетесь разобраться с `502/504`, `404` и запуском HTTP-обёртки. ## Что даёт включение домена - Запросы из интернета приходят на ваш домен по **HTTPS** (порт 443). - Платформа маршрутизирует трафик в **ваш контейнер** на выбранный **внутренний порт** приложения. - Для Telegram-бота можно указать **вебхук** на URL вида `https://ваш-домен/...` — Telegram будет слать обновления на этот адрес. ## Что проверить перед деплоем - Включена опция **«Использовать домен»**. - Веб-сервер слушает `0.0.0.0` и читает порт из `PORT`. - Порт в настройках бота совпадает с портом, который реально слушает приложение. - После смены домена/порта выполнен повторный деплой. Подробно про устройство трафика и портов: [Работа с доменами и портами](domains-and-ports). ## Автоматический поддомен (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 1. Включите домен в настройках бота и сделайте деплой. 2. Убедитесь, что приложение отвечает по `https://ваш-домен/health` (или по вашему health-пути). 3. Настройте webhook в Telegram на `https://ваш-домен/webhook`. 4. Отправьте сообщение боту в Telegram. 5. Проверьте, что: - в логах контейнера есть входящий webhook-запрос, - бот обработал апдейт (например, ответил в чат), - нет цикла рестартов контейнера. Пример минимального тестового проекта: [bothost-tech/bothost_testwebhook](https://github.com/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 - Указан один путь в 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 или проверьте путь вебхука. ## Рекомендации для продакшена - Явно задайте обработчики для путей, которые использует вебхук и браузер. - Логируйте старт сервера и порт, на котором слушаете. - После смены порта или домена сделайте **повторный деплой**, чтобы настройки и образ совпали. --- *Связанные материалы: [домены и порты](domains-and-ports), [переменные окружения](environment-variables).* *Если используете собственную сборку, см. также: [кастомный Dockerfile](custom-dockerfile).*