Настройка мини-приложения Telegram

Эта инструкция описывает, как запустить статическую страницу из каталога miniapp/index.html, подключить её к административному API бота и опубликовать через reverse-proxy (nginx или Caddy). Страница отображает текущую подписку пользователя и использует Telegram WebApp init data для авторизации.

1. Требования

Развёрнутый бот Bedolaga c актуальной базой данных.
Включённое административное API (WEB_API_ENABLED=true).
Доменное имя с действующим TLS-сертификатом (Telegram открывает веб-приложения только по HTTPS).
Возможность разместить статические файлы (miniapp/index.html и app-config.json) и проксировать запросы /miniapp/* к боту.

2. Настройка окружения

Скопируйте пример конфигурации и включите веб-API:
```
cp .env.example .env
nano .env
```
Задайте как минимум следующие переменные:
```
BOT_TOKEN=123456:ABCDEF               # токен вашего бота
WEB_API_ENABLED=true                  # включает FastAPI
WEB_API_HOST=0.0.0.0
WEB_API_PORT=8080
WEB_API_ALLOWED_ORIGINS=https://miniapp.example.com
WEB_API_DEFAULT_TOKEN=super-secret-token
SERVER_STATUS_MODE=external_link_miniapp
SERVER_STATUS_EXTERNAL_URL=https://miniapp.example.com
```
- WEB_API_ALLOWED_ORIGINS должен содержать домен, с которого будет открываться мини-приложение.
- WEB_API_DEFAULT_TOKEN создаёт bootstrap-токен для запросов от страницы. Его можно заменить на токен, созданный через POST /tokens.
Если используете RemnaWave, убедитесь, что заданы REMNAWAVE_API_URL и REMNAWAVE_API_KEY, чтобы в мини-приложении отображались дополнительные ссылки подписки.
Настройте брендирование заголовка при необходимости: MINIAPP_SERVICE_NAME и MINIAPP_SERVICE_DESCRIPTION обновят название сервиса и описание в шапке мини-приложения.

3. Запуск административного API

API можно запускать вместе с ботом (python main.py) или отдельно для тестов:

uvicorn app.webapi.app:create_web_api_app --host 0.0.0.0 --port 8080

После старта проверьте доступность:

curl -H "X-API-Key: super-secret-token" https://miniapp.example.com/miniapp/health || \
curl -H "X-API-Key: super-secret-token" http://127.0.0.1:8080/health

4. Подготовка статических файлов

Скопируйте miniapp/index.html и app-config.json на сервер, из которого nginx/Caddy будет отдавать статический контент. Например:
```
sudo mkdir -p /var/www/remnawave-miniapp
sudo cp miniapp/index.html /var/www/remnawave-miniapp/
sudo cp app-config.json /var/www/remnawave-miniapp/
```
При необходимости отредактируйте app-config.json, чтобы настроить инструкции и ссылки на нужные клиенты.
Убедитесь, что файлы доступны для чтения пользователем веб-сервера.

5. Настройка кнопки в Telegram

В .env уже выставлен SERVER_STATUS_MODE=external_link_miniapp и SERVER_STATUS_EXTERNAL_URL=https://miniapp.example.com.
Перезапустите бота. В главном меню появится кнопка «Статус серверов», открывающая веб-приложение внутри Telegram.
При необходимости задайте кастомную кнопку через @BotFather (команда /setmenu -> Web App URL).

6. Конфигурация nginx

server {
    listen 80;
    listen 443 ssl http2;
    server_name miniapp.example.com;

    ssl_certificate     /etc/letsencrypt/live/miniapp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/miniapp.example.com/privkey.pem;

    # Статические файлы мини-приложения
    root /var/www/remnawave-miniapp;
    index index.html;

    location = /app-config.json {
        add_header Access-Control-Allow-Origin "*";
        try_files $uri =404;
    }

    location / {
        try_files $uri /index.html =404;
    }

    # Проксирование запросов к административному API
    location /miniapp/ {
        proxy_pass http://127.0.0.1:8080/miniapp/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Если нужно проксировать другие эндпоинты API, добавьте аналогичные location-блоки.
}

7. Конфигурация Caddy

miniapp.example.com {
    encode gzip zstd
    root * /var/www/remnawave-miniapp
    file_server

    @config path /app-config.json
    header @config Access-Control-Allow-Origin "*"

    reverse_proxy /miniapp/* 127.0.0.1:8080 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

Caddy автоматически выпустит сертификаты через ACME. Убедитесь, что порт 443 проброшен и домен указывает на сервер.

8. Проверка работы

Откройте мини-приложение прямо в Telegram или через браузер: https://miniapp.example.com.
В консоли разработчика убедитесь, что запрос к https://miniapp.example.com/miniapp/subscription возвращает JSON с данными подписки.
Проверьте, что ссылки из блока «Подключить подписку» открываются и копируются без ошибок.

9. Диагностика

Симптом	Возможная причина	Проверка
Белый экран и ошибка 401	Неверный `X-API-Key` или `WEB_API_ALLOWED_ORIGINS`.	Проверьте токен и заголовки запроса, перегенерируйте токен через `/tokens`.
Ошибка 404 на `/miniapp/subscription`	Прокси не пробрасывает запросы или API не запущено.	Проверьте лог nginx/Caddy и убедитесь, что бот запущен с `WEB_API_ENABLED=true`.
Mini App не открывается в Telegram	URL не соответствует HTTPS или отсутствует сертификат.	Обновите сертификаты и убедитесь, что домен доступен по HTTPS.
Нет ссылок подписки	Не настроена интеграция с RemnaWave или у пользователя нет активной подписки.	Проверьте `REMNAWAVE_API_URL/KEY` и статус подписки пользователя.

После настройки вы сможете использовать мини-приложение в бот-меню и отправлять ссылку пользователям напрямую.

8.1 KiB Raw Blame History Unescape Escape