欢迎光临
我们一直在努力

Docker搭建Paperless-ngx文档库

1. 项目介绍

合同扫描件、设备说明书、票据和资料 PDF 越存越多,查找时经常只能依靠文件名。遇到没有认真命名的扫描件,就需要逐个打开确认。

Paperless-ngx 是一个开源文档管理系统,可以将扫描件和电子文档整理成可搜索的私人文档库。

它适合完成以下工作:

  • 上传并集中保存 PDF、照片和扫描件。
  • 通过 OCR 识别扫描件中的文字。
  • 根据正文关键词查找文档。
  • 使用标签、文档类型等信息分类。
  • 在线预览文档,并下载原始文件。

例如,一份名称为 001.pdf 的扫描件,正文中包含“项目验收”。完成识别和索引后,就可以根据正文关键词找到它。

本教程使用 Docker Compose 部署,配置简体中文识别和域名 HTTPS。基础的上传、搜索、分类功能不需要自建邮局,也不需要购买 AI 接口。

本文固定使用 Paperless-ngx 3.4.2,便于文章与操作视频保持一致。

2. 相关地址

项目地址: Paperless-ngx GitHub 仓库

官方文档: Paperless-ngx 使用文档

版本说明: Paperless-ngx 3.4.2

如果你更需要网盘上传、文件分享等功能,也可以参考本站的 Cloudreve 私有云盘搭建教程。Paperless-ngx 更适合扫描件识别、文档检索和资料归档。

3. 搭建环境

中文 OCR 会占用一定的 CPU 和内存。本次个人文档库演示建议使用以下配置:

  • CPU:建议 2 核及以上,批量识别建议 4 核及以上。
  • 内存:建议 4GB 起,较多扫描件建议 8GB。
  • 磁盘:建议至少准备 30GB 可用 SSD 空间,文档较多时继续扩容。
  • 系统:Debian 12 或 Ubuntu 24.04。
  • Docker:Docker Engine。
  • Compose:Docker Compose V2。
  • 域名:一个可以管理 DNS 解析的域名。
  • 公网端口:TCP 80 和 443。

以上是本教程的配置建议,不代表所有使用场景的最低要求。

本次使用 SQLite 保存数据库,适合个人或小规模文档库。大量用户同时使用、持续批量导入的场景,应另行评估 PostgreSQL 和服务器资源。

Paperless-ngx 会保存原始文件,并生成缩略图、索引及部分归档文件。因此,应同时为文档增长和备份预留磁盘空间。

本次教程推荐使用莱卡云 Linux 云服务器进行搭建。

查看官网购买链接: https://www.lcayun.com

9折优惠码:bloglcayun

提前准备域名

本文使用 docs.example.com 作为示例,实际操作时必须替换为自己的域名。

在域名 DNS 管理页面添加一条 A 记录:

项目填写内容
主机记录docs
记录类型A
记录值云服务器的公网 IPv4 地址
Paperless域名A记录配置

如果没有配置可用的 IPv6,不要保留指向错误地址的 AAAA 记录。首次部署建议先使用普通 DNS 解析,确认网站正常后再考虑接入 CDN。

随后,在云服务器安全组中允许 TCP 80、443 端口;如果服务器已经启用主机防火墙,也需要允许这两个端口,并保留现有 SSH 规则。

本教程建议使用全新服务器。若已经安装宝塔、Nginx、Apache 等服务,应先确认 80、443 没有被占用。

服务器还需要能够正常访问 Docker 官方软件仓库、Docker Hub、GHCR 和容器使用的软件包源。

4. 搭建视频

本节视频将演示 Docker 安装、项目部署、HTTPS 登录、中文扫描件识别、正文搜索、分类和备份。

【视频教程预留位置:录制完成后,在此插入视频播放器或嵌入代码。】

5. 正式搭建

以下命令均在云服务器终端中执行。

普通用户先切换到 root:

sudo -i

5.1 安装 Docker 和 Compose

已有可用 Docker 环境的读者,可以先检查:

docker --version
docker compose version

如果两个命令均正常输出版本,可以跳过引擎安装,并确保所需工具已经安装:

apt-get update
apt-get install -y openssl nano

全新的 Debian 12 或 Ubuntu 24.04 服务器,执行以下完整命令:

bash <<'DOCKER'
set -e

. /etc/os-release

case "$ID" in
  debian|ubuntu) ;;
  *) echo '本段仅适用于 Debian 或 Ubuntu'; exit 1 ;;
