SpaceNet+7 777 777 77 77

Техническая спецификация проекта: SpaceNet Wi-Fi (Access Controller)

1. Суть проекта

Полностью автоматизированная система монетизации интернета (базируемого на Starlink) через Captive Portal. Система позволяет пользователям самостоятельно подключаться к сети, выбирать тарифный план и оплачивать доступ через Kaspi Pay, после чего роутер автоматически открывает им доступ в интернет на оплаченное время без участия администратора.

2. Аппаратная архитектура (Hardware Topology)

  • Провайдер (Uplink): Терминал Starlink (скорость 150-300 Мбит/с).
  • Сетевое ядро (Controller): Роутер MikroTik hAP ax². Выполняет роль шлюза, держит на себе HotSpot-сервер, NAT, DHCP и перехватывает неавторизованный трафик.
  • Раздача Wi-Fi (Access Points): Отдельные точки доступа (например, TP-Link Omada EAP225-Outdoor), подключенные к MikroTik по кабелю (PoE) для обеспечения широкого радиуса покрытия.

3. Пользовательский путь (User Flow)

  1. Клиент подключается к открытой Wi-Fi сети (без пароля).
  2. При попытке выйти в интернет MikroTik перехватывает трафик и редиректит пользователя на стартовую страницу авторизации (login.html), автоматически подставляя в скрытое поле MAC-адрес устройства клиента ($(mac)).
  3. Клиент выбирает тариф:
    • 1 час — 200 ₸
    • 2 часа — 350 ₸
    • 5 часов — 700 ₸
    • 24 часа — 1200 ₸
  4. Фронтенд отправляет запрос на бэкенд, бэкенд генерирует ссылку на оплату в Kaspi Pay.
  5. Клиент оплачивает счет в приложении Kaspi.
  6. Бэкенд получает вебхук об оплате, подключается к MikroTik и мгновенно пускает MAC-адрес клиента в интернет.

4. Технический стек (Software Architecture)

  • Язык: Python 3.11+
  • Фреймворк: FastAPI (асинхронный REST API)
  • База данных: PostgreSQL (асинхронно через asyncpg + SQLAlchemy)
  • Интеграция с железом: asyncssh для выполнения команд RouterOS на MikroTik.
  • Пакетный менеджер: Poetry (строгая фиксация зависимостей).
  • Логирование: loguru (бизнес-логи, аудит доступов и ошибок SSH).
  • Инфраструктура: Docker, Docker Compose (изолированные контейнеры для API и БД).
  • CI/CD: GitHub Actions (автоматический линтинг через Ruff, сборка образа и пуш в Docker Hub при мердже в main).

5. Ключевая логика бэкенда (Core API)

  • POST /order: Принимает MAC-адрес и ID тарифа. Стучится в API Kaspi Pay (OAuth 2.0), создает инвойс и возвращает клиенту ссылку на оплату. Сохраняет заказ в БД со статусом pending.
  • POST /webhook/kaspi: Слушает уведомления от Kaspi. Строго проверяет HMAC-SHA256 подпись вебхука секретным ключом. При успешной проверке меняет статус заказа на paid.
  • Worker (SSH Controller): При статусе paid бэкенд инициирует SSH-сессию с MikroTik и выполняет команды:
    • Добавление MAC-адреса в /ip hotspot ip-binding (type=bypassed).
    • Создание пользователя в /ip hotspot user с жестко заданным лимитом времени (limit-uptime). Роутер сам отключит клиента, когда время выйдет.

6. Безопасность и отказоустойчивость (Security & Reliability)

  • Защита от Command Injection: Строгая Regex-валидация входящих MAC-адресов на уровне Pydantic-схем, чтобы предотвратить выполнение вредоносных скриптов в консоли MikroTik.
  • Защита от Race Conditions: Атомарные UPDATE-запросы в PostgreSQL на уровне БД. Если Kaspi пришлет два вебхука одновременно, система обработает заказ только один раз.
  • SSH Timeouts: Жестко заданные таймауты при подключении к роутеру (5 секунд) и отключенная проверка ключей, чтобы зависший MikroTik не «положил» воркеры FastAPI.
  • Тестовый режим: Флаг TEST_MODE в .env для полного тестирования флоу (с генерацией мок-ссылок на оплату) без необходимости дергать реальное API Kaspi.