paperless-ngx安装与配置完整指南

解决了什么问题

纸质文件、发票、合同、扫描件——这些东西堆在硬盘里，时间一长就再也找不到。Paperless-ngx把这2000页PDF变成可搜索的数据库：上传→自动OCR→全文检索→标签归档，全程不依赖任何云服务。

我自己用这套系统管理创业过程中积累的合同、发票和供应商文档，检索时间从平均15分钟降到了5秒。

核心优势（说透，不废话）

自托管，数据在自己手里。 不需要Dropbox或Google Drive，注册账号就意味着你的财务文件、合同扫描件全在别人服务器上。Paperless-ngx部署在自己的VPS，数据100%私有。

自动OCR，全程不用手动输入。 上传PDF或图片后，系统自动识别文字，生成可搜索的文本。实测扫描件识别准确率在95%以上（英文），中文需确认语言包安装。

标签+日期+类型三维归档。 每份文档自动按日期归档，支持自定义标签、多关键字搜索。找一份两年前的采购合同，原来要翻文件夹，现在搜索3秒出结果。

5分钟安装实战（Docker Compose）

第一步：准备目录结构

mkdir -p ~/paperless/{consume,export,data,media}
cd ~/paperless

第二步：下载官方配置文件

curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.sqlite.yml
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.env
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

第三步：启动服务

docker compose up -d

等待约2分钟后，访问 http://your-server:8000 打开Web界面。默认登录：demo / demo。

第四步（可选）：配置中文OCR

Paperless-ngx默认OCR引擎是tesseract，英文效果很好，中文需要安装中文语言包。修改.env文件：

PAPERLESS_OCR_LANGUAGES=eng+chi_sim

然后重启容器：

docker compose down && docker compose up -d

注意： 中文OCR语言包含完整包较大（约15MB），首次识别会慢一些。如果只需要英文文档，跳过此步。

真实使用工作流

上传方式3种：

1. Web界面上传 — 直接拖拽文件到consume目录或Web界面

2. 邮件上传 — 配置IMAP后，邮件附件自动导入（适合外出时手机拍照上传）

3. 共享文件夹 — 把consume目录映射为网络驱动器，外卖扫描仪直接投喂

检索示例：

• 搜索"2024 Q3 invoice" → 直接出现对应发票PDF
• 搜索"供应商合同" → 按供应商聚合所有合同文档
• 按日期范围过滤 → 某时间段内的所有文件

硬件要求（说清楚，不含糊）

实测在1GB内存的VPS上运行正常，但OCR会慢一些。文档量大（>5000份）建议2GB以上。

适合人群（不是所有人都适合）

推荐用：

• 自由职业者/独立开发者：合同、发票、客户资料管理
• 小团队：共享文档库，避免版本混乱
• 隐私敏感用户：财务/医疗文档不想上云

不推荐：

• 文档量极少（<100份）：文件夹+搜索就够了，别折腾
• 需要多人实时协作编辑：Notion/Airtable更适合
• 要求移动端原生App体验：目前只有Web界面

升级与维护

# 更新到最新版本
docker compose pull && docker compose up -d

# 查看版本
docker exec paperless-webserver-1 paperless --version

目前稳定版为 v2.20.15（2026年4月27日发布，含1个安全修复），测试版 v3.0.0-beta.rc1 已发布但生产环境建议等正式版。

踩坑记录（实战才有的）

坑1：Redis连接失败（VPS网络问题）

Docker Compose默认Redis依赖，有时重启VPS后Redis启动慢于Paperless，导致短暂连接失败。

解决：docker compose restart 即可，通常自动恢复。

坑2：上传大文件（>50MB）超时

Nginx反向代理或Docker容器默认限制。

解决：修改docker-compose.env，添加 PAPERLESS_MAXUploadSize=100（单位MB）。

坑3：中文文件名搜索失效

Paperless-ngx对中文文件名支持没问题，但OCR后的中文全文搜索需要中文语言包。装完语言包后，已上传文件需要手动重新运行OCR。

##