O Stirling PDF é ideal para as seguintes situações:

• Você lida com contratos e documentos digitalizados com frequência e não quer enviá-los a sites de terceiros;
• Uma equipe pequena precisa de uma caixa de ferramentas de PDF compartilhada;
• Você quer mesclar, aplicar OCR ou converter PDFs em lote pela API;
• Você já tem uma VPS e quer aproveitar recursos ociosos.

Ele também tem limitações claras. OCR, conversão de Office para PDF e compressão de arquivos grandes podem consumir muita CPU e memória num instante; os administradores do servidor ainda podem acessar a máquina host, então "auto-hospedado" não significa "ninguém pode ver os arquivos". Se você só processa ocasionalmente um PDF não sensível, o software de desktop acaba sendo mais prático.

Para uso pessoal, você pode começar com 2 núcleos, 2 GB de memória e 20 GB de SSD. Se precisar de OCR em chinês, conversão de documentos do Office ou que várias pessoas usem ao mesmo tempo, recomenda-se pelo menos 2 núcleos, 4 GB de memória e 40 GB de SSD.

A imagem padrão é suficiente para a maioria. latest-fat é maior, mas tem fontes e ferramentas extras mais completas; latest-ultra-lite economiza disco, mas não é adequada para implantações públicas que dependem de login e OCR completo.

O sistema usado aqui é o Ubuntu 24.04 LTS. Prepare um domínio que já resolva para o IP público da VPS, por exemplo pdf.example.com, e abra apenas SSH, 80 e 443 no grupo de segurança e no UFW.

Se o servidor ainda não tem Docker, instale a partir do repositório oficial do Docker. Após a instalação, confirme primeiro que os dois comandos produzem saída:

docker --version
docker compose version

Não continue usando o docker-compose v1, que não recebe mais manutenção. Todos os comandos abaixo usam o Compose v2, ou seja, docker compose com um espaço no meio.

Crie o diretório de implantação:

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

Não coloque a senha de exemplo diretamente na internet. Primeiro gere uma senha aleatória e depois grave-a em .env com permissões 600:

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

O conteúdo de .env é o seguinte; substitua a segunda linha pelo valor que você acabou de gerar:

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

As variáveis de ambiente ainda podem ser vistas por qualquer pessoa com permissões de gerenciamento do Docker, então as permissões de gerenciamento do Docker em si devem ser concedidas apenas a administradores confiáveis. Após o primeiro login, altere a senha nas configurações de conta do Stirling PDF.

Crie /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

Primeiro deixe o Compose expandir as variáveis de ambiente e verificar a sintaxe, depois inicie:

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

O projeto oficial só oferece suporte de segurança para a versão mais recente, por isso o exemplo usa latest. Isso não significa que você deva atualizar às cegas todos os dias. Após a primeira execução bem-sucedida, registre o digest atual da imagem, faça backup de /configs antes de atualizar e depois execute pull e reconstrua:

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

Se o download do registro oficial de imagens falhar, você pode mudar para stirlingtools/stirling-pdf:latest no Docker Hub, ou para ghcr.io/stirling-tools/stirling-pdf:latest no GitHub Container Registry.

O Stirling PDF recebe contratos, documentos de identidade e outros arquivos sensíveis, então não faça login por HTTP sem criptografia. Após instalar o Caddy, edite /etc/caddy/Caddyfile:

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

    request_body {
        max_size 200MB
    }
}

Verifique a configuração e recarregue:

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

Se você ainda não configurou o Caddy, pode ler primeiro o guia completo de Caddy como proxy reverso em uma VPS.

Confirme que o backend não está escutando na internet:

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

A primeira linha deve mostrar 127.0.0.1:8080, não 0.0.0.0:8080; o endpoint de integridade retorna JSON contendo UP. Em seguida, abra https://pdf.example.com, faça login com a conta de administrador de .env e altere a senha imediatamente.

O OCR do Stirling PDF usa o Tesseract. A imagem Docker padrão geralmente inclui pacotes de idioma comuns, como o chinês simplificado; os idiomas realmente disponíveis ainda dependem dos arquivos do contêiner atual:

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

