Casos indicados:

• Arquivar notas fiscais domésticas, certificados de garantia, apólices de seguro e contratos de aluguel;
• Autônomos que guardam comprovantes de reembolso, faturas de fornecedores e material fiscal;
• Equipes pequenas que compartilham documentos de projeto, mas precisam gerenciá-los por tags e permissões;
• Coletar continuamente arquivos PDF, JPEG, PNG e TIFF de scanners, celulares ou e-mail;
• Querer buscar com OCR o texto dentro de arquivos digitalizados em vez de navegar manualmente pelas pastas.

Casos não indicados:

• Você só quer sincronizar fotos e arquivos comuns e não precisa de OCR de jeito nenhum;
• Você precisa que várias pessoas editem documentos do Office em tempo real;
• Você precisa de assinatura eletrônica de nível empresarial, aprovações complexas e auditoria de conformidade;
• Você não tem backups confiáveis, mas pretende guardar seu único contrato original em uma única VPS.

O Paperless-ngx não substitui um sistema de backup. Seu diretório de mídia, banco de dados e diretório de consumo são todos dados importantes e devem ser usados junto com snapshots da VPS, armazenamento de objetos ou outra máquina.

Se você já usa o Nextcloud, pode tratar o Paperless-ngx como uma camada de arquivamento de documentos em vez de criar outro "armazenamento em nuvem para tudo". Os dois podem coexistir, mas não deixe vários programas gravarem ao mesmo tempo no mesmo diretório de mídia, ou você facilmente terá problemas de permissão, importações duplicadas e índices inconsistentes.

Este artigo se baseia na versão estável oficial verificada em agosto de 2026:

Paperless-ngx v3.0.5
PostgreSQL 18
Valkey 9
Docker Compose v2

A relação entre os serviços é a seguinte:

浏览器 / 手机扫描 App
          │ HTTPS
          ▼
反向代理（Nginx Proxy Manager）
          │ http://webserver:8000
          ▼
Paperless-ngx Web + Celery Worker
          ├── PostgreSQL：用户、标签、文档索引元数据
          ├── Valkey：任务队列和缓存
          └── data/media/consume/export：文件、索引和导入导出目录

O OCR e o processamento de miniaturas do Paperless-ngx são tarefas em segundo plano. Um upload bem-sucedido pelo navegador não significa que o OCR terminou; é preciso verificar a fila de tarefas e o log de consumo.

Convém estimar primeiro pela quantidade de documentos e pela frequência de OCR, não apenas pelos núcleos de CPU:

O disco tem mais chance de se tornar gargalo do que a memória. PDFs originais, arquivos arquivados, miniaturas, arquivos intermediários de OCR e o banco de dados crescem juntos. Não trate um disco de 20 GB como arquivo de longo prazo; primeiro calcule o volume total de documentos existentes e depois reserve pelo menos 30% para atualizações e espaço temporário.

Se a VPS tiver apenas 1 GB de memória, o Paperless-ngx pode iniciar, mas o OCR e o PostgreSQL podem facilmente acionar OOM nos picos. Máquinas com pouca memória podem consultar o tutorial de otimização de ZRAM e Swap para VPS com pouca memória, mas o Swap apenas alivia os picos e não substitui memória suficiente.

Primeiro confirme o Docker e o Compose:

docker version
docker compose version

Se o sistema não tiver Docker, consulte o guia prático de implantação com Docker. Crie diretórios dedicados e atribua o diretório de consumo ao UID usado pelo contêiner:

sudo mkdir -p /opt/paperless/data /opt/paperless/media /opt/paperless/consume
sudo mkdir -p /opt/paperless/export /opt/paperless/postgres /opt/paperless/valkey
sudo chown -R "$USER":"$USER" /opt/paperless
sudo chmod 750 /opt/paperless
cd /opt/paperless

As responsabilidades dos diretórios acima são:

