扫描件越存越多怎么找？Docker 部署 Paperless-ngx，把合同、发票变成可搜索档案

前言

纸质文件数字化以后，问题其实并没有自动消失。

合同扫描成 PDF、发票拍成照片、银行账单保存到电脑，如果最后只是按照年份建立几个文件夹，几年以后依然会遇到同一个麻烦：记得内容，却忘了文件叫什么；知道某张发票存在，却不知道到底放在哪一级目录。

Paperless-ngx 解决的是文档进入电脑以后的下一步。文件上传或进入消费目录后，系统可以执行 OCR 提取文字，再结合标题、日期、标签、对应方和文档类型进行整理，最终让扫描件也能够通过正文关键词直接检索。

本文会通过 Docker 部署 Paperless-ngx，配置数据库、消息代理以及 Tika、Gotenberg 等组件，实际测试文档上传、OCR、分类和搜索。

本地服务确认正常以后，再使用 cpolar 为 Web 管理页面增加远程访问入口。

最终目标并不是彻底消灭纸张，而是把那些必须长期保存的合同、票据和资料，从“一个个文件”变成一套真正能够查询和维护的电子档案。

1.什么是Paperless-ngx？

Paperless-ngx是一个开源、免费、自托管的文档管理系统，旨在帮助个人和团队彻底告别纸质文件，实现纸质文档（如发票、合同、收据、信件等）的自动化扫描、识别、归档与检索。

核心功能

自动OCR（光学字符识别）

• 利用Tesseract等引擎，将扫描件或照片中的文字识别为可搜索的文本，即使原始文件是图片或 PDF 扫描件，也能全文检索。

智能分类与打标签

• 支持通过规则（如发件人、关键词、日期）自动为文档打标签、分配对应分类（如“账单”“合同”“身份证”），减少手动整理工作。

全文搜索

• 输入任意关键词（如“2024年电费”“张三合同”），即可秒级定位相关文档，无需翻找文件夹。

多格式支持

• 支持PDF、JPEG、PNG、TIFF等常见格式，可直接上传扫描件、手机拍照或通过“消费文件夹”（consume folder）自动导入。

安全自托管

• 所有数据存储在你自己的服务器上，不依赖第三方云服务，保障隐私与数据主权。

友好的Web界面

• 提供现代化、响应式的网页操作界面，支持多用户、权限管理、文档预览、注释等功能。

自动化工作流

• 可集成邮件接收、定时任务、API接口，甚至配合Gotenberg实现HTML/PDF转换，构建完整文档处理流水线。

技术架构（简要）

• 前端：基于 Angular 的 Web UI
• 后端：Python + Django
• 数据库：SQLite（默认）、PostgreSQL 或 MariaDB/MySQL
• OCR 引擎：Tesseract（内置），也可集成外部服务
• 可选组件：Redis（任务队列）、Apache Tika（文档内容提取）、Gotenberg（PDF 渲染）

它是原项目paperless的活跃社区分支（“ngx” = “next generation”），功能更丰富、更新更频繁、社区更活跃。

适用场景

• 个人：管理家庭账单、证件、医疗记录、学习资料
• 小微企业：归档合同、发票、客户资料、会议纪要
• 自由职业者：整理项目文档、报销凭证、税务材料
• 开源爱好者：搭建私有化、可定制的文档中枢

为什么选择Paperless-ngx？

• 完全免费 & 开源（MIT 许可证）
• 一次部署，长期使用，无订阅费用
• 高度可定制，支持插件与API扩展
• 活跃社区支持，GitHub上持续迭代（截至2024年，Star数超20k+）

官方资源

• GitHub 仓库：https://github.com/paperless-ngx/paperless-ngx
• 官方文档：https://docs.paperless-ngx.com/
• Docker 镜像：ghcr.io/paperless-ngx/paperless-ngx

Paperless-ngx = 你的私人智能档案馆 —— 把杂乱纸堆变成有序、可搜、安全的数字资产，真正实现“无纸化生活”。

2.前提条件

硬件要求（最低）

Docker和Docker Compose

必须已安装并正常运行：

# 检查 Docker
docker –version # ≥ 20.10

# 检查 Docker Compose
docker compose version # ≥ v2.5（或 docker-compose ≥ 1.29）

网络要求

