拆解 handwriting-web 异步任务队列:FastAPI BackgroundTask + SQLite 持久化 + WebSocket 进度推送实现

原创2026-10-11 15:22:551,954 阅读

拆解 handwriting-web 异步任务队列:FastAPI BackgroundTask + SQLite 持久化 + WebSocket 进度推送实现

handwriting-web 是一款把纯文本渲染成手写文字的开源工具,生成的手稿常用于手账、仿手写信等场景。但"把几百字写成一页页手稿"是 CPU 密集型重活,若让 HTTP 请求同步等待,响应会卡住几十秒。本文拆解它的异步任务队列:用 FastAPI BackgroundTask 让请求秒回、SQLite 持久化任务状态、WebSocket 实时推送进度,帮你在自己的手写生成项目里复刻这套"提交—排队—推送—取结果"的完整链路。

为什么手写文字生成要交给异步任务队列

先看看这个工具长什么样——左侧填参数、右侧实时预览手写效果:

handwriting-web 手写文字生成界面与参数设置

问题就出在"预览/生成"这一步:把文本逐字绘制成手写笔迹、再打包成图片或 PDF,是典型的 CPU 密集任务。FastAPI 基于 asyncio 单线程事件循环,一旦在请求里同步跑几十秒的渲染,整个服务的事件循环都会被占住——其他请求(包括心跳、WebSocket 推送)全部跟着卡死。

所以它把"算"和"等"彻底拆开:

  • 接口只负责登记:收到请求,建一条任务记录,立刻返回。
  • 后台负责执行:真正的渲染丢进 FastAPI 的 BackgroundTask 慢慢跑。
  • 进度负责通知:每走一步就把状态推到 WebSocket,前端不用傻等。

这也是它能扛住并发、又不让用户盯着转圈的根本原因。

一图看懂:手写生成请求的完整旅程

一次生成请求的生命周期,可以拆成 5 步:

  1. 提交:前端 POST /api/generate_handwriting(表单带文本、字体、边距、扰动参数…),后端返回 task_id,请求秒回。
  2. 登记:任务写入 SQLite,状态 pending / 阶段 queued。
  3. 执行:BackgroundTask 后台跑 run_generation_task,先过信号量排队,再逐页渲染并上报进度。
  4. 推送:每步状态都通过 WebSocket 推给前端,队列满则返回 503 倒计时。
  5. 取结果:状态变 completed 后,前端再 GET /task/{task_id}/result 把图片/PDF 取走。

用一句话概括这套架构就是:"秒回 + 排队 + 推送 + 取件",四个动作各司其职。

FastAPI BackgroundTask:请求秒回,重活后台慢慢跑

提交接口如何做到"秒回"

核心在提交接口 backend/app.py#L1218-L1283。它做了四件事就返回了:

  • 先 cleanup_expired_generation_tasks() 顺手清掉过期任务;
  • 并发检查:pending + processing 总数 ≥ 8 就直接返回 503 queue_full;
  • 把上传的背景图/字体文件读成内存字节;
  • 生成 task_id = uuid4().hex,写入任务(状态 pending),然后 background_tasks.add_task(...) 把重活登记进后台队列,立刻返回 {"status":"accepted","task_id":...}。

注意:这里没有执行任何渲染,所以 HTTP 请求是"秒回"的。真正干活的协程在响应发出之后才由 FastAPI 调度执行。

用信号量把真实并发钉在 2

后台执行入口是 backend/app.py#L1162-L1215。它内部用一把信号量控制真实同时渲染的任务数:

MAX_CONCURRENT_EXECUTIONS = 2
_generation_semaphore = asyncio.Semaphore(MAX_CONCURRENT_EXECUTIONS)

