2026 实测：Paperless-ngx 在 VPS 上建私有文档库（OCR+扫描件搜索避坑）

2026-08-16 · DevCraft Studio

手把手用 Docker Compose 在便宜 VPS 上自建 Paperless-ngx，把发票合同扫描件变成可全文搜索的私有档案。讲清中文 OCR、自动归类、邮件抓取，以及明文存储与备份那些坑。

你家里是不是也有一个抽屉，塞满了发票、合同、保修卡、银行对账单？要用的时候翻半天，最后干脆重新开一份。Paperless-ngx 干的就是把这个抽屉换成「能全文搜索的私有档案库」：扫描件丢进去，它自动 OCR、识别日期和寄件人、打标签、归档，几个月后你搜「2024 物业费」两秒就能翻出来。2026 年它仍是文档管理类里最活跃的开源项目（v2.x），而且是真的能长期用下去的自托管方案。

延伸阅读

更多相关攻略推荐：一个页面看遍所有信息流：Glance 个人仪表盘自托管避坑指南、2026 实测：5 美元小机用 Immich 自建 Google 相、2026 VPS 选购决策树与白皮书：一张图看懂怎么买、【游戏服 02】游戏服务器 VPS 推荐 2026：Minecraf、如何给 VPS 厂商做"信用评估"：跑路、超售与售后风险排查手册。

一、为什么把文档库放在 VPS 而不是家里 NAS

核心诉求就两个：隐私合规和随时可搜。发票、合同里全是敏感信息，放第三方网盘心里不踏实；放家里 NAS 又得自己搞定外网访问和断电。租一台便宜国外 VPS，数据完全自己掌控，配上 VPN 访问，比把敏感 PDF 丢进大厂云服务安心得多。而且 VPS 常年在线，扫描仪、邮件抓取都能稳定跑，不像家里电脑关机就断档。

二、选机器：内存和硬盘怎么规划

Paperless-ngx 官方推荐至少 2GB 内存，做 OCR 时建议 4GB 以上。OCR 是吃内存的大户，尤其中文页面密度高，单页比英文更占资源。硬盘方面，系统加镜像大约 3–5GB，文档本身按需增长，给个 20–50GB 起步比较舒服。

  • Contabo 的 VPS 给的内存和硬盘一向大方，4GB/6GB 内存档跑 OCR 很从容，适合文档多的家庭或小微团队。
  • RackNerd 年付机型便宜，1–2GB 内存档也能跑，但建议把并行 OCR 任务调到 1，避免卡死。
  • Virtono 欧洲节点多、延迟低，如果你主要服务欧盟客户、在意数据属地，是个稳妥选择。

一句话：预算紧就 RackNerd 入门，要舒服就 Contabo，在意合规属地就 Virtono。下面我都按低配也能跑通的方式写。

顺便说下它到底帮你做了啥：一份文件进来后，Paperless-ngx 会先识别类型（PDF、图片还是 Office），跑 Tesseract 做 OCR 生成可搜索文字层，再从文本里猜日期、认寄件人、分文档类型，最后打标签并建全文索引。所以几个月后你搜「房租 2024」能秒出，靠的就是这套流水线，而不是你手动建文件夹。它把「抽屉」变成了「搜索引擎」，这才是无纸化办公真正省时间的地方。

三、一键部署：Docker Compose 安装

我用官方的 ghcr.io 镜像，配套 PostgreSQL（比默认 SQLite 更适合大库）和 Redis（后台任务队列）。先装好 Docker，然后建项目目录：

mkdir -p ~/paperless && cd ~/paperless mkdir -p consume media export data curl -fsSL https://get.docker.com | sh

把下面内容存成 docker-compose.yml（密码请务必换成自己的随机串）：

