Как установить и настроить Paperless-ngx на VPS: руководство по self-hosted документообороту

1. Что мы настраиваем и зачем: философия Paperless-ngx

В 2026 году проблема накопления бумажных документов — чеков, договоров, медицинских выписок, инструкций и счетов — остается актуальной. Обычное сканирование в папку на компьютере не решает задачу: найти нужный документ среди сотен файлов "SCAN_001.pdf" практически невозможно. Именно здесь на сцену выходит Paperless-ngx.

Paperless-ngx — это форк популярного проекта Paperless-ng, который, в свою очередь, вырос из оригинального Paperless. Это веб-приложение, которое индексирует ваши сканы. Основная магия происходит в процессе OCR (Optical Character Recognition): система "читает" текст на изображении или в PDF-файле, сохраняет его в базу данных и позволяет мгновенно находить документы по ключевым словам.

Почему стоит выбрать self-hosted решение на собственном VPS вместо облачных сервисов вроде Google Drive или специализированных платных DMS?

• Конфиденциальность: Ваши финансовые документы и персональные данные хранятся на вашем сервере, а не на серверах корпораций, которые могут анализировать их для рекламы.
• Отсутствие лимитов: Вы ограничены только объемом диска вашего VPS. Нет ограничений на количество документов или пользователей.
• Автоматизация: Вы можете настроить "горячую папку" (consumption folder). Как только файл попадает туда (через FTP, SMB или мобильное приложение), Paperless-ngx автоматически его обрабатывает, распознает, присваивает теги и отправляет в архив.
• Интеллектуальное тегирование: Система использует машинное обучение для автоматического определения корреспондента (отправителя) и типа документа на основе накопленного опыта.

2. Какой VPS-конфиг нужен под эту задачу

Paperless-ngx — довольно требовательное к ресурсам приложение, особенно в моменты обработки новых документов. Процесс OCR (распознавание текста) активно нагружает процессор, а база данных и поисковый движок требуют оперативной памяти.

Минимальные и рекомендуемые характеристики сервера приведены в таблице ниже:

Важно учитывать, что при нехватке оперативной памяти процесс OCR может аварийно завершаться, оставляя документы необработанными. Если вы планируете загружать сразу тысячи страниц архива, ориентируйтесь на более мощные конфигурации.

Для стабильной работы и быстрой обработки документов мы рекомендуем рассмотреть VPS с указанными характеристиками. Наличие NVMe дисков значительно ускорит индексацию и поиск по базе данных.

Локация сервера: Поскольку вы будете загружать личные документы, выбирайте локацию с минимальным пингом до вас и в юрисдикции, которой вы доверяете. Для пользователей из Европы оптимальны дата-центры в Германии или Нидерландах.

3. Подготовка сервера: безопасность и зависимости

Прежде чем устанавливать само приложение, необходимо подготовить среду. Безопасность критически важна, так как DMS будет содержать ваши самые чувствительные данные.

Обновим список пакетов и установленное ПО:

sudo apt update && sudo apt upgrade -y

Установим базовый набор утилит, которые понадобятся нам в процессе работы:

sudo apt install -y curl wget git vim software-properties-common ufw fail2ban

Настроим базовый межсетевой экран (Firewall). Нам нужно открыть порты для SSH, HTTP и HTTPS:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Рекомендуется также создать отдельного пользователя с правами sudo, чтобы не выполнять все действия от имени root:

# Создание пользователя (замените 'adminuser' на свое имя)
sudo adduser adminuser
sudo usermod -aG sudo adminuser
# Переключение на нового пользователя
su - adminuser

4. Установка Docker и Docker Compose

Paperless-ngx состоит из нескольких компонентов (веб-сервер, база данных, брокер сообщений, OCR-движок). Самый надежный и простой способ запустить всё это — использовать Docker Compose. В 2026 году Docker является стандартом де-факто для self-hosted решений.

Установим Docker из официального репозитория:

# Добавляем GPG-ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Устанавливаем пакеты
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Добавим нашего пользователя в группу docker, чтобы не вводить sudo каждый раз:

sudo usermod -aG docker $USER
# Примените изменения группы (или перезайдите по SSH)
newgrp docker

Проверим работоспособность:

docker compose version

5. Установка Paperless-ngx: пошаговое развертывание