• data: dados de execução do aplicativo, índice de busca e arquivos relacionados a tarefas;
• media: arquivos originais já arquivados, miniaturas e anexos de documentos;
• consume: arquivos aguardando importação, que o Paperless-ngx lê e move automaticamente;
• export: diretório temporário usado para exportar pacotes de arquivo e para restaurações;
• postgres: o banco de dados PostgreSQL;
• valkey: dados de fila e cache.

A PAPERLESS_SECRET_KEY do Paperless-ngx é usada para assinatura de sessão e tokens de segurança. Não deixe o valor de exemplo change-me em produção nem envie o .env para um repositório público.

python3 -c 'import secrets; print(secrets.token_urlsafe(64))'

Crie /opt/paperless/.env:

PAPERLESS_SECRET_KEY=替换为上面生成的长随机字符串
PAPERLESS_URL=https://paperless.example.com
PAPERLESS_TIME_ZONE=Asia/Shanghai
PAPERLESS_OCR_LANGUAGE=chi_sim+eng
PAPERLESS_OCR_LANGUAGES=chi_sim chi_tra
USERMAP_UID=1000
USERMAP_GID=1000
POSTGRES_DB=paperless
POSTGRES_USER=paperless
POSTGRES_PASSWORD=替换为独立的数据库密码

O OCR em chinês exige atenção a duas coisas: PAPERLESS_OCR_LANGUAGE especifica o idioma principal de reconhecimento e PAPERLESS_OCR_LANGUAGES é responsável por fazer o contêiner instalar pacotes de idioma adicionais. O chinês simplificado geralmente usa chi_sim e o chinês tradicional usa chi_tra; a qualidade real do reconhecimento também depende da nitidez da digitalização, das fontes e do layout.

Se os documentos forem basicamente em inglês, você pode alterar para eng para reduzir o tamanho da imagem e a sobrecarga em tempo de execução. Depois de alterar o idioma do OCR, os documentos já concluídos não serão automaticamente reprocessados com OCR por completo; é preciso reprocessá-los em lotes.

Restrinja as permissões do arquivo de ambiente:

chmod 600 /opt/paperless/.env

Crie /opt/paperless/compose.yaml:

services:
  broker:
    image: docker.io/valkey/valkey:9-alpine
    container_name: paperless-broker
    restart: unless-stopped
    volumes:
      - ./valkey:/data

  db:
    image: docker.io/library/postgres:18
    container_name: paperless-db
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.0.5
    container_name: paperless-webserver
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./consume:/usr/src/paperless/consume
      - ./export:/usr/src/paperless/export
    env_file:
      - .env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql

volumes: {}

O exemplo atual do Compose oficial monta os dados do PostgreSQL 18 em /var/lib/postgresql; não siga mecanicamente o /var/lib/postgresql/data de tutoriais antigos. A imagem oficial do PostgreSQL mudou o layout do diretório de dados nas atualizações de versão principal, e um caminho de montagem errado pode fazer você achar que "os dados já estão persistidos" quando, na verdade, o contêiner não encontra o banco de dados após ser recriado.

Aqui o Paperless-ngx é vinculado apenas a 127.0.0.1:8000. O acesso público fica a cargo de um proxy reverso, e o banco de dados e o Valkey não são mapeados para portas do host.

Primeiro verifique o Compose e as variáveis de ambiente:

cd /opt/paperless
docker compose config --quiet

Após confirmar que não há saída, inicie:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=150 webserver

A primeira inicialização precisa executar migrações de banco de dados, criar índices e inicializar tarefas; um status unhealthy breve em alguns minutos não significa necessariamente falha. Continue observando os logs:

docker compose logs -f --tail=200 webserver

Quando você vir o serviço web começar a escutar, teste na própria VPS:

curl -I http://127.0.0.1:8000

Se retornar 502, primeiro confirme se o contêiner ainda está iniciando; se retornar conexão recusada, verifique o mapeamento de portas e os logs do contêiner, e não simplesmente altere a 8000 para escutar publicamente.

