Сэрвіс All File Converter спраектаваны як маштабаваная размеркаваная SaaS-сістэма на базе сучаснага асінхроннага стэка Python 3.12. Архітэктура падзелена на незалежныя слаі: прыём сеткавых падзей, аркестрацыя задач, ізаляванае выкананне цяжкіх бінарных працэсаў і аналітычны контур.

1. Агульны стэк тэхналогій і сістэмная архітэктура

У аснову платформы закладены прынцыпы высокай прадукцыйнасці (high-throughput), мінімальнага спажывання памяці і абароны ад збояў:

  • Telegram Bot Framework: Aiogram 3.13, які працуе ў рэжыме Webhook з валідацыяй сакрэтных токенаў і кастамнымі фільтрамі жыццёвага цыкла паведамленняў.
  • Вэб-шлюз і REST API: FastAPI на базе ASGI-сервера Uvicorn з асінхроннай патокавай аддачай бінарных файлаў (FileResponse) і фонавай ачысткай праз BackgroundTasks.
  • Брокер чарг і кэш: Redis 7 (кіраванне задачамі Celery, блакіроўкі ад стану гонкі, абарона ад брутфорсу, кэшаванне сесій).
  • Фонавы выканаўца (Task Queue): Celery 5.4 з выдзеленым пулам воркераў у ізаляваным кантэйнеры converter_worker.
  • База даных: PostgreSQL 16 з ORM-слаем SQLAlchemy 2.0 (asyncpg), пулам пастаянных злучэнняў (20+10 overflow) і аўтапаўторам збойных транзакцый (@db_retry).
  • Сеткавы контур: Тунэляванне праз Cloudflare Zero Trust з блакіроўкай прамога IP-доступу да сервера праз Middleware.

2. Асінхронныя чаргі і ізаляцыя цяжкіх вылічэнняў (Celery + Redis)

Канвертацыя медыяфайлаў і офісных пакетаў стварае пікавыя нагрузкі на CPU і RAM. Каб працэс апрацоўкі ўваходных паведамленняў у Telegram не блакіраваўся пры цяжкіх аперацыях, рэалізавана строгая ізаляцыя:

  • Дэлегіраванне задач у Redis: Пры выбары фармату Telegram-апрацоўшчык рэгіструе задачу ў БД са статусам PROCESSING і ставіць заданне ў чаргу tasks.execute_conversion праз Celery.
  • Ізаляваны кантэйнер воркера: Выкананне ўтыліт канвертацыі адбываецца ў асобным Linux-кантэйнеры з уласным лімітам працэсарнага часу і памяці.
  • Кантроль завісанняў і тайм-аўты: Выклікі знешніх утыліт агорнутыя ў асінхронны кантэкст з жорсткім кантролем часу (conversion_timeout_sec = 180). Пры перавышэнні ліміту працэс прымусова завяршаецца праз proc.kill(), вызваляючы рэсурсы.
  • Адказаўстойлівы Fallback: Пры часовай недаступнасці брокера Redis задача аўтаматычна перахопліваецца лакальным асінхронным дыспетчарам і выканоўваецца наўпрост без збою для карыстальніка.

3. Канвеер спецыялізаваных рухавікоў канвертацыі

Для кожнага тыпу даных задзейнічаюцца вузкаспецыялізаваныя натыўныя ўтыліты і бібліятэкі:

  • Дакументы і табліцы (LibreOffice): Бязгаловы офісны пакет (soffice --headless) для дакладнага рэндэрынгу DOCX, XLSX, PPTX, RTF, ODT у фармат PDF або тэкставыя файлы.
  • Патокавае аўдыя і відэа (FFmpeg): Шматпатокавае перакадзіраванне відэакодэкаў (H.264), аўдыякодэкаў (MP3, OGG Opus), выманне гукавых дарожак, генерацыя GIF (Lanczos-фільтр) і квадратнае кадраванне (1:1) відэапаведамленняў Telegram.
  • Высокахуткасная апрацоўка PDF (Poppler Utils): Утыліты pdftotext (імгненнае выманне фарматаванага тэксту ў UTF-8) і pdftoppm (пастраничный рэндэрынг PDF у растравыя выявы без накладных выдаткаў LibreOffice).
  • Аптычнае распазнаванне (Tesseract OCR): Нейрасеткавае выманне друкаванага тэксту са сканаў і фатаграфій на 40+ мовах.
  • Растравая і вектарная графіка: Бібліятэкі Pillow (уключаючы падтрымку фарматаў HEIC і AVIF), CairoSVG для вектарных малюнкаў і lottie для аніміраваных стыкераў Telegram (.TGS).
  • Кнігі, субцітры і шрыфты: Рухавік Calibre (ebook-convert), парсер субцітраў pysubs2 (SRT, VTT, ASS, SSA) і кампілятар шрыфтоў fonttools (Brotli-кампрэсія ў WOFF2).