esac

apt-get update
apt-get install -y ca-certificates curl openssl nano

install -m 0755 -d /etc/apt/keyrings

curl -fsSL "https://download.docker.com/linux/$ID/gpg" \
  -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/$ID
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt-get update

apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker

docker --version
docker compose version
docker run --rm hello-world
DOCKER

看到 Docker、Compose 版本,以及 hello-world 的成功提示后,再继续部署。命令中途报错时,应先处理错误。

Docker和Compose安装验证

安装方式采用 Docker 官方软件仓库。更多安装说明可参考本站的 Docker 安装教程。

5.2 创建目录和环境配置

先创建项目目录:

mkdir -p /opt/paperless-ngx
cd /opt/paperless-ngx

mkdir -p data media consume export broker caddy/data caddy/config

下面生成应用密钥和初始管理员密码。

执行前,将 docs.example.com 替换为自己的实际域名。只填写域名,不添加 https:// 或路径。

(
umask 077

cat > .env <<EOF
DOMAIN=docs.example.com
PAPERLESS_SECRET_KEY=$(openssl rand -hex 32)
PAPERLESS_ADMIN_PASSWORD=$(openssl rand -hex 16)
EOF
)

其中:

  • DOMAIN:访问文档库的域名。
  • PAPERLESS_SECRET_KEY:随机生成的应用密钥。
  • PAPERLESS_ADMIN_PASSWORD:随机生成的初始管理员密码。

这一步仅用于首次部署。已有文档库不要重复覆盖原来的 .env 文件。

5.3 创建 Compose 配置

继续在 /opt/paperless-ngx 目录执行以下完整命令:

cat > compose.yaml <<'EOF'
x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

services:
  broker:
    image: valkey/valkey:8.1.11-alpine
    restart: unless-stopped
    command: ["valkey-server", "--appendonly", "yes"]
    volumes:
      - ./broker:/data
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    logging: *default-logging

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.4.2
    restart: unless-stopped
    depends_on:
      broker:
        condition: service_healthy
    environment:
      PAPERLESS_DBENGINE: sqlite
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_SECRET_KEY: "${PAPERLESS_SECRET_KEY}"
      PAPERLESS_URL: "https://${DOMAIN}"
      PAPERLESS_ALLOWED_HOSTS: "${DOMAIN}"
      PAPERLESS_PROXY_SSL_HEADER: '["HTTP_X_FORWARDED_PROTO", "https"]'
      PAPERLESS_ADMIN_USER: admin
      PAPERLESS_ADMIN_PASSWORD: "${PAPERLESS_ADMIN_PASSWORD}"
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGES: chi-sim
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
      PAPERLESS_OCR_MODE: auto
      PAPERLESS_TASK_WORKERS: "1"
      PAPERLESS_THREADS_PER_WORKER: "2"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    logging: *default-logging

  caddy:
    image: caddy:2.11.9-alpine
    restart: unless-stopped
    depends_on:
      - webserver
    environment:
      DOMAIN: "${DOMAIN}"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy/data:/data
      - ./caddy/config:/config
    logging: *default-logging
EOF

这份配置包含三个服务:

服务用途
webserverPaperless-ngx 应用,负责文档管理和处理
brokerValkey,提供任务消息服务
caddy提供域名访问和 HTTPS

数据库保存在 data 目录,文档相关文件保存在 media 目录。上述目录都映射到了服务器磁盘,方便备份和迁移。

中文识别有两个容易混淆的配置:

  • PAPERLESS_OCR_LANGUAGES: chi-sim:安装简体中文语言包。
  • PAPERLESS_OCR_LANGUAGE: chi_sim+eng:识别简体中文和英文。

两个参数中的连字符、下划线用途不同,不要互换。本文使用 auto 模式,按文档情况提取已有文本或进行 OCR。

本教程主要处理 PDF、JPG、PNG 等文件。直接处理 Word、Excel 等 Office 文件需要额外转换组件,不包含在本次配置中。

5.4 配置域名 HTTPS

创建 Caddy 配置文件:

cat > Caddyfile <<'EOF'
{$DOMAIN} {
    reverse_proxy webserver:8000
}
EOF

这里的 {$DOMAIN} 保持原样,它会读取前面配置的域名。

当域名正确解析、服务器时间正常、80 和 443 端口可以从公网访问时,Caddy 会自动申请和续期 HTTPS 证书。

5.5 启动并检查服务