Entre no contêiner web para criar uma conta de administrador:

docker compose exec webserver python manage.py createsuperuser

Digite o e-mail, o nome de usuário e uma senha separada conforme solicitado. Não use a senha root da VPS nem escreva a conta de administrador no arquivo Compose.

Se você ainda não tem domínio, pode acessar a porta local por um túnel SSH:

ssh -L 8000:127.0.0.1:8000 your_user@your_vps_ip

Depois abra no seu próprio computador:

http://127.0.0.1:8000

Isso é adequado para a inicialização inicial. Para uso a longo prazo, ainda se recomenda configurar domínio e HTTPS, porque digitalizações, contratos e credenciais de login não devem trafegar em HTTP sem criptografia.

Se você já tem o Nginx Proxy Manager, pode adicionar um Proxy Host:

Domain Names: paperless.example.com
Forward Hostname / IP: 127.0.0.1
Forward Port: 8000
Scheme: http
Websockets Support: 开启
Block Common Exploits: 开启

Após obter um certificado Let's Encrypt, ative o HTTPS e force o redirecionamento de HTTP para HTTPS. Antes de implantar, você pode ler o tutorial de proxy reverso e HTTPS com Nginx Proxy Manager.

Se o proxy reverso estiver na mesma rede Docker, o Forward Hostname deve usar webserver em vez de 127.0.0.1. Dentro de um contêiner, o 127.0.0.1 aponta para o próprio contêiner do proxy, e essa é uma causa muito comum de 502.

A PAPERLESS_URL do Paperless-ngx deve corresponder ao endereço HTTPS de acesso público:

PAPERLESS_URL=https://paperless.example.com

Após modificar o .env, recrie o contêiner web:

docker compose up -d --force-recreate webserver

Se o servidor de origem não deve expor portas públicas, você também pode fazer o Paperless-ngx escutar apenas no endereço de loopback e oferecer acesso via Cloudflare Tunnel ou VPN. Para os limites relacionados, consulte o tutorial de Cloudflare Tunnel para ocultar o IP de origem.

Os três métodos de importação comuns do Paperless-ngx:

1. Enviar arquivos pela interface web;
2. Copiar arquivos para o diretório consume;
3. Entregar automaticamente por regras de e-mail ou um programa de digitalização.

Primeiro copie um PDF de teste:

cp ~/Downloads/test-invoice.pdf /opt/paperless/consume/

Verifique o log de consumo:

docker compose logs -f --tail=200 webserver | grep -Ei 'consumer|ocr|document'

Quando o processamento termina, o arquivo original vai para o armazenamento de mídia, e os arquivos do diretório consume geralmente são movidos ou excluídos. Não use o consume como diretório de backup de longo prazo nem renomeie manualmente os arquivos em media.

Se o diretório consume nunca for processado, verifique na ordem:

ls -la /opt/paperless/consume
stat /opt/paperless/consume/test-invoice.pdf
docker compose exec webserver id
docker compose exec webserver ls -la /usr/src/paperless/consume

O UID/GID do diretório do host deve permitir que o contêiner leia e mova arquivos. USERMAP_UID e USERMAP_GID no env devem corresponder ao usuário real do host, o que você pode confirmar com o comando a seguir:

id -u
id -g

Após alterar UID/GID, recrie o serviço:

docker compose up -d --force-recreate webserver

Os metadados do Paperless-ngx determinam se você conseguirá encontrar arquivos rapidamente no futuro. Recomenda-se primeiro estabelecer um pequeno conjunto de categorias estáveis:

• Tipos de documento: nota fiscal, contrato, apólice, recibo, documento de identidade, manual;
• Contatos: banco, operadora, locador, fornecedor, cliente;
• Tags: a reembolsar, pago, a renovar, importante, família, trabalho;
• Campos personalizados: valor, data de vencimento do contrato, número do pedido ou número do ativo.

