Casos adecuados:

• Archivar facturas domésticas, certificados de garantía, pólizas de seguro y contratos de alquiler;
• Autónomos que guardan comprobantes de reembolso, facturas de proveedores y material fiscal;
• Equipos pequeños que comparten documentos de proyecto pero necesitan gestionarlos por etiquetas y permisos;
• Recopilar continuamente archivos PDF, JPEG, PNG y TIFF desde escáneres, móviles o correo electrónico;
• Querer buscar con OCR el texto dentro de archivos escaneados en lugar de revisar carpetas manualmente.

Casos no adecuados:

• Solo quieres sincronizar fotos y archivos normales y no necesitas OCR en absoluto;
• Necesitas que varias personas editen documentos de Office en tiempo real;
• Necesitas firma electrónica de nivel empresarial, aprobaciones complejas y auditoría de cumplimiento;
• No tienes copias de seguridad fiables pero planeas guardar tu único contrato original en un solo VPS.

Paperless-ngx no sustituye a un sistema de copias de seguridad. Su directorio de medios, su base de datos y su directorio de consumo son datos importantes y deben usarse junto con instantáneas del VPS, almacenamiento de objetos u otra máquina.

Si ya usas Nextcloud, puedes tratar Paperless-ngx como una capa de archivo de documentos en lugar de crear otro "almacenamiento en la nube para todo". Ambos pueden coexistir, pero no dejes que varios programas escriban al mismo tiempo en el mismo directorio de medios, o fácilmente tendrás problemas de permisos, importaciones duplicadas e índices inconsistentes.

Este artículo se basa en la versión estable oficial verificada en agosto de 2026:

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

La relación entre servicios es la siguiente:

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

El OCR y el procesamiento de miniaturas de Paperless-ngx son tareas en segundo plano. Una carga correcta desde el navegador no significa que el OCR haya terminado; hay que revisar la cola de tareas y el registro de consumo.

Conviene estimar primero según la cantidad de documentos y la frecuencia de OCR, no solo por los núcleos de CPU:

El disco es más propenso a convertirse en cuello de botella que la memoria. Los PDF originales, los archivos archivados, las miniaturas, los archivos intermedios de OCR y la base de datos crecen juntos. No trates un disco de 20 GB como archivo a largo plazo; primero calcula el volumen total de documentos existentes y luego reserva al menos un 30 % para actualizaciones y espacio temporal.

Si el VPS solo tiene 1 GB de memoria, Paperless-ngx puede arrancar, pero el OCR y PostgreSQL pueden provocar fácilmente OOM en los picos. Las máquinas con poca memoria pueden consultar el tutorial de optimización de ZRAM y Swap para VPS con poca memoria, pero Swap solo alivia los picos y no sustituye a la memoria suficiente.

Primero confirma Docker y Compose:

docker version
docker compose version

Si el sistema no tiene Docker, consulta la guía práctica de despliegue con Docker. Crea directorios dedicados y asigna el directorio de consumo al UID que usa el contenedor:

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

Las responsabilidades de los directorios anteriores son:

• data: datos de ejecución de la aplicación, índice de búsqueda y archivos relacionados con tareas;
• media: archivos originales ya archivados, miniaturas y adjuntos de documentos;
• consume: archivos pendientes de importar, que Paperless-ngx lee y mueve automáticamente;
• export: directorio temporal usado para exportar paquetes de archivo y para restauraciones;
• postgres: la base de datos PostgreSQL;
• valkey: datos de cola y caché.

La PAPERLESS_SECRET_KEY de Paperless-ngx se usa para firmar sesiones y tokens de seguridad. No dejes el valor de ejemplo change-me en producción ni subas .env a un repositorio público.

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

Crea /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=替换为独立的数据库密码

El OCR en chino requiere atención a dos cosas: PAPERLESS_OCR_LANGUAGE especifica el idioma principal de reconocimiento y PAPERLESS_OCR_LANGUAGES se encarga de que el contenedor instale paquetes de idioma adicionales. El chino simplificado suele usar chi_sim y el chino tradicional chi_tra; la calidad real del reconocimiento también depende de la claridad del escaneo, las fuentes y el diseño.

