乐于分享
好东西不私藏

告别纸质堆积!文档管理神器Paperless-ngx 部署指南与高效使用技巧

告别纸质堆积!文档管理神器Paperless-ngx 部署指南与高效使用技巧

告别纸质堆积!文档管理神器Paperless-ngx 部署指南与高效使用技巧

一款开源自托管的文档管理系统,主打把纸质单据、合同、发票扫描后自动做 OCR 文字识别,生成可长期保存的 PDF/A 档案,支持全文检索、智能标签、自动分类与权限管理,数据完全存在自己的 NAS 或服务器上,适合家庭与小型团队做无纸化归档,是目前最流行、维护最活跃的自建文档库方案。
功能清单:
  • 强大OCR,扫描件 / 照片也能全文搜索
  • 自动分类、打标签、匹配对应人,越用越智能
  • 支持PDF/A归档,长期保存不失效
  • 多端统一:网页、手机拍照上传、邮件批量导入
  • 多用户 + 权限控制,小团队也能用
  • Docker 一键部署,完美跑在 NAS / 服务器
  • 数据完全本地自托管,隐私安全可控
使用场景:
  • 家庭 / 个人:账单、发票、证件、保单、合同、小票电子化存档,全文搜索
  • 自由职业 / 小团队:合同、报销、项目资料统一管理,多用户权限
  • NAS 用户:本地部署、数据自己掌控,安全不泄露
  • 无纸化办公:纸质文件拍照 / 扫描 → 可搜索数字档案

Docker安装部署

1、创建本地文件夹
mkdir -p /opt/paperless-ngxcd /opt/paperless-ngx#/opt/paperless-ngx目录下,创建5个文件夹mkdir -p data media export consume data/postgres

目录说明:

