remnawave-bedolaga-telegram-bot/docs/web-admin-integration.md

Интеграция веб-админки

Этот документ описывает запуск встроенного административного веб-API бота и типовой сценарий интеграции c внешней веб-админкой. API разворачивается вместе с ботом, использует FastAPI и защищено токенами доступа.

1. Обзор архитектуры

• Веб-API запускается в том же процессе, что и бот, через встроенный uvicorn сервер.
• Авторизация выполняется по токену: X-API-Key или Authorization: Bearer <token>.
• Все эндпоинты работают поверх HTTPS/HTTP и возвращают структуры в формате JSON.
• Встроенный механизм миграций создаёт таблицу web_api_tokens и бутстрап-токен, если указан в конфигурации.

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

Добавьте переменные в .env (или другую систему конфигурации):

Переменная	Назначение	Значение по умолчанию / пример
WEB_API_ENABLED	Включает веб-API.	true
WEB_API_HOST	IP/hostname, на котором слушает API.	0.0.0.0
WEB_API_PORT	Порт веб-API.	8080
WEB_API_ALLOWED_ORIGINS	Список доменов для CORS, через запятую. * разрешит всё.	https://admin.example.com
WEB_API_DOCS_ENABLED	Включить /docs и /openapi.json. В проде лучше false.	false
WEB_API_WORKERS	Количество воркеров uvicorn. В embed-режиме всегда приводится к 1.	1
WEB_API_REQUEST_LOGGING	Логировать каждый запрос API.	true
WEB_API_DEFAULT_TOKEN	Бутстрап-токен, который будет создан при миграции.	super-secret-token
WEB_API_DEFAULT_TOKEN_NAME	Отображаемое имя созданного токена.	Bootstrap Token
WEB_API_TOKEN_HASH_ALGORITHM	Алгоритм хеширования токенов (sha256, sha512, ...).	sha256

⚠️ Если вы храните конфигурацию в Kubernetes/Ansible/других системах — не забудьте обновить секреты, чтобы бот видел эти переменные.

3. Подготовка базы данных

1. Убедитесь, что настройки БД верны (DATABASE_URL или параметры PostgreSQL/SQLite).
2. При старте бота автоматически запускается универсальная миграция run_universal_migration, которая:
   • создаёт таблицу web_api_tokens, если её нет;
   • активирует токен из WEB_API_DEFAULT_TOKEN, если он задан.
3. Если нужно запустить миграцию вручную, выполните:

python -c "import asyncio; from app.database.universal_migration import run_universal_migration; asyncio.run(run_universal_migration())"

Или просто запустите python main.py — бот выполнит ту же процедуру автоматически.

4. Запуск веб-API

# Создаём .env и включаем веб-API
cp .env.example .env
nano .env  # проставьте WEB_API_* переменные и BOT_TOKEN

# Запускаем бота (локально)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

В Docker достаточно пробросить порт WEB_API_PORT из контейнера бота. После запуска API будет доступно по адресу http://<WEB_API_HOST>:<WEB_API_PORT>.

5. Аутентификация и токены

• Первый токен удобно задать через WEB_API_DEFAULT_TOKEN. Он появится в таблице при запуске миграции.
• Для управления токенами используйте эндпоинты /tokens:
  • GET /tokens — список токенов.
  • POST /tokens — создать новый токен. Возвращает открытое значение один раз.
  • POST /tokens/{id}/revoke и /activate — управление статусом.
  • DELETE /tokens/{id} — удаление.
• Заголовок авторизации можно передавать двумя способами:

X-API-Key: <ваш_токен>
# или
Authorization: Bearer <ваш_токен>

Пример запроса на создание токена:

curl -X POST "http://127.0.0.1:8080/tokens" \
  -H "X-API-Key: super-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Web admin", "description": "UI token"}'

6. Основные эндпоинты

