All File Converter 服务采用基于现代 Python 3.12 异步技术栈的可扩展分布式 SaaS 系统架构设计。该架构分为独立层：网络事件接收、任务编排、繁重二进制进程的隔离执行以及分析循环。

1. 整体技术栈与系统架构

该平台基于高性能（high-throughput）、最低内存消耗和故障保护原则构建：

  • Telegram Bot Framework: Aiogram 3.13，以 Webhook 模式运行，带有安全令牌验证和自定义消息生命周期过滤器。
  • Web 网关和 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 进行隧道传输，并通过中间件阻止对服务器的直接 IP 访问。

2. 异步队列与繁重计算隔离 (Celery + Redis)

多媒体文件和办公套件的转换会对 CPU 和 RAM 造成峰值负载。为了确保在处理繁重操作时不会阻塞 Telegram 中传入消息的处理流程，实现了严格的隔离：

  • 将任务委托给 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（无需 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 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. 外部 Web 服务的通用 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 的原生单页控制面板：

  • 带有自定义 Excel 风格复选框过滤器的交互式表格 AG Grid (v32+)（aggrid_filters.js）。
  • 实时监控队列、API 提供商延迟以及 PostgreSQL / Redis ping。
  • 通过签名的 JWT 令牌与 Metabase BI 仪表板无缝集成的按日期端到端过滤。