部署教程｜paperless-ngx：自建无纸化文档库，OCR + 全文搜索

1. 项目亮点

  • OCR：自动识别扫描件/照片文字，支持多语言。
  • 全文搜索与标签：按标题、内容、日期、标签检索。
  • API：可与其他系统集成或自动化。
  • 轻量部署：官方 Docker Compose 一键跑通。

2. 前置条件

  • 服务器：2C4G 起步，磁盘视文档量规划。
  • Docker / Docker Compose。
  • 时区/语言：提前设置好以避免时间戳混乱。

3. Docker Compose 部署

docker-compose.yml（精简示例）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
version: "3.8"
services:
  broker:
    image: redis:7
    restart: unless-stopped

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: strongpassword
    volumes:
      - ./data/db:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on: [db, broker]
    restart: unless-stopped
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: strongpassword
      PAPERLESS_URL: http://localhost:8000
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
    volumes:
      - ./data/media:/usr/src/paperless/media
      - ./data/data:/usr/src/paperless/data
      - ./data/export:/usr/src/paperless/export
      - ./data/consume:/usr/src/paperless/consume
    ports:
      - "8000:8000"

启动：

1
docker compose up -d

首次登录：默认账号/密码在容器日志中（或通过命令行创建超管）。

4. OCR 语言包

  • 通过 PAPERLESS_OCR_LANGUAGE 设置，例：eng、chi_sim+eng。
  • 需要对应的 tesseract 语言包，官方镜像自带常用语言，若缺失可自定义镜像或挂载。

5. 常用目录

  • consume/：投放文件的入口目录，系统会自动导入。
  • media/：存储已处理的文档与预览。
  • export/：批量导出目录。
  • data/：应用配置与数据库相关文件（勿遗失）。

6. 备份与恢复

  • Postgres：定期 pg_dump 或卷快照。
  • 媒体/数据目录：同步到对象存储或异地。
  • 灾备：备份 consume 可选，关键是数据库与 media/data。

7. 反向代理与 HTTPS

  • 用 Nginx/Caddy/Traefik 做反代，开启 TLS。
  • 如需外网访问，建议加 Basic Auth/IP 白名单。

8. 常见问题

  • OCR 慢：检查 CPU/内存，减少并发导入，或用更高性能机器。
  • 中文识别差：确认 chi_sim 语言包已启用，提升图像清晰度。
  • 登录失败/500：查看 webserver 日志，确认数据库连接、迁移状态。

9. 总结

paperless-ngx 是稳定的自建文档库方案：OCR、标签、全文检索开箱即用。用官方 Compose 起步、规划好存储与备份，几分钟即可拥有自己的无纸化档案室。***