data: 数据库和索引文件存储
media: 文档处理后的存储位置
export: 文档导出目录
consume: 文档导入监控目录
2、Docker Compose配置
version: "3.9"services:  webserver:    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.6    restart: unless-stopped    ports:      - "9980:8000"    healthcheck:      test: ["CMD""curl""-f""http://localhost:8000"]      interval: 30s      timeout: 10s      retries: 5    volumes:      - ./data:/usr/src/paperless/data      - ./media:/usr/src/paperless/media      - ./export:/usr/src/paperless/export      - ./consume:/usr/src/paperless/consume    environment:      # Redis设置      PAPERLESS_REDIS:  redis://:passwd@192.168.50.100:16379      # 数据库设置      PAPERLESS_DBENGINE: mariadb      PAPERLESS_DBHOST: 192.168.50.1      PAPERLESS_DBUSER: root       PAPERLESS_DBPASS: 123456       PAPERLESS_DBPORT: 3306      PAPERLESS_TIKA_ENABLED: 1      PAPERLESS_TIKA_ENDPOINT: http://tika:9998      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000    deploy:      resources:        limits:          memory: 1024m  # 限制为使用1GB内存  tika:    image: apache/tika:latest    restart: unless-stopped    deploy:      resources:        limits:          memory: 1024m  # 限制为使用1GB内存  gotenberg:     image: gotenberg/gotenberg:8.19     restart: unless-stopped     deploy:      resources:        limits:          memory: 1024m  # 限制为使用1GB内存
参数说明:
连接已安装好的Redis和数据库,也可以创建独立的数据库和Redis
1)连接Redis
PAPERLESS_REDIS:  redis://:passwd@192.168.50.100:16379
2)根据需求修改数据库配置
选择数据库引擎,支持mariadb
PAPERLESS_DBENGINE: mariadbPAPERLESS_DBHOST: 192.168.50.1PAPERLESS_DBUSER: rootPAPERLESS_DBPASS: 123456PAPERLESS_DBPORT: 3306
安装tika、gotenberg容器,为了识别docx、pptx等Office文档,不安装的话直接上传word文档会报错
3、独立数据库和Redis安装的Docker Compose
services:  # ===== Redis 消息队列服务 =====  broker:    image: redis:7  # 使用 Redis 7 版本作为消息代理    container_name: paperless-redis  # 容器名称    restart: unless-stopped  # 容器退出时自动重启(除非手动停止)    command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru  # 限制内存512MB,LRU淘汰策略    networks:      - paperless-network  # 连接到自定义网络    healthcheck:  # 健康检查配置      test: ["CMD""redis-cli""ping"]  # 使用 redis-cli ping 命令检查服务状态      interval: 30s  # 每30秒检查一次      timeout: 3s  # 超时时间3秒      retries: 3  # 失败3次后标记为不健康      start_period: 10s  # 容器启动后10秒开始健康检查  # ===== PostgreSQL 数据库服务 =====  db:    image: postgres:15  # 使用 PostgreSQL 15 版本    container_name: paperless-db  # 容器名称    restart: unless-stopped  # 容器退出时自动重启(除非手动停止)    environment:      POSTGRES_DB: paperless  # 数据库名称      POSTGRES_USER: paperless  # 数据库用户名      POSTGRES_PASSWORD: paperless  # 数据库密码    volumes:      - ./data/postgres:/var/lib/postgresql/data  # 数据库数据持久化目录映射    networks:      - paperless-network  # 连接到自定义网络    healthcheck:  # 健康检查配置      test: ["CMD-SHELL""pg_isready -U paperless -d paperless"]  # 检查数据库是否就绪      interval: 30s  # 每30秒检查一次      timeout: 5s  # 超时时间5秒      retries: 3  # 失败3次后标记为不健康      start_period: 30s  # 容器启动后30秒开始健康检查(数据库启动较慢)  # ===== Paperless-ngx 主服务 =====  webserver:    # image: ghcr.io/paperless-ngx/paperless-ngx:latest  # 官方镜像    build:      context: .  # 构建上下文为当前目录      dockerfile: Dockerfile  # 使用自定义 Dockerfile 构建    image: paperless-ngx-zh:latest  # 自定义镜像名称(支持中文)    container_name: paperless-web  # 容器名称    restart: unless-stopped  # 容器退出时自动重启(除非手动停止)    depends_on:  # 依赖服务,这些服务会优先启动      db:        condition: service_healthy  # 等待数据库健康检查通过      broker:        condition: service_healthy  # 等待 Redis 健康检查通过      gotenberg:        condition: service_healthy  # 等待 Gotenberg 健康检查通过      tika:        condition: service_healthy  # 等待 Tika 健康检查通过    ports:      - "8000:8000"  # 端口映射:宿主机8000端口 -> 容器8000端口    environment:      # ----- 数据库连接配置 -----      PAPERLESS_REDIS: redis://broker:6379  # Redis 连接地址      PAPERLESS_DBENGINE: postgresql  # 数据库引擎类型      PAPERLESS_DBHOST: db  # 数据库主机地址(容器名)      PAPERLESS_DBNAME: paperless  # 数据库名称      PAPERLESS_DBUSER: paperless  # 数据库用户名      PAPERLESS_DBPASS: paperless  # 数据库密码      # ===== 文档处理核心配置 =====      PAPERLESS_TIKA_ENABLED: "1"  # 启用 Tika 文档解析服务(支持更多文档格式)      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000  # Gotenberg PDF 转换服务地址      PAPERLESS_TIKA_ENDPOINT: http://tika:9998  # Tika 文档解析服务地址      # ----- OCR 光学字符识别配置 -----      # OCR(中文建议开启)      PAPERLESS_OCR_LANGUAGE: chi_sim+eng  # OCR 识别语言:简体中文+英文      PAPERLESS_OCR_MODE: skip  # OCR 模式:跳过已有文本层的文档(避免重复识别)      # ----- 系统性能与安全配置 -----      # 安全 & 性能      PAPERLESS_TASK_WORKERS: 2  # 任务处理工作进程数量      PAPERLESS_THREADS_PER_WORKER: 2  # 每个工作进程的线程数      PAPERLESS_TIME_ZONE: Asia/Shanghai  # 系统时区设置为上海时区      # ----- 任务调度优化配置 -----      PAPERLESS_TRAIN_TASK_CRON: "5 */1 * * *"  # 每小时第5分钟自动训练分类器(提高自动分类准确度)      PAPERLESS_INDEX_TASK_CRON: "15 0 * * *"  # 每天午夜00:15进行索引优化(提高搜索速度)      PAPERLESS_SANITY_TASK_CRON: "30 0 * * 0"  # 每周日午夜00:30进行完整性检查(检查文档一致性)      # ----- 文件权限配置 -----      # 宿主机用户和分组      PAPERLESS_UID: 1000  # 容器内文件所有者的用户ID(对应宿主机用户)      PAPERLESS_GID: 1000  # 容器内文件所有者的组ID(对应宿主机用户组)    volumes:  # 数据卷映射(持久化存储)      - ./data:/usr/src/paperless/data  # 应用数据目录(索引、缓存等)      - ./media:/usr/src/paperless/media  # 文档存储目录(原始文件和归档文件)      - ./export:/usr/src/paperless/export  # 导出目录(用于导出文档)      - ./consume:/usr/src/paperless/consume  # 消费目录(监控此目录自动导入文档)    networks:      - paperless-network  # 连接到自定义网络    healthcheck:  # 健康检查配置      test: ["CMD""curl""-f""http://localhost:8000"]  # 检查 Web 服务是否响应      interval: 30s  # 每30秒检查一次      timeout: 10s  # 超时时间10秒      retries: 3  # 失败3次后标记为不健康      start_period: 60s  # 容器启动后60秒开始健康检查(应用启动较慢)  # ===== Gotenberg PDF 转换服务 =====  gotenberg:    image: gotenberg/gotenberg:8  # 使用 Gotenberg 8 版本    container_name: paperless-gotenberg  # 容器名称    restart: unless-stopped  # 容器退出时自动重启(除非手动停止)    command:  # 容器启动命令参数      - gotenberg  # 主程序      - --chromium-disable-javascript=true  # 禁用 Chromium 的 JavaScript(提高安全性和性能)      - --libreoffice-start-timeout=60s  # LibreOffice 启动超时时间设置为60秒      - --api-timeout=300s  # API 请求超时时间300秒    environment:      DISABLE_GOOGLE_CHROME: "1"  # 禁用 Google Chrome(使用 Chromium 代替)    networks:      - paperless-network  # 连接到自定义网络    healthcheck:  # 健康检查配置      test: ["CMD""curl""-f""http://localhost:3000/health"]  # 检查 Gotenberg 健康状态      interval: 30s  # 每30秒检查一次      timeout: 10s  # 超时时间10秒      retries: 3  # 失败3次后标记为不健康      start_period: 40s  # 容器启动后40秒开始健康检查(LibreOffice 启动较慢)  # ===== Apache Tika 文档解析服务 =====  tika:    image: apache/tika:latest  # 使用 Apache Tika 最新版本    container_name: paperless-tika  # 容器名称    restart: unless-stopped  # 容器退出时自动重启(除非手动停止)    networks:      - paperless-network  # 连接到自定义网络    healthcheck:  # 健康检查配置 - 简化为 TCP 端口检查      test: ["CMD-SHELL""timeout 5 bash -c '</dev/tcp/localhost/9998' || exit 1"]  # 检查 9998 端口是否可访问      interval: 30s  # 每30秒检查一次      timeout: 10s  # 超时时间10秒      retries: 5  # 失败5次后标记为不健康(增加容错)      start_period: 60s  # 容器启动后60秒开始健康检查(Tika 启动较慢)# ===== 网络配置 =====networks:  paperless-network:  # 自定义网络名称    driver: bridge  # 使用桥接网络驱动    name: paperless-net  # 网络显示名称    ipam:  # IP 地址管理配置      driver: default  # 使用默认 IPAM 驱动      config:        - subnet: 172.28.0.0/16  # 子网地址范围          gateway: 172.28.0.1  # 网关地址
4、启动容器
sudo docker compose up

