Stirling-PDF项目OCR处理超时问题分析与解决方案

问题背景

在使用Stirling-PDF进行PDF文档OCR处理时，部分用户遇到了"Failed to fetch"错误。该问题主要出现在处理较大文件(如1.7MB的6页文档)时，而小文件处理正常。错误发生时前端显示"Failed to fetch"提示，但后台日志中无详细堆栈信息。

技术分析

1. 超时机制分析

Stirling-PDF的OCR处理流程涉及多个环节的超时控制：

• 前端请求超时
• 反向代理(如HAProxy)超时设置
• 后端处理超时
• Tesseract OCR引擎处理时间

2. 典型问题场景

当处理较大PDF文件时，OCR处理时间可能超过默认设置的超时阈值，导致：

1. 前端等待超时，显示"Failed to fetch"错误
2. 但后台Tesseract进程仍在继续运行(可通过htop观察到)
3. 实际处理可能最终完成，但用户无法获取结果

3. 关键影响因素

• HAProxy默认超时设置：通常client/server timeout默认为30秒
• Stirling-PDF系统设置：默认连接超时可能不足
• OCR处理复杂度：与文档大小、页面数、内容复杂度成正比

解决方案

1. HAProxy配置调整

建议修改HAProxy配置中的超时参数：

timeout client 10m
timeout connect 30s
timeout server 10m

对于特定后端服务可单独设置：

backend StirlingPDF_backend
    timeout server 10m
    timeout connect 30s

2. Stirling-PDF环境变量配置

在Docker部署时，增加系统超时设置：

environment:
  SYSTEM_CONNECTIONTIMEOUTMINUTES: 10m

3. 系统资源监控

建议在处理大文件时：

1. 监控系统资源使用情况(CPU/内存)
2. 观察Tesseract进程状态
3. 根据实际处理时间调整超时参数

最佳实践建议

1. 渐进式测试：从小文件开始测试，逐步增加文件大小
2. 超时参数阶梯调整：先设置为10分钟，根据实际情况优化
3. 资源分配：确保Docker容器有足够资源处理OCR任务
4. 多语言支持：配置正确的tessdata语言包提高识别效率

总结

Stirling-PDF的OCR处理超时问题通常由多层超时设置导致，通过合理配置HAProxy和系统环境变量，可以有效解决大文件处理时的"Failed to fetch"错误。建议用户根据实际文档处理需求，平衡处理时间和系统资源使用，获得最佳使用体验。