Como instalar o servidor web Caddy com HTTPS automático

O Caddy é um servidor web que obtém e renova certificados TLS por omissão. Num VPS pequeno que aloja um ou dois domínios, isso elimina toda uma classe de temporizadores Certbot e ficheiros de excertos Nginx. A linguagem de configuração (Caddyfile) é curta. Proxy inverso, gzip e HTTP/2 são funções normais, não um fim de semana de módulos extra.

O Nginx continua a ser a escolha certa para algumas equipas: já têm configurações comprovadas, ou precisam de um módulo muito específico. Este guia é para o outro caso frequente — quer HTTPS que funcione num VPS Hiddence novo sem memorizar excertos include. Vamos instalar o Caddy a partir do repositório apt oficial, explicar como fala com o Let's Encrypt, servir um sítio estático, fazer proxy de uma aplicação local, alojar vários domínios, olhar para os registos e cobrir as lutas habituais pela porta 80 com Apache ou um Nginx antigo.

Quando o Caddy encaixa bem

O HTTPS automático é o título, mas o ganho diário são menos peças móveis. O Caddy escuta nas 80 e 443, redireciona HTTP para HTTPS e guarda certificados no seu diretório de dados. Continua a precisar de um domínio a apontar para o VPS. Continua a não poder partir o ACME (firewall 80/tcp, nenhum outro processo a roubar :80). Os certificados wildcard precisam de um módulo de fornecedor DNS — é um caminho mais longo do que um certificado de um só anfitrião.

• Redirecionamento HTTP→HTTPS automático e renovação de certificados
• Caddyfile legível em vez de blocos server longos
• Proxy inverso capaz para Node, Python, PHP-FPM com configuração extra, ou backends Docker
• HTTP/2 e valores TLS modernos sem uma folha de cifras
• Unidade systemd do pacote oficial

Requisitos

Um domínio tem de resolver para este VPS antes de o Caddy poder provar ACME HTTP-01. Se o DNS ainda se estiver a propagar, o Caddy falhará a emissão e tentará de novo; parece «o Caddy está partido» quando é só DNS. Pare o Apache ou o Nginx primeiro se possuírem 80/443.

• Ubuntu 22.04 ou 24.04
• Um registo A do domínio para o IP do VPS (e AAAA se usar IPv6)
• Portas 80 e 443 livres e permitidas na firewall
• Root ou sudo

Passo 1: Instalar o Caddy a partir do repositório oficial

Não instale um Caddy antigo ao acaso do universo Ubuntu se quiser comportamento TLS e ACME atuais. O projeto Caddy documenta uma origem apt. Após a instalação, o utilizador caddy existe e o serviço está ativado.

ssh root@YOUR_VPS_IP
apt update && apt -y install debian-keyring debian-archive-keyring apt-transport-https curl gpg

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list

apt update
apt -y install caddy

caddy version
systemctl status caddy --no-pager

Passo 2: Primeiro Caddyfile — sítio estático

O Caddyfile predefinido é /etc/caddy/Caddyfile. Substitua-o pelo seu domínio. O Caddy tentará obter um certificado assim que a configuração carregar se o nome de anfitrião não for localhost. Coloque os ficheiros do sítio num diretório legível pelo utilizador caddy (muitas vezes permissões ao estilo www-data, mas o pacote usa o utilizador caddy).

mkdir -p /var/www/example
echo '<h1>It works</h1>' > /var/www/example/index.html
chown -R caddy:caddy /var/www/example

