Установка Paperless-ngx на Debian-like

В бесконечном потоке чертежей, квитанций и технических спецификаций современный инженер рискует быть погребенным под горой целлюлозы. Настало время обуздать этот хаос и превратить разрозненные бумажные свитки в стройную систему цифровых знаний. Мы приступаем к сборке «Медного архива» — мощного агрегата на базе Paperless-ngx, который станет вашим автоматическим хронистом, неустанно распознающим и каталогизирующим каждую букву, попавшую в его механические недра. В этом руководстве мы не просто установим софт; мы спроектируем отказоустойчивую паровую машину на фундаменте Debian, защитив её стальными пластинами Nginx и смазав шестерни правильной конфигурацией.

Генезис механизма: От Paperless до NGX

Прежде чем браться за гаечный ключ, стоит вспомнить историю создания этого устройства. Оригинальный проект Paperless, начатый Дэниелом Куинном, был лишь первым прототипом. Затем последовала модификация Paperless-ng от Йонаса Винклера, добавившая современный веб-интерфейс и машинное обучение. Сегодня мы работаем с Paperless-ngx — общественным форком, который вобрал в себя лучшие инженерные решения последних лет и продолжает развиваться силами сообщества.

Этот агрегат предназначен для одной цели: полной оцифровки вашего быта. Он берет PDF-файл или изображение, прогоняет его через линзы оптического распознавания символов (OCR) с помощью движка Tesseract и сохраняет результат в базу данных, делая каждое слово доступным для мгновенного поиска. Больше никаких поисков в пыльных папках; один запрос — и нужная спецификация перед вашими глазами.

Анатомия системы: Узлы и агрегаты

Чтобы запустить Paperless-ngx, нам потребуется собрать воедино несколько ключевых модулей. Каждый из них выполняет свою роль в общем цикле обработки документов.

Выбор базы данных — это вопрос масштаба вашего архива. Для небольшой домашней лаборатории вполне достаточно SQLite, которая проста в обслуживании и не требует отдельного демона. Однако для серьезного предприятия с тысячами чертежей ROADIT настоятельно рекомендует PostgreSQL — она обеспечит необходимую скорость вращения валов при сложных запросах.

Подготовка полигона: Требования и зависимости

Сервер под управлением сервера на базе Linux семейства Debian — идеальная площадка для нашего эксперимента. Но помните: распознавание текста — это процесс, требующий серьезного давления в котлах (ресурсов CPU).

Рекомендации по железу

Для комфортной работы архива мы рекомендуем следующие параметры:

1. Процессор: Минимум 2 ядра. Распознавание текста (OCR) — процесс параллельный, и Tesseract скажет вам спасибо за каждый дополнительный поток.
2. Память: Минимум 4 ГБ RAM. Если вы планируете добавлять модули Tika и Gotenberg для обработки документов Office (Word, Excel), аппетиты системы возрастут.
3. Накопитель: Объем зависит от ваших амбиций, но помните, что Paperless-ngx сохраняет как оригинал документа, так и его PDF/A версию для долгосрочного хранения.

Если вы используете маломощные системы типа Raspberry Pi 3/4, будьте готовы к тому, что обработка многостраничного трактата может занять время. В таких случаях стоит ограничить количество рабочих потоков, чтобы не парализовать остальную систему.

Сборка механизма: Установка через Docker

Самый надежный способ запустить Paperless-ngx сегодня — это использование Docker-контейнеров. Это изолирует наши «шестеренки» от внешнего мира и гарантирует, что все зависимости подогнаны идеально.

Подготовка палубы

Первым делом обновим систему и установим необходимые инструменты для работы с контейнерами:

# Обновляем паровые котлы и добавляем необходимые шестеренки
sudo apt update && sudo apt upgrade -y
sudo apt install ca-certificates curl gnupg apt-transport-https gpg

# Добавляем GPG-ключ
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg

#Подключение чертежей (репозитория)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Запускаем конвейер
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl enable --now docker

# Добавляем инженера в группу механиков
sudo usermod -aG docker $USER
# Перезайдите в сессию, чтобы права вступили в силу!

# Обновляем паровые котлы и добавляем необходимые шестеренки
sudo apt update && sudo apt upgrade -y
sudo apt install ca-certificates curl gnupg apt-transport-https gpg

# Добавляем GPG-ключ
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg

#Подключение чертежей (репозитория)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Запускаем конвейер
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
sudo systemctl enable --now docker

