Paperless-ngx 中文多语言部署指南：3 组环境变量让扫描件可搜索

Paperless-ngx 中文多语言部署指南3 组环境变量让扫描件可搜索【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngxPaperless-ngx 是一个社区维护的开源文档管理系统核心能力是扫描、OCR、索引和归档。很多用户部署后遇到同一个问题中文扫描件上传后搜不到内容、日期字段解析为空。根因不在界面翻译而在三套彼此独立的多语言配置——OCR 识别语言、日期解析语言、搜索索引语言它们各用各的语言代码体系缺任何一层都会断链。本文给出最小可用配置、验证方法和一张排错表。一、先搞清架构三个环节三套语言代码本节解决的问题是配置到底配在哪一层。一份文档从图片变成可搜索文本要经过三个独立环节OCR 识别Tesseract 引擎按指定语言包把图片转成文本配置项是PAPERLESS_OCR_LANGUAGE3 位 ISO 639-2 代码如eng、chi_sim默认eng。注意 Tesseract 语言包名与代码的对应关系含连字符的语言要换下划线例如chi-sim写chi_sim。日期解析dateparser 库从正文里抽日期配置项是PAPERLESS_DATE_PARSER_LANGUAGES用的是短代码例如en、ende支持地区变体如en-AU。不设时系统会从PAPERLESS_OCR_LANGUAGE推断。搜索索引全文索引使用词干提取stemming把 running 匹配到 run 的机制配置项是PAPERLESS_SEARCH_LANGUAGE用 ISO 639-1 两位小写代码en、de、fr或小写全名。修改该值后下次启动会自动重建索引。参数代码体系示例值默认PAPERLESS_OCR_LANGUAGEISO 639-23 位chi_sim、deuengengPAPERLESS_OCR_LANGUAGESTesseract 包名代码空格分隔chi_sim tur ces空不额外安装PAPERLESS_DATE_PARSER_LANGUAGESdateparser 短代码连接zhen、en-AU从 OCR 语言推断PAPERLESS_SEARCH_LANGUAGEISO 639-12 位en、de从 OCR 语言推断PAPERLESS_TIME_ZONEIANA 时区Asia/ShanghaiUTC容易混淆的一对是PAPERLESS_OCR_LANGUAGE和PAPERLESS_OCR_LANGUAGES前者决定用哪种语言识别后者决定容器里安装哪些语言包。镜像默认已内置英语、德语、意大利语、西班牙语、法语五个包其他语言要靠后者安装。中文界面下文档入库、统计与上传入口都在仪表盘二、最小可用配置中文扫描件跑通本节给出一个中文为主、夹带英文数字的最小配置可直接粘进docker-compose.yml示例值按需调整environment: PAPERLESS_TIME_ZONE: Asia/Shanghai PAPERLESS_OCR_LANGUAGE: chi_sim PAPERLESS_OCR_LANGUAGES: chi_sim PAPERLESS_DATE_PARSER_LANGUAGES: zhen为什么这样配PAPERLESS_OCR_LANGUAGEchi_sim把主力识别语言切成简体中文。中英混合文档可以写chi_simeng但官方文档明确提醒多语言会显著增加 CPU 消耗混合环境建议观察处理时长再决定。PAPERLESS_OCR_LANGUAGESchi_sim触发容器启动时的自动安装。安装逻辑在docker/rootfs/etc/s6-overlay/s6-rc.d/init-tesseract-langs/run脚本里脚本按空格拆分语言列表逐个用dpkg --status检查缺失的包通过apt-get install tesseract-ocr-lang安装。所以这个变量只写需要额外安装的包内置五国语言不必重复写。PAPERLESS_DATE_PARSER_LANGUAGESzhen让2026 年 8 月 22 日和Aug 22, 2026两种写法都能被解析。界面语言不在这套环境变量里它是登录后在 Web 界面按用户自行选择的与容器配置无关。三、验证配置真的生效本节解决配了但不知道有没有用的问题分三步验证语言包是否装上docker compose logs里过滤init-tesseract-langs。装包成功会看到Installed package tesseract-ocr-chi-sim已存在则提示already installed包名写错会看到Skipped ... Package not found!。在日志面板检查 init-tesseract-langs 的安装记录OCR 是否产出文本上传一页中文扫描件打开文档详情正文区域应显示识别出的文字在搜索框输入文中的一个词应命中该文档。中文关键词命中正文后搜索结果列出对应文档日期是否解析检查文档的日期字段是否自动填充为上传文档中识别到的日期而不是退回文件修改时间。三步都通过说明 OCR、搜索、元数据三条链路都通了。四、排错现象 → 定位 → 修复现象定位修复日志出现Could not install tesseract-ocr-chi-tra包名与代码写法不符PAPERLESS_OCR_LANGUAGES里chi_tra要写成chi-traPAPERLESS_OCR_LANGUAGE里才用chi_sim这种下划线写法正文识别结果混乱、大量空格语言包未装上或识别语言仍是eng确认dpkg --status tesseract-ocr-chi-sim有记录确认PAPERLESS_OCR_LANGUAGE已改中文日期解析为空dateparser 没被告知用中文设置PAPERLESS_DATE_PARSER_LANGUAGESzhen后重新消费文档正文能显示但中文搜不到索引语言或分词问题显式设置PAPERLESS_SEARCH_LANGUAGE重启后索引自动重建需要容错可试PAPERLESS_ADVANCED_FUZZY_SEARCH_THRESHOLD0.5rootless 容器下装不了语言包官方明确该选项不能用于 rootless 容器以普通容器方式运行或在宿主机预装语言包多语言后处理时长明显变长官方提示多语言模式 CPU 消耗显著增大主力语言单一化或调低并发、接受处理时长另外两个常用旋钮PAPERLESS_OCR_MODE控制识别策略auto默认只对没有文本层的页做 OCRredo会重做已有文本层force强制栅格化重扫扫描质量差的旧档案可先用auto观察再决定是否redo。PAPERLESS_ENABLE_NLTK默认开启影响自动分类的文本预处理一般无需改动。五、长期维护索引、翻译与性能本节解决跑起来之后怎么持续维护。三个关注点索引重建是有代价的PAPERLESS_SEARCH_LANGUAGE每次变更都会触发全量重建文档量大时启动会明显变长不要频繁切换。翻译文件的更新界面翻译源文件在src/locale/zh_CN/LC_MESSAGES/django.po社区翻译通过 Crowdin 同步个别条目不满意可以改django.po后执行django-admin compilemessages重新编译。性能观测以 OCR 处理时长、容器内存占用为两个核心指标。识别语言数直接决定 Tesseract 的 CPU 开销加语言前先估算文档语言分布而不是以防万一全装上。一句话总结选型中文为主的部署核心动作就是PAPERLESS_OCR_LANGUAGEchi_sim、PAPERLESS_OCR_LANGUAGES补齐语言包、PAPERLESS_DATE_PARSER_LANGUAGESzhen这三件事其余参数按上表按需微调。更多选项可在仓库docs/configuration.md的 OCR settings 一节查证。【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考