Mae gwasanaeth All File Converter wedi'i gynllunio fel system SaaS ddosranedig y gellir ei hehangu, yn seiliedig ar y stac anghydamserol modern Python 3.12. Mae'r bensaerniaeth wedi'i rhannu'n haenau annibynnol: derbyn digwyddiadau rhwydwaith, trefnu tasgau, gweithredu prosesau deuaidd trwm yn ynysedig, a chylched ddadansoddol.

1. Stac technoleg gyffredinol a phensaerniaeth system

Mae'r platfform yn seiliedig ar egwyddorion perfformiad uchel (high-throughput), defnydd lleiaf posibl o gof, ac amddiffyniad rhag methiannau:

  • Telegram Bot Framework: Aiogram 3.13, yn gweithredu yn y modd Webhook gyda dilysu tocynnau cyfrinachol a hidlwyr cylch oes negeseuon personol.
  • Porth Gwe a REST API: FastAPI yn seiliedig ar y gweinydd ASGI Uvicorn gyda chyflwyno ffeiliau deuaidd ffrydio anghydamserol (FileResponse) a glanhau cefndirol trwy BackgroundTasks.
  • Brocer ciwiau a storfa dros dro: Redis 7 (rheoli tasgau Celery, cloeon rhag cyflwr rasio, amddiffyniad rhag brute-force, storio sesiynau dros dro).
  • Gweithredwr cefndirol (Task Queue): Celery 5.4 gyda phŵer gweithwyr penodol mewn cynhwysydd ynysig converter_worker.
  • Cronfa ddata: PostgreSQL 16 gydag haen ORM SQLAlchemy 2.0 (asyncpg), pwll o gysylltiadau parhaol (20+10 overflow) ac ailgeisio trafodion a fethodd yn awtomatig (@db_retry).
  • Cylched rhwydwaith: Twnelu trwy Cloudflare Zero Trust gyda rhwystro mynediad IP uniongyrchol i'r gweinydd trwy Middleware.

2. Ciwiau anghydamserol ac ynysu cyfrifiadau trwm (Celery + Redis)

Mae trosi ffeiliau cyfryngau a phekejau swyddfa yn creu llwythi brig ar y CPU a RAM. Er mwyn sicrhau nad yw'r broses o brosesu negeseuon sy'n dod i mewn yn Telegram yn cael ei rhwystro yn ystod gweithrediadau trwm, gweithredwyd ynysu llym:

  • Dirprwyo tasgau i Redis: Wrth ddewis fformat, mae prosesydd Telegram yn cofrestru'r dasg yn y gronfa ddata gyda'r statws PROCESSING ac yn rhoi'r dasg yn y ciw tasks.execute_conversion trwy Celery.
  • Cynhwysydd gweithiwr ynysig: Mae gweithredu cyfleustodau trosi yn digwydd mewn cynhwysydd Linux ar wahân gyda'i derfyn amser prosesu a'i gof ei hun.
  • Rheoli rhewi a therfynau amser: Mae galwadau i gyfleustodau allanol wedi'i lapio mewn cyd-destun anghydamserol gyda rheolaeth amser lem (conversion_timeout_sec = 180). Os caiff y terfyn ei eedd, caiff y broses ei therfynu'n orfodol trwy proc.kill(), gan ryddhau adnoddau.
  • Fallback sy'n gwrthsefyll methiant: Os yw'r brocer Redis yn anateb dros dro, mae'r dasg yn cael ei rhyng-gipio'n awtomatig gan y gweinyddwr anghydamserol lleol ac yn cael ei gweithredu'n uniongyrchol heb ddigwyddiad i'r defnyddiwr.

3. Piblinell peiriannau trosi arbenigol

Ar gyfer pob math o ddata, defnyddir cyfleustodau a llyfrgelloedd brodorol arbenigol iawn:

  • Dogfennau a thabledi (LibreOffice): Pecyn swyddfa penagored (soffice --headless) ar gyfer rendro cywir o DOCX, XLSX, PPTX, RTF, ODT i fformat PDF neu ffeiliau testun.
  • Nodweddion sain a fideo ffrydio (FFmpeg): Ailgodi cod fideo aml-belydr (H.264), codau sain (MP3, OGG Opus), tynnu traciau sain, cynhyrchu GIF (hidlydd Lanczos) a chropio sgwâr (1:1) o negeseuon fideo Telegram.
  • Prosesu PDF cyflym iawn (Poppler Utils): Cyfleustodau pdftotext (tynnu testun fformatiedig ar unwaith yn UTF-8) a pdftoppm (rendro tudalen wrth dudalen o PDFs yn ddelweddau raster heb orbenion LibreOffice).
  • Adnabod testun optig (Tesseract OCR): Tynnu testun printiedig o sganiau a lluniau mewn 40+ o ie اللغه trwy rwydweithiau niwral.
  • Graffeg raster a phetryal: Llyfrgelloedd Pillow (gan gynnwys cefnogaeth ar gyfer fformatau HEIC ac AVIF), CairoSVG ar gyfer delweddau fector, a lottie ar gyfer sticeri animeiddiedig Telegram (.TGS).
  • Llyfr, Is-deitlau a Ffontiau: Peiriant Calibre (ebook-convert), dadansoddwr is-deitlau pysubs2 (SRT, VTT, ASS, SSA), a chasglwr ffontiau fonttools (Cywasgiad Brotli yn WOFF2).

