Die All File Converter-diens is ontwerp as 'n skaalbare, verspreide SaaS-stelsel gebaseer op die moderne asinchroniese Python 3.12-stapel. Die argitektuur is verdeel in onafhanklike lae: netwerkgebeurtenis-ontvangs, taakorkestrasie, geïsoleerde uitvoering van swaar binêre prosesse, en die analitiese kring.

1. Algemene tegnologiestapel en stelselargitektuur

Die platform is gebaseer op die beginsels van hoë deurset (high-throughput), minimale geheueverbruik, en foutbeskerming:

  • Telegram Bot Framework: Aiogram 3.13, wat in Webhook-modus werk met geheime tekenvalidasie en pasgemaakte filters vir die boodskaplewensiklus.
  • Webpoort en REST API: FastAPI gebaseer op die Uvicorn ASGI-bediener met asinchroniese stroomlewering van binêre lêers (FileResponse) en agtergrondskoonmaak via BackgroundTasks.
  • Wagrykase en kas: Redis 7 (bestuur van Celery-take, slotte teen wedlooptoestande, beskerming teen brute force, sessiekas).
  • Agtergrond-uitvoerder (Task Queue): Celery 5.4 met 'n toegewyde poel werkers in 'n geïsoleerde converter_worker-houer.
  • Databasis: PostgreSQL 16 met die ORM-laag SQLAlchemy 2.0 (asyncpg), 'n permanente verbindingspoel (20+10 overflow), en outomatiese herhaling van mislukte transaksies (@db_retry).
  • Netwerkkring: Tonnelwerking via Cloudflare Zero Trust met blokkering van direkte IP-toegang tot die bediener deur 'n Middleware.

2. Asinchroniese wagrye en isolasie van swaar berekeninge (Celery + Redis)

Mediabestands- en kantoorpakketokomskakeling skep piekvragte op CPU en RAM. Om te verhoed dat die verwerking van inkome-boodskappe in Telegram tydens swaar bewerkings geblokkeer word, is streng isolasie geïmplementeer:

  • Delegering van take na Redis: By die kies van 'n formaat registreer die Telegram-verwerker die taak in die databasis met die status PROCESSING en plaas die taak in die tasks.execute_conversion-wagryk via Celery.
  • Geïsoleerde werkerhouer: Die uitvoering van omskakelingsnutsmiddels vind plaas in 'n afsonderlike Linux-houer met sy eie verwerkingstyd- en geheuelimiet.
  • Vriesbeheer en tyduitslae: Oproepe na eksterne nutsmiddels word in 'n asinchroniese konteks toegedraai met streng tydbeheer (conversion_timeout_sec = 180). As die limiet oorskry word, word die proses gedwonge beëindig via proc.kill(), wat hulpbronne vrystel.
  • Foutbestande Fallback: Met tydelike onbeskikbaarheid van die Redis-makelaar word die taak outomaties deur die plaaslike asinchroniese sender onderskep en direk uitgevoer sonder 'n onderbreking vir die gebruiker.

3. Pyplyn van gespesialiseerde omskakelingsenjins

Vir elke datatipe word nougesette, gespesialiseerde inheemse nutsmiddels en biblioteke ingespan:

  • Dokumente en tabelle (LibreOffice): 'n Koplose kantoorpakket (soffice --headless) vir presiese the rendering van DOCX, XLSX, PPTX, RTF, ODT na PDF-formaat of tekslêers.
  • Stroom-oudio en -video (FFmpeg): Multidraad-omskakeling van videokodeks (H.264), oudiokodeks (MP3, OGG Opus), onttrekking van klankbane, GIF-generering (Lanczos-filter) en vierkante snyding (1:1) van Telegram-videoboodskappe.
  • Hoëspoed PDF-verwerking (Poppler Utils): Nutsmiddels pdftotext (onmiddellike onttrekking van geformateerde teks in UTF-8) en pdftoppm (bladsy-vir-bladsy the rendering van PDF na rasterbeelde sonder LibreOffice-bokoste).
  • Optiese karakterherkenning (Tesseract OCR): Neurale netwerk-onttrekking van gedrukte teks vanaf skanderings en foto's in 40+ tale.
  • Raster- en vektorgrafika: Biblioteke Pillow (insluitend ondersteuning vir HEIC- en AVIF-formate), CairoSVG vir vektorbeelde, en lottie vir geanimeerde Telegram-plakkers (.TGS).
  • Boeke, onderskrifte en lettertipes: Die Calibre-enjin (ebook-convert), onderskrif-parser pysubs2 (SRT, VTT, ASS, SSA), en lettertipe-kompilleerder fonttools (Brotli-kompressie in WOFF2).

