Как установить и настроить Paperless-ngx на VPS

MAATRIX

Если дома или в офисе скопились папки со сканами договоров, чеков и справок, а найти нужный документ по слову из текста невозможно — самое время автоматизировать архив. Paperless-ngx превращает поток бумаги в поисковую базу: сканы сами распознаются через OCR, получают теги и корреспондентов, а найти документ можно за секунды по любому слову внутри него. Разворачивать его лучше не дома на роутере, а на отдельном VPS — так система работает стабильно, доступна из любой точки и не зависит от домашнего интернета.

Что такое Paperless-ngx и зачем архивировать документы на VPS

Paperless-ngx — форк оригинального проекта paperless-ng, активно развивается сообществом с 2021 года. Это связка из веб-интерфейса, очереди обработки на Celery, полнотекстового поиска и движка OCR (по умолчанию — Tesseract через обёртку ocrmypdf). Логика простая: вы кладёте скан или фото документа в папку «consume» (или отправляете по почте, через сканер с поддержкой FTP/SMB, или мобильным приложением), система распознаёт текст, определяет дату, пытается угадать корреспондента и тип документа по заранее заданным правилам, а затем сохраняет оригинал и архивную PDF-версию с текстовым слоем.

Домашний NAS для этой задачи подходит плохо: OCR — процесс, прожорливый по CPU, а сам архив документов (паспорта, договоры, счета) — это данные, которые не хочется терять при поломке диска в квартире. VPS с NVMe-диском, регулярным снапшотом и доступом по HTTPS из любой точки решает обе проблемы: обработка идёт быстрее, а данные защищены бэкапами вне дома. Если вы уже разворачивали на сервере другие self-hosted сервисы через Docker Compose для продакшена, Paperless-ngx впишется в ту же схему без сюрпризов.

Требования к серверу и подготовка

Для домашнего архива на 5-10 тысяч документов хватает скромной конфигурации:

Диск — самое важное: сырые сканы и архивные PDF с текстовым слоем занимают место быстрее, чем кажется. Реальный расход зависит от разрешения сканера и количества страниц — заложите запас с учётом роста архива на пару лет вперёд, а не только под текущий объём.

Перед установкой сервер должен быть подготовлен: обновлённая система, непривилегированный пользователь с sudo, вход по SSH-ключу. Если это чистый сервер, пройдите базовую настройку — доступ по ключу вместо пароля описан в статье SSH-ключи вместо пароля на VPS, а затем поставьте сам Docker:

sudo apt update && sudo apt upgrade -y
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker
docker --version && docker compose version

Установка Paperless-ngx через Docker Compose

Официальный проект поставляется как готовый docker-compose.yml с тремя обязательными сервисами: сам паперлесс, Redis (очередь задач) и база данных. По умолчанию можно использовать встроенный SQLite, но для продакшена и стабильности при параллельной обработке лучше сразу поднять PostgreSQL — тем более, если на сервере уже есть PostgreSQL под другие проекты, логично переиспользовать подход.

Создайте рабочую директорию и скачайте файлы окружения:

mkdir -p ~/paperless && cd ~/paperless
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml
mv docker-compose.postgres.yml docker-compose.yml
curl -O https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/.env

В .env задайте таймзону и пароль базы:

PAPERLESS_TIME_ZONE=Europe/Moscow
POSTGRES_PASSWORD=замените-на-длинный-случайный-пароль

В docker-compose.yml стоит явно закрепить версию образа вместо latest — так вы не получите неожиданный breaking change при пересборке контейнера через полгода:

services:
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.14
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env

Обратите внимание: порт 8000 привязан только к 127.0.0.1 — наружу сервис отдаётся через reverse proxy, напрямую в интернет контейнер не смотрит. Конкретную версию образа сверьте на странице релизов проекта на момент установки — на конец августа 2026 актуальна ветка 2.x, но точный номер минорной версии может измениться.

Запускаете стек и создаёте суперпользователя:

docker compose up -d
docker compose exec webserver python3 manage.py createsuperuser

Через пару минут интерфейс будет доступен на http://127.0.0.1:8000 (пока только локально с сервера — снаружи подключим через nginx чуть позже).

OCR: языки распознавания и качество сканов

Из коробки Paperless-ngx распознаёт английский. Для русскоязычного архива нужно явно указать язык — иначе кириллица в тексте просто не появится в индексе поиска. В docker-compose.env (или .env, в зависимости от того, какой файл использует webserver) добавьте:

PAPERLESS_OCR_LANGUAGE=rus+eng
PAPERLESS_OCR_LANGUAGES=rus eng
PAPERLESS_OCR_MODE=skip