依次执行:

cd /opt/paperless-ngx

docker compose config -q

docker compose pull

docker compose up -d

docker compose ps

docker compose logs --tail=80 webserver caddy

docker compose config -q 没有报错并返回终端提示符,表示配置检查通过。

首次启动需要准备数据库、应用环境和中文 OCR 语言包,所需时间与服务器性能、网络状况有关。

Paperless容器运行状态

先确认三个服务持续运行,日志没有反复报错,再检查 OCR 语言:

docker compose exec webserver tesseract --list-langs

列表中应该包含:

chi_sim
eng

如果没有 chi_sim,先查看 webserver 日志,处理语言包下载或安装错误,再继续上传中文扫描件。

简体中文OCR语言包检查

6. 登录文档管理页面

在浏览器打开自己的域名,例如:

https://docs.example.com
Paperless HTTPS登录页面

首次启动时,配置会自动创建管理员账户:

用户名:admin

在服务器终端执行以下命令,查看随机生成的初始密码:

cd /opt/paperless-ngx

sed -n 's/^PAPERLESS_ADMIN_PASSWORD=//p' .env

复制密码并妥善保存,然后登录。

如果正在录屏,读取和输入密码时暂停录制,清理终端画面后再恢复。

登录后,如果界面不是中文,可以在用户设置中选择简体中文。

本教程没有配置邮件服务,正常登录、上传文件、中文识别和分类不依赖邮件。邮件通知、通过邮箱找回密码等功能,需要另行配置 SMTP。

7. 上传扫描件并验证中文搜索

7.1 上传演示文件

建议准备三份不含真实客户信息的资料:

文件内容
001.pdf图片型扫描件,正文包含“项目验收记录”
002.pdf普通文字 PDF,例如设备使用说明
003.jpg一张清晰的虚构收据照片

其中,001.pdf 应当是真正的图片型扫描件:在普通 PDF 阅读器里,不能直接选中并复制正文。

可以使用下面这段文字制作演示扫描件:

演示资料 01

项目验收记录

验收编号 DEMODOC2026

设备已完成安装与功能检查。

本文件仅用于教程演示。

在 Paperless-ngx 中通过上传入口选择文件,或拖入上传区域。

等待后台处理完成,确认文件已经出现在文档列表中。

上传后的文档列表

7.2 检查识别文字,再搜索正文

打开第一份扫描件,查看文档内容或识别文本,确认能够看到“项目验收记录”和 DEMODOC2026。

扫描件中文OCR识别内容

建议将这份文档的显示标题设为“演示资料 01”。

随后,在文档列表的全文搜索或高级查询输入框中输入:

content:项目验收
按扫描件正文搜索文档

也可以使用:

content:DEMODOC2026

content: 用于限定搜索文档正文。Paperless-ngx 支持这种按字段查询的搜索方式。

演示时,不要把“项目验收”写进文件名、标题或标签。这样才能明确验证搜索结果来自识别后的正文。

如果没有找到文件,依次检查:

  1. 上传和处理任务是否已经完成。
  2. 识别文本中是否确实包含检索词。
  3. 是否仍然启用了其他标签或类型筛选。
  4. 是否使用了文档全文查询,而不是只搜索文件名。

扫描清晰度、倾斜程度和字体都会影响识别结果。重要编号、金额和日期仍应人工核对。

7.3 使用标签和文档类型分类

打开文档编辑页面,为文件添加标签,例如:

  • 演示资料
  • 待整理
  • 已归档

再为不同资料设置文档类型,例如:

  • 验收记录
  • 设备说明
  • 收据

保存后返回文档列表,通过标签或文档类型筛选。

刷新页面后再次检查,确认分类信息已经保存。资料较多时,可以按自己的工作习惯逐步建立分类规则。

文档标签与类型分类

7.4 下载原始文件

打开文档后,使用下载菜单中的原始文件下载功能,确认文件可以正常保存和打开。

Paperless-ngx 会保留导入文档的原始版本。日常使用时,可以先在线预览,需要传递或离线保存时再下载。

8. 备份和恢复数据

8.1 备份整个项目目录

这套配置的数据库、文档和应用配置均保存在:

/opt/paperless-ngx

仅备份 compose.yaml 无法恢复文档库,必须同时保存数据库和原始文档。

下面采用暂停服务后整体打包的方式,以保持 SQLite 数据库和文档文件的一致性。

执行前,等待上传和 OCR 任务完成,并暂停继续导入。备份期间网站会短暂不可用。

