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 地址 |

如果没有配置可用的 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 官方软件仓库。更多安装说明可参考本站的 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

这份配置包含三个服务:
| 服务 | 用途 |
|---|---|
webserver | Paperless-ngx 应用,负责文档管理和处理 |
broker | Valkey,提供任务消息服务 |
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 语言包,所需时间与服务器性能、网络状况有关。

先确认三个服务持续运行,日志没有反复报错,再检查 OCR 语言:
docker compose exec webserver tesseract --list-langs
列表中应该包含:
chi_sim
eng
如果没有 chi_sim,先查看 webserver 日志,处理语言包下载或安装错误,再继续上传中文扫描件。

6. 登录文档管理页面
在浏览器打开自己的域名,例如:
https://docs.example.com

首次启动时,配置会自动创建管理员账户:
用户名: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。

建议将这份文档的显示标题设为“演示资料 01”。
随后,在文档列表的全文搜索或高级查询输入框中输入:
content:项目验收

也可以使用:
content:DEMODOC2026
content: 用于限定搜索文档正文。Paperless-ngx 支持这种按字段查询的搜索方式。
演示时,不要把“项目验收”写进文件名、标题或标签。这样才能明确验证搜索结果来自识别后的正文。
如果没有找到文件,依次检查:
- 上传和处理任务是否已经完成。
- 识别文本中是否确实包含检索词。
- 是否仍然启用了其他标签或类型筛选。
- 是否使用了文档全文查询,而不是只搜索文件名。
扫描清晰度、倾斜程度和字体都会影响识别结果。重要编号、金额和日期仍应人工核对。
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 私人文档库。
它适合整理合同扫描件、票据、说明书和日常资料。文件导入后,先检查识别内容,再按用途添加标签,后续查找时就可以直接搜索正文关键词。
建议先从少量资料开始,确认上传、识别、搜索和备份流程都正常,再逐步导入自己的文档。同时定期备份数据库、原始文件和应用配置,并安排恢复验证,让整理好的资料能够长期使用。







