Paperless-ngx на Ubuntu 24.04: пошаговая установка

MAATRIX

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

Что такое Paperless-ngx и зачем он нужен

Paperless-ngx — форк проекта paperless-ng, развивающийся сообществом с 2021 года. Это не просто хранилище файлов, а полноценная система документооборота с распознаванием текста:

• OCR на входе. Каждый загруженный файл (PDF, JPG, PNG, TIFF) прогоняется через Tesseract OCR, распознанный текст индексируется для поиска.
• Автоматическая классификация. Правила «если в тексте есть слово X — присвоить тег Y» избавляют от ручной сортировки.
• Извлечение метаданных. Дата документа, корреспондент (отправитель) и тип документа определяются автоматически по настраиваемым паттернам.
• Оригинал + архивная копия. Хранится и исходный файл, и версия с текстовым слоем (PDF/A), пригодная для полнотекстового поиска и долговременного архивирования.
• Веб-интерфейс и API. Загрузка через браузер, email-инбокс, папку с файлами (consume-каталог) или REST API — удобно интегрировать со сканером или мобильным приложением.

OCR — процесс, требовательный к CPU и памяти, особенно на многостраничных PDF с плохим качеством скана. Держать это дома на роутере или NAS с 1 ГБ RAM — плохая идея: очередь задач будет копиться, а веб-интерфейс — подвисать. На арендованном VPS с нормальным CPU и SSD задача решается предсказуемо, плюс сервер доступен 24/7 из любой точки, а не только из домашней сети.

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

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

• веб-приложение и API (Django + Gunicorn);
• воркер задач (Celery) — именно он делает OCR;
• Redis — брокер очереди задач;
• PostgreSQL — основная база данных (документы, теги, метаданные);
• Gotenberg и Tika (опционально) — конвертация офисных файлов (docx, xlsx) в PDF перед OCR.

По ресурсам ориентируйтесь так: для личного архива хватает 2 vCPU и 4 ГБ RAM — минимальный порог, при котором OCR не блокирует интерфейс. Для активной загрузки (десятки документов в день, небольшая компания) лучше брать 4 vCPU и 8 ГБ RAM — OCR многопоточный и с лихвой съедает лишние ядра при пакетной обработке. Диск — SSD, потому что PostgreSQL и полнотекстовый индекс чувствительны к IOPS; под сами документы закладывайте запас, архив обычно растёт на несколько гигабайт в год.

Если сервер под задачу ещё не выбран — у нас можно арендовать VPS с SSD и нужным набором ядер и памяти, оплата доступна картой РФ и криптовалютой, что снимает вопрос международных платежей.

Дальше предполагаем чистую Ubuntu 24.04 LTS с root-доступом или пользователем с sudo. Если Docker на сервере ещё не стоит, ставим его официальным скриптом — так гарантированно получаем актуальную версию:

apt update && apt upgrade -y
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
systemctl enable --now docker
docker --version
docker compose version

Если предпочитаете разобрать установку Docker по шагам и с пояснениями каждого пункта — есть отдельная инструкция: Ubuntu 24.04: установка Docker с нуля.

Создаём отдельного пользователя для эксплуатации сервиса (не обязательно, но снижает риск при компрометации других сервисов на той же машине):

adduser --disabled-password --gecos "" paperless
usermod -aG docker paperless
su - paperless

Подготовка docker-compose и файлов окружения

Официальный проект держит готовые compose-файлы для разных бэкендов БД. Берём вариант с PostgreSQL — он масштабируется лучше SQLite и не имеет ограничений на конкурентную запись.

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

Точный набор сервисов в шаблоне может отличаться от версии к версии проекта, поэтому после скачивания стоит открыть файл и свериться со списком контейнеров, а не полагаться слепо. Структура выглядит так (сокращённо):

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

  db:
    image: docker.io/library/postgres:15
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    env_file: docker-compose.env

  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

volumes:
  pgdata:
  redisdata:
  data:
  media:

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

PAPERLESS_URL=https://docs.example.com
PAPERLESS_SECRET_KEY=<сгенерируйте случайную строку минимум 50 символов>
PAPERLESS_TIME_ZONE=Europe/Moscow
PAPERLESS_OCR_LANGUAGE=rus+eng
PAPERLESS_OCR_LANGUAGES=rus eng
PAPERLESS_ADMIN_USER=admin
PAPERLESS_ADMIN_PASSWORD=<надёжный пароль>

Секретный ключ можно сгенерировать так:

openssl rand -base64 48