4. Amddiffyniad adnoddau ataliol (System Guard)

Er mwegeio rhag i'r gweinydd gwympo oherwydd diffyg cof (OOM Killer), cyflwynwyd gwasanaeth diagnosis ataliol System Guard. Cyn derbyn ffeil i'w phrosesu, mae'r system yn gwirio metrigau allweddol y gwesteiwr:

  • Cof gweithredol rhydd (RAM): Lleiafswm o 500 MB o le rhydd (guard_min_free_ram_mb).
  • Lle ar y ddisg: Lleiafswm o 2 GB o le rhydd yn y cyfeiriadur /tmp (guard_min_free_disk_mb).
  • Ciw tasgau: Cyfyngu ar hyd ciw Celery (dim mwy na 20 o dasgau yn aros).

Pan fydd y terfynau'n cael eu hysgubo, mae'r gwasanaeth yn troi ar yr amddiffyniad dros dro (HTTP 503 / neges yn y sgwrs), gan atal gorlwytho'r gweinydd ac anfon hysbysiad ar unwaith i'r gweinyddwyr yn Telegram.

5. Cylch oes ffeiliau a diogelwch (GDPR)

Mae'r bensaerniaeth wedi'i dylunio yn ôl y model Zero-Data-Footprint:

  • Mae ffeiliau defnyddwyr yn cael eu llwytho i gyfrol ddiogel tmp/conversions/ gyda rhagddodiaid unigryw yn seiliedig ar ddangosyddion tasg.
  • Mae ffeiliau yn aros ar gael yn llym o fewn y sesiwn waith — dim mwy na 15 munud (900 eiliad).
  • Mae'r casglwr sbwriel awtomatig yn dileu ffeiliau gwreiddiol a gorffenedig yn union ar ôl cadarnhau bod anfon llwyddiannus i'r sgwrs neu ar ôl i derfyn amser y sesiwn ddod i ben.
  • Nid yw'r gronfa ddata PostgreSQL yn storio ffeiliau deuaidd na thestyll dogfennau personol — dim ond metadata technegol dienw sy'n cael ei gofnodi yn y tablau (fformatau, meintiau mewn beitiau, amser gweithredu, statws).

6. REST API cyffredinol ar gyfer gwasanaethau gwe allanol

Mae'r gwasanaeth wedi'i ddylunio o'r dechrau fel ôl-ben aml-blatfform. Ynghyd â'r bot, mae rhyngwyneb meddalwedd diogel cwbl weithredol yn gweithredu ar gyfer gwefannau (er enghraifft, ar Django) a botiau trydydd parti:

  • GET /api/v1/formats — matrics JSON deinamig o gyfeiriadau trosi sydd ar gael, wedi'i gydamseru â gosodiadau Google Sheets.
  • POST /api/v1/convert — diweddbwynt cyffredinol sy'n derbyn multipart/form-data (ffeil, fformat targed, ID cleient allanol) ac yn cyflwyno ffrwd o beitiau paratô fel lawrlwythiad uniongyrchol.
  • Awdurdodiad trwy docynnau Bearer (WEBHOOK_REFRESH_TOKEN) gyda diogelwch rhag ymosodiadau amser trwy secrets.compare_digest.

7. Panel rheoli ac Observability (NiceGUI + AG Grid)

Mae monitro dangosyddion busnes a chyflwr y system wedi'i symud i banel rheoli Single-Page brodorol yn seiliedig ar NiceGUI 2.x:

  • Tablau rhyngweithiol AG Grid (v32+) gyda hidlwyr blwch ticio arddull Excel personol (aggrid_filters.js).
  • Monitro ciwiau, oedi darparwyr API, a ping PostgreSQL / Redis mewn amser real.
  • Hidlo ar draws dyddiadau gydag integreiddio di-dor o ddangosfwrdd BI Metabase trwy docynnau JWT wedi'u llofnodi.