Ten samouczek z grudnia 2025 roku jest jednym z bardziej szczegółowych poradników społeczności dotyczących Paperless-ngx w ZimaOS, ale odnosi się do konkretnego pakietu BigBear i ZimaOS 1.5.3 Plus. Trwałe elementy to koncepcje dotyczące pamięci masowej i konfiguracji: nadaj folderowi consume jasną, trwałą lokalizację, ustaw prawidłowy adres URL aplikacji, skonfiguruj języki OCR i poznaj opcjonalne usługi Tika/Gotenberg.
Niektóre szczegóły źródłowe wymagają aktualnego zastrzeżenia. Konfiguracja Docker Paperless-ngx w projekcie nadrzędnym ewoluowała, PostgreSQL jest obecnie zalecaną bazą danych dla nowych instalacji, bieżące pliki Compose proszą o superużytkownika podczas pierwszej konfiguracji, a Tika/Gotenberg nadal są opcjonalne i nie są wymagane w każdym procesie przetwarzania dokumentów.
Samouczek źródłowy przetestowano na skromnym ZimaBoard 2
Autor opisał system oparty na N150 z 16 GB pamięci RAM, działający pod kontrolą ZimaOS 1.5.3 Plus. Celem był dostęp z sieci lokalnej lub przez Tailscale do użytku domowego, a nie bezpośrednie udostępnienie publiczne.
Ten zakres ma znaczenie, ponieważ wdrożenie w publicznym Internecie wymaga innego planu dotyczącego HTTPS, odwrotnego serwera proxy, uwierzytelniania i bezpieczeństwa.
Przewodnik wykorzystał instalację niestandardową BigBear Paperless-ngx
W opisanym procesie wyszukano w App Store pakiet BigBear Paperless-ngx, otwarto listę instalacji i wybrano instalację niestandardową, aby przed pierwszym uruchomieniem można było edytować wolumeny i wartości środowiskowe.
To procedura charakterystyczna dla konkretnego pakietu. Aktualna definicja aplikacji może dodawać, usuwać lub zmieniać nazwy usług i zmiennych.
Nadaj katalogowi consume jasną, trwałą ścieżkę na hoście
/usr/src/paperless/consume jako folder, z którym użytkownicy najprawdopodobniej będą mieć kontakt podczas dodawania dokumentów.Aktualna dokumentacja Paperless nadal wskazuje /usr/src/paperless/consume jako standardową lokalizację docelową kontenera i wyraźnie obsługuje zmianę części tego montowania dotyczącej hosta.
Samouczek ustawił zmienne administratora, konsumenta, OCR i adresu URL
Najważniejsze opcje źródłowe obejmowały:
- niestandardowa nazwa użytkownika i hasło administratora;
- rekurencyjne przetwarzanie dokumentów;
- usuwanie oryginałów z folderu consume po pomyślnym zaimportowaniu;
- Czyszczenie OCR i ustawienia języka;
- Zaufane źródło CSRF i adres URL aplikacji;
- Adresy endpointów Tika/Gotenberg.
Adresy PAPERLESS_URL i CSRF muszą odpowiadać rzeczywistemu sposobowi uzyskiwania dostępu do Paperless
Poradnik ostrzegał, że nieprawidłowa konfiguracja URL/origin może spowodować błąd weryfikacji CSRF 403. Pozostaje to prawidłowe w ujęciu ogólnym.
Aktualna dokumentacja Paperless informuje PAPERLESS_URL powinien być ustawiony, gdy aplikacja działa za odwrotnym serwerem proxy, i powinien wskazywać domenę/URL używane z zewnątrz. Nie wpisuj na stałe adresu LAN autora źródłowego do innej instalacji.
Ustawienia OCR zostały również zmienione w Paperless
Języki OCR muszą odpowiadać pakietom językowym dostępnym w kontenerze. Dodanie języków może zwiększyć rozmiar obrazu lub zmienić wymagania dotyczące kontenerów bez uprawnień root, zależnie od bieżącego pakietu.
Ponowne uruchamianie po każdej dużej partii dokumentów w katalogu Consume to zalecenie źródłowe, a nie wymaganie upstream
Bieżący Paperless-ngx został zaprojektowany do ciągłego monitorowania katalogu Consume. Dokumentacja upstream nie stwierdza, że duże partie dokumentów zwykle wymagają ponownego uruchomienia. Jeśli dokumenty przestają być przetwarzane, sprawdź uprawnienia, logi konsumenta, obsługę powiadomień systemu plików oraz stan brokera i workera, zamiast traktować ponowne uruchomienie jako obowiązkowy rytuał.
Bieżąca konfiguracja upstream zaleca PostgreSQL dla nowych instalacji
Bieżąca konfiguracja Docker Paperless-ngx zaleca PostgreSQL dla nowych instalacji, chociaż SQLite i MariaDB pozostają dostępne w obsługiwanych konfiguracjach.
W przypadku długoterminowego archiwum dokumentów sprawia to, że bieżąca topologia Compose upstream jest lepszym punktem odniesienia niż założenie, że dokładna usługa bazy danych BigBear 2025 nadal pozostaje niezmieniona.
Tika i Gotenberg są opcjonalne
Aktualna dokumentacja Paperless informuje, że Tika i Gotenberg są potrzebne do analizowania dokumentów pakietu Office, takich jak DOC/XLSX/ODT, oraz plików e-mail. Jeśli importujesz wyłącznie formaty obsługiwane przez podstawowy stos Paperless, tę funkcję można pozostawić wyłączoną.
Przed ręcznym odtwarzaniem historycznego stosu BigBear użyj bieżącej konfiguracji Paperless-ngx Docker.
Uprawnienia do folderu Consume mają większe znaczenie niż wielokrotne ponowne uruchamianie
Bieżąca konfiguracja upstream udostępnia USERMAP_UID i USERMAP_GID aby kontener mógł zapisywać w podłączonych katalogach hosta. Jeśli Paperless widzi folder consume, ale nie może przetwarzać ani usuwać plików, sprawdź właściciela zamapowanego katalogu oraz tożsamość kontenera.
W ZimaOS sprawdź również, czy ścieżka consume na hoście znajduje się w zamierzonej zarządzanej pamięci masowej, a nie w mapowaniu woluminu tylko do odczytu.
Usuwanie oryginałów z /consume to nie to samo co usuwanie zarchiwizowanych dokumentów
W źródle włączono PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Ta opcja określa, co dzieje się z plikiem wejściowym w katalogu consume po pomyślnym zaimportowaniu. Zarchiwizowany dokument zarządzany przez Paperless pozostaje w jego magazynie multimediów.
Przetestuj to działanie na dokumentach przeznaczonych do usunięcia, zanim wskażesz produkcyjny folder automatycznemu skanerowi lub usłudze synchronizacji.
Odpowiedzi dotyczące Paperless-AI należą do osobnej integracji
W późniejszych odpowiedziach omówiono, jak Paperless-AI odczytuje dokumenty za pośrednictwem API Paperless, ale nie może analizować ani zapisywać tagów przy użyciu wbudowanej konfiguracji OpenAI. Użytkownicy zgłaszali, że Mistral działał, a ręczna konfiguracja OpenAI pozwalała obejść problem.
Te odpowiedzi nie dowodzą, że podstawowa instalacja Paperless-ngx jest niesprawna. Paperless-AI to osobna integracja zewnętrzna, z własną konfiguracją dostawcy i interfejsu API.
Późniejsze błędy 500 i pytania dotyczące haseł nie zostały rozwiązane w wątku
Użytkownik zgłosił w lutym 2026 roku błąd HTTP 500 podczas przesyłania, a inny użytkownik w maju 2026 roku nie mógł uzyskać poprawnego działania oczekiwanych haseł. Publiczny wątek nie zawiera ostatecznych diagnoz tych przypadków.
Nie zamieniaj przykładowych danych logowania z oryginalnego samouczka w uniwersalną instrukcję logowania dla późniejszych wydań BigBear.
Eksportowanie danych Paperless przed poważnymi zmianami pakietów
Obecny Paperless udostępnia eksporter dokumentów obejmujący dokumenty, miniatury, metadane i informacje pochodzące z bazy danych na potrzeby migracji i tworzenia kopii zapasowych. Przed zastąpieniem bazy danych lub stosu Compose użyj eksportu uwzględniającego aplikację oraz standardowych kopii zapasowych pamięci masowej.
FAQ dotyczące Paperless-ngx na ZimaOS
Czy Tika jest wymagana przy każdej instalacji Paperless-ngx?
Nie. Jest to opcjonalne i potrzebne głównie w przypadku dokumentów pakietu Office oraz analizowania wiadomości e-mail.
Czy duże partie zadań consume zwykle wymagają ponownego uruchomienia?
Autor źródłowy zalecał to na podstawie własnych doświadczeń, ale aktualna dokumentacja projektu nadrzędnego nie wskazuje, że ponowne uruchamianie jest standardowo wymagane.
Jaką bazę danych Paperless obecnie zaleca przy nowych instalacjach?
PostgreSQL jest zalecanym backendem dla nowych wdrożeń Docker.
Czy Paperless-AI jest częścią samego Paperless-ngx?
Nie. To osobna integracja zewnętrzna, omówiona w dalszej części wątku.
