All File Converter қызметі заманауи асинхронды Python 3.12 стегі негізінде масштабталатын бөлінген SaaS-жүйе ретінде жобаланған. Архитектура тәуелсіз қабаттарға бөлінген: желілік оқиғаларды қабылдау, тапсырмаларды оркестрлеу, ауыр бинарлы процестерді оқшаулап орындау және аналитикалық контур.

1. Жалпы технологиялар стегі және жүйелік архитектура

Платформаның негізіне жоғары өнімділік (high-throughput), жадты минималды тұтыну және ақаулардан қорғау принциптері салынған:

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

2. Асинхронды кезектер және ауыр есептеулерді оқшаулау (Celery + Redis)

Медиафайлдар мен кеңсе пакеттерін конвертациялау CPU мен RAM-ға шамадан тыс жүктеме түсіреді. Telegram-дағы кіріс хабарламаларын өңдеу процесі ауыр операциялар кезінде бұғатталмауы үшін қатаң оқшаулау жүзеге асырылған:

  • Тапсырмаларды Redis жүйесіне делегаттау: Пішінді таңдаған кезде Telegram өңдеушісі деректер базасында PROCESSING күйі бар тапсырманы тіркейді және Celery арқылы tasks.execute_conversion кезегіне тапсырма қояды.
  • Жұмысшының оқшауланған контейнері: Конвертациялау утилиталарын орындау процесі процессор уақыты мен жадының өз лимиттері бар жеке Linux контейнерінде жүзеге асырылады.
  • Қатып қалуды бақылау және таймауттар: Сыртқы утилиталарды шақыру уақытты қатаң бақылайтын асинхронды контекстке оралған (conversion_timeout_sec = 180). Лимит асып кеткен жағдайда процесс ресурс босату үшін proc.kill() арқылы мәжбүрлі түрде аяқталады.
  • Ақауларға төзімді Fallback: Redis брокері уақытша қолжетімсіз болған кезде тапсырманы локалды асинхронды диспетчер автоматты түрде қағып алып, пайдаланушы үшін қателіксіз тікелей орындайды.

3. Арнайы конвертациялау қозғалтқыштарының конвейері

Деректердің әрбір түрі үшін мамандандырылған жергілікті утилиталар мен кітапханалар қолданылады:

  • Құжаттар мен кестелер (LibreOffice): DOCX, XLSX, PPTX, RTF, ODT файлдарын PDF немесе мәтіндік форматтарға дәл көрсету үшін басқарылмайтын кеңсе пакеті (soffice --headless).
  • Ағынды аудио мен видео (FFmpeg): Бейне кодектерін (H.264), аудио кодектерін (MP3, OGG Opus) көп ағынды қайта кодтау, дыбыс жолақтарын шығарып алу, GIF генерациялау (Lanczos сүзгісі) және Telegram бейнехабарламаларын шаршы пішімге келтіру (1:1).
  • PDF жоғары жылдамдықта өңдеу (Poppler Utils): pdftotext (форматталған мәтінді UTF-8 форматына лезде шығару) және pdftoppm (LibreOffice шығындарынсыз PDF файлдарын бет бойынша растрлық кескіндерге айналдыру) утилиталары.
  • Оптикалық тану (Tesseract OCR): Сканерленген құжаттар мен фотосуреттерден 40-тан астам тілде баспа мәтінін нейрожелі көмегімен шығару.
  • Растрлық және векторлық графика: Pillow кітапханалары (HEIC және AVIF форматтарын қолдауды қоса алғанда), векторлық кескіндерге арналған CairoSVG және Telegram анимацияланған стикерлеріне (.TGS) арналған lottie.
  • Кітаптар, субтитрлер және қаріптер: Calibre қозғалтқышы (ebook-convert), pysubs2 субтитр парсері (SRT, VTT, ASS, SSA) және fonttools қаріп компиляторы (WOFF2 үшін Brotli сығу).

4. Ресурстарды алдын ала қорғау (System Guard)

Жад тапшылығына байланысты сервердің жұмысын тоқтатудан қорғау үшін (OOM Killer) System Guard алдын ала диагностика қызметі енгізілген. Файлды өңдеуге қабылдамас бұрын жүйе хосттың негізгі көрсеткіштерін тексереді:

  • Бос жедел жад (RAM): Кемінде 500 МБ бос көлем (guard_min_free_ram_mb).
  • Дискідегі орын: /tmp директориясында кемінде 2 ГБ бос кеңістік (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 — Google Кестелерінің параметрлерімен синхрондалған қолжетімді конвертациялау бағыттарының динамикалық JSON матрицасы.
  • POST /api/v1/convert — multipart/form-data (файл, мақсатты формат, сыртқы клиенттің ID-і) қабылдайтын және тікелей жүктеп алу түрінде дайын байттар ағынын беретін әмбебап эндпоинт.
  • secrets.compare_digest арқылы уақыт бойынша шабуылдардан қорғалған Bearer токендері бойынша авторизация (WEBHOOK_REFRESH_TOKEN).

7. Басқару панелі және Observability (NiceGUI + AG Grid)

Бизнес көрсеткіштері мен жүйе күйін мониторинг жасау NiceGUI 2.x негізіндегі жергілікті Single-Page басқару панеліне шығарылған:

  • Арнайы Excel-style чекбокс-сүзгілері бар AG Grid (v32+) интерактивті кестелері (aggrid_filters.js).
  • Кезектерді, API провайдерлерінің кідірістерін және PostgreSQL / Redis пингін нақты уақыт режимінде мониторинг жасау.
  • Қол қойылған JWT токендері арқылы Metabase BI-дашбордымен үздіксіз біріктірілген күндер бойынша кешенді сүзгілеу.