O chinês simplificado corresponde a chi_sim.traineddata, o tradicional a chi_tra.traineddata e o inglês a eng.traineddata. Se um idioma não aparecer na interface, não altere apenas a lista suspensa; primeiro confirme se o pacote de idioma correspondente realmente existe.

O resultado do OCR também depende do arquivo original. Uma digitalização a 300 DPI, com texto nítido e orientação de página correta, costuma ser muito melhor do que uma foto tirada com o celular, com sombras evidentes e texto menor que 8 pt. O Tesseract consegue reconhecer texto, mas não reconstruirá de forma confiável estruturas complexas de tabelas e fórmulas.

Após processar uma digitalização de teste, confirme pelo menos três coisas: que o chinês pode ser pesquisado, que o texto pode ser copiado e que o PDF baixado abre em leitores comuns. Ver apenas uma mensagem de tarefa concluída não significa que o resultado do reconhecimento seja realmente utilizável.

A configuração mais perigosa é desativar o login e expor a 8080 diretamente à internet. Outras pessoas não só podem consumir sua CPU e memória, como também podem enviar arquivos maliciosamente construídos para sondar os componentes de conversão.

Verifique cada item antes de publicar:

• SECURITY_ENABLELOGIN=true, e a senha de administrador já foi alterada;
• A 8080 está vinculada apenas a 127.0.0.1, e somente 80/443 estão abertas à internet;
• /configs está persistido, e .env tem permissões 600;
• Usuários, chaves de API e recursos desnecessários são desativados a tempo;
• Baixe atualizações de segurança regularmente, mas faça backup antes de cada atualização;
• Configure alertas de disco no servidor para evitar que arquivos temporários ou logs encham o disco.

A página de segurança do Stirling PDF afirma explicitamente que versões antigas não receberão correções de segurança retroativas. Não deixe uma instância pública sem atualização por anos, nem considere que "o contêiner inicia" significa que a manutenção de segurança está concluída.

Na versão gratuita, os usuários com login, as configurações locais e o banco de dados H2 integrado ficam principalmente em /configs. A forma mais simples é fazer backup de todo o diretório data, em vez de copiar apenas compose.yaml.

Primeiro pare o contêiner e crie um arquivo compactado mais 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

Um arquivo compactado local não é um backup completo. Depois use restic, rclone ou armazenamento de objetos para copiá-lo para outra máquina e defina um período de retenção. Você pode seguir o guia de simulação de backup e restauração em VPS para fazer uma restauração em outra máquina.

Ao restaurar, não sobrescreva diretamente os arquivos de banco de dados em 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

Após restaurar, faça login de verdade e confirme que as contas, as configurações e os idiomas de OCR continuam lá. Um arquivo de backup que existe mas nunca foi restaurado conta apenas como "ter um arquivo compactado", não como "ter capacidade de restauração".

Após a implantação, eu validaria com os seguintes critérios em vez de apenas verificar se a página inicial abre:

1. docker compose ps mostra o contêiner como healthy;
2. A 8080 escuta apenas no endereço de loopback e não pode ser acessada diretamente pela internet;
3. O certificado HTTPS é válido e o HTTP redireciona automaticamente para HTTPS;
4. Usuários sem login não podem usar as ferramentas de PDF;
5. Execute um arquivo de teste para mesclar, um para comprimir e um para OCR em chinês;
6. As contas e configurações continuam existindo após reiniciar o contêiner;
7. Restaure do backup para um diretório de teste, e você consegue fazer login novamente e processar arquivos.

Se você pretende usar com sua equipe a longo prazo, acrescente também a rotação de logs do contêiner, alertas de disco e janelas de atualização. Para verificações de integridade, limites de recursos e estratégias de reversão em Compose de produção, você pode continuar lendo a lista de configuração de produção do Docker Compose em VPS.

O valor do Stirling PDF não é apenas "muitas ferramentas de PDF gratuitas", mas sim que arquivos sensíveis não precisam passar por sites desconhecidos. Depois de montar com uma VPS de 2 núcleos e 4 GB, Docker Compose, Caddy HTTPS e login obrigatório, e fazer uma rodada de testes de OCR, reinício e restauração, o serviço estará realmente utilizável.