services: broker: image: redis:7-alpine restart: unless-stopped volumes: - ./data/redis:/data db: image: postgres:16-alpine restart: unless-stopped environment: POSTGRES_DB: paperless POSTGRES_USER: paperless POSTGRES_PASSWORD: 换成强密码 volumes: - ./data/pg:/var/lib/postgresql/data web: image: ghcr.io/paperless-ngx/paperless-ngx:latest restart: unless-stopped depends_on: - db - broker ports: - "8000:8000" volumes: - ./data:/usr/src/paperless/data - ./media:/usr/src/paperless/media - ./export:/usr/src/paperless/export - ./consume:/usr/src/paperless/consume environment: PAPERLESS_REDIS: redis://broker:6379 PAPERLESS_DBHOST: db PAPERLESS_DBNAME: paperless PAPERLESS_DBUSER: paperless PAPERLESS_DBPASS: 换成强密码 PAPERLESS_SECRET_KEY: 换成64位随机串 PAPERLESS_URL: http://你的IP:8000 PAPERLESS_TIME_ZONE: Asia/Shanghai PAPERLESS_OCR_LANGUAGE: chi_sim+eng PAPERLESS_ADMIN_USER: admin PAPERLESS_ADMIN_PASSWORD: 换成强密码

启动：docker compose up -d。第一次会拉镜像、跑数据库迁移、下载 OCR 模型，等一两分钟，看日志 docker compose logs -f web 出现监听 8000 就成功了。浏览器打开 http://你的IP:8000，用上面设的 admin 登录。注意：首次启动后把 PAPERLESS_ADMIN_USER / PASSWORD / MAIL 三行删掉，它们只在第一次建用户时生效。

四、中文 OCR 怎么配（重点避坑）

中文圈教程最容易在这翻车。关键点：官方镜像已经内置了绝大多数 Tesseract 语言包，所以你不需要再进容器装 tesseract-ocr-chi-sim。只要在环境变量里指定语言代码即可，多语言用加号连：

PAPERLESS_OCR_LANGUAGE: chi_sim+eng
  • 简体中文用 chi_sim，繁体用 chi_tra；混合中英文文档就 chi_sim+eng。
  • 常见坑：有人照着系统包教程去 apt install tesseract-ocr-chi-sim，结果容器重建后语言包没了。认准 PAPERLESS_OCR_LANGUAGE 这一个变量就行。
  • 另一个坑：中文 OCR 比英文慢且更吃内存。低配机（1–2GB）建议把 PAPERLESS_TASK_WORKERS: 1 和 PAPERLESS_OCR_THREADS: 1 都设上，避免一上大文档就 OOM 被杀。
  • OCR 模式默认 skip：已经有文字层的数字 PDF 不再重复识别，最省 CPU；如果你的扫描仪自带烂 OCR，想要更准就设 PAPERLESS_OCR_MODE: redo。

中文搜索本身是能用的——OCR 之后会生成一层可搜索文字，Paperless 把它建进索引。只是中文是连续字串，别指望像英文那样按单词高亮，关键词命中即可。

五、让文档自动归类：correspondent、标签与规则

真正让你「用得下去」的是自动化，而不是手动整理。Paperless-ngx 有三层自动能力：

  • 对应人（Correspondent）：谁发来的，比如「国家电网」「房东」。
  • 文档类型（Document Type）：发票、合同、收据、信函。
  • 匹配规则（Matching）：按标题/内容里的词，用「任意 / 全部 / 正则」匹配自动套标签和分类。

比如建一条规则：内容包含「增值税专用」就自动打「发票」标签并归到「财务」类型。consume 目录还支持子目录自动打标签：在 consume/发票 下放文件，就会被自动标上「发票」。再配合机器学习标签建议，用得越久越省心。

六、邮件抓取与扫描仪：文档自己进来

除了手动丢文件，两个省事入口：

  • 邮件抓取（IMAP）：给 Paperless 配一个专用邮箱，把供应商发来的电子发票转发过去。加这几行环境变量即可：PAPERLESS_CONSUMER_ENABLE_IMAP_MAILBOX: true、PAPERLESS_CONSUMER_IMAP_SERVER、IMAP_PORT: 993、IMAP_USER、IMAP_PASSWORD。注意用邮箱的应用专用密码，别用主密码。
  • consume 目录：让网络扫描仪把文件扫到这个共享文件夹，或者手机用官方 App 拍完直接传，Paperless 每几秒轮询一次自动收。

