feat(kb): SPLIT backlog.md (72 KB) -> 19 dokumentow + cienki indeks
Rozstrzygniecie 1. Monolit mieszal cztery typy OKF. Rozbity PER TYP po
granicy sekcji `##`:
10 x decision — pozycje backlogu (w tym backlog-aktywne 28 KB
i backlog-zamkniete 12 KB, ktore zostaja calosciami)
7 x incident — bugi/awarie dotad wtopione w backlog: cutover HA ken,
checkpoint observera, ha-diag-agent node=unknown,
deploy-local ghost-kontenery, paperless-worker config,
deploy-node nie przebudowuje obrazu, ollama bez sterownika
2 x phase — HA configs-as-code, monitoring floty Prometheus
kb/phases/backlog.md zostaje jako cienki indeks (type: phase, status: active):
oryginalna preambula + wygenerowany spis linkow do wszystkich 19 elementow.
23 przychodzace odwolania zostaja przepiete na ta sciezke w grupie 7.
NIE rozbijano po `###` (38 pozycji w "Aktywne" + 13 w "Zamkniete" = 51
plikow). Rozstrzygniecie mowi "rozbij per typ", a nie per pozycja;
rozdrobnienie do 51 plikow rozerwaloby czytelnosc backlogu.
Kontrola: preambula + 19 sekcji == oryginal z HEAD (multizbior niepustych
linii). Tresc pozycji nietknieta.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 15:09:40 +02:00
|
|
|
---
|
|
|
|
|
okf: "0.1"
|
|
|
|
|
type: incident
|
|
|
|
|
visibility: private
|
|
|
|
|
status: active
|
|
|
|
|
updated: 2026-08-03
|
|
|
|
|
links:
|
|
|
|
|
- ../phases/backlog.md
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Fix: paperless-worker@SOLARIA — dwa bugi configu, naprawione i zweryfikowane na żywo (2026-07-12)
|
|
|
|
|
|
|
|
|
|
**Kontekst.** Moduł 3 (`services/paperless-worker/`, split-host OCR worker) był
|
|
|
|
|
zdeployowany i brał zadania z kolejki, ale miał dwa bugi w compose:
|
|
|
|
|
|
|
|
|
|
1. **`command: celery ...` nie odpalał celery.** Obraz paperless-ngx
|
|
|
|
|
(`/sbin/docker-entrypoint.sh`) routuje każdy argument NIE zaczynający się
|
|
|
|
|
od `/` do `manage.py` — więc `celery` lądował jako nieznana subkomenda
|
|
|
|
|
Django, nie jako program. Fix: `command: /usr/sbin/gosu paperless
|
|
|
|
|
/usr/local/bin/celery ...` (ścieżka absolutna wchodzi w gałąź `exec "$@"`
|
|
|
|
|
entrypointu; `gosu paperless` z przodu bo ta gałąź nie dostaje automatycznego
|
|
|
|
|
gosu, inaczej proces poszedłby jako root i zepsuł właściciela plików na NFS).
|
|
|
|
|
2. **Brak współdzielonego `SCRATCH_DIR`.** Paperless@PIHA staguje wgrywany
|
|
|
|
|
plik w `/tmp/paperless` (domyślny `SCRATCH_DIR`) i niesie tę ścieżkę w
|
|
|
|
|
payloadzie zadania celery jako ścieżkę absolutną. Worker@SOLARIA miał
|
|
|
|
|
własny, lokalny `/tmp/paperless` — gdy odbierał zadanie zamiast workera
|
|
|
|
|
PIHA, padał `Cannot consume ...: File not found`. Fix: NFS volume
|
|
|
|
|
`paperless_scratch` (ten sam wzorzec co `data/media/consume`) na
|
|
|
|
|
`/opt/homelab/data/paperless/scratch` (już istniał na PIHA, `chown 1000:1000`),
|
|
|
|
|
mount na `/tmp/paperless` po obu stronach.
|
|
|
|
|
|
|
|
|
|
Oba fixy + uzasadnienie: `services/paperless/docker-compose.yml`,
|
fix(kb): przepiecie wszystkich odwolan wewnetrznych po migracji
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>
2026-08-04 15:12:24 +02:00
|
|
|
`services/paperless-worker/docker-compose.yml`, `kb/services/paperless-worker.md`.
|
feat(kb): SPLIT backlog.md (72 KB) -> 19 dokumentow + cienki indeks
Rozstrzygniecie 1. Monolit mieszal cztery typy OKF. Rozbity PER TYP po
granicy sekcji `##`:
10 x decision — pozycje backlogu (w tym backlog-aktywne 28 KB
i backlog-zamkniete 12 KB, ktore zostaja calosciami)
7 x incident — bugi/awarie dotad wtopione w backlog: cutover HA ken,
checkpoint observera, ha-diag-agent node=unknown,
deploy-local ghost-kontenery, paperless-worker config,
deploy-node nie przebudowuje obrazu, ollama bez sterownika
2 x phase — HA configs-as-code, monitoring floty Prometheus
kb/phases/backlog.md zostaje jako cienki indeks (type: phase, status: active):
oryginalna preambula + wygenerowany spis linkow do wszystkich 19 elementow.
23 przychodzace odwolania zostaja przepiete na ta sciezke w grupie 7.
NIE rozbijano po `###` (38 pozycji w "Aktywne" + 13 w "Zamkniete" = 51
plikow). Rozstrzygniecie mowi "rozbij per typ", a nie per pozycja;
rozdrobnienie do 51 plikow rozerwaloby czytelnosc backlogu.
Kontrola: preambula + 19 sekcji == oryginal z HEAD (multizbior niepustych
linii). Tresc pozycji nietknieta.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 15:09:40 +02:00
|
|
|
Zweryfikowane end-to-end na żywo (branch `task/paperless-worker-fix`, jeszcze
|
|
|
|
|
niezmergowany do master w momencie pisania tego wpisu): 3 dokumenty testowe
|
|
|
|
|
wrzucone do `consume/` na PIHA, jeden odebrany i dokończony przez worker@SOLARIA
|
|
|
|
|
(log: `ocrmypdf`/`tesseract` → `ConsumeTaskPlugin completed with: Success`),
|
|
|
|
|
zero `File not found`. Dokumenty testowe usunięte po teście (`document.delete()`
|
|
|
|
|
+ ręczny cleanup plików) — produkcyjne 6 dokumentów nietknięte.
|
|
|
|
|
|
|
|
|
|
**Otwarte (świadomie odłożone, nie blokuje działania):**
|
|
|
|
|
- `hosts/solaria/services.yaml` i `inventory/topology.yaml` nie mają wpisu
|
|
|
|
|
`paperless-worker` (SOLARIA ma tam tylko `node-agent`) — było zaplanowane w
|
|
|
|
|
cutover checkliście README jako krok "przy deployu", ale nigdy nie zrobione.
|
|
|
|
|
Bez tego wpisu supervisor/observer nie widzą tego serwisu w desired-state —
|
|
|
|
|
drift (np. worker padnie i nie wstanie) nie zostanie automatycznie wykryty
|
|
|
|
|
przez agent system, tylko przez brak przetwarzania kolejki.
|
|
|
|
|
- Test formalnego fallbacku (stop worker@SOLARIA → kolejka mieli na PIHA →
|
|
|
|
|
start → drenaż) nie był wykonany w tej sesji — mechanizm nie zmienił się
|
|
|
|
|
tym fixem (był już OK), ale warto zweryfikować przy okazji.
|
|
|
|
|
|