Resposta atual: não utilize a falha de instalação da versão beta 1.4.2 como modelo de configuração do Paperless-ngx para 2026
A instalação original ficou bloqueada nos 83% no ZimaOS 1.4.2-beta2, e a IceWhale afirmou que essa versão tinha alterado a tecnologia de origem/proxy da instalação de aplicações e que o problema estava a ser corrigido. O ZimaOS atual disponibiliza agora um procedimento dedicado para instalar o Paperless-ngx, e o projeto upstream dispõe de um processo maduro baseado em Docker Compose. Considere o bloqueio de 2025 um erro histórico do instalador, não uma prova de que o Paperless-ngx é fundamentalmente incompatível com o ZimaOS.
Comece pela configuração atual da App Store do ZimaOS
As instruções atuais do ZimaOS utilizam o Paperless-ngx a partir da App Store com a instalação personalizada, para que possa definir o caminho de consumo, as credenciais de administrador, os idiomas de OCR e os valores dos URL fidedignos antes do primeiro arranque. A configuração do Paperless no ZimaOS é a referência específica atual do produto.
Os requisitos do Paperless-ngx ajudam a dimensionar a aplicação antes de executar grandes tarefas de OCR.
Coloque os dados persistentes num armazenamento que possa salvaguardar
O Paperless tem vários tipos de estado: dados da base de dados, dados da aplicação, ficheiros multimédia/documentos, ficheiros exportados e a pasta de consumo. Mantenha esses caminhos persistentes fora da camada descartável do contentor. Se eliminar os dados da aplicação enquanto estiver a resolver problemas, poderá também eliminar as provas ou o estado necessários para perceber por que motivo a instalação anterior falhou.
A configuração Docker do Paperless define os serviços upstream e a implementação recomendada do PostgreSQL.
Compreenda a questão do Tika e do Gotenberg
O Paperless pode funcionar sem Tika/Gotenberg para o fluxo principal de documentos PDF/imagem. O Tika e o Gotenberg são serviços opcionais utilizados quando pretende processar ficheiros do Office e mensagens de e-mail. Se um pacote apresentar uma falha relacionada com o Tika, determine primeiro se realmente precisa dessa funcionalidade, antes de bloquear toda a instalação por causa dela.
As definições do Tika no Paperless apresentam os endpoints e as variáveis de ativação.
Se a instalação parar numa percentagem, observe os contentores em vez de esperar horas
docker ps -a
docker logs --tail=200 paperless-webserver
docker logs --tail=200 paperless-db
docker logs --tail=200 paperless-redisOs nomes exatos dos contentores dependem do pacote da App Store. Procure falhas ao obter imagens, problemas de disponibilidade da base de dados, permissões, configuração de CSRF ou um serviço preso num ciclo de reinício. “83%” é um sintoma da interface; os registos dos contentores identificam o componente que está a falhar.
Corrija a propriedade da pasta de consumo antes de culpar o OCR
O Paperless tem de conseguir ler e mover ficheiros a partir do diretório de consumo. A configuração Docker upstream suporta USERMAP_UID/USERMAP_GID para alinhar as permissões do anfitrião. Se os ficheiros aparecerem na pasta de consumo do anfitrião, mas o Paperless nunca os processar, verifique a propriedade, o caminho de montagem e as notificações do sistema de ficheiros.
Os requisitos das aplicações do ZimaOS ajudam a evitar colocar um arquivo de documentos em crescimento num disco pequeno do sistema operativo.
Configure corretamente o URL externo
Quando o Paperless é acedido através de um endereço do anfitrião ZimaOS ou de um proxy inverso, defina as origens fidedignas e o URL público para o endereço que os utilizadores realmente abrem. Uma configuração incorreta da origem manifesta-se frequentemente mais tarde como um erro 403 de CSRF, apesar de todos os contentores estarem a funcionar corretamente.
Faça uma cópia de segurança conjunta da base de dados e dos documentos
Os ficheiros dos documentos sem a base de dados do Paperless perdem as etiquetas, os correspondentes, os campos personalizados e o estado do fluxo de trabalho; a base de dados sem os ficheiros multimédia perde os documentos propriamente ditos. Faça uma cópia de segurança de ambos como uma única unidade de recuperação e teste o restauro antes de atualizações importantes.
A cópia de segurança do ZimaOS proporciona a camada de recuperação ao nível do NAS.
Perguntas frequentes
Porque é que o Paperless-ngx parou nos 83% no ZimaOS?
No caso original, a IceWhale associou a falha a alterações na origem da aplicação e no proxy do ZimaOS 1.4.2 beta. Num sistema atual, consulte os registos dos contentores em vez de presumir que se trata do mesmo erro antigo.
O Paperless-ngx requer o Tika?
Não, para a gestão principal de documentos PDF/imagem. O Tika e o Gotenberg são opcionais quando precisa de processar documentos do Office e mensagens de e-mail.
Onde deve ficar a pasta de consumo?
Utilize o armazenamento persistente de dados do ZimaOS, com um caminho claro no anfitrião e permissões que permitam ao contentor do Paperless ler e modificar os ficheiros.
Devo eliminar os dados da aplicação e reinstalar?
Apenas depois de compreender quais os dados que serão removidos e de ter uma cópia de segurança. Reinstalar não corrige um caminho de volume, uma permissão ou uma configuração de URL incorretos.
Que base de dados deve utilizar uma nova instalação do Paperless?
Atualmente, o projeto upstream recomenda o PostgreSQL para novas instalações.