4. Прэвентыўная абарона рэсурсаў (System Guard)

Для абароны ад падзення сервера па прычыне недахопу памяці (OOM Killer) укаранёны сэрвіс прэвентыўнай дыягностыкі System Guard. Перад прыёмам файла ў апрацоўку сістэма правярае ключавыя метрыкі хоста:

  • Свободная аператыўная памяць (RAM): Мінімум 500 МБ вольнага аб'ёму (guard_min_free_ram_mb).
  • Месца на дыску: Мінімум 2 ГБ вольнай прасторы ў дырэкторыі /tmp (guard_min_free_disk_mb).
  • Чрга задач: Абмежаванне даўжыні чаргі Celery (не больш за 20 чакаючых задач).

Пры перавышэнні лімітаў сэрвіс часова ўключае абарону (HTTP 503 / паведамленне ў чаце), прадухіляючы перагрузку сервера і адпраўляючы імгненны алерт адміністратарам у Telegram.

5. Жыццёвы цыкл файлаў і бяспека (GDPR)

Архітэктура спраектаваная па мадэлі Zero-Data-Footprint:

  • Файлы карыстальнікаў загружаюцца ў абаронены том tmp/conversions/ з унікальнымі прэфіксамі на базе ідэнтыфікатараў задач.
  • Файлы застаюцца даступнымі строга ў рамках рабочай сесіі — не больш за 15 хвілін (900 секунд).
  • Аўтаматычны зборшчык смецця сцірае зыходныя і гатовыя файлы адразу пасля пацвярджэння паспяховай адпраўкі ў чат альбо па заканчэнні тайм-аўта сесіі.
  • База даных PostgreSQL не захоўвае бінарныя файлы або персанальныя тэксты дакументаў — у табліцах фіксуюцца толькі ананізаваныя тэхнічныя метаданыя (фарматы, памеры ў байтах, час працы, статусы).

6. Універсальны REST API для знешніх вэб-сэрвісаў

Сэрвіс першапачаткова спраектаваны як мультыплатформавы бэкенд. Нараўне з ботам функцыянуе паўнацэнны абаронены праграмны інтэрфейс для вэб-сайтаў (напрыклад, на Django) і старонніх ботаў:

  • GET /api/v1/formats — дынамічная JSON-матрыца даступных напрамкаў канвертацыі, сінхранізаваная з наладамі Google Табліц.
  • POST /api/v1/convert — універсальны эндпоінт, які прымае multipart/form-data (файл, мэтавы фармат, ID знешняга кліента) і аддае гатовы паток байтаў у выглядзе простага спампоўвання.
  • Аўтарызацыя па Bearer-такенех (WEBHOOK_REFRESH_TOKEN) з абаронай ад нападаў па часе праз secrets.compare_digest.

7. Панэль кіравання і Observability (NiceGUI + AG Grid)

Маніторынг бізнес-паказчыкаў і стану сістэмы выведзены ў натыўную Single-Page панэль кіравання на базе NiceGUI 2.x:

  • Інтэрактыўныя табліцы AG Grid (v32+) з кастамнымі Excel-style чэкбокс-фільтрамі (aggrid_filters.js).
  • Маніторынг чаргаў, затрымак API-правайдэраў і пінга PostgreSQL / Redis у рэальным часе.
  • Скразная фільтрацыя па датах з беспешнаю інтэграцыяй BI-дашборда Metabase праз падпісаныя JWT-токены.