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

-
强大OCR,扫描件 / 照片也能全文搜索 -
自动分类、打标签、匹配对应人,越用越智能 -
支持PDF/A归档,长期保存不失效 -
多端统一:网页、手机拍照上传、邮件批量导入 -
多用户 + 权限控制,小团队也能用 -
Docker 一键部署,完美跑在 NAS / 服务器 -
数据完全本地自托管,隐私安全可控
-
家庭 / 个人:账单、发票、证件、保单、合同、小票电子化存档,全文搜索 -
自由职业 / 小团队:合同、报销、项目资料统一管理,多用户权限 -
NAS 用户:本地部署、数据自己掌控,安全不泄露 -
无纸化办公:纸质文件拍照 / 扫描 → 可搜索数字档案
Docker安装部署
mkdir -p /opt/paperless-ngxcd /opt/paperless-ngx#/opt/paperless-ngx目录下,创建5个文件夹mkdir -p data media export consume data/postgres
目录说明:
version: "3.9"services:webserver:image: ghcr.io/paperless-ngx/paperless-ngx:2.20.6restart: unless-stoppedports:- "9980:8000"healthcheck:test: ["CMD", "curl", "-f", "http://localhost:8000"]interval: 30stimeout: 10sretries: 5volumes:- ./data:/usr/src/paperless/data- ./media:/usr/src/paperless/media- ./export:/usr/src/paperless/export- ./consume:/usr/src/paperless/consumeenvironment:# Redis设置PAPERLESS_REDIS: redis://:passwd@192.168.50.100:16379# 数据库设置PAPERLESS_DBENGINE: mariadbPAPERLESS_DBHOST: 192.168.50.1PAPERLESS_DBUSER: rootPAPERLESS_DBPASS: 123456PAPERLESS_DBPORT: 3306PAPERLESS_TIKA_ENABLED: 1PAPERLESS_TIKA_ENDPOINT: http://tika:9998PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000deploy:resources:limits:memory: 1024m # 限制为使用1GB内存tika:image: apache/tika:latestrestart: unless-stoppeddeploy:resources:limits:memory: 1024m # 限制为使用1GB内存gotenberg:image: gotenberg/gotenberg:8.19restart: unless-stoppeddeploy:resources:limits:memory: 1024m # 限制为使用1GB内存
PAPERLESS_REDIS: redis://:passwd@192.168.50.100:16379
PAPERLESS_DBENGINE: mariadbPAPERLESS_DBHOST: 192.168.50.1PAPERLESS_DBUSER: rootPAPERLESS_DBPASS: 123456PAPERLESS_DBPORT: 3306
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 # 网关地址
sudo docker compose up
Paperless-ngx使用指南
#进入paperless-ngx 的安装目录cd /usr/src/paperless/srcdocker exec -it <容器名> python manage.py createsuperuser





4、为什么一定要 Tika + Gotenberg?
5、其他一些设置建议
deploy:resources:limits:memory: 1024m
夜雨聆风