• 主机需能访问互联网（首次拉取镜像）
• 若使用外部数据库/Redis，需确保网络互通
• 开放Web访问端口（如8000或自定义端口）

数据库

Paperless-ngx必须连接一个PostgreSQL数据库，可任选其一：

不支持SQLite或MySQL！仅支持PostgreSQL ≥ 12

消息队列

Paperless-ngx使用Redis作为任务队列和缓存：

3.在postgres创建用户

还没有postgres的小伙伴，可以参考这篇文章：谁说没公网IP不能远程连数据库？PostgreSQL+cpolar打通任督二脉

你需要 先创建paperless用户，然后再设置密码。

在PostgreSQL的psql命令行中（你已经以postgres身份登录了），执行以下命令：

— 1. 创建用户（角色）
CREATE USER paperless WITH LOGIN PASSWORD 'Sj***520!';

— 2. 创建数据库（如果还没建）
CREATE DATABASE paperless OWNER paperless;

— 3. （可选）授予权限
GRANT ALL PRIVILEGES ON DATABASE paperless TO paperless;

注意：CREATE USER = CREATE ROLE … LOGIN 密码必须和你docker-compose.yml中的PAPERLESS_DBPASS: Sj***520!完全一致（包括大小写、特殊字符）

能不能直接用postgres用户？

技术上可以，比如后续编写docker-compose.yml文件时：

但强烈不建议，原因：

4.安装Paperless-ngx

通过Docker部署Paperless-ngx：

在开始部署之前，确保你的系统已经安装了Docker。可以通过以下命令检查 Docker 是否已安装：

docker –version

首先创建一下安装的目录并进入到该目录：

mkdir -p /docker/paperless
chmod -R 777 /paperless

创建并编辑 docker-compose.yml文件：

vi docker-compose.yml

version: "3.6"
services:
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:2.19.6
restart: unless-stopped
ports:
– "9981:8000"
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://:my_redis_password@redis:6379
PAPERLESS_DBHOST: 192.168.42.140 # 数据库仍用外部
PAPERLESS_DBUSER: paperless # 输入刚建好的账号密码
PAPERLESS_DBPASS: Sjixin520!
PAPERLESS_DBNAME: paperless
PAPERLESS_TIKA_ENABLED: 1
PAPERLESS_TIKA_ENDPOINT: http://tika:9998
PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000

redis:
image: redis:7-alpine
restart: unless-stopped
command: redis-server –requirepass my_redis_password
# 如果需要持久化，可加 volume

tika:
image: apache/tika:latest
restart: unless-stopped

gotenberg:
image: gotenberg/gotenberg:8.19
restart: unless-stopped

启动容器：

docker-compose up -d

验证是否启动成功：

docker logs -f paperless-webserver-1

出现下图所示信息，即为成功！

部署完成后，在浏览器中输入 http://IP:9981 就能看到paperless的界面：

5.使用Paperless-ngx

下载完成后，注册用户：

登录成功！

设置为自己喜欢的布局：

上传文档：

上传成功后，点击打开文档，可以在这里修改并编辑文档：

创建新的联系人一起编辑文档：

可以在这里讲文档排序，显示，编辑等等：

Paperless-ngx是一款强大的开源文档管理系统，而通过与cpolar结合，用户可以轻松实现内网穿透，将本地部署的Paperless-ngx服务安全、稳定地暴露到公网，无需复杂的网络配置或固定IP。cpolar凭借其简单易用、高可靠性和多协议支持的优势，成为远程访问Paperless-ngx的理想桥梁，让用户随时随地通过浏览器高效管理文档，真正释放Paperless-ngx的全部潜能——这一切，都得益于cpolar强大的内网穿透能力。

6.安装cpolar实现随时随地开发

6.1 什么是cpolar？

cpolar是一款安全高效的内网穿透工具，无需公网IP或复杂配置，只需一条命令，即可将本地服务器、Web服务或任意端口映射到公网，让你随时随地远程访问内网应用，特别适合开发调试、远程运维和应急部署等场景。

6.2 部署cpolar

cpolar 可以将你本地电脑中的服务（如 SSH、Web、数据库）映射到公网。即使你在家里或外出时，也可以通过公网地址连接回本地运行的开发环境。

❤️以下是安装cpolar步骤：

使用一键脚本安装命令：

