Obecna odpowiedź: nie używaj nieudanej instalacji wersji beta 1.4.2 jako modelu konfiguracji Paperless-ngx w 2026 roku
Pierwotna instalacja zatrzymała się na poziomie 83% w ZimaOS 1.4.2-beta2, a IceWhale poinformowało, że w tej wersji zmieniono technologię źródła/proxy instalacji aplikacji i że problem jest naprawiany. Obecne wersje ZimaOS udostępniają dedykowaną procedurę instalacji Paperless-ngx, a projekt nadrzędny oferuje dojrzałą ścieżkę opartą na Docker Compose. Traktuj zatrzymanie instalacji z 2025 roku jako historyczny błąd instalatora, a nie dowód na fundamentalną niezgodność Paperless-ngx z ZimaOS.
Zacznij od bieżącej konfiguracji sklepu aplikacji ZimaOS
Aktualne instrukcje ZimaOS wykorzystują Paperless-ngx ze sklepu aplikacji z opcją instalacji niestandardowej, dzięki czemu przed pierwszym uruchomieniem możesz ustawić ścieżkę danych, dane logowania administratora, języki OCR oraz wartości zaufanych adresów URL. Konfiguracja Paperless w ZimaOS stanowi obecnie podstawę dla tego produktu.
Wymagania Paperless-ngx pomagają dobrać odpowiednie zasoby przed rozpoczęciem dużych zadań OCR.
Umieść dane trwałe na nośniku, który możesz tworzyć kopie zapasowe
Paperless przechowuje kilka rodzajów danych: dane bazy danych, dane aplikacji, multimedia/dokumenty, wyeksportowane pliki oraz folder consume. Przechowuj te ścieżki trwale, poza nietrwałą warstwą kontenera. Jeśli podczas debugowania usuniesz AppData, możesz również usunąć dowody lub stan potrzebny do zrozumienia przyczyny poprzedniej nieudanej instalacji.
Konfiguracja Paperless w Dockerze definiuje usługi nadrzędne i zalecane wdrożenie PostgreSQL.
Rozstrzygnij kwestię Tika i Gotenberg
Paperless może działać bez Tika/Gotenberg w przypadku podstawowej obsługi dokumentów PDF i obrazów. Tika i Gotenberg to opcjonalne usługi używane do obsługi plików Office i analizy wiadomości e-mail. Jeśli pakiet zgłasza błąd związany z Tika, przed zablokowaniem całej instalacji sprawdź, czy rzeczywiście potrzebujesz tej funkcji.
Ustawienia Tika w Paperless zawierają adresy punktów końcowych i zmienne aktywacyjne.
Jeśli instalacja zatrzyma się na określonym procencie, obserwuj kontenery zamiast czekać godzinami
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redisDokładne nazwy kontenerów zależą od pakietu ze sklepu aplikacji. Szukaj błędów pobierania obrazu, gotowości bazy danych, uprawnień, konfiguracji CSRF lub usługi, która utknęła w pętli ponownego uruchamiania. „83%” to objaw w interfejsie; logi kontenera wskażą wadliwy komponent.
Napraw właściciela folderu consume, zanim obwinisz OCR
Paperless musi móc odczytywać pliki z katalogu consume i przenosić je z tego katalogu. Nadrzędna konfiguracja Dockera obsługuje zmienne USERMAP_UID/USERMAP_GID służące do dopasowania uprawnień hosta. Jeśli pliki pojawiają się w folderze consume na hoście, ale Paperless nigdy ich nie przetwarza, sprawdź właściciela, ścieżkę montowania i powiadomienia systemu plików.
Wymagania aplikacji ZimaOS pomagają uniknąć przechowywania rosnącego archiwum dokumentów na małym dysku systemowym.
Poprawnie skonfiguruj zewnętrzny adres URL
Gdy uzyskujesz dostęp do Paperless przez adres hosta ZimaOS lub odwrotne proxy, ustaw zaufane źródła oraz publiczny adres URL na adres, który użytkownicy rzeczywiście otwierają. Błędna konfiguracja źródła często ujawnia się później jako błąd CSRF 403, mimo że wszystkie kontenery działają prawidłowo.
Twórz kopie zapasowe bazy danych i dokumentów razem
Same pliki dokumentów bez bazy danych Paperless tracą tagi, korespondentów, pola niestandardowe i stan przepływu pracy; sama baza danych bez multimediów traci rzeczywiste dokumenty. Twórz kopie zapasowe obu elementów jako jednego zestawu do odtworzenia i przetestuj przywracanie przed większymi aktualizacjami.
Kopia zapasowa ZimaOS zapewnia warstwę odzyskiwania na poziomie NAS.
FAQ
Dlaczego Paperless-ngx zatrzymał się na poziomie 83% w ZimaOS?
W opisanym przypadku IceWhale powiązało awarię ze zmianami źródła aplikacji/proxy w wersji beta ZimaOS 1.4.2. W aktualnym systemie sprawdź logi kontenerów, zamiast zakładać, że wystąpił ten sam dawny błąd.
Czy Paperless-ngx wymaga Tika?
Nie w przypadku podstawowego zarządzania dokumentami PDF i obrazami. Tika i Gotenberg są opcjonalne, gdy potrzebujesz obsługi dokumentów Office i analizy wiadomości e-mail.
Gdzie powinien znajdować się folder consume?
Użyj trwałego magazynu danych ZimaOS z jasno określoną ścieżką na hoście oraz uprawnieniami umożliwiającymi kontenerowi Paperless odczytywanie i modyfikowanie plików.
Czy powinienem usunąć AppData i zainstalować aplikację ponownie?
Tylko wtedy, gdy rozumiesz, jakie dane zostaną usunięte, i masz kopię zapasową. Ponowna instalacja nie naprawi błędnej ścieżki woluminu, uprawnień ani konfiguracji adresu URL.
Jakiej bazy danych powinien użyć nowy instalator Paperless?
Projekt nadrzędny obecnie zaleca PostgreSQL w przypadku nowych instalacji.