# Добавляем инженера в группу механиков
sudo usermod -aG docker $USER
# Перезайдите в сессию, чтобы права вступили в силу!

Проектирование структуры каталогов

Создадим рабочее пространство для нашего архива. Порядок в папках — залог долгой службы механизма.

sudo mkdir -p /opt/paperless/{data,media,export,consume,pgdata}
sudo chown -R $USER:$USER /opt/paperless
cd /opt/paperless

sudo mkdir -p /opt/paperless/{data,media,export,consume,pgdata}
sudo chown -R $USER:$USER /opt/paperless
cd /opt/paperless

Манифест сборки (docker-compose.yml)

Создайте файл docker-compose.yml. Мы будем использовать конфигурацию с PostgreSQL и Redis для максимальной надежности.

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:
      -./pgdata:/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:
      - "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

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:
      -./pgdata:/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:
      - "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

Настройка давления (docker-compose.env)

Этот файл — пульт управления нашей машиной. Здесь мы задаем критически важные параметры.

# Генерация секретного ключа
# python3 -c "import secrets; print(secrets.token_hex(50))"
PAPERLESS_SECRET_KEY=сгенерированный_ключ_здесь

PAPERLESS_URL=https://paperless.roadit.ru
PAPERLESS_TIME_ZONE=Europe/Moscow
PAPERLESS_OCR_LANGUAGE=rus+eng # Поддержка русского и английского [15]

# Настройки базы данных
PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_strong_password_here

# Генерация секретного ключа
# python3 -c "import secrets; print(secrets.token_hex(50))"
PAPERLESS_SECRET_KEY=сгенерированный_ключ_здесь

PAPERLESS_URL=https://paperless.roadit.ru
PAPERLESS_TIME_ZONE=Europe/Moscow
PAPERLESS_OCR_LANGUAGE=rus+eng # Поддержка русского и английского [15]

# Настройки базы данных
PAPERLESS_REDIS=redis://broker:6379
PAPERLESS_DBHOST=db
PAPERLESS_DBNAME=paperless
PAPERLESS_DBUSER=paperless
PAPERLESS_DBPASS=your_strong_password_here

Альтернативный путь: Установка Bare Metal

Для тех, кто предпочитает чувствовать холодную сталь кода и полностью контролировать каждый винтик, существует путь установки напрямую в систему (Bare Metal). Это сложнее, но дает полный доступ к рычагам управления.

Системные зависимости

Приготовьтесь, список внушительный. Нам нужны библиотеки для обработки изображений, PDF и сам движок распознавания.

sudo apt install -y \
  python3-pip python3-dev python3-venv imagemagick \
  fonts-liberation gnupg libmagic-dev libzbar0 poppler-utils \
  unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 \
  pngquant zlib1g tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng \
  build-essential libpq-dev redis-server

sudo apt install -y \
  python3-pip python3-dev python3-venv imagemagick \
  fonts-liberation gnupg libmagic-dev libzbar0 poppler-utils \
  unpaper ghostscript icc-profiles-free qpdf liblept5 libxml2 \
  pngquant zlib1g tesseract-ocr tesseract-ocr-rus tesseract-ocr-eng \
  build-essential libpq-dev redis-server

Настройка ImageMagick

В Debian по умолчанию закручены гайки безопасности: ImageMagick запрещено обрабатывать PDF. Нужно ослабить этот зажим.

Отредактируйте /etc/ImageMagick-6/policy.xml:

Найдите строку:

<policy domain="coder" rights="none" pattern="PDF" />

И замените её на:

<policy domain="coder" rights="read|write" pattern="PDF" />

Изоляция (Virtual Environment)

В Debian системный Python защищен (PEP 668), поэтому мы обязаны использовать виртуальное окружение, чтобы не испортить системные механизмы.

sudo groupadd paperless
sudo adduser --system --home /opt/paperless --group paperless
sudo mkdir -p /opt/paperless
sudo chown paperless:paperless /opt/paperless

sudo -Hu paperless python3 -m venv /opt/paperless/venv
sudo -Hu paperless /opt/paperless/venv/bin/pip install --upgrade pip
# Далее устанавливаем зависимости из requirements.txt проекта 

sudo groupadd paperless
sudo adduser --system --home /opt/paperless --group paperless
sudo mkdir -p /opt/paperless
sudo chown paperless:paperless /opt/paperless

sudo -Hu paperless python3 -m venv /opt/paperless/venv
sudo -Hu paperless /opt/paperless/venv/bin/pip install --upgrade pip
# Далее устанавливаем зависимости из requirements.txt проекта 