cat >/etc/caddy/Caddyfile <<'EOF'
example.com {
    root * /var/www/example
    file_server
    encode gzip
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

# Watch issuance:
journalctl -u caddy -f

Passo 3: Proxy inverso de uma aplicação local

Se o Gunicorn, o Node ou o Docker escutarem em 127.0.0.1:8000, o Caddy deve ser o único processo público. A diretiva reverse_proxy reenvia Host e os cabeçalhos X-Forwarded-* de forma razoável para a maioria das aplicações. Se a aplicação gerar URL HTTP absolutos, defina as opções de proxy de confiança / HTTPS na aplicação (Django SECURE_PROXY_SSL_HEADER, Express trust proxy, e assim por diante).

app.example.com {
    encode gzip
    reverse_proxy 127.0.0.1:8000
}

# Several hosts in one file are normal:
# blog.example.com {
#     root * /var/www/blog
#     file_server
# }

Passo 4: Firewall e systemd

Permita 80 e 443. A unidade do Caddy é caddy.service; um reload chega após edições do Caddyfile se o processo estiver saudável. Se alterar variáveis de ambiente de um plugin DNS, um reinício completo é mais claro. Os certificados vivem por omissão em /var/lib/caddy/.local/share/caddy/ — inclua esse caminho nas cópias se os limites de taxa numa reinstalação lhe importarem.

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

systemctl enable --now caddy
systemctl reload caddy

# Backup cert storage (path may vary slightly by version):
ls -la /var/lib/caddy/

Passo 5: Registos, compressão e cabeçalhos

Os registos de acesso ajudam quando um robot martela um caminho ou quando depura 404. Pode registar por sítio. Acrescente cabeçalhos de segurança se alojar uma aplicação de browser; não copie um pacote enorme de cabeçalhos sem perceber HSTS (depois de definir um max-age longo, os browsers recordam-no).

example.com {
    root * /var/www/example
    file_server
    encode gzip
    log {
        output file /var/log/caddy/example.log
    }
    header {
        X-Content-Type-Options nosniff
        Referrer-Policy no-referrer-when-downgrade
        -Server
    }
}

mkdir -p /var/log/caddy
chown caddy:caddy /var/log/caddy
systemctl reload caddy

Passo 6: PHP e outros extras

O Caddy pode falar com o PHP-FPM com a diretiva php_fastcgi. Chega para muitos alojamentos WordPress ou Laravel, mas continua a precisar do php-fpm instalado e de um caminho de socket que coincida. Se já tiver uma configuração PHP Nginx perfeita, migrar numa noite é opcional — o Caddy brilha mais em proxy inverso + estático + TLS automático.

example.com {
    root * /var/www/example
    php_fastcgi unix//run/php/php8.3-fpm.sock
    file_server
}

# Confirm FPM is running:
systemctl status php8.3-fpm

Migrar a partir do Nginx sem surpresas de interrupção

Pare o Nginx antes de arrancar o Caddy ou vão lutar pelas 80/443. Baixe o TTL de DNS no dia anterior se também estiver a mudar de IP. Teste com curl --resolve para atingir o VPS novo antes de mudar o registo A. Mantenha as configurações Nginx no git durante uma semana caso precise de voltar atrás.

• systemctl stop nginx && systemctl disable nginx
• Instalar o Caddy, validar o Caddyfile, arrancar o Caddy
• curl -I --resolve example.com:443:NEW_IP https://example.com
• Só então altere o DNS se o IP for novo
• A reemissão é automática; não execute também o Certbot contra o mesmo nome de anfitrião

Resolução de problemas

As falhas ACME são quase sempre DNS, firewall ou outro serviço na porta 80. As linhas de registo do Caddy mencionam tls.obtain. Se o sítio funcionar em HTTP mas não em HTTPS, a emissão nunca foi concluída. Se vir demasiados certificados, bateu nos limites de taxa do Let's Encrypt — use a CA de ensaios ao testar, não a de produção.

• validate falha: sintaxe do Caddyfile, chave em falta
• permission denied em root: chown caddy para o diretório do sítio
• bind: address already in use — ss -tulpn | grep -E ':80|:443'
• tempo de espera do certificado: dig +short do domínio a partir do VPS, ufw allow 80
• 502 reverse_proxy: backend parado, ou fez proxy para localhost a partir de uma rede de contentores de forma incorreta

Notas de segurança

Os valores TLS predefinidos do Caddy são conservadores. O seu trabalho é a segurança da aplicação e o SSH. Não ative a API de administração do Caddy numa interface pública. O ponto de administração predefinido é local; deixe-o assim. Se usar um Caddyfile da internet, leia cada matcher — um excerto que faz reverse_proxy de /* para um IP interno pode tornar-se um proxy aberto.

• Não exponha a API de administração
• Mantenha o pacote atualizado
• HSTS só depois de ter a certeza de que o HTTPS funciona para todos os nomes de anfitrião
• Separe nomes de anfitrião de teste e de produção para proteger os limites de taxa ACME

Dicas

• caddy fmt --overwrite /etc/caddy/Caddyfile mantém o ficheiro legível
• Use excertos import quando tiver muitos sítios semelhantes
• Para Docker, a imagem caddy:alpine com um Caddyfile montado é comum
• Certificados de carácter de substituição precisam de um módulo DNS e de um token de API — proteja esse token
• Leia journalctl -u caddy antes de reescrever o ficheiro inteiro

O Caddy num VPS é: pacote oficial, um Caddyfile curto, portas 80/443 abertas, DNS já a apontar para o servidor e reload systemd após edições. Use-o como servidor de ficheiros estáticos ou como proxy inverso à frente do Gunicorn, Node ou Docker. O HTTPS automático funciona quando o ACME consegue responder na porta 80; se a emissão falhar, corrija DNS e conflitos de portas antes de culpar o Caddy. Faça cópia de /var/lib/caddy se reinstalar com frequência.