bash <<'BACKUP'
set -e
umask 077

cd /opt/paperless-ngx

mkdir -p /opt/backups

backup_file="/opt/backups/paperless-ngx-$(date +%Y%m%d-%H%M%S).tar.gz"

trap 'docker compose start' EXIT

docker compose stop

tar -czf "$backup_file" -C /opt paperless-ngx

tar -tzf "$backup_file" >/dev/null

printf "备份文件:%s\n" "$backup_file"
BACKUP

docker compose ps

命令会将备份保存到:

/opt/backups/
文档库备份与服务恢复

完成后,检查终端没有报错、服务已经恢复,再通过浏览器打开文档进行确认。

备份包包含账户数据、应用密钥和文档,应该保存在受控的位置,并另外保存一份到其他设备或备份存储中。

8.2 在新服务器恢复

恢复演练建议使用全新的空白服务器,先按照第 5.1 节安装 Docker。

将备份上传到新服务器,并命名为:

/root/paperless-backup.tar.gz

确认新服务器上的 /opt/paperless-ngx 目录不存在,再执行:

mkdir -p /opt

tar -xzf /root/paperless-backup.tar.gz -C /opt

cd /opt/paperless-ngx

docker compose config -q

docker compose up -d

docker compose ps

保留备份中的域名和密钥,将域名 A 记录指向新服务器,并确认 80、443 端口可以访问。

恢复后至少检查:

  • 原有账户可以登录。
  • 文档数量和标签正确。
  • 正文搜索能够找到文件。
  • 原始文件可以下载并打开。

本次恢复建议使用相同 CPU 架构和相同应用版本。不要直接将备份覆盖到正在使用的另一套文档库。

9. 日常维护和常见问题

9.1 如何更新 Paperless-ngx?

先完成备份,再阅读目标版本的更新说明。

编辑配置:

cd /opt/paperless-ngx

nano compose.yaml

将 Paperless-ngx 镜像标签从 3.4.2 修改为准备升级的明确版本,再执行:

docker compose config -q

docker compose pull webserver

docker compose up -d

docker compose ps

由于本文固定了版本,仅执行 pull 而没有修改版本号,不会自动切换到其他版本。

更新后重新检查登录、上传、搜索和下载功能。

9.2 HTTPS 页面打不开怎么办?

先检查:

  • 域名 A 记录是否指向当前服务器。
  • 是否存在错误的 AAAA 记录。
  • 安全组和已启用的主机防火墙是否允许 80、443。
  • 这两个端口是否被已有网站服务占用。

查看 Caddy 日志:

cd /opt/paperless-ngx

docker compose logs --tail=100 caddy

如果出现 502,再检查应用日志:

docker compose logs --tail=100 webserver

首次启动尚未完成、语言包安装失败或应用持续重启,都可能导致页面暂时不可用。

9.3 中文识别不正常怎么办?

先重新确认语言包:

docker compose exec webserver tesseract --list-langs

再检查管理界面中的 OCR 设置。界面内保存的设置可能覆盖环境变量,因此需要确认实际识别语言仍包含 chi_sim。

测试时优先使用清晰、摆正、没有密码保护的扫描件。

9.4 忘记管理员密码怎么办?

在服务器终端执行:

cd /opt/paperless-ngx

docker compose exec webserver \
  python3 /usr/src/paperless/src/manage.py changepassword admin

根据提示输入新密码即可。

修改 .env 中的初始密码,不会改变已经存在的管理员账户密码。

9.5 可以直接上传 Word 或 Excel 吗?

本文配置没有包含 Office 文档转换组件。

本次先使用 PDF、JPG、PNG 完成归档。需要处理 Word、Excel 等文件时,可以先导出 PDF,或者按照官方文档增加相应转换服务。

10. 总结

通过以上步骤,就可以搭建一个支持域名 HTTPS、中文 OCR、正文搜索和标签分类的 Paperless-ngx 私人文档库。

它适合整理合同扫描件、票据、说明书和日常资料。文件导入后,先检查识别内容,再按用途添加标签,后续查找时就可以直接搜索正文关键词。

建议先从少量资料开始,确认上传、识别、搜索和备份流程都正常,再逐步导入自己的文档。同时定期备份数据库、原始文件和应用配置,并安排恢复验证,让整理好的资料能够长期使用。

赞(0)
未经允许不得转载:莱卡云 » Docker搭建Paperless-ngx文档库