Обратите внимание на PAPERLESS_OCR_LANGUAGE и PAPERLESS_OCR_LANGUAGES — это разные параметры: первый задаёт язык по умолчанию для распознавания, второй — список языковых пакетов Tesseract, которые нужно установить в контейнере. Если работаете с документами на русском, обе строки обязательны, иначе OCR будет пытаться распознать русский текст английским словарём и результат окажется мусорным.

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

Поднимаем стек:

docker compose up -d
docker compose logs -f webserver

Первый запуск выполняет миграции базы данных — это может занять минуту-другую, дождитесь строки о старте Gunicorn перед следующим шагом. Если в .env не задан PAPERLESS_ADMIN_USER/PAPERLESS_ADMIN_PASSWORD, создаём суперпользователя вручную:

docker compose exec webserver createsuperuser

Проверяем, что интерфейс отвечает:

curl -I http://localhost:8000

Ожидаем 200 OK или редирект на страницу логина. Дальше временно открываем порт для проверки из браузера (после настройки reverse proxy порт 8000 наружу лучше закрыть):

ufw allow 8000/tcp

Заходим на http://IP-сервера:8000, логинимся под созданным администратором — должен открыться пустой дашборд с разделами «Документы», «Корреспонденты», «Теги», «Типы документов».

Настройка HTTPS через reverse proxy

Открывать сервис документов по HTTP на голом порту 8000 — плохая практика: логин и пароль, а тем более сами документы, будут идти в открытом виде. Правильный путь — reverse proxy с автоматическим SSL-сертификатом.

Если на сервере ещё нет обратного прокси, проще всего поднять Caddy — он получает сертификат Let's Encrypt автоматически, без ручного certbot. Подробный пошаговый разбор есть в отдельной статье: Caddy с авто-SSL на Ubuntu 24.04. Кратко, конфиг для Paperless-ngx выглядит так:

docs.example.com {
    reverse_proxy localhost:8000
}

После перезапуска Caddy закрываем прямой доступ к порту 8000 извне:

ufw delete allow 8000/tcp

Порт остаётся доступен только внутри сервера, наружу отдаётся исключительно 443 через прокси. Если файрвол на сервере ещё не настроен в принципе — начните с базовой настройки: UFW на Ubuntu 24.04.

Загрузка документов и правила автоматизации

Есть три штатных способа отправить документ в обработку:

1. Consume-папка. Файл, положенный в ~/paperless-ngx/consume, подхватывается автоматически в течение нескольких секунд — удобно для сканера, который сохраняет файлы по SMB/FTP в эту директорию.
2. Веб-интерфейс. Drag-and-drop прямо в браузере, подходит для разовой загрузки фото с телефона.
3. Email-инбокс. Paperless-ngx можно подключить к почтовому ящику (IMAP) — вложения из писем будут забираться автоматически. Настраивается в разделе «Почтовые ящики» админки, потребуется отдельный ящик или папка-фильтр, чтобы не тащить в архив всю переписку.

После загрузки система запускает OCR и пытается автоматически определить корреспондента, дату и тип документа по правилам, которые вы задаёте в разделе «Автоматизация» → «Правила сопоставления». Правило — это условие (совпадение по тексту, regex, имени файла) плюс действие (присвоить тег, корреспондента, тип документа). Например, правило «если в тексте есть ИНН вашей компании и слово "счёт"» может автоматически проставлять тег «Входящие счета» и тип документа «Счёт-фактура» — без ручной разметки каждого файла.

Важный нюанс: правила применяются только к новым документам, поэтому сначала настройте теги и правила, а затем начинайте массовую загрузку архива — так вы не будете вручную доразмечать сотни уже загруженных файлов.

Резервное копирование данных

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

• База PostgreSQL — метаданные, теги, связи, права доступа;
• media — сами файлы документов (оригиналы и архивные PDF/A);
• data — индекс полнотекстового поиска и служебные данные.

Штатный экспорт документа делается командой:

docker compose exec webserver document_exporter ../export

Она выгружает документы вместе с метаданными в JSON — это удобно для миграции на другой сервер, но не заменяет регулярный бэкап на случай сбоя диска. Для регулярного копирования volume'ов и базы данных на внешнее хранилище логично использовать restic — он умеет инкрементальные снапшоты и шифрование на лету. Пошаговая настройка описана здесь: Restic на Ubuntu 24.04. Ориентировочный сценарий — снапшот раз в сутки с ретеншеном на несколько недель назад, чтобы была возможность откатиться, если ошибочное правило автоматизации испортит разметку большого числа документов.

Дамп базы отдельно (для быстрого восстановления без полного volume-снапшота):

docker compose exec -T db pg_dump -U paperless paperless > paperless_$(date +%F).sql

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