159 lines
12 KiB
Markdown
159 lines
12 KiB
Markdown
# Контейнер 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 (из [архитектуры](../architecture/architecture.md))
|
||
- **Доступ:** с 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/` — подкаталоги с оригинальными и обработанными файлами документов.
|
||
|
||
**Команды:**
|
||
```bash
|
||
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.
|
||
|
||
**Команды:**
|
||
```bash
|
||
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 и др.).
|
||
|
||
**Команды:**
|
||
```bash
|
||
docker exec paperless-broker-1 redis-cli ping
|
||
docker logs paperless-broker-1
|
||
```
|
||
|
||
---
|
||
|
||
## Порты (сводка на хосте)
|
||
|
||
| Порт | Сервис / примечание |
|
||
|------|----------------------|
|
||
| 8000 | Paperless-ngx (веб) |
|
||
|
||
---
|
||
|
||
## Логи и ротация
|
||
|
||
- **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
|
||
|
||
- [ ] **Логи 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.
|
||
|
||
---
|
||
|
||
## Связь с другими документами
|
||
|
||
- [Архитектура и подключение](../architecture/architecture.md) — таблица контейнеров, домен docs.katykhin.ru, схема сети.
|
||
- [Контейнер 100 (nginx)](container-100.md) — NPM, через который проксируется docs.katykhin.ru.
|
||
- [Paperless + Ollama: поиск по документам](paperless-ollama.md) — интеграция Paperless-ngx с Ollama для вопросов по документам.
|