Paperless-ngx

Обзор

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

Рецепт запускает закреплённый образ Paperless-ngx 3.1.2 с PostgreSQL 18 и Valkey 9. По умолчанию включён английский OCR, другие языки добавляются одной переменной. Данные приложения, оригиналы и производные файлы, import/export, база и broker находятся в отдельных Docker volumes. Tika и Gotenberg не включены, поэтому импорт Office и email-файлов, для которого они нужны, этим рецептом не поддерживается.

Безопасность и границы рецепта

Полный HTTP smoke-тест прошёл на amd64; export документов и restore практически не проверялись. Paperless-ngx не шифрует документы и распознанный текст на диске; для чувствительного архива нужны шифрование диска и зашифрованные внешние копии. OCR, Ghostscript и обработчики изображений получают недоверенные файлы, которые могут исчерпать ресурсы или атаковать парсеры. Web-порт привязан к localhost, PostgreSQL и Valkey наружу не публикуются.

Пошаговая инструкция

1. Проверьте сервер Ubuntu или Debian

Нужны Ubuntu 22.04+ или Debian 12+, Docker Engine и Compose v2.24+. Выделите минимум 2 CPU, 2 ГБ RAM и 10 ГБ диска; рекомендуется 4 ГБ RAM. OCR кратковременно нагружает CPU и требует дополнительное место для оригинала, PDF/A и миниатюр.

docker --version
docker compose version

2. Подготовьте рецепт и секреты

mkdir -p ~/services/paperless-ngx
cd ~/services/paperless-ngx
cp .env.example .env
chmod 600 .env
sed -i "s|^PAPERLESS_SECRET_KEY=.*|PAPERLESS_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(64))')|" .env
sed -i "s|^PAPERLESS_DB_PASSWORD=.*|PAPERLESS_DB_PASSWORD=$(openssl rand -hex 32)|" .env

Не публикуйте .env. PAPERLESS_SECRET_KEY подписывает сессии и чувствительные данные, PAPERLESS_DB_PASSWORD защищает PostgreSQL; оба обязательны. Сохраните их в менеджере секретов и не меняйте при восстановлении существующего архива.

Все переменные .env:

• PAPERLESS_PORT — локальный web-порт, по умолчанию 8000;
• PAPERLESS_URL — единственный внешний origin с https, без завершающего / и без пути; он задаёт allowed hosts, CORS и CSRF origins;
• PAPERLESS_SECRET_KEY — обязательный случайный ключ подписи;
• PAPERLESS_DB_PASSWORD — обязательный случайный пароль БД;
• PAPERLESS_DB_NAME и PAPERLESS_DB_USER — имя базы и роли, меняются только до первого запуска;
• PAPERLESS_TIME_ZONE — часовой пояс IANA для дат и фоновых задач;
• PAPERLESS_OCR_LANGUAGE — что распознавать в документе, по умолчанию eng; для двух языков rus+eng;
• PAPERLESS_OCR_LANGUAGES — какие пакеты tesseract доустановить при старте, поэтому rus сначала добавляется сюда;
• переменные PAPERLESS_*_VOLUME — имена volumes для data, media, export, consume, PostgreSQL и Valkey;
• PAPERLESS_BACKUP_DIR — каталог итоговых архивов на хосте.

paperless-data хранит индекс, модель классификации и служебные данные; paperless-media — оригиналы, архивные версии и миниатюры; paperless-export — результат exporter; paperless-consume — входящие файлы; остальные volumes — кластер PostgreSQL и состояние Valkey. Ни один из них не зашифрован рецептом.

3. Запустите и создайте администратора

docker compose config
docker compose pull
docker compose up -d --wait
curl -I --fail http://127.0.0.1:8000/
docker compose exec webserver createsuperuser

Последняя команда интерактивно спрашивает имя, email и пароль: пароль не попадает ни в .env, ни в shell history и не остаётся постоянной переменной контейнера. Самостоятельная регистрация выключена. Не публикуйте сервис до создания администратора. Посмотреть состояние: docker compose ps и docker compose logs --tail=100 webserver.

Запуск на VPS

Оставьте bind 127.0.0.1:${PAPERLESS_PORT}:8000: доступ к web даёт только HTTPS reverse proxy на этом хосте. PostgreSQL и Valkey не имеют published ports. В firewall откройте только SSH, HTTP и HTTPS. Перед первым входом замените домен в PAPERLESS_URL и proxy-примере, настройте DNS и TLS.

Доступ в доверенной локальной сети

Без домена оставьте localhost bind и используйте туннель ssh -L 8000:127.0.0.1:8000 user@server; для такого временного доступа задайте PAPERLESS_URL=http://localhost:8000 и пересоздайте webserver. Для постоянного LAN-доступа замените 127.0.0.1 в compose.yaml на конкретный приватный адрес, например 192.168.1.10, задайте PAPERLESS_URL=http://192.168.1.10:8000 и ограничьте порт firewall. Не используйте 0.0.0.0 без сетевых ограничений.

Домен, HTTPS и WebSockets

Установите PAPERLESS_URL=https://paperless.example.com именно без завершающего слеша: путь вроде /paperless в этой переменной запрещён. Замените домен в proxy/Caddyfile, proxy/nginx.conf или proxy/traefik.yaml. Caddy получает сертификат автоматически, Nginx ожидает Certbot, Traefik использует resolver letsencrypt. Затем:

docker compose up -d --force-recreate webserver

