Paperless-ngx：纸质文件拍一下就归档，4.7 万 star 的文档管理系统

家里那摞东西：购房合同、保修卡、体检报告、每年的发票、孩子的疫苗本。

纸会丢、会黄、会被水泡。拍成照片呢？存进相册，过两年你在一万张照片里找不到那张保修单。

Paperless-ngx 是专门管这个的。4.7 万 star，地址：

https://github.com/paperless-ngx/paperless-ngx

它的工作方式很简单：你把扫描件扔进一个目录，它自己识别文字、猜日期、猜金额、打标签、建索引。之后你搜"2024 空调 保修"，它就给你翻出来。

装：三个容器

它比前面几个重，因为要数据库和队列：

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: 换成一个你自己的密码

  webserver:
    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_DBUSER: paperless
      PAPERLESS_DBPASS: 换成同一个密码
      PAPERLESS_SECRET_KEY: 随便一串长的随机字符
      PAPERLESS_URL: http://192.168.1.10:8000
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: 设一个
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"

docker compose up -d
docker compose logs -f webserver

看到 Paperless-ngx ... ready 就好了，打开 http://NAS地址:8000。

PAPERLESS_SECRET_KEY 别照抄示例，自己随便敲一串长的。PAPERLESS_URL 必须填你实际访问的地址，否则下载链接会指错。

四个目录，各管一件事

media 和 data 必须一起备份。只备 media，恢复出来没有索引；只备 data，文件都丢了。

最简单的用法：往目录里扔

这是它设计的核心。把扫描件、拍照件、下载的 PDF 直接丢进 consume 目录：

cp 保修单.pdf /vol1/paperless/consume/

几十秒后它出现在网页上，标题自动取文件名，日期尽量从内容里猜。

处理成功的文件会从 consume 移走（或留下标记），失败的会进一个 consume/error 之类的目录——看到有文件一直不动，去那儿找原因。

手机扫描：别用拍照

手机拍照出来的文件，斜的、暗的、有阴影，OCR 效果很差。

正确做法是用扫描类 App（很多手机自带，或者装个开源的）拍成"文档模式"，输出 PDF 或 JPG，再传到 consume。

判断标准：文字横平竖直、背景干净、没有手指入镜。达到这三条，中文 OCR 基本能认全。

让检索真正好用

装完别急着入库，先花二十分钟配这几样：

1. 标签（Tags） 建一套自己的分类：发票、合同、保修、医疗、证件。上传时勾一下，之后按标签筛。

2. 文档类型（Document Types） 发票、收据、合同、报告。和标签不同，一个文档只能有一个类型。

3. 对应人（Correspondent） 这笔钱付给谁、这份合同和谁签的。比如"国家电网"、“XX 物业”。

4. 自动匹配规则 这是省时间的关键。比如"文件名含 发票 → 打上 发票 标签 + 类型设为发票"。配好之后新文件进来自动归类，不用手动点。

5. 全文检索 不用特意开，它默认就建索引。搜"美的 空调"能搜到正文里出现这两个词的文档，不只是标题。

几个会踩的坑

中文 OCR 出来是乱码或方块 PAPERLESS_OCR_LANGUAGE 必须包含 chi_sim。改完要重启容器，并且对已入库的文档重新 OCR（网页上可以批量操作）。

上传后一直"待处理" broker 没起来。docker ps 看 redis 是不是在跑。

数据目录权限报错 USERMAP_UID/GID 要跟你宿主机目录的属主对上。SSH 进 NAS 跑 id 看当前用户，填那个数字。

从外网访问，下载链接指到内网 PAPERLESS_URL 没改。它用这个值拼下载链接。

备份恢复了但没有索引 只备了 media。data 目录里有 index 和 db 的映射，必须一起。

一个额外玩法：自动归档发票

如果你每月收到的电子发票是邮件附件，可以写个脚本定时下载到 consume。配上自动匹配规则，等于每月自动归档，你只需要偶尔检查一下。

这个用法一旦跑通，你会发现"报税时找不到发票"这种事再也不会发生了。

它适合谁

• 家里纸质文件多、想彻底数字化的；
• 每年报税要找发票的；
• 有大量 PDF 需要能搜索内容的。

不适合：只有几十份文件、用文件夹分类就够的人。这套东西要维护数据库，为了几十份文件不值。

最后

Paperless 的门槛不在安装，在养成习惯：收到纸质文件先扫、下载的发票直接扔进目录。

头一个月要手动归类，配上自动规则后就开始省事了。半年之后，你会发现找东西的方式变了——从"翻抽屉"变成"搜一下"。

装的过程中有问题，留言。