Docker 玩法

飞牛NAS部署 Paperless-ngx：文档管理系统

2026-07-30 2 admin

前言

在日常工作和生活中，我们常常被堆积如山的纸质文件、PDF合同、扫描件所困扰。如何高效地管理这些文档，让它们变得可搜索、可分类？Paperless-ngx 正是为此而生的开源文档管理系统。它能自动对文档进行 OCR 识别、分类、标记，让你彻底告别“找文件找到崩溃”的窘境。

本文将带领你在飞牛NAS（fnOS）上，通过 Docker Compose 的方式，完整部署 Paperless-ngx，并配置好常用的消费目录、数据库和反向代理，助你快速搭建一个属于自己的“无纸化”文档中心。

准备工作

在开始部署前，请确保你的飞牛NAS满足以下条件：

  • 已安装并正常运行的 Docker 和 Docker Compose（fnOS 应用中心可直接安装 Docker 套件）。
  • 预留至少 2GB 内存和 10GB 以上磁盘空间（建议 SSD 存放文档，HDD 存放归档数据）。
  • 已开启 SSH 访问，或者可以使用飞牛NAS的“文件管理”直接创建文件夹和文件。
  • 有一个稳定的网络环境，用于拉取镜像（建议配置国内镜像加速）。

第一步：创建项目目录与配置文件

首先，在飞牛NAS的文件管理器中，创建一个专用目录来存放 Paperless-ngx 的数据。假设我们将其放在 /vol1/1000/docker/paperless（请根据你的实际存储卷路径调整）。

在该目录下，创建以下子文件夹：

paperless/
├── data          # 存放应用数据（数据库、索引等）
├── media         # 存放原始文档与缩略图
├── export        # 导出文件存储目录
├── consume       # 消费目录（放入此文件夹的文件会被自动处理）
└── docker-compose.yml

你可以直接在文件管理器里新建这些文件夹，或者通过 SSH 执行：

mkdir -p /vol1/1000/docker/paperless/{data,media,export,consume}

第二步：编写 docker-compose.yml

进入 paperless 目录，创建并编辑 docker-compose.yml 文件。推荐使用飞牛NAS自带的文本编辑器，或者使用 SSH + vim/nano。

以下是一个经过精简但功能完整的配置示例：

version: '3.8'

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

  db:
    image: postgres:14-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_secure_password  # 请修改为强密码
    volumes:
      - ./data/db:/var/lib/postgresql/data

  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_DBUSER: paperless
      PAPERLESS_DBPASS: your_secure_password
      PAPERLESS_DBNAME: paperless
      PAPERLESS_TIME_ZONE: Asia/Shanghai
      PAPERLESS_OCR_LANGUAGE: chi_sim+eng  # 简体中文+英文OCR支持
      PAPERLESS_SECRET_KEY: a_very_long_random_string_here  # 至少50位随机字符
      PAPERLESS_URL: http://你的NAS_IP:8000  # 按实际修改
      USERMAP_UID: 1000
      USERMAP_GID: 1000

请务必修改以下敏感信息：

  • POSTGRES_PASSWORD 和 PAPERLESS_DBPASS：统一使用一个强密码。
  • PAPERLESS_SECRET_KEY：生成一个足够长的随机字符串，可以使用 openssl rand -base64 48 生成。
  • PAPERLESS_URL：填写你的飞牛NAS内网IP和端口，例如 http://192.168.1.100:8000。

第三步：启动服务

保存好 docker-compose.yml 后，打开终端或 SSH 连接到飞牛NAS，切换到 paperless 目录，执行以下命令：

cd /vol1/1000/docker/paperless
docker-compose up -d

首次启动会拉取三个镜像：Redis、PostgreSQL 和 Paperless-ngx 本体，根据网络情况可能需要几分钟到十几分钟。拉取完成后，容器会自动启动。

你可以使用 docker-compose logs -f 查看启动日志，确认没有错误信息。当看到类似 Starting Paperless-ngx 和 Listening on: http://0.0.0.0:8000 的输出时，说明启动成功。

第四步：创建管理员账户

服务启动后，需要创建一个管理员账户来登录 Web 界面。执行以下命令：

docker-compose exec webserver manage createsuperuser

按照提示输入用户名（例如 admin）、邮箱（可选）和密码。记住这个账户，后续所有管理操作都需要它。

第五步：访问与基本设置

打开浏览器，访问 http://你的飞牛NAS_IP:8000，使用刚创建的管理员账户登录。

首次登录后，建议立即进行以下设置：

  1. 进入“设置” -> “文档处理”，将“OCR 语言”设为 chi_sim+eng（如果之前环境变量已配置，则无需重复设置）。
  2. 进入“设置” -> “消费”，将“消费目录”指向容器内的 /usr/src/paperless/consume（即我们映射的本地 consume 文件夹）。
  3. 你可以在这里配置自动分类规则（基于文件名、发件人、标签等），初学者可以先跳过，后期再优化。

第六步：测试文档消费

Paperless-ngx 最核心的功能是“消费目录”：你只需要将 PDF、图片等文件放入飞牛NAS的 consume 文件夹，系统就会自动 OCR、分类并入库。

你可以复制一个 PDF 文件到 /vol1/1000/docker/paperless/consume 目录下，稍等片刻（视文件大小和NAS性能，约10-60秒），刷新 Web 界面，应该就能看到新文档出现在“文档”列表中了。

如果文档标题是乱码或未正确识别，请检查 OCR 语言设置是否正确，以及 PDF 是否包含可识别的文字层。

进阶优化：配置 Nginx 反向代理（可选）

如果你希望通过标准端口（如 80 或 443）访问，或需要配置 SSL 证书，可以在飞牛NAS上使用 Nginx 进行反向代理。这里提供一个简单的 nginx 配置片段，供你参考（假设你的飞牛NAS已经安装了 Nginx）：

server {
    listen 80;
    server_name paperless.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
    }
}

如果你不需要外网访问，直接使用 IP:8000 即可，无需配置反向代理。

总结

通过以上步骤，你已经在飞牛NAS上成功部署了 Paperless-ngx 文档管理系统。现在，你可以将散落在各个角落的 PDF、扫描件、电子发票等文件统一丢入消费目录，享受自动分类、全文搜索带来的便利。Paperless-ngx 还支持标签、文档类型、对应方等高级分类功能，以及 REST API 和移动端适配，非常适合个人或小团队构建无纸化工作流。趁着周末，试试把家里的纸质文档都数字化吧！