Свой электронный архив документов и чеков на VDS: развертывание Paperless-ngx в Docker Compose с OCR-распознаванием на русском языке

У любого практикующего системного администратора, вебмастера или владельца IT-бизнеса со временем накапливаются сотни и тысячи рабочих документов: акты выполненных работ от заказчиков, закрывающие накладные, счета на оплату серверов и доменов, договоры аренды, гарантийные талоны и кассовые чеки на оборудование. Обычно эти файлы оседают в хаотичном виде: часть хранится во вложениях рабочей почты, часть в чатах Telegram, а бумажные чеки выцветают в коробках на полке.

Попытки структурировать документы в Google Drive, Яндекс Диске или Nextcloud быстро упираются в фундаментальный недостаток обычных файловых хранилищ: они не умеют осуществлять сквозной полнотекстовый поиск внутри отсканированных графических документов и PDF. Если файл назван сканером как SCAN_2026_09_29_001.pdf, найти в нем реквизиты контрагента или сумму платежа невозможно без ручного открытия каждого файла.

Решением этой проблемы является Paperless-ngx — ведущая open-source система управления электронными документами (EDMS), возглавляющая топы популярности в сообществах Reddit r/selfhosted и GitHub (свыше 25 000 звёзд). Она берет на себя автоматический захват входящих файлов, распознавание текста через движок Tesseract OCR, индексацию и организацию умного поиска с фильтрацией по тегам, датам и корреспондентам.

1. Проблема хаоса в документах: почему облака проигрывают self-hosted архиву

Коммерческие SaaS-решения для документооборота и корпоративные облака создают для IT-специалистов и малого бизнеса ряд существенных рисков:

• Проблемы с оплатой и привязкой к платформе: Зарубежные сервисы требуют регулярных платежей в валюте, блокируют учетные записи пользователей из РФ и в любой момент могут ограничить доступ к архиву.
• Конфиденциальность персональных и финансовых данных: Договоры с паспортными данными, финансовые балансы и выписки по расчетным счетам небезопасно доверять сторонним облачным платформам, где файлы анализируются алгоритмами машинного обучения.
• Отсутствие интеллектуальной категоризации: В стандартных облаках сортировка выполняется вручную по вложенным папкам. В Paperless-ngx встроен самообучающийся классификатор на базе алгоритмов машинного обучения: система анализирует текст документа и автоматически назначает нужного контрагента (корреспондента), тип документа (акт, чек, договор) и теги.

2. Архитектура Paperless-ngx: веб-сервер, воркеры Celery, Tesseract OCR, Valkey и PostgreSQL

Современный стек Paperless-ngx состоит из нескольких тесно интегрированных микросервисов, разворачиваемых в единой сети Docker Compose:

• Webserver (Django / Gunicorn): Обеспечивает работу современного отзывчивого веб-интерфейса, REST API для мобильных клиентов и аутентификацию пользователей.
• Consumer & Celery Workers: Фоновые воркеры, которые непрерывно сканируют каталог входящих файлов, распаковывают архивы, обрабатывают очереди задач и вызывают OCR-пайплайн.
• Tesseract OCR: Оптический движок распознавания текста, преобразующий растровые сканы и изображения в векторный машиночитаемый текст.
• Брокер сообщений (Valkey 9 / Redis 7): Быстрое in-memory хранилище очередей задач Celery и кэша сессий. В актуальных релизах Paperless-ngx по умолчанию используется valkey:9-alpine — независимый высокопроизводительный форк Redis с открытой лицензией.
• База данных (PostgreSQL 18): Хранит метаданные документов, историю изменений, права пользователей, теги и связи. Хотя Paperless поддерживает SQLite, в production-среде строго рекомендуется использовать PostgreSQL для исключения блокировок базы при параллельном распознавании нескольких тяжелых файлов.
• Apache Tika и Gotenberg: Конвертеры документов. Gotenberg преобразует файлы Word (.docx), Excel (.xlsx) и письма (.eml) в PDF, а Apache Tika извлекает из них текстовый поток.

3. Системные требования и сайзинг VDS под задачи оптического распознавания (OCR)

Распознавание растровых изображений через OCR — ресурсоемкая операция, активно нагружающая процессор и оперативную память. Ниже приведены проверенные на практике рекомендации по выбору тарифа VDS в зависимости от объема документооборота:

4. Надежные VDS-хостинги для хранения архива и фоновой обработки документов

Для безотказной работы оптического распознавания, быстрой обработки PDF-файлов и безопасного хранения архива сервер VDS должен иметь честную виртуализацию KVM, быстрые накопители NVMe и надежное резервирование каналов.

5. Подготовка сервера: структура каталогов, права доступа и генерация секретов

Подключитесь к вашему VDS по SSH и создайте рабочую директорию для стека Paperless-ngx. В целях безопасности контейнеры Paperless запускаются от непривилегированного пользователя с UID/GID 1000:

# Создаем изолированную директорию проекта
sudo mkdir -p /opt/paperless
cd /opt/paperless