Não crie uma nova tag para cada arquivo. As tags devem expressar condições de filtro reutilizáveis, enquanto os tipos de documento e os contatos descrevem a origem e a finalidade.

Você pode configurar regras de correspondência na interface de administração para que o nome do arquivo ou o texto do OCR preencham automaticamente os metadados. Por exemplo, se o nome do arquivo contiver "conta de luz", definir automaticamente o tipo de documento como "conta"; anexos de um determinado endereço de e-mail definem automaticamente o contato e as tags.

Valide as regras com 5-10 arquivos de teste antes de ativá-las. Uma vez que as regras automáticas sejam amplas demais, elas podem classificar contratos incorretamente, e depois você terá que corrigi-los um por um.

Após enviar um PDF digitalizado, o Paperless-ngx executa o OCR em segundo plano. As falhas de OCR geralmente não são causadas pelo próprio Paperless-ngx, mas por:

• Resolução de digitalização muito baixa ou imagem muito inclinada;
• O contêiner não tem o pacote de idioma correspondente;
• As tarefas de OCR estão na fila e ainda não terminaram;
• O arquivo é um PDF criptografado ou corrompido;
• Memória insuficiente e o worker foi encerrado pelo sistema.

Ver tarefas recentes:

docker compose logs --tail=300 webserver | grep -Ei 'ocr|tesseract|celery|task|error'
docker stats --no-stream

Para documentos em chinês e mistos de chinês e inglês, recomenda-se chi_sim+eng; adicione chi_tra para documentos em chinês tradicional conforme necessário. Se os resultados da busca ainda estiverem incompletos, primeiro baixe um arquivo original para confirmar se ele realmente contém texto reconhecível e depois determine se é um problema de qualidade da digitalização ou de configuração de idioma.

A busca de texto completo do Paperless-ngx depende do índice. Arquivos recém-importados podem precisar aguardar as tarefas em segundo plano; não importe novamente de imediato alegando que "não encontra" logo após o upload. Verifique primeiro o status das tarefas e os logs e depois aguarde a indexação terminar.

Você pode configurar um endereço de caixa de entrada dedicado para o Paperless-ngx para que os anexos de contas entrem automaticamente no fluxo de consumo. Mas a automação por e-mail amplia a superfície de ataque: remetentes desconhecidos podem enviar anexos enormes, arquivos maliciosos ou grandes quantidades de spam.

Limites de segurança recomendados:

• Use uma caixa de e-mail separada e não escreva a senha da sua caixa principal pessoal no contêiner;
• Permita apenas remetentes confiáveis ou encaminhe primeiro para uma caixa de revisão manual;
• Limite o tamanho dos anexos e os tipos de arquivo permitidos;
• Configure monitoramento de disco para o diretório consume e as tarefas de e-mail;
• Mantenha uma etapa de revisão manual antes de ativar as regras automáticas.

Se você só arquiva arquivos ocasionalmente, o upload pela web ou a cópia manual para o consume são mais fáceis de diagnosticar e não exigem manutenção extra da conexão de e-mail.

O Paperless-ngx tem pelo menos três tipos de dados que precisam ser protegidos:

1. media: documentos originais, PDFs arquivados, miniaturas e anexos;
2. postgres: usuários, tags, regras, permissões e metadados de documentos;
3. data: índice de busca, status das tarefas e dados de execução do aplicativo.

consume e export também devem ser incluídos no escopo do backup, especialmente os arquivos do diretório consume que ainda não foram processados. O Valkey é principalmente filas e cache e normalmente não contém dados de origem de longo prazo, mas fazer backup dele pode reduzir a perda de tarefas após uma restauração.

Primeiro pare o serviço web e o worker e depois faça o dump do banco de dados:

cd /opt/paperless
docker compose stop webserver
mkdir -p export/backup-$(date +%F)
docker compose exec -T db pg_dump -U paperless paperless > export/backup-$(date +%F)/paperless.sql
tar -czf export/backup-$(date +%F)/paperless-files.tar.gz data media consume .env compose.yaml
docker compose start webserver

