kerrad/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
604f0c705f55a37917395c4e71c5ad3e4bd63abc
homelab-docs/docs/containers/container-104.md

12 KiB
Raw Blame History

Контейнер 104 (Paperless): Paperless-ngx, PostgreSQL, Redis

Подробное описание LXC-контейнера 104 на Proxmox (192.168.1.104): архив документов Paperless-ngx (домен docs.katykhin.ru), PostgreSQL 18, Redis 8 для очередей задач.

Общие сведения

  • Хостнейм: paperless
  • IP: 192.168.1.104/24
  • ОС: Debian 12 (bookworm)
  • Ресурсы: 1 core, 2 GB RAM (из архитектуры)
  • Доступ: с Proxmox — pct exec 104 -- bash или по SSH на 192.168.1.104, если настроен.

Диск контейнера: ~10 GB, занято ~3.9 GB. Основной объём данных — в каталоге /mnt/paperless-data/ (ZFS: tank/subvol-104-disk-0): данные приложения, медиа (документы), БД PostgreSQL. Плюс образы и тома Docker (~2 GB). Следить за местом и логами (см. раздел «Логи и ротация» и TODO).

Доступ и логины

  • Debian (CT 104): логин root (пароль — в менеджере паролей или как настраивал при установке).
  • Paperless (веб): http://192.168.1.104:8000 (или через NPM: https://docs.katykhin.ru, если настроен). Учётные записи — пользователи Paperless (создаются в веб-интерфейсе).

Сервисы (Docker Compose)

Один проект: /opt/paperless/docker-compose.yml. Сеть: paperless_default (bridge).

Контейнер Образ Порты (хост) Назначение
paperless-webserver-1 paperless-ngx/paperless-ngx:latest 8000 Веб-интерфейс, API, OCR, фоновые задачи (Celery)
paperless-db-1 postgres:18 — БД Paperless
paperless-broker-1 redis:8 — Очередь задач (Celery broker)

1. Paperless-ngx (webserver)

Каталог: /opt/paperless/
Compose: docker-compose.yml, переменные из docker-compose.env (не коммитить).

Порты: 8000 (хост) → 8000 (контейнер).
Тома:

  • /mnt/paperless-data/data → /usr/src/paperless/data (конфиг, индекс, логи, celerybeat-schedule, lock-файлы).
  • /mnt/paperless-data/media → /usr/src/paperless/media (оригиналы и производные документов: documents/).
  • ./export → /usr/src/paperless/export (экспорт из приложения).
  • ./consume → /usr/src/paperless/consume (каталог для автоматического импорта: сюда класть файлы для постановки в очередь).

Переменные окружения: из docker-compose.env: PAPERLESS_URL, PAPERLESS_SECRET_KEY, PAPERLESS_TIME_ZONE, PAPERLESS_OCR_LANGUAGE(S). В compose заданы: PAPERLESS_REDIS=redis://broker:6379, PAPERLESS_DBHOST=db.

Структура данных на хосте:

  • /mnt/paperless-data/data/ — index/ (поисковый индекс), log/ (celery.log, paperless.log; приложение может создавать rotated файлы celery.log.1, .2 и т.д.), celerybeat-schedule.db, .index_version, migration_lock.
  • /mnt/paperless-data/media/documents/ — подкаталоги с оригинальными и обработанными файлами документов.

Команды:

cd /opt/paperless && docker compose up -d
docker logs paperless-webserver-1
docker exec paperless-webserver-1 document_exporter /usr/src/paperless/export --no-input  # экспорт

Импорт: положить файлы (PDF, изображения и т.д.) в /opt/paperless/consume/ на хосте — Paperless подхватит их и обработает (OCR, теги, корреспонденты настраиваются в веб-интерфейсе).

2. PostgreSQL (db)

Образ: postgres:18.
Том: /mnt/paperless-data/pgdata → /var/lib/postgresql.
Переменные: POSTGRES_DB=paperless, POSTGRES_USER=paperless, POSTGRES_PASSWORD=paperless (в compose).
Зависимость: webserver зависит от db и broker.

Команды:

docker exec paperless-db-1 pg_isready -U paperless
docker exec paperless-db-1 psql -U paperless -d paperless -c '\dt'

3. Redis (broker)

Образ: redis:8.
Том: volume redisdata → /data (внутри контейнера). На хосте: /var/lib/docker/volumes/paperless_redisdata/_data.
Используется как брокер для Celery (очередь задач OCR и др.).

Команды:

docker exec paperless-broker-1 redis-cli ping
docker logs paperless-broker-1

Порты (сводка на хосте)

Порт Сервис / примечание
8000 Paperless-ngx (веб)