Si los documentos son principalmente en inglés, puedes cambiarlo a eng para reducir el tamaño de la imagen y la sobrecarga en tiempo de ejecución. Después de cambiar el idioma de OCR, los documentos ya completados no se volverán a procesar automáticamente con OCR en su totalidad; hay que reprocesarlos por lotes.

Restringe los permisos del archivo de entorno:

chmod 600 /opt/paperless/.env

Crea /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: {}

El ejemplo actual de Compose oficial monta los datos de PostgreSQL 18 en /var/lib/postgresql; no sigas mecánicamente el /var/lib/postgresql/data de tutoriales antiguos. La imagen oficial de PostgreSQL cambió la disposición del directorio de datos en las actualizaciones de versión mayor, y una ruta de montaje incorrecta puede hacerte creer que "los datos ya están persistidos" cuando en realidad el contenedor no encuentra la base de datos tras recrearse.

Aquí Paperless-ngx se vincula solo a 127.0.0.1:8000. El acceso público lo gestiona un proxy inverso, y la base de datos y Valkey no se asignan a puertos del host.

Primero revisa Compose y las variables de entorno:

cd /opt/paperless
docker compose config --quiet

Tras confirmar que no hay salida, inicia:

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

El primer arranque necesita ejecutar migraciones de base de datos, crear índices e inicializar tareas; un estado unhealthy breve en unos minutos no significa necesariamente un fallo. Sigue observando los registros:

docker compose logs -f --tail=200 webserver

Cuando veas que el servicio web empieza a escuchar, prueba en el propio VPS:

curl -I http://127.0.0.1:8000

Si devuelve 502, primero confirma si el contenedor sigue arrancando; si devuelve conexión rechazada, revisa la asignación de puertos y los registros del contenedor, y no cambies 8000 para que escuche públicamente sin más.

Entra en el contenedor web para crear una cuenta de administrador:

docker compose exec webserver python manage.py createsuperuser

Introduce el correo, el nombre de usuario y una contraseña independiente según se indique. No uses la contraseña root del VPS ni escribas la cuenta de administrador en el archivo Compose.

Si aún no tienes dominio, puedes acceder al puerto local mediante un túnel SSH:

ssh -L 8000:127.0.0.1:8000 your_user@your_vps_ip

Luego abre en tu propio ordenador:

http://127.0.0.1:8000

Esto es adecuado para la inicialización inicial. Para uso a largo plazo se recomienda configurar un dominio y HTTPS, porque los escaneos, contratos y credenciales de inicio de sesión no deben transmitirse por HTTP en texto plano.

Si ya tienes Nginx Proxy Manager, puedes añadir un Proxy Host:

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

Tras obtener un certificado Let's Encrypt, activa HTTPS y fuerza la redirección de HTTP a HTTPS. Antes de desplegar, puedes leer el tutorial de proxy inverso y HTTPS con Nginx Proxy Manager.

Si el proxy inverso se ejecuta en la misma red Docker, Forward Hostname debe usar webserver en lugar de 127.0.0.1. Dentro de un contenedor, 127.0.0.1 apunta al propio contenedor del proxy, y esta es una causa muy común de 502.

La PAPERLESS_URL de Paperless-ngx debe coincidir con la dirección HTTPS de acceso público:

PAPERLESS_URL=https://paperless.example.com

Después de modificar .env, recrea el contenedor web:

docker compose up -d --force-recreate webserver

Si el servidor de origen no debe exponer puertos públicos, también puedes hacer que Paperless-ngx escuche solo en la dirección de bucle invertido y ofrecer acceso mediante Cloudflare Tunnel o una VPN. Para los límites relacionados, consulta el tutorial de Cloudflare Tunnel para ocultar la IP de origen.

Los tres métodos de importación habituales de Paperless-ngx:

1. Subir archivos en la interfaz web;
2. Copiar archivos al directorio consume;
3. Entregar automáticamente mediante reglas de correo o un programa de escaneo.

Primero copia un PDF de prueba:

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

Revisa el registro de consumo:

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

Cuando el procesamiento termina, el archivo original pasa al almacenamiento de medios y los archivos del directorio consume normalmente se mueven o se eliminan. No uses consume como directorio de copia de seguridad a largo plazo ni cambies manualmente los nombres de archivo bajo media.

Si el directorio consume nunca se procesa, revisa en orden:

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

El UID/GID del directorio del host debe permitir que el contenedor lea y mueva archivos. USERMAP_UID y USERMAP_GID en env deben coincidir con el usuario real del host, lo que puedes confirmar con el siguiente comando:

id -u
id -g

Después de cambiar UID/GID, recrea el servicio:

docker compose up -d --force-recreate webserver

Los metadatos de Paperless-ngx determinan si podrás encontrar archivos rápidamente en el futuro. Se recomienda establecer primero un conjunto pequeño de categorías estables:

• Tipos de documento: factura, contrato, póliza, recibo, documento de identidad, manual;
• Contactos: banco, operador, arrendador, proveedor, cliente;
• Etiquetas: pendiente de reembolso, pagado, pendiente de renovación, importante, familia, trabajo;
• Campos personalizados: importe, fecha de vencimiento del contrato, número de pedido o número de activo.

No crees una etiqueta nueva para cada archivo. Las etiquetas deben expresar condiciones de filtro reutilizables, mientras que los tipos de documento y los contactos describen el origen y el propósito.

Puedes configurar reglas de coincidencia en la interfaz de administración para que el nombre de archivo o el texto OCR rellenen automáticamente los metadatos. Por ejemplo, si el nombre de archivo contiene "factura de luz", establecer automáticamente el tipo de documento como "factura"; los adjuntos de una determinada dirección de correo establecen automáticamente el contacto y las etiquetas.

Valida las reglas con 5-10 archivos de prueba antes de activarlas. Una vez que las reglas automáticas son demasiado amplias, pueden clasificar mal los contratos y luego tendrás que corregirlos uno por uno.

Después de subir un PDF escaneado, Paperless-ngx ejecuta OCR en segundo plano. Los fallos de OCR normalmente no se deben a Paperless-ngx en sí, sino a:

• Resolución de escaneo demasiado baja o imagen muy inclinada;
• El contenedor carece del paquete de idioma correspondiente;
• Las tareas de OCR están en cola y aún no han terminado;
• El archivo es un PDF cifrado o dañado;
• Memoria insuficiente y el worker fue terminado por el sistema.

Ver tareas recientes:

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

Para documentos en chino y mixtos chino-inglés se recomienda chi_sim+eng; añade chi_tra para documentos en chino tradicional según sea necesario. Si los resultados de búsqueda siguen siendo incompletos, primero descarga un archivo original para confirmar si realmente contiene texto reconocible y luego determina si es un problema de calidad del escaneo o de configuración de idioma.

La búsqueda de texto completo de Paperless-ngx depende del índice. Los archivos recién importados pueden necesitar esperar a las tareas en segundo plano; no vuelvas a importar inmediatamente alegando que "no se encuentra" justo después de subirlo. Revisa primero el estado de las tareas y los registros, y luego espera a que termine la indexación.

Puedes configurar una dirección de correo dedicada para Paperless-ngx para que los adjuntos de facturas entren automáticamente en el flujo de consumo. Pero la automatización por correo amplía la superficie de ataque: remitentes desconocidos pueden enviar adjuntos enormes, archivos maliciosos o grandes cantidades de spam.

Límites de seguridad recomendados:

• Usa un buzón independiente y no escribas la contraseña de tu buzón principal personal en el contenedor;
• Permite solo remitentes de confianza, o reenvía primero a un buzón de revisión manual;
• Limita el tamaño de los adjuntos y los tipos de archivo permitidos;
• Configura monitorización de disco para el directorio consume y las tareas de correo;
• Mantén un paso de revisión manual antes de activar las reglas automáticas.