Proxy должен сохранять Host, передавать X-Forwarded-Proto: https и клиентский адрес. Статус фоновой обработки использует WebSocket /ws/status/: Caddy и Traefik поддерживают upgrade автоматически, в Nginx он настроен явно. Если proxy работает в контейнере, 127.0.0.1 означает сам proxy; укажите доступный host gateway вместо localhost.

Резервное копирование

Сначала дождитесь окончания задач и убедитесь, что consume пуст. Затем:

chmod +x backup.sh restore.sh
./backup.sh

Скрипт запускает официальный document_exporter, сохраняет export, ещё не поглощённые файлы consume, .env и Compose в один tar. Export включает документы, миниатюры, метаданные, пользователей и точный снимок данных, но не включает API tokens: после restore их нужно выпустить заново. Изменения, начавшиеся во время export, могут не попасть в согласованный снимок, поэтому на время операции не добавляйте документы и не меняйте метаданные. Архив содержит документы и секреты: зашифруйте его, скопируйте за пределы сервера и проверяйте restore.

Восстановление

Импорт необратимо заменяет все шесть volumes. Он поддерживается только в полностью пустую установку той же версии Paperless-ngx, с теми же настройками путей. Проверьте тег 3.1.2, свободное место и активный .env, затем:

./restore.sh ./backups/paperless-ngx-YYYYMMDDTHHMMSSZ.tar
docker compose ps
docker compose exec webserver document_sanity_checker

Скрипт сначала делает страховочный export текущего состояния, удаляет volumes, поднимает пустую установку и запускает document_importer. Сохранённый configuration.env оставляется только для ручного сравнения и не заменяет активный .env. Процедура ещё не прошла практический restore-тест; сначала испытайте копию на отдельном сервере. Перевыпустите API tokens после импорта.

Обновление Paperless-ngx

Дождитесь задач, сделайте backup и прочитайте release notes и инструкции по миграции. Замените только точный тег paperlessngx/paperless-ngx:3.1.2 на проверенную версию, не используйте latest, затем:

docker compose pull
docker compose up -d --wait
docker compose logs --tail=200 webserver
docker compose exec webserver document_sanity_checker

Запуск применяет миграции автоматически. Не обновляйте Paperless одновременно с PostgreSQL или Valkey: так причина ошибки и откат остаются однозначными.

PostgreSQL major update

Тег postgres:18-alpine закреплён отдельно. Смена major не является обычным docker compose pull: формат каталога данных может быть несовместим. Следуйте официальной процедуре pg_upgrade/dump-restore PostgreSQL либо используйте document_exporter --data-only и importer в новой пустой БД. Перед этим нужен полный проверенный backup; не меняйте пути и не удаляйте старый volume до проверки новой базы.

Откат

Не запускайте старый образ поверх базы после миграций. Верните прежний точный тег и восстановите полный pre-update export через restore.sh. Это откатывает БД, documents и индекс вместе. Для неудачного PostgreSQL major update верните старый тег и старый volume; не подключайте старый сервер к каталогу данных новой major.

Остановка и полное удаление

docker compose down сохраняет данные. После проверки внешнего backup удалить всё безвозвратно:

docker compose down
docker volume rm paperless-data paperless-media paperless-export paperless-consume paperless-database paperless-broker
rm -rf ~/services/paperless-ngx

Если имена volumes изменены в .env, подставьте их фактические значения.

Источники: configuration, backup, exporter/importer и update, release 3.1.2 и PostgreSQL major upgrades.

Диагностика

Paperless-ngx не становится healthy

docker compose ps
docker compose logs --tail=200 webserver database broker
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q webserver)"

Проверьте, что оба обязательных секрета заменены, PostgreSQL и Valkey healthy, на диске есть место, а curl http://127.0.0.1:8000/ возвращает redirect. Первый запуск дольше обычного из-за миграций, индекса и установки языка OCR.

Ошибка CSRF, неверные ссылки или redirect на другой адрес

PAPERLESS_URL должен точно совпадать с внешним origin: схема https, домен, необязательный нестандартный порт, без завершающего / и без пути. После изменения выполните docker compose up -d --force-recreate webserver. Проверьте, что proxy передаёт исходные Host и X-Forwarded-Proto.

Статус обработки не обновляется

Проверьте WebSocket route и broker:

docker compose logs --tail=200 webserver broker
docker compose exec broker valkey-cli ping

Proxy обязан разрешать upgrade соединения для /ws/status/. Контейнерный proxy не может обращаться к 127.0.0.1 хоста без host gateway.

OCR не распознаёт язык

Переменные должны быть согласованы. PAPERLESS_OCR_LANGUAGES доустанавливает пакет tesseract при старте контейнера, а PAPERLESS_OCR_LANGUAGE выбирает, что распознавать; язык, указанный только во второй, молча не сработает. Для русского вместе с английским задайте PAPERLESS_OCR_LANGUAGES=rus и PAPERLESS_OCR_LANGUAGE=rus+eng. В логах старта должна быть установка языковых данных. Повторный OCR существующих документов запускайте через UI только после backup: он расходует много CPU и может изменить архивную версию документа.

Документ остаётся в consume или обработка падает

docker compose logs --since=30m webserver
docker system df
docker compose exec webserver document_sanity_checker

Проверьте формат, права volume, свободный диск и RAM. Tika/Gotenberg в рецепт не входят: требующие их Office и email-файлы не будут обрабатываться этим стеком.

Ошибка 502 от reverse proxy

С хоста проверьте curl -I http://127.0.0.1:8000/. Затем проверьте upstream, firewall и сетевой namespace proxy. Из контейнера 127.0.0.1 указывает на сам контейнер, а не на Paperless-ngx на хосте.