Логи и ротация

  • Базовая политика LXC: в контейнере настроен logrotate /etc/logrotate.d/homelab-lxc.conf — 14 дней, 50 MB, 5 архивов (системные логи в /var/log). Подробнее: Logrotate — базовая политика homelab.
  • Paperless: логи приложения в /mnt/paperless-data/data/log/:
    • celery.log — фоновые задачи (OCR, индекс и т.д.); приложение может делать собственную ротацию (celery.log.1, .2, .3). На момент проверки каталог ~568 KB.
    • paperless.log — основной лог приложения. Для этих файлов нет правил logrotate на хосте — при длительной работе объём может расти (см. TODO).
  • Docker: драйвер логов контейнеров — json-file без ограничения размера и количества файлов. Рост логов контейнеров (stdout/stderr) может заполнять диск.

Системный logrotate в CT — только стандартные правила (apt, dpkg, btmp, wtmp). Отдельных правил для Paperless или Docker нет.

Риск: при большом количестве документов и активной очереди Celery логи в data/log/ и логи Docker могут разрастаться. Рекомендуется настроить ротацию (см. TODO).

Запуск и порядок поднятия

  1. Убедиться, что смонтирован /mnt/paperless-data (ZFS или иной бэкенд).
  2. cd /opt/paperless && docker compose up -d.
    Порядок: broker и db поднимаются первыми, затем webserver (depends_on).

После смены переменных в docker-compose.env или compose: docker compose up -d (пересоздание при необходимости). Обновление образа: docker compose pull && docker compose up -d.

Уязвимости и риски

  1. Пароли в конфигах: В docker-compose.yml заданы пароль БД (paperless/paperless). В docker-compose.env — PAPERLESS_SECRET_KEY, PAPERLESS_URL и др. Файлы лежат только на сервере; не помещать в публичный репозиторий. Ограничить права на docker-compose.env (например chmod 600).
  2. Доступ по порту 8000: Веб-интерфейс доступен по 192.168.1.104:8000 из LAN. Снаружи доступ только через NPM (https://docs.katykhin.ru). Не пробрасывать 8000 в интернет.
  3. Логи: Ротация логов Paperless (data/log/) и Docker не настроена — возможен рост и заполнение диска (см. TODO).
  4. Каталог consume: Файлы в /opt/paperless/consume/ автоматически обрабатываются и удаляются после импорта. Не класть туда единственные копии важных файлов без бэкапа.

TODO по контейнеру 104

  • Базовая политика logrotate: для системных логов настроена (homelab-lxc.conf — 14 дней, 50 MB, 5 архивов). См. Logrotate — базовая политика homelab.

  • Логи Paperless: Настроить logrotate для /mnt/paperless-data/data/log/*.log: например еженедельная ротация или по размеру (max 50–100 MB), хранить 3–4 копии, сжатие. Создать /etc/logrotate.d/paperless и проверить работу.

  • Логи Docker: Включить ограничение размера логов контейнеров: в docker-compose.yml добавить для сервисов logging: driver: json-file options: max-size: "50m" max-file: "3" или задать default в /etc/docker/daemon.json и перезапустить Docker, затем контейнеры.

  • Домен и NPM: При необходимости настроить в NPM proxy для docs.katykhin.ru → 192.168.1.104:8000, выпустить SSL. В Paperless в docker-compose.env задать PAPERLESS_URL=https://docs.katykhin.ru (если ещё не задан).

  • Мониторинг диска: Следить за местом на корне и на /mnt/paperless-data (df -h). При желании — оповещение при заполнении выше порога (например 80%).

  • Резервное копирование: Регулярный бэкап критичных данных (оценка размеров на момент документации):

    • /mnt/paperless-data/data — конфиг, индекс, логи, celerybeat-schedule. ~1 MB (логи могут расти).
    • /mnt/paperless-data/media — все документы (оригиналы и производные). ~178 MB (будет расти с новыми документами).
    • /mnt/paperless-data/pgdata — БД PostgreSQL. ~22 MB. Для консистентного бэкапа предпочтительно дамп: docker exec paperless-db-1 pg_dump -U paperless paperless > backup_paperless_$(date +%Y%m%d).sql.
    • /var/lib/docker/volumes/paperless_redisdata — данные Redis. ~12 KB. Восстановление не критично (очередь задач), по желанию.
    • /opt/paperless — docker-compose.yml, docker-compose.env (секреты), каталоги consume/export. ~20 KB. Обязательно; docker-compose.env не коммитить.

    Учитывать, что /mnt/paperless-data может быть отдельным ZFS-томом (tank/subvol-104-disk-0) — при бэкапе с хоста Proxmox нужно включить этот каталог или снапшот ZFS.

Связь с другими документами

Reference in New Issue View Git Blame Copy Permalink