Разработчики Paperless-ngx предоставляют удобный скрипт для установки, но мы разберем "ручной" метод через Docker Compose, так как он дает больше контроля над конфигурацией и путями хранения данных.

Создадим директорию для проекта:

mkdir ~/paperless-ngx && cd ~/paperless-ngx

Для работы нам понадобятся три файла: docker-compose.yml, docker-compose.env и пустые папки для данных.

Создадим структуру папок:

mkdir -p {data,media,export,consume,db}

Теперь создадим файл конфигурации окружения docker-compose.env. Это "сердце" настроек вашего сервера. Обязательно измените значения паролей и секретного ключа!

# Секретный ключ (сгенерируйте длинную случайную строку)
PAPERLESS_SECRET_KEY=change-this-to-something-very-long-and-random

# Настройки базы данных
PAPERLESS_DBENGINE=postgresql
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_strong_password_here

# Настройки Redis
PAPERLESS_REDIS=redis://broker:6379

# Языки OCR (добавьте нужные, например rus, eng, deu)
PAPERLESS_OCR_LANGUAGE=rus+eng

# Часовой пояс
PAPERLESS_TIME_ZONE=Europe/Moscow

# Настройки URL (укажите ваш домен позже)
PAPERLESS_URL=https://paperless.yourdomain.com

Теперь создадим основной файл docker-compose.yml. Мы будем использовать актуальные версии образов на 2026 год:

services:
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - ./redisdata:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./db:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: your_strong_password_here

  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
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db

Запускаем контейнеры в фоновом режиме:

docker compose up -d

После запуска необходимо создать первого суперпользователя (админа):

docker compose exec webserver python3 manage.py createsuperuser

Следуйте инструкциям в терминале, чтобы задать логин, почту и пароль.

6. Глубокая конфигурация: OCR, языки и почта

Одной из самых мощных функций Paperless-ngx является возможность автоматического сбора документов из электронной почты. Например, вы можете настроить систему так, чтобы она проверяла ваш ящик и автоматически скачивала счета от провайдеров.

Добавьте следующие параметры в ваш docker-compose.env для настройки почтового агрегатора:

# Включение обработки почты
PAPERLESS_EMAIL_SECRET=your_email_password_or_app_token
# Частота проверки (в минутах)
PAPERLESS_EMAIL_TASK_INTERVAL=10

Настройка OCR (Tesseract):

Paperless-ngx использует Tesseract для распознавания текста. Вы можете настроить режим работы OCR через переменную PAPERLESS_OCR_MODE:

• clean: Создает PDF с текстовым слоем, очищая оригинал (по умолчанию).
• redo: Принудительно запускает OCR, даже если в PDF уже есть текстовый слой.
• skip: Пропускает OCR, если текст уже обнаружен.

Если у вас слабый процессор на VPS, можно ограничить количество потоков для OCR, чтобы сервер не "зависал" при загрузке больших файлов:

# Ограничение до 2 параллельных процессов OCR
PAPERLESS_OCR_THREADS=2

Обработка документов Office:

По умолчанию Paperless-ngx хорошо работает с PDF и изображениями. Чтобы он понимал .docx, .xlsx и .pptx, нужно добавить сервис Gotenberg и Tika. Это расширит возможности системы до полноценного офисного комбайна.

7. Настройка веб-сервера и HTTPS (SSL)

Запускать Paperless-ngx на порту 8000 через незашифрованный HTTP — небезопасно. Нам нужен Reverse Proxy, который обеспечит поддержку HTTPS через Let's Encrypt.

Мы будем использовать Caddy, так как он автоматически получает и продлевает SSL-сертификаты, требуя минимум настроек.

Установим Caddy на VPS:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1G 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Отредактируем файл конфигурации Caddy (/etc/caddy/Caddyfile):

paperless.yourdomain.com {
    reverse_proxy localhost:8000
    
    header {
        # Настройки безопасности
        Strict-Transport-Security "max-age=31536000;"
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Referrer-Policy no-referrer-when-downgrade
    }
}

Перезапустите Caddy, чтобы применить изменения:

sudo systemctl restart caddy

Теперь ваш Paperless-ngx доступен по адресу https://paperless.yourdomain.com с валидным SSL-сертификатом.

8. Бэкапы и обслуживание: сохраняем данные навсегда

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

