4658089e21
126 plikow (md, yaml, sh, py) odwolywalo sie do sciezek sprzed migracji.
15 markdown-linkow [..](..) -> policzona sciezka WZGLEDNA wobec pliku
odsylajacego (wczesniej czesc z nich byla repo-root-relative i nie
rozwiazywala sie z katalogu, w ktorym lezala)
200 odwolan tekstowych (backticki, proza, yaml, importy w kodzie)
-> nowa sciezka repo-root-relative, zgodnie z konwencja repo
5 linkow rodzenstwa (gole nazwy plikow, np. "](DEPLOY.md)") — dzialaly
tylko w starym katalogu; przeliczone recznie
Objete m.in.: CLAUDE.md (scripts/onboard/README.md -> kb/runbooks/
node-onboarding-tool.md, docs/backlog.md -> kb/phases/backlog.md),
README.md, .claude/skills/, 20 session logow, kod jobow.
Ostatnie 5 odwolan pochodzi z tresci wciagnietej rebasem z origin/master
(session log 2026-07-31, override node-agenta na SOLARII, dwie pozycje
backlogu) — wskazywaly na docs/incidents/, docs/kb/modules/ i
services/narty27/README.md sprzed migracji.
Dodany wzajemny link miedzy kb/services/control-plane.md (stub kodu)
a kb/subsystems/control-plane.md (opis, deprecated) — dwa dokumenty o tym
samym systemie, latwe do pomylenia.
Weryfikacja na 790 plikach: 0 odwolan do starych sciezek,
0 martwych linkow markdown. Lint OKF: 190/190 plikow ZGODNE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
121 lines
6.4 KiB
Markdown
121 lines
6.4 KiB
Markdown
---
|
|
okf: "0.1"
|
|
type: service
|
|
visibility: private
|
|
status: active
|
|
updated: 2026-07-12
|
|
links:
|
|
- ../runbooks/paperless-worker-deploy.md
|
|
---
|
|
|
|
# Paperless OCR worker (SOLARIA)
|
|
|
|
Ciężki OCR filaru KB #2 (moduł 3, `kb/phases/kb-m3-ocr-worker.md`).
|
|
Ten sam obraz co `services/paperless/`, ale z nadpisanym poleceniem — działa
|
|
**wyłącznie** jako celery worker podpięty do brokera/bazy paperless@PIHA,
|
|
ze storage widzianym przez NFS z PIHA. Realizuje wzorzec kb-02
|
|
„serwis always-on + compute-worker on-demand z fallback".
|
|
|
|
**Status (2026-07-12): ZDEPLOYOWANY I DZIAŁA.** Worker bierze zadania z kolejki
|
|
razem z workerem PIHA, kończy OCR bez błędów, dokumenty trafiają do Paperless
|
|
niezależnie od tego, który worker odebrał zadanie. Zweryfikowane end-to-end:
|
|
kilka dokumentów testowych wrzuconych do `consume/` na PIHA, część odebrana
|
|
przez worker@SOLARIA (log: `Consuming ...` → `ocrmypdf`/`tesseract` →
|
|
`ConsumeTaskPlugin completed with: Success` → dokument widoczny w DB), zero
|
|
`File not found`. Dwa bugi znalezione i naprawione po drodze — patrz sekcje
|
|
„Gotcha: `command` i entrypoint obrazu" i „SCRATCH_DIR" niżej.
|
|
|
|
## Wynik badania: czy split-host worker jest wykonalny?
|
|
|
|
**TAK — z zastrzeżeniami.** Ustalenia (GH discussion #3900 + docs):
|
|
|
|
1. **Nie jest to oficjalnie wspierane** przez Paperless-ngx, ale maintainerzy
|
|
potwierdzają wykonalność i podają dokładnie ten wzorzec: drugi host, ten sam
|
|
obraz, `command: celery --app paperless worker --loglevel INFO`, dostęp
|
|
sieciowy do Redis + Postgres + współdzielonych plików.
|
|
2. Worker potrzebuje **pełnego kontekstu aplikacji**: broker (Redis), baza
|
|
(Postgres) i **te same pliki pod tymi samymi ścieżkami kontenerowymi**
|
|
(`/usr/src/paperless/{data,media,consume}`) — payloady zadań i DB niosą
|
|
ścieżki absolutne.
|
|
3. **Podział pracy**: consumer (inotify na `consume/`), beat (harmonogram)
|
|
i webserver zostają na PIHA; na SOLARIA idzie wyłącznie egzekucja zadań
|
|
celery (OCR/parsowanie/archiwizacja). Consumer na PIHA działa na lokalnym
|
|
dysku, więc inotify działa normalnie (ograniczenie „inotify nie działa po
|
|
NFS" nas nie dotyka — po NFS czyta tylko worker, nie consumer).
|
|
4. **Fallback**: obu-stronny worker na tej samej kolejce. Gdy SOLARIA śpi —
|
|
zadania czekają w Redis (AOF na PIHA) i wbudowany worker PIHA
|
|
(concurrency 1) mieli powoli. Gdy SOLARIA wstaje — worker z concurrency 4+
|
|
rozładowuje kolejkę. Gdy worker zniknie w połowie zadania, celery na
|
|
transporcie redis odda nieodebrane zadanie po visibility timeout
|
|
(domyślnie 1 h) — zadanie nie ginie, najwyżej się opóźnia.
|
|
5. **GPU nie gra roli** — stockowy OCR (ocrmypdf/tesseract) jest CPU-only.
|
|
Zysk SOLARII to 24 rdzenie i 62 Gi RAM, nie CUDA.
|
|
|
|
### Znane ryzyka (świadomie zaakceptowane / do obserwacji)
|
|
|
|
- **Indeks Whoosh w `data/` przy dwóch piszących hostach.** Po konsumpcji
|
|
dokumentu worker dopisuje go do indeksu wyszukiwania (plikowy Whoosh
|
|
w `data/index`). Przy workerze na PIHA (lokalnie) i na SOLARIA (po NFS)
|
|
równolegle istnieje ryzyko wyścigu na lockach plikowych (znane objawy
|
|
w upstream: „This writer is closed", skorumpowany TOC indeksu). Mitygacja:
|
|
indeks to dane **pochodne** — `docker exec paperless document_index reindex`
|
|
odtwarza go w całości; oryginały i metadane nie są zagrożone. Jeśli
|
|
korupcje będą się powtarzać, opcje: przenieść cały batch-OCR w okna, gdy
|
|
działa tylko jeden worker, albo zrezygnować z fallbacku PIHA (kolejka
|
|
po prostu czeka na SOLARIĘ).
|
|
- **Postgres `max_connections`**: każdy proces workera trzyma połączenie.
|
|
Przy defaultowym 100 i concurrency 4+1 zapasu jest dużo; podbijając
|
|
`WORKER_CONCURRENCY` pilnować sumy połączeń (formuła w docs upstream).
|
|
- **Wersje obrazów muszą być identyczne** (PIHA i SOLARIA) — wspólny schemat
|
|
DB i sygnatury zadań. Podbijać oba compose naraz.
|
|
|
|
## Gotcha: `command` i entrypoint obrazu
|
|
|
|
Nadpisanie `command:` w compose na `celery --app paperless worker ...` (jak
|
|
sugeruje GH discussion #3900 i punkt 1 wyżej) **nie działa** — pada
|
|
`Unknown command: 'celery'`. Przyczyna w `/sbin/docker-entrypoint.sh` obrazu:
|
|
|
|
```bash
|
|
if [[ "$1" != "/"* ]]; then
|
|
exec gosu paperless python3 manage.py "$@" # argv[0] bez "/" -> manage.py
|
|
else
|
|
exec "$@" # argv[0] zaczyna się od "/" -> exec wprost
|
|
fi
|
|
```
|
|
|
|
Każdy argument NIE zaczynający się od `/` jest traktowany jako nazwa komendy
|
|
Django i lądowany w `manage.py <arg>` — stąd `celery` jest interpretowane jako
|
|
nieznana subkomenda `manage.py`, a nie program do uruchomienia. Fix: ścieżka
|
|
absolutna, żeby wejść w gałąź `exec "$@"`, plus jawne `gosu paperless` z
|
|
przodu (bo ten branch NIE dostaje automatycznego gosu jak branch manage.py) —
|
|
inaczej proces poszedłby jako root, co psuje właściciela plików na NFS
|
|
(musi być uid 1000, patrz "UID mapping" niżej):
|
|
|
|
```yaml
|
|
command: /usr/sbin/gosu paperless /usr/local/bin/celery --app paperless worker --loglevel INFO --concurrency ${WORKER_CONCURRENCY:-4}
|
|
```
|
|
|
|
Ścieżki zweryfikowane w obrazie `ghcr.io/paperless-ngx/paperless-ngx:2.14`:
|
|
`gosu` = `/usr/sbin/gosu`, `celery` = `/usr/local/bin/celery`, user `paperless`
|
|
= uid/gid 1000.
|
|
|
|
## SCRATCH_DIR — musi być współdzielony tak samo jak data/media/consume
|
|
|
|
Paperless zapisuje wgrywany plik do katalogu roboczego przed konsumpcją —
|
|
`SCRATCH_DIR`, domyślnie `/tmp/paperless` (paperless-ngx:
|
|
`tempfile.gettempdir() / "paperless"` w `src/paperless/settings.py`, gdy
|
|
`PAPERLESS_SCRATCH_DIR` nie jest ustawione — nie trzeba go więc ustawiać
|
|
jawnie, domyślna wartość już pasuje do mount pointu poniżej). Payload zadania
|
|
celery niesie ścieżkę do tego pliku jako ścieżkę **absolutną**. Ponieważ
|
|
worker@PIHA i worker@SOLARIA dzielą jedną kolejkę, ten, który akurat odbierze
|
|
zadanie, musi widzieć dokładnie ten sam plik pod dokładnie tą samą ścieżką —
|
|
identyczna zasada jak dla `data/media/consume` (patrz komentarz w
|
|
`services/paperless/docker-compose.yml`). To zostało pominięte przy
|
|
pierwszym wdrożeniu modułu 3: dokumenty konsumowane na PIHA, ale odebrane do
|
|
OCR przez SOLARIĘ, padały z `Cannot consume ...: File not found`, bo SOLARIA
|
|
miała własny, lokalny, pusty `/tmp/paperless`. Fix: NFS-owy wolumen
|
|
`paperless_scratch` (ten sam wzorzec co `paperless_data/media/consume`) na
|
|
katalog `/opt/homelab/data/paperless/scratch` (już istnieje na PIHA,
|
|
`chown 1000:1000`), montowany na `/tmp/paperless` po obu stronach.
|
|
|