(见 backend/app.py#L685-L688)

为什么提交能进 8 个、真正只跑 2 个?因为 Python 的 GIL 让 CPU 密集任务没法真并行,渲染 2 个已经能把 CPU 打满。所以设计成两级闸门:

  • 队列上限 8:pending + processing 总数上限,管住"能进多少";
  • 信号量 2:同时执行的渲染任务数,管住"真跑几个"。

多进来的任务就在信号量处排队等待,避免互相挤占。任务每推进一个阶段,都会调 set_generation_task(...) 写库,并 push_task_status_update(...) 推帧。

进度是分阶段的,前端能据此画出进度条:

阶段 文案 进度
validating 正在校验参数 5%
system_check 正在检查服务器负载 10%
prepare_background 正在创建背景图 20%
prepare_font 正在加载字体 30%
rendering 正在生成手写图像(逐页) 45% → 90%
packaging 正在打包 ZIP / PDF 92%
finalizing 正在返回结果 100%

SQLite 持久化:任务状态跨进程安全存储

元数据进数据库,图片/PDF 大文件进磁盘

任务状态层在 backend/task_store.py,注释里写得很直白:"元数据存 SQLite,response_body(图片/PDF 等大文件)存磁盘,避免 DB 膨胀"。表结构见 backend/task_store.py#L44-L59:

  • status:pending / processing / completed / failed(类型定义在 backend/task_types.py#L5)
  • stage、message、progress:推送给前端的阶段、文案、百分比
  • result_file_path:渲染产物(图片/ZIP/PDF)的磁盘路径
  • created_at、updated_at:用于排队位置和 TTL 清理

连接开启了 PRAGMA journal_mode=WAL 和 synchronous=NORMAL,并用一把 _write_lock 保证跨线程/worker 的写安全。这样即使多进程部署,任务状态也不会错乱。

30 分钟 TTL 自动清理过期任务

_TTL_SECONDS = 60 * 30(30 分钟)。cleanup_expired()(见 backend/task_store.py#L245-L262)会删掉超过 30 分钟没更新的任务,并连同磁盘结果文件一起清掉。提交和查询接口每次都会顺手触发一次清理,让磁盘不会无限堆积。

一个有意思的细节:取结果接口不做"取过即删"。因为 GET 带销毁副作用的话,跨站的 <img>/<script> 只要 URL 里带对 task_id 就能把用户结果吃掉,而且下载中断线重试时第二次必然 404。所以"取过但没删"和"压根没取过"走同一条 TTL 回收路径——读取保持幂等,回收交给 TTL。

WebSocket 进度推送:把进度实时送进浏览器

连接、注册与逐帧推送

后端开了一个 WebSocket 端点 backend/app.py#L1286-L1313:

  • 先校验来源(跨站请求直接 close(1008)),因为 WebSocket 不走 HTTP 中间件、也不受 CORS 约束;
  • 接受连接后把 websocket 注册进 task_websocket_connections[task_id] 这个 set(同一任务允许多个前端窗口订阅);
  • 立刻补发一帧当前状态,之后进入保活循环。

真正推帧的是 push_task_status_update(task_id):从 SQLite 读任务 → 拼上队列指标(queue_pending_count、queue_ahead_count、processing_count、active_task_count)→ 一次性 send_json 给该任务的所有订阅者,并顺手清理掉已断开的"死连接"。

这样前端不仅知道"我的任务到哪一步了",还能顺带知道"前面还排着几个"。

前端降级轮询,断线也能出图

前端 waitForTaskViaWebSocket(见 frontend/src/views/HomeView.vue#L1432-L1495)连上 /api/generate_handwriting/ws/{task_id},每收到一帧就更新界面文案与进度:

  • 收到 completed → 关闭连接、去取结果;
  • 收到 failed → 抛出 error_message;
  • 超时(默认 5 分钟)/连接失败 → reject。

关键点:WebSocket 连不上会自动降级成轮询。pollGenerationTask(见 frontend/src/views/HomeView.vue#L1496-L1511)每 1.5 秒 GET 一次 /task/{id},两条路径出图效果一样。之所以要用推送而非纯轮询,正是因为并发一上来,轮询会把任务状态接口打爆——这也是为什么项目专门有一条 E2E 用例盯着"必须真的走了 WebSocket"(见 e2e/tests/websocket-task.spec.js)。

handwriting-web 前端参数面板与手写预览区域

队列限流:队列满就返回 503 并倒计时

当 pending + processing 总数达到上限(MAX_ACTIVE_TASKS = 8),提交接口不会硬塞,而是直接返回 503:

{
  "status": "queue_full",
  "message": "当前服务器队列已满,请稍后再试",
  "active_task_count": 8,
  "max_active_tasks": 8,
  "estimated_wait_seconds": 60
}

前端捕获到这个 queue_full 后,会调 startQueueFullCountdown(见 frontend/src/views/HomeView.vue#L1396)给用户一个友好的倒计时提示,而不是把 503 当普通报错弹出来。这是一条很实用的"软限流"——用固定等待建议值,比现场瞎算队列时长更可靠。

另外还有一个 CPU 保护:任务执行前会采样 psutil.cpu_percent,超过阈值(默认 90%)就返回 429,防止服务器被彻底打满。这套限流 + 信号量的组合,最终压测表现是 8 并发 0% 失败、16 并发开始触发 503。

handwriting-web 页面性能 Lighthouse 评分

核心文件索引

想动手改这套链路,看这几个文件就够了:

小结:这套异步链路可以照搬到哪

handwriting-web 的异步任务队列,本质是四块积木的拼接,任何"CPU 密集 + 需要进度反馈"的 Web 任务(渲染、导出、转码、AI 生成)都能直接照搬:

  1. FastAPI BackgroundTask 让请求秒回,重活后台跑;
  2. SQLite + 磁盘 把"状态"和"大文件"分开存,跨进程安全、TTL 自动回收;
  3. 信号量 + 队列上限 两级闸门,管住"能进多少"和"真跑几个";
  4. WebSocket 推送 + 轮询降级 实时反馈进度,断线也能出结果。

理解这四个积木怎么配合,你就拥有了一个可复用的"异步任务队列模板"——拿去改造自己的手写生成、图片处理或导出服务,都会事半功倍。

登录后查看全文
handwriting-web