Stirling PDF encaja bien en las siguientes situaciones:

• Gestionas contratos y documentos escaneados con frecuencia y no quieres subirlos a sitios de terceros;
• Un equipo pequeño necesita una caja de herramientas PDF compartida;
• Quieres fusionar, aplicar OCR o convertir PDF por lotes mediante la API;
• Ya tienes un VPS y quieres aprovechar los recursos inactivos.

También tiene limitaciones claras. El OCR, la conversión de Office a PDF y la compresión de archivos grandes pueden consumir mucha CPU y memoria en un instante; los administradores del servidor aún pueden acceder a la máquina anfitriona, así que "autoalojado" no significa "nadie puede ver los archivos". Si solo procesas ocasionalmente un PDF no sensible, el software de escritorio resulta más cómodo.

Para uso personal puedes empezar con 2 núcleos, 2 GB de memoria y 20 GB de SSD. Si necesitas OCR en chino, conversión de documentos de Office o que varias personas lo usen a la vez, se recomienda al menos 2 núcleos, 4 GB de memoria y 40 GB de SSD.

La imagen estándar es suficiente para la mayoría. latest-fat es más grande pero incluye fuentes y herramientas adicionales más completas; latest-ultra-lite ahorra disco, pero no es adecuada para despliegues públicos que dependan del inicio de sesión y del OCR completo.

El sistema usado aquí es Ubuntu 24.04 LTS. Prepara un dominio que ya resuelva a la IP pública del VPS, por ejemplo pdf.example.com, y abre solo SSH, 80 y 443 en el grupo de seguridad y en UFW.

Si el servidor aún no tiene Docker, instálalo desde el repositorio oficial de Docker. Tras la instalación, confirma primero que ambos comandos producen salida:

docker --version
docker compose version

No sigas usando docker-compose v1, que ya no recibe mantenimiento. Todos los comandos siguientes usan Compose v2, es decir, docker compose con un espacio en medio.

Crea el directorio de despliegue:

sudo mkdir -p /opt/stirling-pdf/data/{configs,customFiles,logs,pipeline,tessdata}
sudo chown -R "$USER":"$USER" /opt/stirling-pdf
cd /opt/stirling-pdf

No pongas la contraseña de ejemplo directamente en internet. Primero genera una contraseña aleatoria y luego escríbela en .env con permisos 600:

openssl rand -base64 24
nano .env
chmod 600 .env

El contenido de .env es el siguiente; sustituye la segunda línea por el valor que acabas de generar:

STIRLING_ADMIN_USER=admin
STIRLING_ADMIN_PASSWORD=请替换成随机密码

Las variables de entorno todavía pueden ser vistas por cualquiera con permisos de gestión de Docker, así que los permisos de gestión de Docker en sí deben concederse solo a administradores de confianza. Tras el primer inicio de sesión, cambia la contraseña en la configuración de cuenta de Stirling PDF.

Crea /opt/stirling-pdf/compose.yaml:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data/configs:/configs
      - ./data/customFiles:/customFiles:rw
      - ./data/logs:/logs
      - ./data/pipeline:/pipeline
      - ./data/tessdata:/usr/share/tessdata
    environment:
      DISABLE_ADDITIONAL_FEATURES: "false"
      SECURITY_ENABLELOGIN: "true"
      SECURITY_INITIALLOGIN_USERNAME: "${STIRLING_ADMIN_USER:?set STIRLING_ADMIN_USER in .env}"
      SECURITY_INITIALLOGIN_PASSWORD: "${STIRLING_ADMIN_PASSWORD:?set STIRLING_ADMIN_PASSWORD in .env}"
      SYSTEM_DEFAULTLOCALE: "zh-CN"
      SYSTEM_GOOGLEVISIBILITY: "false"
      SHOW_SURVEY: "false"
    healthcheck:
      test:
        - CMD-SHELL
        - >-
          curl -fsS http://localhost:8080/api/v1/info/status |
          grep -q 'UP'
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 60s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G

Primero deja que Compose expanda las variables de entorno y compruebe la sintaxis, y luego inicia:

docker compose config >/dev/null
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 stirling-pdf

El proyecto oficial solo ofrece soporte de seguridad para la última versión, por lo que el ejemplo usa latest. Esto no significa que debas actualizar a ciegas todos los días. Tras la primera ejecución correcta, registra el digest actual de la imagen, haz una copia de seguridad de /configs antes de actualizar y luego ejecuta pull y reconstruye:

docker image inspect \
  docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest \
  --format '{{index .RepoDigests 0}}'

Si falla la descarga desde el registro oficial de imágenes, puedes cambiar a stirlingtools/stirling-pdf:latest en Docker Hub, o a ghcr.io/stirling-tools/stirling-pdf:latest en GitHub Container Registry.

Stirling PDF recibe contratos, documentos de identidad y otros archivos sensibles, así que no inicies sesión por HTTP sin cifrar. Tras instalar Caddy, edita /etc/caddy/Caddyfile:

pdf.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080

    request_body {
        max_size 200MB
    }
}

Comprueba la configuración y recarga:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager

Si aún no has configurado Caddy, puedes leer primero la guía completa de Caddy como proxy inverso en un VPS.

Confirma que el backend no escucha en internet:

sudo ss -lntp | grep ':8080'
curl -fsS http://127.0.0.1:8080/api/v1/info/status
curl -I https://pdf.example.com

