Este tutorial de dezembro de 2025 é um dos guias comunitários mais detalhados para o Paperless-ngx no ZimaOS, mas está associado a um pacote BigBear específico e ao ZimaOS 1.5.3 Plus. As partes duradouras são os conceitos de armazenamento e configuração: atribuir à pasta de consumo uma localização persistente clara, definir corretamente o URL da aplicação, configurar os idiomas de OCR e compreender os serviços opcionais Tika/Gotenberg.
Alguns detalhes da fonte precisam de uma ressalva atual. A configuração Docker a montante do Paperless-ngx evoluiu, o PostgreSQL é agora recomendado para novas instalações, os ficheiros Compose atuais solicitam um superutilizador durante a primeira configuração e o Tika/Gotenberg continua a ser opcional, em vez de ser obrigatório para todos os fluxos de trabalho de documentos.
O tutorial de origem foi testado num modesto ZimaBoard 2
O autor documentou um sistema baseado num N150 com 16 GB de RAM a executar o ZimaOS 1.5.3 Plus. O objetivo era o acesso através da rede local ou do Tailscale para utilização doméstica, e não a exposição direta ao público.
Esse âmbito é importante, porque uma implementação na Internet pública requer um plano diferente para HTTPS, proxy inverso, autenticação e segurança.
O guia utilizou a instalação personalizada do BigBear Paperless-ngx
O fluxo de trabalho de origem procurou o pacote BigBear Paperless-ngx na App Store, abriu o menu pendente de instalação e escolheu Instalação personalizada, para que os volumes e os valores de ambiente pudessem ser editados antes do primeiro arranque.
Esse é um fluxo de trabalho específico do pacote. Uma definição atual da aplicação pode adicionar, remover ou mudar o nome de serviços e variáveis.
Atribua à pasta de consumo um caminho persistente claro no anfitrião
/usr/src/paperless/consume como a pasta com que os utilizadores têm maior probabilidade de interagir ao adicionar documentos.A documentação atual do Paperless a montante continua a utilizar /usr/src/paperless/consume como o destino padrão do contentor e suporta explicitamente a alteração do lado do anfitrião dessa montagem de ligação.
O tutorial definiu as variáveis de administrador, consumidor, OCR e URL
Principais opções de origem incluídas:
- nome de utilizador/palavra-passe de administrador personalizados;
- consumo recursivo de documentos;
- eliminação dos originais da pasta de consumo após uma ingestão bem-sucedida;
- Limpeza de OCR e definições de idioma;
- Origem fidedigna do CSRF e URL da aplicação;
- Endpoints do Tika/Gotenberg.
O URL do PAPERLESS_URL e as origens CSRF têm de corresponder à forma como acede efetivamente ao Paperless
O tutorial advertia que uma configuração incorreta do URL/origem poderia causar uma falha de verificação CSRF 403. Isto continua conceptualmente correto.
A documentação atual do Paperless indica PAPERLESS_URL deve ser definido quando a aplicação está atrás de um proxy inverso e deve representar o domínio/URL utilizado externamente. Não codifique o endereço LAN do autor da fonte noutra instalação.
As definições de OCR também foram ajustadas dentro do Paperless
As línguas de OCR devem corresponder aos pacotes linguísticos disponíveis no contentor. Adicionar línguas pode aumentar o tamanho da imagem ou alterar os requisitos de contentores rootless, dependendo do pacote atual.
Reiniciar depois de cada grande lote de consumo é um conselho da fonte, não um requisito a montante
O Paperless-ngx atual foi concebido para monitorizar continuamente o diretório de consumo. A documentação a montante não indica que os lotes grandes exijam normalmente um reinício. Se os documentos deixarem de ser processados, verifique as permissões, os registos do consumidor, o suporte de notificações do sistema de ficheiros e o estado do broker/trabalhador, em vez de transformar o reinício num ritual obrigatório.
A configuração atual a montante recomenda o PostgreSQL para novas instalações
A configuração Docker atual do Paperless-ngx recomenda o PostgreSQL para novas instalações, embora o SQLite e o MariaDB continuem disponíveis em configurações suportadas.
Para um arquivo de documentos de longo prazo, isto torna a topologia atual do Compose a montante uma referência melhor do que presumir que o serviço de base de dados exato do BigBear 2025 permanece inalterado.
O Tika e o Gotenberg são opcionais
A documentação atual do Paperless indica que o Tika e o Gotenberg são necessários para analisar documentos do Office, como DOC/XLSX/ODT, e ficheiros de e-mail. Se apenas importar formatos tratados pela stack principal do Paperless, esta funcionalidade pode permanecer desativada.
Utilize a configuração atual do Paperless-ngx com Docker antes de reconstruir manualmente a stack histórica do BigBear.
As permissões da pasta de consumo são mais importantes do que reinícios repetidos
A configuração atual a montante expõe USERMAP_UID e USERMAP_GID para que o contentor possa escrever em montagens de ligação do anfitrião. Se o Paperless detetar uma pasta consume, mas não conseguir processar ou eliminar ficheiros, verifique a propriedade do diretório mapeado e a identidade do contentor.
No ZimaOS, verifique também se o caminho consume do anfitrião está no armazenamento gerido pretendido e não num mapeamento de volume só de leitura.
Eliminar os originais de /consume não é o mesmo que eliminar documentos arquivados
A fonte ativou PAPERLESS_CONSUMER_DELETE_ORIGINALS=true. Isto controla o que acontece ao ficheiro de entrada no diretório consume após uma ingestão bem-sucedida. O documento arquivado gerido pelo Paperless permanece no respetivo armazenamento de multimédia.
Teste este comportamento com documentos descartáveis antes de apontar um scanner automatizado ou serviço de sincronização para uma pasta de produção.
As respostas sobre o Paperless-AI pertencem a uma integração separada
As respostas posteriores abordaram o Paperless-AI a ler documentos através da API do Paperless, mas a falhar ao analisar/escrever etiquetas com a configuração OpenAI integrada. Os utilizadores relataram que o Mistral funcionava e que a configuração manual da OpenAI contornava o problema.
Essas respostas não provam que a instalação principal do Paperless-ngx esteja avariada. O Paperless-AI é uma integração de terceiros separada, com a sua própria configuração de fornecedor/API.
Os erros 500 posteriores e as questões sobre palavras-passe não foram resolvidos na discussão
Em fevereiro de 2026, um utilizador comunicou um erro HTTP 500 durante o carregamento, e, em maio de 2026, outro utilizador não conseguiu fazer funcionar as palavras-passe esperadas. A discussão pública não contém diagnósticos finais para esses casos.
Não transforme as credenciais de exemplo do tutorial original num método de início de sessão universal para versões posteriores do BigBear.
Exporte os dados do Paperless antes de alterações importantes nos pacotes
Atualmente, o Paperless disponibiliza um exportador de documentos que inclui documentos, miniaturas, metadados e informações derivadas da base de dados, para fluxos de trabalho de migração/cópia de segurança. Utilize a exportação com conhecimento da aplicação, além de cópias de segurança normais do armazenamento, antes de substituir a base de dados ou a pilha do Compose.
Perguntas frequentes sobre o Paperless-ngx no ZimaOS
O Tika é necessário em todas as instalações do Paperless-ngx?
Não. É opcional e necessário sobretudo para documentos do Office e análise de e-mails.
Os grandes lotes de documentos consumidos normalmente exigem um reinício?
O autor da fonte recomendou-o com base na sua experiência, mas a documentação atual do projeto original não indica que reiniciar seja normalmente necessário.
Que base de dados recomenda atualmente o Paperless para novas instalações?
O PostgreSQL é o backend recomendado para novas implementações com Docker.
O Paperless-AI faz parte do próprio Paperless-ngx?
Não. É uma integração de terceiros separada, abordada mais adiante na discussão.