Метод	Путь	Назначение
GET	/health	Статус API, версия бота, флаги включённых сервисов.
GET	/stats/overview	Сводная статистика по пользователям, подпискам, платежам и тикетам.
GET	/settings/categories	Категории системных настроек.
GET	/settings	Полный список настроек (с текущими и дефолтными значениями).
GET	/settings/{key}	Получить одну настройку.
PUT	/settings/{key}	Обновить значение настройки.
DELETE	/settings/{key}	Сбросить настройку к значению по умолчанию.
GET	/users	Список пользователей с фильтрами и пагинацией.
GET	/users/{id}	Детали пользователя.
POST	/users	Создать пользователя (например, для ручной выдачи доступа).
PATCH	/users/{id}	Обновить профиль пользователя или статус.
POST	/users/{id}/balance	Корректировка баланса с созданием транзакции.
GET	/subscriptions	Список подписок с фильтрами.
POST	/subscriptions	Создать триальную или платную подписку.
POST	/subscriptions/{id}/extend	Продлить подписку на N дней.
POST	/subscriptions/{id}/traffic	Добавить трафик (ГБ).
POST	/subscriptions/{id}/devices	Добавить устройства.
POST	/subscriptions/{id}/squads	Привязать сквад.
DELETE	/subscriptions/{id}/squads/{uuid}	Удалить сквад.
GET	/transactions	История транзакций.
GET	/tickets	Список тикетов поддержки.
GET	/tickets/{id}	Тикет с перепиской.
POST	/tickets/{id}/status	Изменить статус тикета.
POST	/tickets/{id}/priority	Изменить приоритет.
POST	/tickets/{id}/reply-block	Заблокировать ответы пользователя.
DELETE	/tickets/{id}/reply-block	Снять блокировку.
GET	/promo-groups	Список промо-групп с количеством участников.
POST	/promo-groups	Создать промо-группу.
PATCH	/promo-groups/{id}	Обновить промо-группу.
DELETE	/promo-groups/{id}	Удалить промо-группу.
GET	/tokens	Управление токенами доступа.

Все списковые эндпоинты поддерживают пагинацию (limit, offset) и фильтры, описанные в OpenAPI спецификации. Если WEB_API_DOCS_ENABLED=true, документация доступна по /docs. В ответах /settings поле choices всегда массив: пустой список означает отсутствие предопределённых значений.

7. Сценарий интеграции веб-админки

1. Health-check — перед авторизацией UI вызывает GET /health, чтобы отобразить статус и версию бота.
2. Настройки UI — подгружает категории через GET /settings/categories, далее выводит форму со значениями из GET /settings.
3. Статистика дашборда — GET /stats/overview для карточек с показателями.
4. Раздел пользователи — GET /users с поиском (search), фильтрами по статусу или промо-группе. Для детальной карточки использовать GET /users/{id}.
5. Операции с подпиской — использовать POST /subscriptions/{id}/... эндпоинты для продления, выдачи трафика и устройств.
6. Поддержка — список тикетов (GET /tickets), изменение статуса (POST /tickets/{id}/status), блокировка ответов (POST /tickets/{id}/reply-block).
7. История операций — GET /transactions с фильтрами по пользователю, типу и периоду.

8. CORS, безопасность и логирование

• Разрешённые домены указываются в WEB_API_ALLOWED_ORIGINS. Для нескольких доменов перечислите их через запятую.
• Для продакшена рекомендуется отключить публичную документацию (WEB_API_DOCS_ENABLED=false).
• WEB_API_REQUEST_LOGGING=true добавляет middleware, которое логирует метод, путь и статус ответа. Используйте его для аудита или отключите в продакшене, если хватает reverse-proxy логов.
• Все токены хранятся в базе в хешированном виде. Не храните открытые значения в коде.

9. Диагностика проблем

Симптом	Возможная причина	Что проверить
401 Unauthorized	Неверный или просроченный токен.	Пересоздайте токен через /tokens и обновите UI.
403/404 при работе с настройками	Неверный ключ настройки.	Получите список доступных ключей через GET /settings.
422 Unprocessable Entity	Неверный тип данных в теле запроса.	Проверьте типы (числа, булевы, строки) и формат JSON.
API не стартует	Порт занят или неверные переменные окружения.	Проверьте логи контейнера бота и значения WEB_API_HOST/PORT.

10. Рекомендации по эксплуатации

• Регулярно ревизируйте список активных токенов и отключайте неиспользуемые.
• Для внешних админок размещайте API за reverse-proxy (nginx, Caddy, Traefik) с TLS.
• Включите мониторинг доступности (например, curl на /health) в систему наблюдения.
• Обновляйте бота и админку синхронно, чтобы использовать новые поля API.