Pierwotna instalacja Paperless-ngx ze sklepu aplikacji ZimaOS nie powiodła się na późnym etapie. Najpierw pojawił się błąd braku autoryzacji podczas pobierania obrazu Tika z GitHub Container Registry, a później błąd DNS dotyczący serwera lustrzanego rejestru. To sprawia, że wątek jest bardziej złożony niż stwierdzenie „Paperless nie działa”: zawodny był opcjonalny mechanizm usługi/obrazu Tika, a punkt końcowy rejestru zmienił się między próbami.
Publiczny wątek nie doprowadził do potwierdzonej poprawki Paperless-ngx w sklepie aplikacji ZimaOS. Jeden z użytkowników zmienił obraz Tika na obraz Apache i osiągnął 100% instalacji, ale stos nadal nie uruchomił się poprawnie. Obecna dokumentacja Paperless-ngx oferuje wyraźniejszą ścieżkę: należy używać utrzymywanych szablonów Docker Compose i włączać wariant z Tika/Gotenberg tylko wtedy, gdy potrzebne są te formaty dokumentów.
Pierwsza awaria była błędem autoryzacji GHCR
Pierwotny błąd wystąpił przy około 80%:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedUsunięcie lokalnych obrazów Dockera i ponowna instalacja nie zmieniły rezultatu, co wskazuje, że przyczyną nie był po prostu nieaktualny lokalny obraz.
Kolejna próba zakończyła się niepowodzeniem rozpoznawania DNS
Dwa dni później błąd zmienił się w nieudaną próbę wyszukania DNS nazwy hosta serwera lustrzanego rejestru. Dlatego członek społeczności zasugerował sprawdzenie rozpoznawania nazw, podstawowej łączności HTTPS, filtrowania DNS, działania VPN/proxy oraz ręcznego pobrania obrazu.
Była to diagnostyka społeczności, a nie potwierdzona przez IceWhale przyczyna źródłowa.
Tika jest obecnie opcjonalna w Paperless-ngx
Obecna dokumentacja Paperless-ngx informuje, że Tika i Gotenberg są opcjonalnymi usługami używanymi do obsługi dokumentów pakietu Office, takich jak DOC/XLSX/ODT, oraz do analizowania wiadomości e-mail. Jeśli te formaty nie są potrzebne, włączanie Tika nie jest konieczne.
Jeśli są potrzebne, użyj utrzymywanego wariantu Compose zawierającego Tika i Gotenberg zamiast starego odwołania do obrazu ze sklepu aplikacji.
Obecny Docker Compose projektu nadrzędnego to najlepszy punkt odniesienia
Obecny przewodnik konfiguracji Paperless-ngx zaleca Dockera większości użytkowników i udostępnia utrzymywane pliki Compose. W przypadku nowych instalacji zalecany jest PostgreSQL, a szablony z włączoną usługą Tika są udostępniane osobno.
Jeśli pakiet ze sklepu aplikacji ZimaOS jest nieaktualny lub odwołuje się do niedostępnego obrazu pomocniczego, użyj obecnego modelu instalacji Paperless-ngx Docker Compose.
Sama zmiana obrazu Tika może nie wystarczyć
Jeden z uczestników zastąpił obraz Tika obrazem apache/tika:latest. Instalacja osiągnęła 100%, ale aplikacja nadal nie działała po uruchomieniu.
Ten negatywny rezultat ma znaczenie, ponieważ Paperless wymaga zgodności punktu końcowego usługi, flagi funkcji i integracji z Gotenbergiem z konfiguracją Compose. Zastąpienie obrazu kontenera nie musi oznaczać pełnej migracji stosu.
Przechowuj trwałe dane Paperless na głównej przestrzeni dyskowej
Paperless może zwiększać zajmowane miejsce przez przechowywane dokumenty, miniatury, dane OCR, indeksy wyszukiwania i bazę danych. Obecne zalecenia ZimaOS mówią, aby przed instalacją aplikacji intensywnie korzystających z pamięci przenieść dane aplikacji poza dysk systemowy.
Obecny model ścieżek pamięci aplikacji ZimaOS jest szczególnie istotny w przypadku Paperless, ponieważ rozmiar jego danych może znacznie przekroczyć rozmiar obrazu Dockera.
Uprawnienia mają znaczenie dla folderu przetwarzania dokumentów
Obecna dokumentacja Paperless-ngx udostępnia zmienne USERMAP_UID i USERMAP_GID, aby kontener mógł zapisywać dane w folderach hosta podłączonych jako bind mount. Jeśli stos się instaluje, ale nie może importować dokumentów, sprawdź te wartości oraz uprawnienia folderów na hoście, zamiast ponownie zajmować się problemami z rejestrem.
Nie traktuj nazwy hosta serwera lustrzanego rejestru jako aplikacji Paperless
Drugi błąd źródłowy odwoływał się do nazwy hosta przypominającej serwer lustrzany, a nie do głównego punktu końcowego ghcr.io. To rozróżnienie ma znaczenie: pakiet aplikacji może być całkowicie prawidłowy, podczas gdy skonfigurowany serwer lustrzany obrazu, serwer DNS lub regionalna ścieżka rejestru mogą być niedostępne.
Jeśli ręczne pobranie z nadrzędnego rejestru zakończy się powodzeniem, ale sklep aplikacji nadal próbuje używać uszkodzonego serwera lustrzanego, problem dotyczy warstwy pakietu lub routingu rejestru, a nie samego Paperless.
Oddziel awarię pobierania obrazu od awarii uruchamiania kontenera
Pierwsza próba opisana w źródle nie zakończyła pobierania wszystkich wymaganych obrazów. Późniejszy eksperyment z Apache Tika osiągnął 100% instalacji, ale następnie zakończył się niepowodzeniem po uruchomieniu. Są to dwa różne etapy awarii i wymagają odmiennych danych diagnostycznych.
- Etap pobierania: uwierzytelnianie w rejestrze, DNS, dostępność serwera lustrzanego, znacznik obrazu.
- Etap uruchamiania: zmienne środowiskowe, połączenie z bazą danych, punkty końcowe Tika/Gotenberg, woluminy, uprawnienia i testy stanu.
Utwórz kopię działającej instancji Paperless przed zastąpieniem stosu ze sklepu aplikacji
Jeśli Paperless jest już używany, nie zmieniaj szablonów Compose wyłącznie po to, aby naprawić usługę pomocniczą, bez wcześniejszego zabezpieczenia dokumentów i bazy danych. Obecny Paperless udostępnia narzędzie eksportu przeznaczone do tworzenia kopii zapasowych i migracji.
W przypadku nowej instalacji najprościej rozpocząć od utrzymywanego pliku Compose projektu nadrzędnego; w przypadku istniejącej instalacji przed przepisaniem stosu zachowaj bieżącą bazę danych i ścieżki multimediów.
Najczęstsze pytania dotyczące instalacji Paperless-ngx
Czy potwierdzono, że przyczyną awarii z 2025 roku był problem z DNS?
Nie. Wątek wykazał zarówno błędy autoryzacji, jak i DNS, a oficjalna ostateczna diagnoza nie została opublikowana.
Czy Tika jest wymagana podczas każdej instalacji Paperless-ngx?
Nie. Jest opcjonalna i jest potrzebna głównie do obsługi dokumentów pakietu Office oraz analizowania wiadomości e-mail.
Czy przejście na apache/tika w pełni rozwiązało przypadek opisany w źródle?
Nie. Jeden z użytkowników osiągnął 100% instalacji, ale aplikacja nadal się nie uruchomiła.