# Создаем каталоги для данных, медиа-файлов, экспорта и папки входящих документов
sudo mkdir -p data media export consume
sudo chown -R 1000:1000 data media export consume
sudo chmod -R 755 data media export consume

Для защиты сессий и шифрования токенов сгенерируем криптостойкий секретный ключ Django длиной 64 символа с помощью генератора SysKit или команды OpenSSL:

Создайте файл переменных окружения /opt/paperless/docker-compose.env с правами 600:

# Создаем файл окружения с ограниченными правами
sudo touch /opt/paperless/docker-compose.env
sudo chmod 600 /opt/paperless/docker-compose.env

Внесите в /opt/paperless/docker-compose.env базовые параметры конфигурации:

# /opt/paperless/docker-compose.env
# Системные идентификаторы пользователя на хосте
USERMAP_UID=1000
USERMAP_GID=1000

# Секретный ключ Django (сгенерирован через openssl rand -hex 32)
PAPERLESS_SECRET_KEY=a7d9f2e4b8c10567e3215890abcefd4512389abcde01456789abcdef01234567

# Внешний URL вашего архива (критично для защиты CSRF и формирования ссылок)
PAPERLESS_URL=https://docs.yourdomain.ru

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

# Языковые параметры OCR: комбинация языков через знак плюс (+)
PAPERLESS_OCR_LANGUAGE=rus+eng

# Корректная обработка заголовков при работе за Reverse Proxy (защита CSRF)
PAPERLESS_USE_X_FORWARD_HOST=true
PAPERLESS_USE_X_FORWARD_PORT=true

# Настройка производительности OCR (1 воркер для серверов с 2 ГБ RAM)
PAPERLESS_TASK_WORKERS=1
PAPERLESS_WEBSERVER_WORKERS=1

# Игнорировать цифровые подписи в сканах для корректного наложения OCR-слоя
PAPERLESS_OCR_USER_ARGS='{"invalidate_digital_signatures": true}'

# Интеграция с Gotenberg и Apache Tika для офисных документов (.docx, .xlsx)
PAPERLESS_TIKA_ENABLED=1
PAPERLESS_TIKA_GOTENBERG_ENDPOINT=http://gotenberg:3000
PAPERLESS_TIKA_ENDPOINT=http://tika:9998

6. Эталонный манифест Docker Compose с лимитами ресурсов и изоляцией портов

Создайте манифест /opt/paperless/docker-compose.yml. Обратите особое внимание на два ключевых архитектурных требования безопасности и стабильности:

• Изоляция порта webserver: порт веб-интерфейса привязывается строго к локальному адресу 127.0.0.1:8000:8000. Это исключает прямой доступ из интернета в обход фаервола UFW. Внешний трафик пойдет только через защищенный Nginx с HTTPS.
• Нативные лимиты mem_limit и cpus: заданы на верхнем уровне каждого сервиса, что гарантирует работу ограничений в обычном Docker Compose без кластера Swarm.

# /opt/paperless/docker-compose.yml
services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    container_name: paperless-broker
    restart: unless-stopped
    mem_limit: 256m
    cpus: 0.5
    volumes:
      - redisdata:/data

  db:
    image: docker.io/library/postgres:18
    container_name: paperless-db
    restart: unless-stopped
    mem_limit: 512m
    cpus: 1.0
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: super_secure_db_password_syskit
    volumes:
      - pgdata:/var/lib/postgresql/data

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.2.1
    container_name: paperless-webserver
    restart: unless-stopped
    mem_limit: 1536m
    cpus: 1.5
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    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
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: super_secure_db_password_syskit

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.37
    container_name: paperless-gotenberg
    restart: unless-stopped
    mem_limit: 512m
    cpus: 1.0
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=file:///tmp/.*"

  tika:
    image: docker.io/apache/tika:3.3.1.0
    container_name: paperless-tika
    restart: unless-stopped
    mem_limit: 512m
    cpus: 0.8

volumes:
  pgdata:
  redisdata:

7. Тонкая настройка Tesseract OCR для точного распознавания русского языка

Для корректной работы с русскоязычными актами, накладными и чеками важно понимать механику работы Tesseract OCR внутри официального Docker-образа Paperless-ngx:

• Официальный образ уже содержит установленные языковые пакеты Tesseract для большинства распространенных языков, включая русский (rus) и английский (eng).
• Переменная PAPERLESS_OCR_LANGUAGE принимает трёхбуквенные коды языков по стандарту ISO 639-2. Если в ваших документах встречается только русский текст, укажите rus.
• Для корректного распознавания смешанных документов (счета-фактуры с артикулами на латинице, договоры с реквизитами SWIFT/IBAN, чеки с названиями брендов) языки комбинируются строго через знак плюс: PAPERLESS_OCR_LANGUAGE=rus+eng. В официальной документации Paperless-ngx отсутствует переменная во множественном числе — объединение словарей управляется исключительно этой директивой.
• Параметр PAPERLESS_OCR_MODE=skip (режим по умолчанию) проверяет, содержит ли входящий PDF уже готовый текстовый слой. Если документ экспортирован из 1С, Word или онлайн-банка, Paperless мгновенно извлечет существующий векторный текст без запуска тяжелого оптического распознавания, что экономит 95% времени и ресурсов CPU.
• Если вы сканируете мятые кассовые чеки или нечеткие сканы, можно включить предварительную очистку изображения через параметр PAPERLESS_OCR_CLEAN=clean (применяет утилиту unpaper для выравнивания страниц и удаления шумов).

