[BUG]: OCR of multi-page scanned PDF fails on all pages except one (race condition in PDFSharp/Sharp buffer handling)

问题场景

用户使用 AnythingLLM（Docker 部署）上传一个 8 页、无文本层的扫描版 PDF 到工作区。OCR 流程被正确触发（OCRLoader 初始化成功，检测到捷克语/英语），但在 PDFSharp 页面转图片步骤中，几乎所有页面都失败，仅有一页成功。更严重的是，文档仍被标记为 [SUCCESS]，用户界面上看不到任何错误提示。

报错原文

[BUG]: OCR of multi-page scanned PDF fails on all pages except one (race condition in PDFSharp/Sharp buffer handling)

Error: Expected width, height and channels for raw pixel input
    at Sharp._createInputDescriptor (/app/collector/node_modules/sharp/lib/input.js:184:15)
    at new Sharp (/app/collector/node_modules/sharp/lib/constructor.js:361:29)
    at PDFSharp.Sharp [as sharp] (/app/collector/node_modules/sharp/lib/constructor.js:178:12)
    at PDFSharp.pageToBuffer (/app/collector/utils/OCRLoader/index.js:323:30)
    at async /app/collector/utils/OCRLoader/index.js:170:35
    at async Promise.all (index 0)
    at async processPages (/app/collector/utils/OCRLoader/index.js:188:11)
    at async OCRLoader.ocrPDF (/app/collector/utils/OCRLoader/index.js:198:7)
    at async asPdf (/app/collector/processSingleFile/convert/asPDF/index.js:30:12)
    at async processSingleFile (/app/collector/processSingleFile/index.js:85:10)

原因分析

可能原因有两点：

1. 图片编码格式不兼容（最可能）：用户通过合成测试文件确认，使用 1-bit 位图（DeviceGray、BitsPerComponent 1）配合 CCITTFaxDecode（传真 Group 4）压缩、300 DPI 的扫描件（即真实扫描仪/复印机典型输出）可以 100% 复现问题。而使用连续色调 JPEG/RGB 图片的 PDF 则无此问题。PDFSharp/Sharp 的 raw pixel buffer 计算很可能假设了固定的字节/像素布局（如每通道 1 字节），没有正确处理 1-bit-per-pixel 的 CCITT 解码数据，导致 buffer 大小不匹配。

2. 并发竞态（可能原因）：原始 Issue 标题提到 race condition，用户最初观察到 8 页中只有 1 页（总是同一页）成功。但后续合成测试显示所有页面都可能失败，因此并发问题更像是次要因素，而非根本原因。

环境排查

• 部署方式：确认是 Docker 本地部署（mintplexlabs/anythingllm:latest）。
• OCR 语言：检查 TARGET_OCR_LANG 是否包含目标语言（如 ces,eng）。
• 并发设置：确认 MAX_CONCURRENT_WORKERS 是否为默认值 4。
• PDF 格式：检查待处理 PDF 是否为扫描版（无文本层），以及内嵌图片的编码格式（可通过 pdfimages -list 或类似工具查看）。重点确认是否包含 1-bit 位图 + CCITT G4 压缩的图片。
• 复现测试：用 Issue 中提供的 test-scanned-bitonal.pdf 做对照测试。

解决步骤

1. 确认 PDF 内嵌图片格式：使用 PDF 检查工具（如 pdfimages -list file.pdf）查看图片对象属性，确认是否存在 Filter: /CCITTFaxDecode、ColorSpace: /DeviceGray、BitsPerComponent: 1 的图片。
2. 对照测试：下载 Issue 中提供的 test-scanned-bitonal.pdf 上传测试，验证是否能复现错误。
3. 降低并发（可优先尝试）：将 MAX_CONCURRENT_WORKERS 设置为 1，观察是否能规避竞态问题。注意：这只能作为临时规避手段，不解决根本的编码兼容问题。
4. 转换文档格式：如果条件允许，可将扫描 PDF 转换为非 CCITT 压缩格式（如 JPEG/RGB）再上传，可避免触发此问题。
5. 跟踪上游修复：关注 AnythingLLM 的 GitHub Issue #6118，等待 PDFSharp/Sharp buffer 处理逻辑的官方修复。

验证方法

上传处理后，检查 collector 日志中是否仍出现 “Expected width, height and channels for raw pixel input” 错误。同时，在 AnythingLLM 中查看解析后的文档内容，确认所有页面（而非仅部分页面）的文本都被正确提取并入库。

参考来源

Mintplex-Labs/anything-llm #6118