Оптическая линза: Тонкая настройка OCR

Движок Tesseract — это сердце «Медного архива». Он превращает пятна света на сканах в осмысленный текст. Но его нужно правильно откалибровать.

Двуязычное распознавание

Если ваши документы содержат и кириллицу, и латиницу (что в нашей инженерной среде норма), убедитесь, что в конфиге указано rus+eng. Paperless-ngx скачает необходимые пакеты данных при запуске, если они не найдены в системе.

Оптимизация потоков

По умолчанию Tesseract пытается захватить все доступные ресурсы. Чтобы механизм работал плавно и не перегревался, добавьте в docker-compose.env следующие ограничения :

# Ограничиваем количество потоков на один процесс Tesseract
OMP_THREAD_LIMIT=1 

# Количество страниц, обрабатываемых параллельно
PAPERLESS_TASK_WORKERS=2

# Ограничиваем количество потоков на один процесс Tesseract
OMP_THREAD_LIMIT=1 

# Количество страниц, обрабатываемых параллельно
PAPERLESS_TASK_WORKERS=2

Это позволит системе обрабатывать документы поточно, не вызывая резких скачков нагрузки, которые могут привести к падению других служб.

Стальной заслон: Настройка Nginx

Выставлять Paperless-ngx напрямую в сеть — дурной тон. Мы установим Nginx в качестве главного шлюза, который будет отвечать за шифрование (SSL) и фильтрацию входящего пара (трафика).

Конфигурация прокси

Создайте файл /etc/nginx/sites-available/paperless:

server {
    listen 80;
    server_name paperless.roadit.ru;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name paperless.roadit.ru;

    ssl_certificate /etc/letsencrypt/live/paperless.roadit.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paperless.roadit.ru/privkey.pem;

    # Важнейшая настройка для тяжелых документов! [20, 21]
    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;
        
        # Поддержка WebSockets для живого интерфейса [22]
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

server {
    listen 80;
    server_name paperless.roadit.ru;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name paperless.roadit.ru;

    ssl_certificate /etc/letsencrypt/live/paperless.roadit.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/paperless.roadit.ru/privkey.pem;

    # Важнейшая настройка для тяжелых документов! [20, 21]
    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;
        
        # Поддержка WebSockets для живого интерфейса [22]
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Автоматический конвейер: Подача документов

Система Paperless-ngx наиболее эффективна, когда документы попадают в неё без вашего участия.

Сетевое сканирование (Samba)

Настройте ваш офисный сканер на отправку файлов в папку consume. Для этого можно поднять Samba-сервер, который будет смотреть в ту же директорию. Как только файл падает в папку, Paperless-ngx подхватывает его, обрабатывает и удаляет оригинал (или перемещает в архив).

Почтовый шлюз

Вы можете настроить Paperless на проверку специального почтового ящика. Отправьте письмо с вложением на docs@yourdomain.com, и через пару минут документ появится в вашем архиве с тегом «E-mail».

Мобильный десант

Используйте мобильные приложения для Android или iOS (например, Paperless Share), чтобы быстро сфотографировать квитанцию и отправить её в недра механизма прямо «с полей».

Сохранность данных: Регламент бэкапов

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

Документ-экспортер

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

# Запуск экспорта внутри контейнера
docker exec paperless-webserver-1 document_exporter../export/ -z [27]

# Запуск экспорта внутри контейнера
docker exec paperless-webserver-1 document_exporter../export/ -z [27]

Флаг -z упакует всё в ZIP-архив. Рекомендуем настроить cron-задачу, которая будет выполнять этот экспорт каждую ночь и отправлять его на удаленный сервер или в облако через rclone.

Устранение неполадок: Когда шестерни скрипят

Даже самый надежный механизм иногда требует внимания механика.

Заключение: Триумф над бумагой

Установка Paperless-ngx на Debian — это не просто настройка софта, это создание надежной инженерной инфраструктуры. Теперь каждый ваш чертеж, каждая накладная и каждый технический отчет находятся под надежной защитой «Медного архива». Система сама найдет дату документа, определит отправителя и присвоит нужные теги, используя мощь машинного обучения.

Ваша библиотека больше не пылится в шкафах. Она живет, дышит паром и мгновенно откликается на каждый ваш запрос. Помните о регулярной смазке (обновлениях) и проверке давления (бэкапах), и этот механизм прослужит вам долгие десятилетия.