O comando acima empacota juntos arquivos de ambiente sensíveis e documentos, portanto as permissões devem ser restritas:

chmod 600 export/backup-*/paperless.sql
chmod 600 export/backup-*/paperless-files.tar.gz

Copie o backup para outra máquina ou armazenamento de objetos; não o deixe apenas na mesma VPS. Para a estratégia de backup, consulte restic, rclone e simulações de restauração de banco de dados em VPS.

docker compose down
tar -xzf paperless-files.tar.gz -C /opt/paperless
cat paperless.sql | docker compose exec -T db psql -U paperless paperless
docker compose up -d
docker compose logs --tail=200 webserver

Não use latest a longo prazo em produção. Primeiro fixe a versão no Compose, por exemplo:

webserver:
  image: ghcr.io/paperless-ngx/paperless-ngx:3.0.5
broker:
  image: docker.io/valkey/valkey:9-alpine
db:
  image: docker.io/library/postgres:18

Antes de atualizar, execute:

cd /opt/paperless
docker compose config > export/compose.before-upgrade.yaml
docker compose exec -T db pg_dump -U paperless paperless > export/paperless-before-upgrade.sql
docker compose pull

Após confirmar que o download da imagem terminou, recrie:

docker compose up -d
docker compose ps
docker compose logs --tail=300 webserver

Após atualizar, verifique pelo menos:

• O login do administrador e o redirecionamento HTTPS;
• Se novos arquivos podem ser importados e o OCR concluído;
• Se a busca de texto completo em chinês retorna resultados;
• Se as tags, as regras e as permissões foram preservadas;
• Se o uso de disco do banco de dados cresce de forma anormal.

O Paperless-ngx v3 tem notas de migração; antes de atravessar versões principais, é preciso ler a documentação oficial de migração. Não reverta apenas a imagem do aplicativo sem restaurar o banco de dados; o código do aplicativo e o esquema do banco de dados devem permanecer compatíveis.

• Use uma chave aleatória separada para o .env e defina as permissões como 600;
• O Paperless-ngx escuta apenas no endereço de loopback ou na rede privada e não expõe a 8000 diretamente;
• O proxy reverso ativa HTTPS, senhas fortes e bloqueio de ataques comuns;
• PostgreSQL e Valkey não são mapeados para portas públicas;
• O diretório consume não é gravável por todos os usuários do sistema;
• A importação por e-mail aceita apenas fontes confiáveis e limita o tamanho dos anexos;
• Mantenha pelo menos uma cópia de backup fora do site e faça simulações de restauração regularmente;
• Fixe as versões antes de atualizar, exporte o banco de dados e mantenha uma imagem de reversão;
• Não envie contratos, documentos de identidade e outros arquivos para repositórios Git públicos;
• Quando usado por uma equipe, conceda o mínimo privilégio por função;
• Monitore o disco, o banco de dados, a fila de OCR e o número de reinicializações de contêineres.

Usuários individuais podem começar com 2 núcleos, 2 GB, um SSD de 80 GB, Paperless-ngx v3.0.5 e OCR em chinês. Importe primeiro dez arquivos de teste, confirme que as regras de arquivamento, a busca de texto completo, o HTTPS e o backup e a restauração funcionam e depois migre o material histórico em massa.

O valor do Paperless-ngx não está em "colocar arquivos em uma VPS", mas em tornar os documentos acumulados ao longo de anos encontráveis pelo conteúdo. Desde que você faça backup de mídia, banco de dados, índice e chaves juntos e fixe as permissões do diretório consume e o processo de atualização, ele pode se tornar um sistema estável de arquivo digital pessoal.

• Documentação oficial do Paperless-ngx
• Paperless-ngx v3.0.5 Release
• Docker Compose oficial do Paperless-ngx
• Documentação de configuração do Paperless-ngx