Метод 1: Экспорт встроенной утилитой

Paperless-ngx имеет встроенную команду экспорта, которая выгружает всё в папку /export:

docker compose exec webserver document_exporter ../export/

Метод 2: Скрипт автоматического бэкапа

Создадим простой bash-скрипт backup.sh, который будет архивировать данные и отправлять их в удаленное хранилище (например, S3 или другой сервер через rsync):

#!/bin/bash
BACKUP_DIR="/home/adminuser/backups"
DATE=$(date +%Y-%m-%d)
PROJECT_DIR="/home/adminuser/paperless-ngx"

mkdir -p $BACKUP_DIR

# 1. Дамп базы данных PostgreSQL
docker compose exec -t db pg_dumpall -c -U paperless > $BACKUP_DIR/db_backup_$DATE.sql

# 2. Архивация медиа-файлов и конфигов
tar -czf $BACKUP_DIR/paperless_files_$DATE.tar.gz -C $PROJECT_DIR data media docker-compose.yml docker-compose.env

# 3. Удаление старых бэкапов (старше 30 дней)
find $BACKUP_DIR -type f -mtime +30 -delete

Добавьте выполнение скрипта в crontab (crontab -e), чтобы он запускался каждую ночь в 03:00:

0 3   * /bin/bash /home/adminuser/paperless-ngx/backup.sh

9. Troubleshooting + FAQ

Почему процесс OCR занимает так много времени?

Распознавание текста — ресурсоемкая задача. На 2-ядерном VPS одна страница может обрабатываться от 5 до 20 секунд. Если вы загрузили сразу 100 документов, система поставит их в очередь. Проверить состояние очереди можно в веб-интерфейсе в разделе "Settings" -> "Worker Status". Для ускорения процесса увеличьте количество ядер CPU.

Ошибка "Out of Memory" при обработке больших PDF

Это происходит, когда Tesseract пытается обработать многостраничный документ высокого разрешения. Решение: добавьте Swap-файл на ваш VPS (минимум 2-4 ГБ). Это позволит системе использовать диск как временную оперативную память.

Как обновить Paperless-ngx до последней версии?

Благодаря Docker обновление проходит бесшовно:

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

Docker автоматически скачает новые образы и перезапустит контейнеры, сохранив все ваши данные.

Какой VPS-конфиг минимально подойдёт?

Минимально работоспособный вариант — 2 ГБ RAM и 2 vCPU, но вам обязательно потребуется настроить Swap-файл, иначе веб-интерфейс будет "падать" во время загрузки документов. Для комфортной работы без задержек мы рекомендуем 4-8 ГБ RAM.

Что выбрать — VPS или dedicated для этой задачи?

Для личного архива (до 10 000 документов) VPS более чем достаточно. Dedicated сервер стоит рассматривать только в том случае, если вы внедряете Paperless-ngx в крупной компании с десятками сотрудников, которые ежедневно сканируют сотни страниц, или если вам требуется экстремально высокий уровень дисковой производительности для мгновенного поиска по миллионам слов.

Как сканировать документы прямо в Paperless?

Самый удобный способ — мобильные приложения (например, Paperless Mobile для iOS/Android). Они позволяют сфотографировать документ, обрезать его и отправить по API в ваш Paperless-ngx. Также многие современные сканеры поддерживают функцию "Scan to FTP" — настройте сканер на отправку файлов в папку consume на вашем сервере.

10. Выводы и следующие шаги

Мы успешно развернули профессиональную систему управления документами на собственном сервере. Теперь у вас есть безопасное, быстрое и полностью контролируемое хранилище для всех ваших бумаг.

Что делать дальше для улучшения системы?

• Настройте иерархию тегов: Разделите документы по категориям: "Финансы", "Здоровье", "Работа", "Авто".
• Подключите IMAP: Настройте автоматический забор писем из вашего почтового ящика, чтобы счета за интернет или электричество попадали в архив сами.
• Организуйте оффлайн-копию: Настройте синхронизацию папки export с вашим домашним ПК или NAS через Syncthing, чтобы иметь доступ к документам даже при отсутствии интернета.

Переход на безбумажный офис — это не только экологично, но и невероятно удобно. Больше никаких папок-регистраторов и потерянных гарантийных талонов — всё, что вам нужно, теперь находится на расстоянии одного поискового запроса.