4. Voorkomende hulpbronbeskerming (System Guard)

Om te verhoed dat die bediener om te min geheue (OOM Killer) neerstort, is die System Guard-diens vir voorkomende diagnostiek geïmplementeer. Voordat 'n lêer vir verwerking aanvaar word, kontroleer die stelsel sleutelgasheermetrieke:

  • Vrye geheue (RAM): Ten minste 500 MB vrye volume (guard_min_free_ram_mb).
  • Skyfspasie: Ten minste 2 GB vrye spasie in die /tmp-gids (guard_min_free_disk_mb).
  • Taakwagryk: Beperking van die Celery-wagryklengte (nie meer as 20 take wat wag nie).

Wanneer die limiete oorskry word, skakel die diens tydelik beskerming aan (HTTP 503 / boodskap in die klets), wat bedieroorlading voorkom en 'n onmiddellike waarskuwing aan administrateurs in Telegram stuur.

5. Lêerlewensiklus en sekuriteit (GDPR)

Die argitektuur is ontwerp volgens die Zero-Data-Footprint-model:

  • Gebruikerslêers word op 'n veilige tmp/conversions/-volume gelaai met unieke voorvoegsels gebaseer op taak-ID's.
  • Lêers bly streng beskikbaar binne die werksessie — nie langer as 15 minute nie (900 sekondes).
  • Die outomatiese rommelversamelaar vee oorspronklike en voltooide lêers uit sodra suksesvolleversending na die klets bevestig is of na verstryking van die sessie-tyduitslag.
  • Die PostgreSQL-databasis stoor geen binêre lêers of persoonlike dokumenttekste nie — slegs geanonimiseerde tegniese metadata (formate, groottes in grepe, werksduur, statusse) word in die tabelle aangeteken.

6. Universele REST API vir eksterne webdienste

Die diens is aanvanklik as 'n multiplatform-agterkant (backend) ontwerp. Benewens die bot, funksioneer 'n volslae, beveiligde programmatiewe koppelvlak vir webwerwe (byvoorbeeld op Django) en derdeparty-botte:

  • GET /api/v1/formats — 'n dinamiese JSON-matriks van beskikbare omskakelingsrigtings, gesinkroniseer met Google Blaaie-instellings.
  • POST /api/v1/convert — 'n universele eindpunt wat multipart/form-data aanvaar (lêer, teikenformaat, eksterne kliënt-ID) en 'n gereed greepstroom as 'n direkte aflaai teruggee.
  • Magtiging via Bearer-tekens (WEBHOOK_REFRESH_TOKEN) met beskerming teen tydaanvalle via secrets.compare_digest.

7. Beheerpaneel en Observability (NiceGUI + AG Grid)

Monitering van besigheidsmaatstawwe en stelselstatus is na 'n inheemse Single-Page beheerpaneel gebaseer op NiceGUI 2.x geskuif:

  • Interaktiewe AG Grid (v32+)-tabelle met pasgemaakte Excel-styl hokkiefilters (aggrid_filters.js).
  • Monitering van wagrye, API-verskaffer vertragings, en PostgreSQL / Redis-ping in reële tyd.
  • Deurlopende datumfiltrering met naatlose integrasie van die Metabase BI-dashboard via ondertekende JWT-tekens.