Paperless-ngx 完整指南从部署到自动化归档【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx每月三十张快递单、发票、合同散落抽屉翻起来全靠运气——这正是 Paperless-ngx 要解决的问题。它是一套社区维护的文档管理系统把扫描件丢进目录自动完成 OCR 识别、元数据分类和数字化归档之后全部文档支持全文搜索。从部署到跑通自动化归档这里按最短路径走一遍。 一条命令跑起来前置要求只有 Docker 和 Docker Compose2GB 内存、10GB 磁盘就能起步。最短路径是仓库自带的交互式安装脚本# 克隆仓库含安装脚本与全套 compose 模板 git clone https://gitcode.com/GitHub_Trending/pa/paperless-ngx cd paperless-ngx bash install-paperless-ngx.sh脚本会检查 Docker 环境、让你选数据库PostgreSQL 是推荐项、设置管理员账户然后自动拉起服务。如果想自己掌控 Compose 文件仓库docker/compose/下自带 PostgreSQL / MariaDB / SQLite 三套模板以 PostgreSQL 版为例核心配置就是这几行services: webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: unless-stopped ports: - 8000:8000 # Web 界面端口 volumes: - ./consume:/usr/src/paperless/consume # 投递目录 - data:/usr/src/paperless/data # 元数据 - media:/usr/src/paperless/media # 原件归档 env_file: docker-compose.env # 密钥与 OCR 配置跑起来后浏览器访问 8000 端口即可登录。consume、data、media 三个目录后面会反复出现值得先记住。这一步跑通后面就顺了。 一份文档的完整旅程跟一张发票走一遍整条数据链路就清楚了。一份文档进入系统后经历六个阶段投递把文件放进consume目录即可常驻消费任务默认每 10 秒轮询一次发现新文件开始处理处理完原件移入media。OCR 识别Tesseract 对图像文档做文字识别PDF 若已带文字层默认的auto模式会直接跳过不重复计算。识别后的文档以 PDF/A 归档格式重新生成适合长期保存。元数据分类系统按文件名和内容做匹配自动分配对应人来源、文档类型和标签工作流可以在这个阶段进一步介入。全文索引识别出的文本写入 Tantivy 索引——这是基于 Rust 引擎的全文搜索引擎搜索性能不依赖数据库实现见 search 模块源码。检索在 Web 界面输入关键词命中的原文位置会高亮显示。归档与修正原件在media中以带版本的归档文件保存之后随时可以手动修正标题、日期、标签系统会把旧版本保留下来。整条链路里人工只参与两头投递和修正中间全部自动化。⚙️ 四个真正影响体验的配置其余环境变量保持默认即可下面四项是日常使用中最值得动手改的OCR 语言包PAPERLESS_OCR_LANGUAGE默认eng。中文文档要改成chi_simDocker 部署还需声明PAPERLESS_OCR_LANGUAGES让容器安装对应语言包只改前者不装包等于白改。混排语言chi_simeng可以但 CPU 开销明显上升。OCR 模式PAPERLESS_OCR_MODE默认auto——有文字层就跳过。如果扫描仪自带的文字层识别质量差改成redo会重跑识别并替换原有文字层。时区PAPERLESS_TIME_ZONE默认 UTC日期推断、任务调度都会偏八小时国内部署应设成Asia/Shanghai。文件名模板PAPERLESS_FILENAME_FORMAT控制归档后的文件名默认取文档标题。改成日期加标题的组合后批量导出到本地目录时更好整理。# docker-compose.env 中的典型改动 PAPERLESS_OCR_LANGUAGEchi_sim # 识别语言 PAPERLESS_OCR_LANGUAGESchi_sim # 容器内安装的语言包 PAPERLESS_TIME_ZONEAsia/Shanghai # 时区 PAPERLESS_FILENAME_FORMAT[title]_[date] # 归档文件名改了 OCR 语言或模式后存量文档需要重建索引才能生效容器内执行一次即可带--if-needed时幂等升级前后都安全docker compose exec webserver python manage.py document_index reindex --if-needed 扩展与集成工作流触发器覆盖文档添加、更新、定时三类事件动作包括分配标签、移除属性、发邮件、发 Webhook多个动作按排序顺序执行后执行的赋值会覆盖前面的。触发器上还能挂内容匹配条件实现含特定关键词才触发。邮件自动化paperless_mail模块定时轮询 IMAP 账户按发件人、主题等规则筛选附件自动进入消费链路和手动投递走同一套处理。APIREST 接口加 Token 鉴权覆盖上传、检索、批量编辑、状态查询脚本对接基本够用接口说明见 docs/api.md。插件日期解析走插件机制通过 Python entry point 注册即可替换系统默认的日期推断逻辑适合有自定义单据日期格式的团队。 踩坑与排障文档卡在 consume 不处理多为宿主机目录属主和容器内运行用户不一致容器内进程读不到也写不动文件。在docker-compose.env里把USERMAP_UID/USERMAP_GID设成宿主机用户的对应值仍不行时用docker compose logs webserver看服务日志Web 界面的日志页也能看到任务执行情况。中文搜不到任何结果PAPERLESS_OCR_LANGUAGES没装chi_sim识别出来的是乱码或空文本。装包、改语言后跑一次上面那条 reindex 命令。OCR 队列积压、处理极慢检查PAPERLESS_OCR_MODE是否被设成force它会把每一页栅格化再识别文件变大、耗时翻倍。没有特殊理由就用auto。8000 端口被占用compose 里改宿主机侧映射8080:8000容器内端口不用动。重复文档入库同内容文件靠校验和去重默认机制会拦截确实需要删掉旧副本时再开PAPERLESS_CONSUMER_DELETE_DUPLICATES默认不开是有意的避免误删。生产环境要点备份三处data元数据、media原件、数据库SQLite 部署则合并为前两处反代加 HTTPS同时设置PAPERLESS_URL否则链接和回调指向会错PAPERLESS_SECRET_KEY用随机强密钥生成不要用示例值多人使用时开启双因素认证用用户组限制文档可见范围升级前备份升级后执行document_index reindex --if-needed扫描进去随时能找回来。完整配置项与 API 参考见 官方文档。【免费下载链接】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），仅供参考 Paperless-ngx 完整指南：从部署到自动化归档
Paperless-ngx 完整指南从部署到自动化归档【免费下载链接】paperless-ngxA community-supported supercharged document management system: scan, index and archive all your documents项目地址: https://gitcode.com/GitHub_Trending/pa/paperless-ngx每月三十张快递单、发票、合同散落抽屉翻起来全靠运气——这正是 Paperless-ngx 要解决的问题。它是一套社区维护的文档管理系统把扫描件丢进目录自动完成 OCR 识别、元数据分类和数字化归档之后全部文档支持全文搜索。从部署到跑通自动化归档这里按最短路径走一遍。 一条命令跑起来前置要求只有 Docker 和 Docker Compose2GB 内存、10GB 磁盘就能起步。最短路径是仓库自带的交互式安装脚本# 克隆仓库含安装脚本与全套 compose 模板 git clone https://gitcode.com/GitHub_Trending/pa/paperless-ngx cd paperless-ngx bash install-paperless-ngx.sh脚本会检查 Docker 环境、让你选数据库PostgreSQL 是推荐项、设置管理员账户然后自动拉起服务。如果想自己掌控 Compose 文件仓库docker/compose/下自带 PostgreSQL / MariaDB / SQLite 三套模板以 PostgreSQL 版为例核心配置就是这几行services: webserver: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: unless-stopped ports: - 8000:8000 # Web 界面端口 volumes: - ./consume:/usr/src/paperless/consume # 投递目录 - data:/usr/src/paperless/data # 元数据 - media:/usr/src/paperless/media # 原件归档 env_file: docker-compose.env # 密钥与 OCR 配置跑起来后浏览器访问 8000 端口即可登录。consume、data、media 三个目录后面会反复出现值得先记住。这一步跑通后面就顺了。 一份文档的完整旅程跟一张发票走一遍整条数据链路就清楚了。一份文档进入系统后经历六个阶段投递把文件放进consume目录即可常驻消费任务默认每 10 秒轮询一次发现新文件开始处理处理完原件移入media。OCR 识别Tesseract 对图像文档做文字识别PDF 若已带文字层默认的auto模式会直接跳过不重复计算。识别后的文档以 PDF/A 归档格式重新生成适合长期保存。元数据分类系统按文件名和内容做匹配自动分配对应人来源、文档类型和标签工作流可以在这个阶段进一步介入。全文索引识别出的文本写入 Tantivy 索引——这是基于 Rust 引擎的全文搜索引擎搜索性能不依赖数据库实现见 search 模块源码。检索在 Web 界面输入关键词命中的原文位置会高亮显示。归档与修正原件在media中以带版本的归档文件保存之后随时可以手动修正标题、日期、标签系统会把旧版本保留下来。整条链路里人工只参与两头投递和修正中间全部自动化。⚙️ 四个真正影响体验的配置其余环境变量保持默认即可下面四项是日常使用中最值得动手改的OCR 语言包PAPERLESS_OCR_LANGUAGE默认eng。中文文档要改成chi_simDocker 部署还需声明PAPERLESS_OCR_LANGUAGES让容器安装对应语言包只改前者不装包等于白改。混排语言chi_simeng可以但 CPU 开销明显上升。OCR 模式PAPERLESS_OCR_MODE默认auto——有文字层就跳过。如果扫描仪自带的文字层识别质量差改成redo会重跑识别并替换原有文字层。时区PAPERLESS_TIME_ZONE默认 UTC日期推断、任务调度都会偏八小时国内部署应设成Asia/Shanghai。文件名模板PAPERLESS_FILENAME_FORMAT控制归档后的文件名默认取文档标题。改成日期加标题的组合后批量导出到本地目录时更好整理。# docker-compose.env 中的典型改动 PAPERLESS_OCR_LANGUAGEchi_sim # 识别语言 PAPERLESS_OCR_LANGUAGESchi_sim # 容器内安装的语言包 PAPERLESS_TIME_ZONEAsia/Shanghai # 时区 PAPERLESS_FILENAME_FORMAT[title]_[date] # 归档文件名改了 OCR 语言或模式后存量文档需要重建索引才能生效容器内执行一次即可带--if-needed时幂等升级前后都安全docker compose exec webserver python manage.py document_index reindex --if-needed 扩展与集成工作流触发器覆盖文档添加、更新、定时三类事件动作包括分配标签、移除属性、发邮件、发 Webhook多个动作按排序顺序执行后执行的赋值会覆盖前面的。触发器上还能挂内容匹配条件实现含特定关键词才触发。邮件自动化paperless_mail模块定时轮询 IMAP 账户按发件人、主题等规则筛选附件自动进入消费链路和手动投递走同一套处理。APIREST 接口加 Token 鉴权覆盖上传、检索、批量编辑、状态查询脚本对接基本够用接口说明见 docs/api.md。插件日期解析走插件机制通过 Python entry point 注册即可替换系统默认的日期推断逻辑适合有自定义单据日期格式的团队。 踩坑与排障文档卡在 consume 不处理多为宿主机目录属主和容器内运行用户不一致容器内进程读不到也写不动文件。在docker-compose.env里把USERMAP_UID/USERMAP_GID设成宿主机用户的对应值仍不行时用docker compose logs webserver看服务日志Web 界面的日志页也能看到任务执行情况。中文搜不到任何结果PAPERLESS_OCR_LANGUAGES没装chi_sim识别出来的是乱码或空文本。装包、改语言后跑一次上面那条 reindex 命令。OCR 队列积压、处理极慢检查PAPERLESS_OCR_MODE是否被设成force它会把每一页栅格化再识别文件变大、耗时翻倍。没有特殊理由就用auto。8000 端口被占用compose 里改宿主机侧映射8080:8000容器内端口不用动。重复文档入库同内容文件靠校验和去重默认机制会拦截确实需要删掉旧副本时再开PAPERLESS_CONSUMER_DELETE_DUPLICATES默认不开是有意的避免误删。生产环境要点备份三处data元数据、media原件、数据库SQLite 部署则合并为前两处反代加 HTTPS同时设置PAPERLESS_URL否则链接和回调指向会错PAPERLESS_SECRET_KEY用随机强密钥生成不要用示例值多人使用时开启双因素认证用用户组限制文档可见范围升级前备份升级后执行document_index reindex --if-needed扫描进去随时能找回来。完整配置项与 API 参考见 官方文档。【免费下载链接】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），仅供参考