Paperless-ngx превращает ворох PDF, сканов и фотографий в упорядоченный электронный архив с полнотекстовым поиском. Система распознаёт текст через OCR, раскладывает документы по корреспондентам, типам и тегам, хранит оригиналы и умеет автоматически применять правила. В этой статье — установка в Docker, русский OCR, резервное копирование и типичные ошибки эксплуатации.

Из чего состоит система

Paperless-ngx — веб-приложение на Django. Основные компоненты: контейнер webserver, в котором работают веб-процесс с интерфейсом и API, потребитель (consumer) и планировщик, Redis для очередей, база данных PostgreSQL и хранилище файлов. Для офисных форматов дополнительно поднимают Tika и Gotenberg.

Основные данные лежат в трёх каталогах: data — база, индекс и настройки; media — оригиналы и распознанные PDF; consume — папка, куда вы кладёте новые файлы. Эти каталоги должны быть на постоянном диске и попадать в резервную копию.

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

Создайте каталог проекта и файл compose. Ниже минимальный рабочий набор: PostgreSQL, Redis и контейнер webserver. Версию образа лучше зафиксировать, а не использовать latest, чтобы обновление не сломало архив неожиданно.

services:
  broker:
    image: redis:7-alpine
    restart: unless-stopped
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: change-me
    volumes:
      - ./pgdata:/var/lib/postgresql/data
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    restart: unless-stopped
    depends_on: [db, broker]
    ports: ["8000:8000"]
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    env_file: docker-compose.env

Файл окружения задаёт подключение и поведение OCR. Секретный ключ сгенерируйте случайно и не публикуйте в репозитории.

PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=change-me
PAPERLESS_SECRET_KEY=replace-with-random-value
PAPERLESS_URL=https://archive.example.ru
PAPERLESS_TIME_ZONE=Europe/Moscow
PAPERLESS_OCR_LANGUAGE=rus+eng
PAPERLESS_OCR_LANGUAGES=rus
PAPERLESS_FILENAME_FORMAT={{ created_year }}/{{ correspondent }}/{{ title }}

Запуск и проверка логов:

docker compose up -d
docker compose logs -f webserver
curl -I http://127.0.0.1:8000

Создайте администратора командой:

docker compose exec webserver python3 manage.py createsuperuser

Русский OCR и качество распознавания

В образе может не быть русского языкового пакета Tesseract. Переменная PAPERLESS_OCR_LANGUAGES=rus доустанавливает его при старте контейнера, а PAPERLESS_OCR_LANGUAGE задаёт языки распознавания. Для смешанных документов используйте rus+eng: это медленнее, но точнее на счетах и договорах с английскими реквизитами.

Качество сильно зависит от исходника. Сканируйте в 300 dpi, используйте чёрно-белый режим для текста и не применяйте сильное сжатие JPEG. Параметры очистки и выравнивания включаются переменными PAPERLESS_OCR_CLEAN и PAPERLESS_OCR_DESKEW. Если документ уже содержит текстовый слой, выбирайте режим skip, чтобы не тратить время.

docker compose exec webserver tesseract --list-langs
docker compose exec webserver python3 manage.py document_sanity_checker

Как устроен импорт

Потребитель следит за папкой consume. Положите туда PDF или картинку — через несколько секунд появится задача: определить текст, создать превью, предложить корреспондента и тип. Файл перемещается в media, а исходное имя сохраняется в метаданных.

Правила автоматизации (workflows) назначают теги по совпадению в тексте, корреспонденту или имени файла. Начните с простых правил: «если в тексте есть ИНН организации, добавить тег договор». Не создавайте десятки пересекающихся правил — отладка станет сложной.

  • Корреспондент — организация или человек, отправивший документ.
  • Тип документа — счёт, договор, акт, справка.
  • Теги — свободные метки для сквозной фильтрации.
  • Права доступа — отдельные пользователи и группы видят только свои документы.

Почтовый импорт и API

Paperless-ngx умеет забирать вложения из почтового ящика по IMAP. Это удобно для счетов: создайте отдельный ящик, включите правило и укажите сервер, логин и пароль в интерфейсе. Ограничьте папку входящими и добавьте фильтр по отправителю, иначе в архив попадёт реклама.

Для интеграции с другими системами используйте REST API и токен пользователя. Токен создаётся в профиле и передаётся в заголовке Authorization. Не храните его в клиентском JavaScript.

curl -H "Authorization: Token ВАШ_ТОКЕН" \
  "https://archive.example.ru/api/documents/?query=договор"

Через API можно загружать файлы, менять теги и получать статус задач. Для массовой загрузки удобнее подготовить файлы и отправить их в consume, чем делать тысячи HTTP-запросов.

Резервное копирование и восстановление

Копировать только каталог media недостаточно: метаданные, теги и связи хранятся в базе. Надёжный вариант — остановить webserver, сделать дамп PostgreSQL и скопировать data, media и consume. Второй вариант — встроенный экспорт, который складывает документы и метаданные в переносимый формат.

docker compose stop webserver
docker compose exec -T db pg_dump -U paperless paperless > backup.sql
docker compose run --rm webserver document_exporter /usr/src/paperless/export
docker compose start webserver

Восстановление обязательно проверяйте на отдельном стенде. Пустой архив, который «вроде открывается», не считается проверенной копией. Раз в квартал разворачивайте копию и ищите в ней случайный документ.

Безопасность и обновления

Не публикуйте порт 8000 в интернет напрямую. Поставьте обратный прокси с HTTPS, ограничьте размер загружаемых файлов и включите двухфакторную аутентификацию, если она доступна в вашей версии. Регулярно обновляйте образ и читайте примечания к выпуску: миграции базы иногда требуют свободного места.

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

Чек-лист внедрения

  • Отдельный диск или том для media и data.
  • PostgreSQL вместо встроенной базы, если документов больше нескольких тысяч.
  • Русский языковой пакет Tesseract и проверка на реальном скане.
  • Правила именования файлов и структура тегов до массового импорта.
  • Ежедневная резервная копия базы и файлов, ежеквартальная проверка восстановления.
  • HTTPS, сильные пароли и ограничение доступа по сети.

Итог

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

Насколько публикация полезна?

Нажмите на звезду, чтобы оценить!

Средняя оценка 0 / 5. Количество оценок: 0

Оценок пока нет. Поставьте оценку первым.

Поделиться: Telegram ВКонтакте