8. Первый запуск стека и создание учетной записи администратора

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

# Запуск всех сервисов в фоновом режиме
cd /opt/paperless
docker compose up -d

# Проверка статуса запущенных контейнеров
docker compose ps

Убедитесь по логам, что база данных успешно инициализирована, миграции Django применены, а воркер подключился к брокеру Valkey:

# Просмотр логов веб-сервера
docker compose logs -f webserver

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

# Интерактивное создание администратора Paperless-ngx
docker compose exec -it webserver python3 manage.py createsuperuser

Система запросит логин (username), адрес электронной почты и надежный пароль.

9. Публикация веб-интерфейса через Nginx Reverse Proxy с сертификатом Let's Encrypt

Поскольку веб-интерфейс Paperless слушает локальный адрес 127.0.0.1:8000, настроим Nginx в качестве реверс-прокси с автоматическим получением бесплатного SSL-сертификата Let's Encrypt.

Создайте конфигурационный файл виртуального хоста /etc/nginx/sites-available/paperless.conf:

# /etc/nginx/sites-available/paperless.conf
server {
    listen 80;
    listen [::]:80;
    server_name docs.yourdomain.ru;

    # Максимальный размер загружаемого скана/документа (до 100 МБ)
    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_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # Поддержка WebSocket для мгновенных уведомлений об окончании OCR
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Увеличенные таймауты для загрузки и обработки тяжелых сканов
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Активируйте сайт и проверьте конфигурацию Nginx:

# Создаем символическую ссылку
sudo ln -s /etc/nginx/sites-available/paperless.conf /etc/nginx/sites-enabled/

# Проверяем синтаксис Nginx
sudo nginx -t

# Перезагружаем Nginx
sudo systemctl reload nginx

Выпустите бесплатный сертификат Let's Encrypt с автоматической настройкой HTTPS и перенаправлением трафика:

# Выпуск SSL-сертификата с автоматическим редиректом на HTTPS
sudo certbot --nginx -d docs.yourdomain.ru --redirect --non-interactive --agree-tos -m admin@yourdomain.ru

Проверьте корректность цепочки SSL-сертификата и шифрования через бесплатный чекер SysKit:

10. Автоматизация импорта: папка consume, мобильное сканирование и обработка почты

Сила Paperless-ngx заключается в том, что вам не нужно каждый раз вручную нажимать кнопку «Загрузить» в браузере. Доступны три удобных канала автоматического пополнения архива:

• Каталог быстрого сброса (каталог consume): Любой файл (PDF, PNG, JPG, TIFF, DOCX), скопированный в каталог /opt/paperless/consume, мгновенно подхватывается воркером. После успешного распознавания и индексации файл удаляется из входящей папки и сохраняется в защищенном хранилище media. Можно расшарить эту папку по протоколу SMB/Samba для домашнего сетевого сканера.
• Мобильное приложение (Paperless Mobile / QuickPaper): Бесплатные приложения для Android и iOS с открытым исходным кодом. Вы фотографируете чек в магазине или акт у клиента камерой смартфона — приложение автоматически обрезает границы страницы, выравнивает перспективу и отправляет документ по API в ваш Paperless-ngx.
• Автоматический сбор из почты (Mail Ingestion): В интерфейсе Paperless перейдите в Настройки → Почта. Подключите корпоративный почтовый ящик по IMAP (Яндекс 360, Mail.ru, собственный почтовый сервер). Создайте правило: «Каждое входящее письмо с темой Акт или от адреса бухгалтерии автоматически скачивать во вложениях и отправлять на OCR».

11. Резервное копирование документов и базы данных с помощью встроенного exporter

Потеря архива документов при сбое накопителя VDS недопустима. Paperless-ngx включает встроенную утилиту экспорта document_exporter, которая выгружает оригиналы файлов, PDF/A-копии и логический дамп базы данных со всеми метаданными в единый структурированный каталог:

# Запуск экспорта архива документов и метаданных во внешнюю папку export
docker compose exec -T webserver document_exporter ../export/

Утилита сохраняет оригиналы документов, их архивные копии и манифест manifest.json. Обратите внимание: экспорт создает снимок текущего состояния данных, но не является атомарной транзакцией во время активного распознавания новых файлов. Для максимальной надежности выполняйте экспорт по расписанию в часы минимальной активности (например, ночью) перед отправкой снапшотов в объектное S3-хранилище через Restic: