All File Converter 服務採用現代 Python 3.12 非同步堆疊設計，是一個具備可擴展性的分散式 SaaS 系統。架構分為獨立的層級：網路事件接收、任務協調、大型二進位行程的隔離執行，以及分析迴路。

1. 整體技術堆疊與系統架構

平台建立在高效能（high-throughput）、低記憶體消耗與防故障原則的基礎上：

  • Telegram Bot Framework: Aiogram 3.13，運行於 Webhook 模式，具備密鑰權杖驗證與自訂訊息生命週期過濾器。
  • 網頁閘道與 REST API: 基於 Uvicorn ASGI 伺服器的 FastAPI，支援非同步二進位檔案串流傳輸（FileResponse）以及透過 BackgroundTasks 進行背景清理。
  • 佇列代理與快取: Redis 7（Celery 任務管理、競爭狀態鎖定、暴力破解防護、工作階段快取）。
  • 背景執行器 (Task Queue): Celery 5.4，在隔離的 converter_worker 容器中配置專用的工作執行緒集區。
  • 資料庫: PostgreSQL 16，搭配 SQLAlchemy 2.0 (asyncpg) ORM 層、持久連線集區（20+10 overflow）以及失敗交易自動重試（@db_retry）。
  • 網路迴路: 透過 Cloudflare Zero Trust 進行通道傳輸，並使用 Middleware 封鎖對伺服器的直接 IP 存取。

2. 非同步佇列與密集運算隔離 (Celery + Redis)

多媒體與辦公室檔案轉換會對 CPU 和 RAM 造成尖峰負載。為了確保 Telegram 中incoming訊息的處理過程不會在進行密集運算時被阻塞，實現了嚴格的隔離：

  • 將任務委派至 Redis: 當選擇格式時，Telegram 處理常式會在資料庫中將任務註冊為 PROCESSING 狀態，並透過 Celery 將作業放入 tasks.execute_conversion 佇列中。
  • 隔離的工作執行緒容器: 轉換公用程式的執行是在具有自身處理時間和記憶體限制的獨立 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 濾鏡）以及 Telegram 視訊訊息的正方形裁切（1:1）。
  • 高速 PDF 處理 (Poppler Utils): pdftotext（即時萃取 UTF-8 格式化文字）與 pdftoppm（將 PDF 分頁算繪為點陣圖，無 LibreOffice 的額外負擔）公用程式。
  • 光學字元辨識 (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 MB 的可用空間（guard_min_free_ram_mb）。
  • 磁碟空間: /tmp 目錄中至少有 2 GB 的可用空間（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）並以直接下載的形式傳回準備好的位元組串流。
  • 透過 secrets.compare_digest 進行基於 Bearer 權杖（WEBHOOK_REFRESH_TOKEN）的授權，並具備時序攻擊防護。

7. 控制台與 Observability (NiceGUI + AG Grid)

業務指標與系統狀態的監控已匯出至基於 NiceGUI 2.x 的原生 Single-Page 控制台：

  • 具備自訂 Excel 風格核取方塊過濾器的互動式 AG Grid (v32+) 表格（aggrid_filters.js）。
  • 即時監控佇列、API 提供者延遲以及 PostgreSQL / Redis Ping。
  • 透過簽署的 JWT 權杖無縫整合 Metabase BI 儀表板的按日期範圍全域過濾。