sudo curl https://get.cpolar.sh | sh

安装完成后，执行下方命令查看cpolar服务状态：（如图所示即为正常启动）

sudo systemctl status cpolar

Cpolar安装和成功启动服务后，在浏览器上输入虚拟机主机IP加9200端口即:【http://ip:9200】访问Cpolar管理界面，使用Cpolar官网注册的账号登录,登录后即可看到cpolar web 配置界面,接下来在web 界面配置即可：

打开浏览器访问本地9200端口，使用cpolar账户密码登录即可,登录后即可对隧道进行管理。

7.配置公网地址

登录cpolar web UI管理界面后,点击左侧仪表盘的隧道管理——创建隧道：

• 隧道名称：可自定义，本例使用了:paperless，注意不要与已有的隧道名称重复
• 协议：http
• 本地地址：9981
• 域名类型：随机域名
• 地区：选择China Top

创建成功后，打开左侧在线隧道列表,可以看到刚刚通过创建隧道生成了公网地址，接下来就可以在其他电脑或者移动端设备（异地)上，使用地址访问。

访问成功。

8.保留固定公网地址

使用cpolar为其配置二级子域名，该地址为固定地址，不会随机变化。

点击左侧的预留，选择保留二级子域名，地区选择china Top，然后设置一个二级子域名名称，我使用的是paperless，大家可以自定义。填写备注信息，点击保留。

登录cpolar web UI管理界面，点击左侧仪表盘的隧道管理——隧道列表，找到所要配置的隧道，点击右侧的编辑。

修改隧道信息，将保留成功的二级子域名配置到隧道中

• 域名类型：选择二级子域名
• Sub Domain：填写保留成功的二级子域名
• 地区: China Top

点击更新

更新完成后，打开在线隧道列表，此时可以看到随机的公网地址已经发生变化，地址名称也变成了保留和固定的二级子域名名称。

最后，我们使用固定的公网地址在任意设备的浏览器中访问，可以看到成功访问的页面，这样一个永久不会变化的二级子域名公网网址即设置好了。

总结

Paperless-ngx 真正改变的不是扫描方式，而是文档进入电脑以后怎么继续管理。

以前一张发票扫描成 PDF，工作基本就结束了；使用 Paperless-ngx 后，OCR 会让扫描件中的文字进入搜索体系，标签、对应方、文档类型和工作流则继续帮助整理这些内容。以后寻找一份资料时，不一定非要记住它存在哪个目录，只要还记得其中的一段文字、日期或者相关单位，就有机会直接检索出来。

通过 cpolar 增加远程访问以后，这套档案系统还可以从其他网络打开。但 Paperless-ngx 保存的往往不是普通媒体文件，而是合同、账单、证件和财务资料，因此公网访问时更应该认真处理账号、HTTPS和访问权限，不能把“生成了公网地址”等同于“部署已经安全完成”。

另外，数字化同样需要备份。文档媒体目录、Paperless 数据目录以及 PostgreSQL 或 MariaDB 数据库，都应该进入独立的备份计划。

至于现在 Paperless-ngx 新增的 LLM 功能，可以作为后续增强项，而不是这套系统成立的前提。即使完全不开启外部 AI，仅靠 OCR、全文索引、自动匹配和工作流，它已经能够解决大量纸质与扫描文档长期归档时最实际的问题。

扫描只是把纸变成文件，真正的文档管理，是让多年以后依然能够把这份文件找回来。

r.com/) 增加远程访问以后，这套档案系统还可以从其他网络打开。但 Paperless-ngx 保存的往往不是普通媒体文件，而是合同、账单、证件和财务资料，因此公网访问时更应该认真处理账号、HTTPS和访问权限，不能把“生成了公网地址”等同于“部署已经安全完成”。

另外，数字化同样需要备份。文档媒体目录、Paperless 数据目录以及 PostgreSQL 或 MariaDB 数据库，都应该进入独立的备份计划。

至于现在 Paperless-ngx 新增的 LLM 功能，可以作为后续增强项，而不是这套系统成立的前提。即使完全不开启外部 AI，仅靠 OCR、全文索引、自动匹配和工作流，它已经能够解决大量纸质与扫描文档长期归档时最实际的问题。

扫描只是把纸变成文件，真正的文档管理，是让多年以后依然能够把这份文件找回来。