Хостинг Telegram Mini App на своём VPS

Mini App — HTTPS-интерфейс, который открывается внутри Telegram. Он может работать рядом с polling-ботом: браузер обращается к веб-backend, а бот продолжает получать сообщения через Bot API. Ради кнопки меню переключать бота на webhooks не нужно.

Скачать исходники Mini App. Пример показывает пользователю его подтверждённые имя и Telegram ID. Внутри — EN/RU интерфейс, backend на стандартной библиотеке Node 24 и Caddy для HTTPS. Нет базы, обращений к модели, оплаты или хранения переписки. Сначала можно проверить хостинг и границу авторизации, затем проектировать своё приложение.

Подготовьте DNS и сервер

Нужен Linux VPS с Docker Compose и отдельный hostname, например mini.example.com. Для одного демонстрационного приложения предлагаем начать с 1 vCPU, 1 ГБ RAM и 20 ГБ диска; это не замер ёмкости. Если сервер общий с другими службами, см. выбор VPS.

Направьте A-запись домена на VPS. AAAA добавляйте только при настроенном и доступном IPv6. Разрешите входящие TCP 80/443 в firewall провайдера и хоста, сохранив SSH. Порты должны быть свободны. Если их уже использует веб-сервер, настройте совместную работу через существующий reverse proxy, не останавливая посторонний сайт.

Настройте и запустите

mkdir -p /opt/telegram-mini-app
cd /opt/telegram-mini-app
curl --fail --show-error --location \
  https://cloudcompute.ru/downloads/telegram-mini-app-v1.zip \
  --output mini-app.zip
unzip mini-app.zip
cd telegram-mini-app
cp .env.example .env
chmod 600 .env
nano .env

Укажите токен того бота, из меню которого откроется страница, и настоящий DNS hostname:

MINI_APP_DOMAIN=mini.example.com
TELEGRAM_BOT_TOKEN=replace-with-botfather-token

docker compose up -d --build
docker compose ps
docker compose logs --tail=50 app caddy

Caddy принимает HTTPS и передаёт запросы на app:8080 внутри Docker. Порты хоста публикует только Caddy; не открывайте 8080 наружу. Выпуск сертификата зависит от DNS и доступности сервера. Caddy получает домен, а токен бота — только backend. Не помещайте токен в JavaScript, адрес браузера или публичный каталог.

Откройте https://YOUR_HOSTNAME/healthz: {"ok":true} проверяет доступность HTTP, не вход Telegram. При обычном посещении / браузером страница показывает инструкцию и отключает проверку, поскольку данных запуска Telegram нет.

Откройте через меню бота

У подтверждённого @BotFather выберите /setmenubutton, нужного бота, подпись кнопки и https://YOUR_HOSTNAME/. В личном чате нажмите эту кнопку, затем Проверить подключение. Должны появиться подтверждённые имя и числовой ID. Через пять минут закройте Mini App и откройте заново для свежих данных запуска.

Если страница открывается, но проверка не проходит, проверьте принадлежность токена этому боту, точное совпадение hostname с origin страницы и часы сервера. См. диагностику. Ручной ввод Telegram ID в обычном браузере не создаёт аутентифицированный запрос.

Каким данным доверяет backend

Браузер передаёт исходный Telegram.WebApp.initData в JSON POST. Сервер проверяет HMAC с токеном бота по всем подписанным полям, кроме hash; поле signature, если есть, также участвует. Это отличается от Ed25519-проверки для третьих сторон. Сервер отклоняет повторяющиеся и повреждённые поля, старые timestamps и некорректные данные пользователя. initDataUnsafe не используется как подтверждение личности.

Допускаются данные не старше пяти минут и до 30 секунд расхождения часов в будущее. Ответы не кэшируются, подписанные данные и имена не записываются в логи. В течение этого окна корректные данные можно отправить повторно. Для показа человеку только его собственного ID это допустимо, но не даёт прав на чужие записи и не защищает покупки, изменения или платный inference от повторов. Для них нужна отдельная логика продукта.

Сохраняйте .env, исходники и Caddyfile, а при перезапусках — volumes сертификатов. Docker tags Node/Caddy и URL Telegram SDK изменяемые: среда не полностью зафиксирована. Offline-тесты проверяют искусственно подписанные данные и локальный HTTP. Реальный запуск из Telegram, публичный TLS и развёртывание на VPS пока не проверены.

Далее: главная страница кластера, обслуживание, официальная документация Mini Apps.