Paperless-ngx 文档管理系统安装指南

郎赞柱

于 2025-06-01 09:03:44 发布

阅读量384

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00615/article/details/148360705

Paperless-ngx 文档管理系统安装指南

paperless-ngx A community-supported supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ngx

项目概述

Paperless-ngx 是一款开源的文档管理系统，旨在帮助用户实现无纸化办公。它能够自动扫描、索引和归档文档，支持OCR文字识别、全文搜索等功能，让文档管理变得简单高效。

安装方式选择

Paperless-ngx 提供多种安装方式，适合不同技术水平的用户：

Docker脚本安装（推荐新手使用）
Docker Compose手动安装
自行构建Docker镜像
原生系统安装（适合开发者）

推荐安装方式：Docker脚本安装

这是最简单快捷的安装方法，适合大多数用户。

准备工作

确保系统已安装：

Docker引擎
Docker Compose

安装步骤

执行安装脚本命令：

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

脚本会交互式询问配置选项，完成后自动：
- 创建配置文件
- 拉取Docker镜像
- 启动Paperless-ngx
- 创建管理员账户
macOS用户需要额外安装：
- gnu-sed（支持作为sed运行）
- wget工具

Docker Compose手动安装

适合需要自定义配置的用户。

安装步骤

下载必要的配置文件：
- docker-compose.yml（选择适合的数据库版本）
- docker-compose.env
- .env文件
修改docker-compose.yml：
- 调整数据卷挂载路径
- 修改默认端口（如8000改为8010）
- 如需rootless运行，设置用户映射
配置docker-compose.env：
- 设置USERMAP_UID和USERMAP_GID（使用id -u和id -g获取）
- 其他可选配置参数

启动服务：

docker compose pull
docker compose up -d

访问http://127.0.0.1:8000创建管理员账户

自行构建Docker镜像

适合需要自定义镜像或开发环境的用户。

构建步骤

克隆项目仓库
复制docker-compose配置文件
修改配置使用本地构建而非预构建镜像
执行构建命令：
```
docker compose build
```
后续步骤与Docker Compose安装相同

原生系统安装

适合开发者或需要直接修改代码的用户。

系统要求

Linux系统（推荐Debian/Ubuntu）
Python 3.10-3.12
Redis ≥6.0
可选PostgreSQL/MariaDB

安装步骤

安装系统依赖：

apt install python3 python3-pip python3-dev imagemagick fonts-liberation gnupg libpq-dev default-libmysqlclient-dev pkg-config libmagic-dev libzbar0 poppler-utils unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 pngquant zlib1g tesseract-ocr

安装OCR依赖：

apt install tesseract-ocr-eng tesseract-ocr-deu

创建系统用户：

adduser paperless --system --home /opt/paperless --group

下载并解压发布包到/opt/paperless
配置paperless.conf：
- 设置Redis连接
- 配置数据库
- 设置文档消费目录
- 配置OCR语言等参数
创建必要目录并设置权限

安装Python依赖：

sudo -Hu paperless pip3 install -r requirements.txt

初始化数据库：

sudo -Hu paperless python3 manage.py migrate

配置系统服务（使用提供的systemd脚本）
配置ImageMagick允许处理PDF

安装后配置建议

OCR优化：
- 设置PAPERLESS_OCR_LANGUAGE匹配文档主要语言
- 考虑安装jbig2enc减小PDF体积
性能优化：
- 生产环境建议使用PostgreSQL
- 合理配置Redis缓存
安全建议：
- 确保Redis安全配置
- 设置强密码的SECRET_KEY
- 生产环境使用反向代理
使用技巧：
- 配置Samba共享消费目录方便上传
- 设置定时任务自动处理文档

常见问题解决

消费目录文件不自动处理：
- 检查目录权限
- NFS共享需设置PAPERLESS_CONSUMER_POLLING
OCR质量不佳：
- 检查语言包安装
- 调整OCR参数
性能问题：
- 增加Redis内存
- 优化数据库配置

通过以上步骤，您应该能够成功安装并运行Paperless-ngx文档管理系统。根据实际需求选择合适的安装方式，并注意生产环境的安全配置。

paperless-ngx A community-supported supercharged version of paperless: scan, index and archive all your physical documents 项目地址: https://gitcode.com/gh_mirrors/pa/paperless-ngx

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考