RFC: Flask/Quart → FastAPI Migration Feasibility Assessment

快速结论：RAGFlow 项目中 12,000 行 Quart REST API 已完整迁移至 FastAPI，但管理面板仍保留在 Flask 上。迁移的关键风险在于 URLSafeTimedSerializer 生成的认证令牌与 JWT 不兼容，强行替换会破坏所有现有登录令牌。如果遇到迁移相关问题，应优先排查令牌兼容性方案。

问题场景

该 Issue 讨论 RAGFlow 项目（83K⭐）从 Flask/Quart 迁移到 FastAPI 的技术可行性。评估基于源码分析，同时提供了概念验证代码（3 个 API 文件、47 条路由、~1,280 行代码）和完整迁移后结果（28 个文件、~270 条路由、~12,000 行代码）。适用于需要将现有 ASGI（Quart）或 WSGI（Flask）应用迁移到 FastAPI 的开发团队。

报错原文

No specific runtime errors reported. The core migration blocker is:

Token format critical: URLSafeTimedSerializer → NOT JWT-compatible.
Migrating to python-jose (actual JWT) would break all existing login tokens at cutover.
Either a backward-compatibility layer (dual token format during transition) or a token-reissue plan is required before migration.

原因分析

可能原因：项目使用 itsdangerous.URLSafeTimedSerializer 生成登录令牌（位于 db_models.py:729-730 和 __init__.py:96-114），该格式与 JWT 不兼容。如果直接将认证迁移到 python-jose（标准 JWT），会破坏所有现有登录令牌，导致用户无法登录。迁移后方案保留了原 URLSafeTimedSerializer 兼容。

环境排查

RAGFlow 项目版本（Issue 基于主代码分析，建议确认本地分支版本）
Python 版本（ASGI 应用需要 Python 3.7+）
Flask/Quart 当前使用的依赖版本：quart_cors、quart_auth、quart_schema、itsdangerous、flask_login、flask_session
迁移后 FastAPI 依赖版本：fastapi、uvicorn、python-multipart（文件上传需要）
如需完整测试，需确认 ~350 个项目依赖是否可获取（Issue 指出 gitee 不可达导致无法验证 graspologic）

解决步骤

评估迁移范围：确认待迁移模块。本项目中，主 API（api/）使用 Quart（26 个文件，~10,000 行），管理面板（admin/server/）使用 Flask（7 个文件，~2,200 行）。
处理认证令牌兼容性（关键步骤）：
- 保留 itsdangerous.URLSafeTimedSerializer，不要替换为 JWT。
- 在迁移后的 fastapi_app/auth.py 中实现三个依赖注入函数：get_current_user、get_current_user_beta、load_user，使用原序列化器。
替换 Flask/Quart 特定依赖：
- quart_cors → FastAPI 内置 CORSMiddleware（低难度）
- quart_schema → FastAPI 原生 OpenAPI 支持（低难度）
- quart_auth → FastAPI Depends() 注入（中难度）
- flask_login 和 flask_session → 管理面板保留在 Flask 上，暂不迁移（高难度，无直接替代）
替换 Quary 上下文对象：将 Flask/Quart 的 g 对象替换为 FastAPI 的 request.state。
处理流式响应：将 Quart 的 Response(stream()) 替换为 FastAPI 的 StreamingResponse（SSE 流 ~12 条）。
保留同步路由：FastAPI 支持同步和异步路由，现有同步路由可直接保留。
构建集成测试套件：Issue 指出迁移后 没有现有测试，需要自行编写。

验证方法

确认问题已解决的方法：

迁移后所有 ~270 条路由正确注册，访问 /api/v1/ 下任意路由返回正常响应。
使用原始 URLSafeTimedSerializer 生成的登录令牌能在迁移后应用正常工作（向后兼容性验证）。
文件上传（multipart）、文件下载（StreamingResponse/Response）、OAuth 流程（Google Drive/Gmail、Box）均能正常处理。
管理面板（Flask 部分）独立部署后功能不受影响。