Paperless-ngx 项目部署

一、功能概览

二、部署架构

典型的 Docker Compose 部署包含以下服务：

默认也可使用内置 SQLite，仅适合试用或极小规模，正式使用建议 PostgreSQL。

三、环境要求

• Linux 服务器、NAS 或家用主机，Docker Engine 与 Docker Compose 插件
• 内存：2GB 起步，建议 4GB 以上（OCR 与并发任务占用较多资源）
• 磁盘：为文档库预留充足空间，扫描件和 PDF 会占用不少容量
• CPU：OCR 是 CPU 密集型任务，核心数越多处理越快
• 默认端口：8000

四、Docker Compose 部署

4.1 创建目录

提前创建 consume 与 export 目录，避免 Docker 自动创建出 root 所属的目录而产生权限问题：

mkdir -p ~/paperless-ngx/{consume,export}
cd ~/paperless-ngx

4.2 获取当前用户 ID

id -u
id -g

记下输出，下面填入 USERMAP_UID 与 USERMAP_GID，使容器内用户与宿主机用户一致，避免 consume 目录权限问题。

4.3 生成密钥

openssl rand -base64 64 | tr -d '\n'

把输出作为 PAPERLESS_SECRET_KEY。密钥用于加密签名，请保密，并且部署后不要随意更换。

4.4 编写 docker-compose.yml

下面是基础版（Paperless + PostgreSQL + Redis），可直接作为起点：

services:
  broker:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: 请替换为强密码

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: 与上面数据库密码一致
      PAPERLESS_SECRET_KEY: 填入上一步生成的密钥
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng
      PAPERLESS_OCR_LANGUAGES: chi-sim
      USERMAP_UID: 1000
      USERMAP_GID: 1000

volumes:
  data:
  media:
  pgdata:
  redisdata:

要点说明：

• PAPERLESS_OCR_LANGUAGE 是识别时使用的语言，格式为 Tesseract 语言代码，用加号连接，简体中文是 chi_sim，英文是 eng。
• PAPERLESS_OCR_LANGUAGES 用于在容器启动时额外安装语言包，格式为带连字符的包名后缀，简体中文是 chi-sim。两者不要混淆。
• 配置文件里的 redis 地址是容器之间互相通信用的内部连接串，不是对外链接。
• 具体的镜像版本与官方示例可能随版本更新，建议对照官方仓库 docker 目录下的 Compose 示例，并把镜像固定到具体版本号。
• 数据库密码、密钥等敏感信息也可以放入单独的 .env 文件，由 Compose 引用，并且不要提交到代码仓库。

4.5 启动

docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f webserver

首次启动需要一两分钟初始化数据库。

4.6 创建管理员

docker compose exec webserver createsuperuser

按提示输入用户名、邮箱和密码。也可以通过环境变量 PAPERLESS_ADMIN_USER 与 PAPERLESS_ADMIN_PASSWORD 在首次启动时自动创建，但密码留在配置中有泄露风险，创建完成后建议移除。

之后用浏览器访问「服务器IP地址:8000」登录。

五、使用公网域名时的关键配置

使用域名并通过反向代理提供 HTTPS 时，务必在环境变量中补充：

      PAPERLESS_URL: https://你的域名

说明：

• PAPERLESS_URL 必须是用户实际访问的完整地址（含 https）。若 HTTPS 访问而此项设置成 HTTP，分享链接和密码重置流程会出错。
• 该变量同时影响跨站请求校验，遇到登录后提示 CSRF 相关错误，优先检查它，必要时补充 PAPERLESS_CSRF_TRUSTED_ORIGINS 与 PAPERLESS_ALLOWED_HOSTS。

反向代理示例（Caddy）

你的域名 {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8000
}

若使用 Nginx，请注意：

• 需要开启 WebSocket 支持（用于状态实时推送）。
• 将 client_max_body_size 调大，否则大文件上传会失败。
• 设置较长的读写超时。

