A instalação do Paperless-ngx a partir da App Store do ZimaOS falhou numa fase avançada do processo: primeiro surgiu um erro de não autorizado ao obter uma imagem do Tika a partir do GitHub Container Registry e, mais tarde, uma falha de DNS para um espelho de registo. Esta combinação torna o tópico mais complexo do que simplesmente dizer que “o Paperless está avariado”: o componente que falhou foi um serviço/caminho de imagem opcional do Tika, e o próprio endpoint do registo mudou entre as tentativas.
O tópico público nunca chegou a uma solução confirmada para a App Store do ZimaOS. Um utilizador alterou a imagem do Tika para a imagem da Apache e chegou aos 100% da instalação, mas a pilha continuou sem arrancar. A documentação atual do Paperless-ngx fornece agora um caminho mais claro: utilizar os modelos Docker Compose mantidos pelo projeto e ativar a variante Tika/Gotenberg apenas quando esses formatos de documentos forem necessários.
A Primeira Falha Foi um Erro de Autorização do GHCR
O erro original ocorreu por volta dos 80%:
Head "https://ghcr.io/v2/paperless-ngx/tika/manifests/2.9.1-minimal": unauthorizedEliminar as imagens Docker locais e reinstalar não alterou o resultado, o que aponta contra uma simples imagem local desatualizada.
A Tentativa Seguinte Falhou na Resolução de DNS
Dois dias mais tarde, o erro tinha mudado para uma pesquisa de DNS falhada para o nome de anfitrião de um espelho de registo. Por isso, um membro da comunidade sugeriu verificar a resolução de nomes, a conectividade HTTPS básica, a filtragem de DNS, o comportamento da VPN/proxy e uma obtenção manual da imagem.
Esses procedimentos eram diagnósticos da comunidade, não uma causa-raiz confirmada pela IceWhale.
O Tika É Opcional no Paperless-ngx Atual
A documentação atual do Paperless-ngx indica que o Tika e o Gotenberg são serviços opcionais utilizados para documentos do Office, como DOC/XLSX/ODT, e para a análise de emails. Se esses formatos não forem necessários, não é preciso ativar o Tika.
Se forem necessários, utilize a variante Compose mantida pelo projeto que inclui o Tika e o Gotenberg, em vez de uma referência antiga à imagem da App Store.
O Docker Compose Atual do Projeto É a Melhor Base
O guia de configuração atual do Paperless-ngx recomenda o Docker para a maioria dos utilizadores e disponibiliza ficheiros Compose mantidos pelo projeto. Para novas instalações, recomenda-se utilizar PostgreSQL, e os modelos com Tika são fornecidos separadamente.
Utilize o modelo atual de instalação do Paperless-ngx com Docker Compose se o pacote da App Store do ZimaOS estiver desatualizado ou fizer referência a uma imagem auxiliar indisponível.
Alterar Apenas a Imagem do Tika Pode Não Ser Suficiente
Um participante substituiu a imagem do Tika por apache/tika:latest. A instalação chegou aos 100%, mas a aplicação continuou a falhar após o arranque.
Esse resultado negativo é importante, porque o Paperless precisa que o endpoint do serviço, o sinalizador da funcionalidade e a integração com o Gotenberg correspondam à configuração do Compose. A substituição da imagem de um contentor não constitui necessariamente uma migração completa da pilha.
Coloque os Dados Persistentes do Paperless no Espaço de Armazenamento Principal
O Paperless pode crescer através dos documentos consumidos, miniaturas, dados de OCR, índices de pesquisa e base de dados. O ZimaOS atual recomenda mover os dados das aplicações para fora da unidade do sistema antes de instalar aplicações que exijam muito armazenamento.
O modelo atual de caminhos de armazenamento de aplicações do ZimaOS é particularmente relevante para o Paperless, porque a sua utilização de dados pode crescer muito além do tamanho da imagem Docker.
As Permissões São Importantes para a Pasta de Consumo
A documentação atual do Paperless-ngx disponibiliza USERMAP_UID e USERMAP_GID para que o contentor possa escrever em pastas do anfitrião montadas por bind. Se a pilha for instalada mas não conseguir importar documentos, verifique estes valores e as permissões das pastas do anfitrião, em vez de voltar a investigar problemas do registo.
Não Confunda o Nome de Anfitrião de um Espelho de Registo com a Aplicação Paperless
O segundo erro de origem referia um nome de anfitrião com formato de espelho, em vez do endpoint principal ghcr.io. Esta distinção é importante: um pacote de aplicação pode ser perfeitamente válido, enquanto o espelho de imagens configurado, o servidor DNS ou o caminho de registo regional podem estar indisponíveis.
Se uma obtenção manual a partir do registo upstream funcionar, mas a App Store continuar a tentar utilizar um espelho avariado, o problema pertence à camada do pacote ou do encaminhamento do registo, não ao próprio Paperless.
Separe as Falhas de Obtenção da Imagem das Falhas de Arranque do Contentor
A primeira tentativa de origem nunca terminou de obter todas as imagens necessárias. A experiência posterior com o Tika da Apache chegou aos 100% da instalação, mas falhou depois do arranque. Estas são duas fases de falha diferentes e requerem evidências diferentes.
- Fase de obtenção: autenticação no registo, DNS, disponibilidade do espelho e etiqueta da imagem.
- Fase de arranque: variáveis de ambiente, conectividade à base de dados, endpoints do Tika/Gotenberg, volumes, permissões e verificações de estado.
Faça uma Cópia de Segurança de uma Instância Funcional do Paperless Antes de Substituir a Pilha da App Store
Se o Paperless já estiver a ser utilizado, não mude os modelos Compose apenas para corrigir um serviço auxiliar sem proteger primeiro os documentos e a base de dados. O Paperless upstream atual inclui um exportador específico para cópias de segurança e migrações.
Para uma instalação nova, é mais simples começar pelo ficheiro Compose upstream mantido pelo projeto; para uma instalação existente, preserve os caminhos atuais da base de dados e dos ficheiros multimédia antes de reescrever a pilha.
Perguntas Frequentes sobre a Instalação do Paperless-ngx
A falha de 2025 foi conclusivamente um problema de DNS?
Não. O tópico apresentou erros de autorização e de DNS, e não foi publicada nenhuma explicação final oficial.
O Tika é necessário em todas as instalações do Paperless-ngx?
Não. É opcional e é principalmente necessário para documentos do Office e para a análise de emails.
A mudança para apache/tika resolveu totalmente o caso de origem?
Não. Um utilizador chegou aos 100% da instalação, mas a aplicação continuou sem funcionar.