La primera línea debería mostrar 127.0.0.1:8080, no 0.0.0.0:8080; el endpoint de estado devuelve JSON que contiene UP. Después abre https://pdf.example.com, inicia sesión con la cuenta de administrador de .env y cambia la contraseña de inmediato.

El OCR de Stirling PDF usa Tesseract. La imagen Docker estándar suele incluir paquetes de idioma habituales como el chino simplificado; los idiomas realmente disponibles dependen de los archivos del contenedor actual:

docker exec stirling-pdf sh -lc \
  'find /usr/share/tessdata -maxdepth 1 -name "*.traineddata" -printf "%f\n" | sort'

El chino simplificado corresponde a chi_sim.traineddata, el tradicional a chi_tra.traineddata y el inglés a eng.traineddata. Si un idioma no aparece en la interfaz, no cambies solo el desplegable; primero confirma si el paquete de idioma correspondiente existe realmente.

El resultado del OCR también depende del archivo original. Un escaneo a 300 DPI, con texto claro y orientación de página correcta, suele ser mucho mejor que una foto tomada con el móvil, con sombras evidentes y texto menor de 8 pt. Tesseract puede reconocer texto, pero no reconstruirá de forma fiable estructuras complejas de tablas y fórmulas.

Tras procesar un escaneo de prueba, confirma al menos tres cosas: que el chino se puede buscar, que el texto se puede copiar y que el PDF descargado se abre en lectores habituales. Ver solo un mensaje de tarea completada no significa que el resultado del reconocimiento sea realmente utilizable.

La configuración más peligrosa es desactivar el inicio de sesión y exponer 8080 directamente a internet. Otros no solo pueden consumir tu CPU y memoria, sino también subir archivos maliciosamente construidos para sondear los componentes de conversión.

Revisa cada punto antes de publicar:

• SECURITY_ENABLELOGIN=true, y la contraseña de administrador ya se ha cambiado;
• 8080 solo está vinculado a 127.0.0.1, y solo 80/443 están abiertos a internet;
• /configs está persistido, y .env tiene permisos 600;
• Los usuarios, claves de API y funciones que no necesitas se desactivan a tiempo;
• Descarga actualizaciones de seguridad con regularidad, pero haz una copia de seguridad antes de cada actualización;
• Configura alertas de disco en el servidor para evitar que archivos temporales o registros llenen el disco.

La página de seguridad de Stirling PDF indica claramente que las versiones antiguas no recibirán correcciones de seguridad retroportadas. No dejes una instancia pública sin actualizar durante años, ni consideres que "el contenedor arranca" significa que el mantenimiento de seguridad está completo.

En la versión gratuita, los usuarios con sesión iniciada, la configuración local y la base de datos H2 integrada se guardan principalmente en /configs. La forma más sencilla es hacer una copia de seguridad de todo el directorio data, en lugar de copiar solo compose.yaml.

Primero detén el contenedor y crea un archivo comprimido más consistente:

cd /opt/stirling-pdf
mkdir -p backups
docker compose stop stirling-pdf
tar -czf "backups/stirling-data-$(date +%F-%H%M%S).tar.gz" data
docker compose start stirling-pdf

Un archivo comprimido local no es una copia de seguridad completa. Después usa restic, rclone o almacenamiento de objetos para copiarlo a otra máquina y establece un periodo de retención. Puedes seguir la guía de simulacro de copia de seguridad y restauración en VPS para hacer una restauración en otra máquina.

Al restaurar, no sobrescribas directamente los archivos de base de datos en uso:

cd /opt/stirling-pdf
docker compose stop stirling-pdf
mv data "data.before-restore-$(date +%F-%H%M%S)"
tar -xzf backups/stirling-data-YYYY-MM-DD-HHMMSS.tar.gz
docker compose up -d
curl -fsS http://127.0.0.1:8080/api/v1/info/status

Tras restaurar, inicia sesión de verdad y confirma que las cuentas, la configuración y los idiomas de OCR siguen ahí. Un archivo de copia de seguridad que existe pero nunca se ha restaurado solo cuenta como "tener un archivo comprimido", no como "tener capacidad de restauración".

Tras el despliegue, yo lo validaría con los siguientes criterios en lugar de comprobar solo si la página de inicio abre:

1. docker compose ps muestra el contenedor como healthy;
2. 8080 solo escucha en la dirección de loopback y no es accesible directamente desde internet;
3. El certificado HTTPS es válido y HTTP redirige automáticamente a HTTPS;
4. Los usuarios sin sesión iniciada no pueden usar las herramientas PDF;
5. Ejecuta un archivo de prueba para fusionar, otro para comprimir y otro para OCR en chino;
6. Las cuentas y la configuración siguen existiendo tras reiniciar el contenedor;
7. Restaura desde la copia de seguridad a un directorio de prueba, y puedes iniciar sesión de nuevo y procesar archivos.

Si vas a usarlo con tu equipo a largo plazo, añade también la rotación de registros del contenedor, las alertas de disco y las ventanas de actualización. Para comprobaciones de estado, límites de recursos y estrategias de reversión en Compose de producción, puedes seguir leyendo la lista de configuración de producción de Docker Compose en VPS.

El valor de Stirling PDF no es solo "muchas herramientas PDF gratuitas", sino que los archivos sensibles no tienen que pasar por sitios web desconocidos. Una vez montado con un VPS de 2 núcleos y 4 GB, Docker Compose, Caddy HTTPS e inicio de sesión obligatorio, y tras una ronda de pruebas de OCR, reinicio y restauración, el servicio es realmente utilizable.