安全建议：端口映射改为只监听本机（127.0.0.1:8000:8000），再由反向代理对外提供 443，避免直接暴露 8000 端口。

六、文档入库方式

6.1 consume 文件夹

把文件放进 consume 目录，Paperless 会自动检测并处理。适合配合扫描仪的「扫描到文件夹」功能使用。

• 默认会递归处理子目录，可通过环境变量控制行为，并可让子目录名自动成为标签。
• 若 consume 目录位于网络共享（NFS、SMB）上，文件系统事件可能不触发，需要启用轮询模式并设置轮询间隔（PAPERLESS_CONSUMER_POLLING）。
• 处理完成后原文件会被移除，请把「放入 consume」当作移交，原件另行保留。

6.2 网页上传

登录后直接拖拽文件到网页。

6.3 邮件入库

在「邮件」设置中添加邮箱账户与规则，Paperless 会定期收取并把附件（或邮件本身）转为文档。处理邮件正文需要启用 gotenberg 与 tika 服务。

6.4 手机端

官方不提供独立手机应用，可使用第三方社区应用，通过接口上传拍照文档，或使用扫描类应用把文件存到 consume 目录。

6.5 可选：启用 Office 与邮件解析

在 Compose 中增加 gotenberg 与 tika 服务，并在 webserver 中启用：

      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998

上面两个地址是容器间的内部服务连接配置，对应的 gotenberg、tika 服务镜像与启动参数请对照官方示例补全。

七、整理与自动化建议

1. 规划分类体系：先想好标签、通信方、文档类型和存储路径，不要一开始就建太多。
2. 善用自动匹配：给标签或通信方设置匹配规则，选择自动匹配时，系统会根据已有文档训练分类模型。
3. 自动分类需要样本：通常每类需要一定数量的已分类文档，模型才会可靠，初期请手动校正。
4. 使用工作流：例如「来自某邮箱的文件自动加上某标签」「文件名包含某关键词自动设置类型」。
5. ASN 编号：给纸质原件贴上归档序号（ASN），入库时通过条形码识别，便于按编号找到实体文件。
6. 保留实体件：重要的法律文件和证件，数字化后仍应保留原件。

八、备份与恢复

8.1 推荐方式：官方导出工具

docker compose exec -T webserver document_exporter ../export

导出内容包括原始文档、存档版本，以及记录元数据的清单文件。导出目录再用 tar 打包并同步到异地：

tar -czf paperless-export-$(date +%Y%m%d).tar.gz ./export

建议用 cron 每天自动执行。

8.2 完整备份

停止容器后，备份 data、media 两个卷、数据库卷以及 Compose 与环境配置文件，同样要同步到异地。

8.3 恢复

在新环境部署相同版本的 Paperless-ngx，把导出目录放到 export，然后执行：

docker compose exec webserver document_importer ../export

注意：

• 导入需要在尽量干净的实例上进行，并使用与导出时相同的版本。
• 遵循 3-2-1 原则：3 份副本、2 种介质、1 份异地。
• 备份中含有你的全部文档，请加密保存。
• 定期做恢复演练。

九、升级与维护

cd ~/paperless-ngx
docker compose pull
docker compose up -d
docker image prune

建议：

• 升级前先导出一份备份，并阅读版本发布说明，重点关注破坏性变更。
• 固定镜像版本号，按需升级，不要让 latest 在无意中自动升级。
• 数据库大版本（如 PostgreSQL 升级主版本）需要单独规划数据迁移，不能只改镜像标签。
• 修改 OCR 语言或相关设置后，旧文档不会自动重新识别，必要时手动触发重新处理。

十、性能调优

十一、常见问题排查

十二、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart webserver

# 日志
docker compose logs -f webserver

# 创建管理员
docker compose exec webserver createsuperuser

# 导出 / 导入
docker compose exec -T webserver document_exporter ../export
docker compose exec webserver document_importer ../export

# 升级
docker compose pull && docker compose up -d

# 查看已安装的 OCR 语言
docker compose exec webserver tesseract --list-langs