Paperless-ngx使用指南

1、创建用户
#进入paperless-ngx 的安装目录cd /usr/src/paperless/srcdocker exec -it <容器名> python manage.py createsuperuser
按照交互式提示输入用户名、邮箱、密码即可完成创建
2、登录
浏览器使用NAS IP:端口地址登录,使用刚才创建的用户名和密码登录
3、上传文档和文档操作
1)上传文档
上传文档非常简单,将文档直接拖进浏览器,或者点击上传文件按钮
上传文档后,查看和现实上传文档的状态
也可以在文档任务中查看进展状态,尤其是上传多个文档的时候,比较方便
2)文档操作
点击打开文档
设置单个文档的属性,查看文档内容,设置文档权限,添加备注,查看文档修改历史等
批量操作文档:
点击文档,进入文档列表页面进行操作

4、为什么一定要 Tika + Gotenberg?

官方推荐的方案
Tika:识别 Word/Excel/ 文本内容
Gotenberg:负责 LibreOffice 转 PDF
Paperless:本体只做编排与OCR

5、其他一些设置建议

1)安全性考虑
建议使用 HTTPS 进行加密访问
配置反向代理保护服务
定期更新系统和镜像
2)性能优化
内存不够的建议,限制约束容器内存
deploy:    resources:        limits:        memory1024m

限制为使用1GB内存,避免影响到其他容器

为文档存储预留足够空间
根据需要调整 OCR 语言包
合理设置文档处理队列
3)数据备份
做好数据备份,比如定期备份数据库、备份重要的配置文件,备份文件目录
本站文章均为手工撰写未经允许谢绝转载:夜雨聆风 » 告别纸质堆积!文档管理神器Paperless-ngx 部署指南与高效使用技巧

评论 抢沙发

9 + 7 =
  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
×
订阅图标按钮