PAPERLESS_OCR_LANGUAGES подтягивает нужные языковые пакеты Tesseract при сборке образа, а PAPERLESS_OCR_LANGUAGE задаёт язык по умолчанию для распознавания. Режим skip означает: если в PDF уже есть текстовый слой (например, документ изначально в цифровом виде), OCR повторно не запускается — это экономит CPU. Для смешанного архива, где встречаются и сканы, и «нативные» PDF, это разумный дефолт; вариант redo пересобирает слой заново, но заметно медленнее.

Качество распознавания сильно зависит от исходника. Практические наблюдения:

• Сканы с разрешением ниже 200 dpi Tesseract читает плохо, особенно рукописный текст и мелкий кегль на чеках.
• Фото документов с телефона (кривые, с тенями) дают заметно больше ошибок распознавания, чем плоский скан — если есть возможность, сканируйте, а не фотографируйте.
• Многостраничные PDF обрабатываются дольше линейно от числа страниц — на слабом VPS большая пачка документов может выстроиться в очередь на 10-20 минут, это нормально, задачи Celery просто ждут своей очереди.

После изменения переменных окружения контейнер нужно пересоздать:

docker compose up -d --force-recreate webserver

Домен, HTTPS и reverse proxy

Открывать панель по IP и порту 8000 напрямую не стоит — документы внутри содержат персональные данные, и трафик обязан идти по HTTPS. Разверните nginx как reverse proxy перед контейнером — общий подход описан в статье nginx как reverse proxy на VPS, здесь — конфиг конкретно под Paperless-ngx:

server {
    listen 80;
    server_name docs.example.com;

    client_max_body_size 100M;

    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_read_timeout 300s;
    }
}

Два параметра здесь критичны и часто забываются: client_max_body_size — иначе загрузка многостраничного скана крупным файлом упадёт с 413 Request Entity Too Large, и proxy_read_timeout — распознавание больших документов через веб-загрузку может занимать больше стандартных 60 секунд таймаута nginx.

Сертификат выпускается стандартно через certbot — процесс подробно разобран в статье про Let's Encrypt SSL на VPS:

sudo certbot --nginx -d docs.example.com

После выпуска сертификата добавьте в .env контейнера домен в список доверенных хостов, иначе Django вернёт 400 Bad Request на запросы с внешнего домена:

PAPERLESS_URL=https://docs.example.com
PAPERLESS_ALLOWED_HOSTS=docs.example.com
PAPERLESS_CSRF_TRUSTED_ORIGINS=https://docs.example.com

Автоматизация: правила обработки, теги и бэкап

Ручная сортировка документов сводит на нет весь смысл автоматизации. В Paperless-ngx за это отвечают «Workflows» (или Consumption Templates в старых версиях) — правила вида «если в тексте документа встречается слово ИНН или название банка — назначить корреспондента и тег автоматически». Настраиваются через веб-интерфейс: Settings → Workflows, задаёте триггер (например, «при добавлении документа» или «по совпадению имени файла») и действия (присвоить тег, тип документа, корреспондента, переместить в папку хранения).

Практичная схема тегов для домашнего архива:

• по типу: договор, чек, счёт, справка, паспорт
• по статусу: требует-действия, в-архиве, просрочен
• по году — Paperless-ngx сам умеет извлекать дату из текста документа, но это стоит перепроверять на первых порах, дата в тексте не всегда совпадает с реальной датой выдачи

Для автоматической загрузки удобно настроить папку consume как точку входа с телефона или сканера — примонтируйте её через Samba или SFTP, чтобы можно было просто «скинуть» файл со смартфона без захода в веб-интерфейс. Второй канал приёма документов — почтовый ящик: в разделе Settings → E-Mail можно указать IMAP-аккаунт, куда падают счета от поставщиков, и Paperless-ngx будет сам вытаскивать вложения оттуда по расписанию.

База данных, документы и медиафайлы живут в Docker volumes — их обязательно нужно бэкапить отдельно от остального сервера, это единственная копия ваших документов. Общий подход к резервному копированию контейнерных данных разобран в статье бэкап Docker volume на VPS. Для самого Paperless-ngx есть встроенный экспортёр, который выгружает документы вместе с метаданными в читаемом виде — это удобнее, чем просто копировать volume, потому что позволяет восстановиться даже на другой версии системы:

docker compose exec webserver python3 manage.py document_exporter ../export --no-progress-bar

Добавьте это в cron раз в сутки, а саму папку export синхронизируйте на внешнее хранилище (S3-совместимое или другой сервер) через rclone или restic — держать единственную копию архива документов на том же диске, где крутится сервис, рискованно.

Частые вопросы