Si solo archivas archivos ocasionalmente, la carga web o la copia manual a consume son más fáciles de diagnosticar y no requieren mantenimiento adicional de la conexión de correo.

Paperless-ngx tiene al menos tres tipos de datos que deben protegerse:

1. media: documentos originales, PDF archivados, miniaturas y adjuntos;
2. postgres: usuarios, etiquetas, reglas, permisos y metadatos de documentos;
3. data: índice de búsqueda, estado de tareas y datos de ejecución de la aplicación.

consume y export también deben incluirse en el alcance de la copia de seguridad, especialmente los archivos del directorio consume que aún no se han procesado. Valkey es principalmente colas y caché y normalmente no contiene datos fuente a largo plazo, pero respaldarlo puede reducir la pérdida de tareas tras una restauración.

Primero detén el servicio web y el worker, y luego realiza el volcado de la base de datos:

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

El comando anterior empaqueta juntos archivos de entorno sensibles y documentos, por lo que se deben restringir los permisos:

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

Copia la copia de seguridad a otra máquina o a almacenamiento de objetos; no la dejes solo en el mismo VPS. Para la estrategia de copias de seguridad, consulta restic, rclone y simulacros de restauración de bases de datos en 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

No uses latest a largo plazo en producción. Primero fija la versión en Compose, por ejemplo:

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 actualizar, ejecuta:

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

Tras confirmar que la descarga de la imagen ha terminado, recrea:

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

Después de actualizar, comprueba al menos:

• El inicio de sesión del administrador y la redirección HTTPS;
• Si los archivos nuevos se pueden importar y completar el OCR;
• Si la búsqueda de texto completo en chino devuelve resultados;
• Si se conservan las etiquetas, las reglas y los permisos;
• Si el uso de disco de la base de datos crece de forma anómala.

Paperless-ngx v3 tiene notas de migración; antes de cruzar versiones mayores hay que leer la documentación oficial de migración. No revertir solo la imagen de la aplicación sin restaurar la base de datos; el código de la aplicación y el esquema de la base de datos deben seguir siendo compatibles.

• Usa una clave aleatoria independiente para .env y establece los permisos en 600;
• Paperless-ngx escucha solo en la dirección de bucle invertido o en la red privada y no expone 8000 directamente;
• El proxy inverso activa HTTPS, contraseñas fuertes y bloqueo de ataques comunes;
• PostgreSQL y Valkey no se asignan a puertos públicos;
• El directorio consume no es escribible por todos los usuarios del sistema;
• La importación por correo acepta solo fuentes de confianza y limita el tamaño de los adjuntos;
• Mantén al menos una copia de seguridad fuera del sitio y realiza simulacros de restauración con regularidad;
• Fija las versiones antes de actualizar, exporta la base de datos y conserva una imagen de reversión;
• No subas contratos, documentos de identidad y otros archivos a repositorios Git públicos;
• Cuando lo use un equipo, concede el mínimo privilegio por rol;
• Monitoriza el disco, la base de datos, la cola de OCR y el número de reinicios de contenedores.

Los usuarios individuales pueden empezar con 2 núcleos, 2 GB, un SSD de 80 GB, Paperless-ngx v3.0.5 y OCR en chino. Importa primero diez archivos de prueba, confirma que las reglas de archivo, la búsqueda de texto completo, HTTPS y la copia y restauración funcionan, y luego migra el material histórico en bloque.

El valor de Paperless-ngx no está en "poner archivos en un VPS", sino en hacer que los documentos acumulados durante años se puedan encontrar por su contenido. Siempre que hagas copia de seguridad de medios, base de datos, índice y claves juntos, y fijes los permisos del directorio consume y el proceso de actualización, puede convertirse en un sistema estable de archivo digital personal.

• Documentación oficial de Paperless-ngx
• Paperless-ngx v3.0.5 Release
• Docker Compose oficial de Paperless-ngx
• Documentación de configuración de Paperless-ngx