想识别 Word/Excel 这类 Office 文档，还要额外挂 Gotenberg + Tika 两个服务，体积会大一些；纯 PDF 和图片场景可以省掉。

七、安全：明文存储风险与 HTTPS/VPN 防护

这是中文教程最常说漏、却最要命的一块。Paperless-ngx 默认把原始文件明文存在 media/ 目录里，数据库里也是明文。也就是说，谁拿到你 VPS 的磁盘或备份，就能直接翻出你的合同和身份证扫描件。防护要三层做：

  • 磁盘加密：在宿主机层面用 LUKS 或云厂商的加密卷，至少让「拿到磁盘」这一层失效。
  • 不要裸奔 8000 端口：别直接把 8000 暴露公网。最稳的是只开 VPN（WireGuard），回家连上 VPN 再访问；要对外就用反向代理上 HTTPS。
  • 反向代理 + HTTPS：用 Caddy 最省心，证书自动申请续期，配置里转发到 localhost:8000，并记得开启 WebSocket（Paperless 实时任务靠它）。同时把 PAPERLESS_URL 改成 https 域名。
  • 密钥与密码：PAPERLESS_SECRET_KEY 用 openssl rand -hex 32 生成，千万别提交到 Git；admin 密码要强，且首次启动后从 compose 删掉。

八、备份：数据库 + 媒体一个都不能少

只备份 media 会丢标签和规则，只备份数据库会丢原文件。正确姿势是两份都备：

  • 数据库：docker compose exec db pg_dump -U paperless paperless > paperless.sql 导出 SQL。
  • 媒体与原文件：把 media/ 整个打 tar 包。
  • 更省事的是用官方导出器：docker compose exec web python3 manage.py document_exporter ../export，一份就包含文档+元数据。

遵循 3-2-1：3 份拷贝、2 种介质、1 份离线。加密后再传远端，别把明文备份也裸奔。

还有一个常被忽略的点：恢复演练。备份不等于能恢复，很多人第一次真要用时才发现 SQL 导出的版本和镜像对不上。建议每次大版本升级前后各做一次导出，并在另一台机器用同版本镜像试着导回一次，确认标签、规则、原文件都回来了。另外 media/ 和 data/ 最好一起备份，单独恢复 media 会丢掉搜索索引，单独恢复数据库会丢掉原文件，两份齐了才算完整档案。

九、低配 VPS 性能调优与日常维护

在 RackNerd 这种 1–2GB 内存的小鸡上，想跑得稳得做几件减法。第一是限并发：把 PAPERLESS_TASK_WORKERS 和 PAPERLESS_OCR_THREADS 都设成 1，牺牲一点速度换不崩。第二是限页数：PAPERLESS_OCR_PAGES: 1 只 OCR 第一页，合同封面识别到关键字就够搜了，后面页数省掉能快很多。第三是关掉用不上的东西：不处理 Office 文档就把 Gotenberg 和 Tika 删了，内存立马松一截。

  • 命名格式：设 PAPERLESS_FILENAME_FORMAT 比如 {created_year}/{correspondent}/{title}，归档后目录清爽，导出备份也好人眼核对。
  • 去重：开 PAPERLESS_CONSUMER_DELETE_DUPLICATES，同一张发票重复丢进来不会建两份。
  • 定期更新：docker compose pull && docker compose up -d 拉新镜像，v2.x 迭代快，安全补丁和 OCR 改进值得跟。
  • 看日志：某份文档一直卡在「正在处理」，先看 docker compose logs web，九成是 OCR 内存爆了或语言包没配对。

把这几点做对，哪怕是年付几美元的小鸡，也能稳稳当当地当你的私有档案库，发票合同一扫即搜，比翻抽屉强太多。