Caddy como Proxy Reverso: HTTPS Automático e SSL sem Configuração

TL;DR — Resumo Rápido

Guia completo do Caddy como proxy reverso com HTTPS automático. Configure SSL, balanceamento de carga, verificações de saúde e hospedagem multi-site.

O Caddy é um servidor web em Go que torna o HTTPS automático o comportamento padrão — não uma tarefa adicional. Diferente do Nginx ou Apache onde TLS significa instalar certbot, escrever scripts de renovação e depurar cron jobs, o Caddy negocia certificados com Let’s Encrypt ou ZeroSSL no momento em que você adiciona um domínio à sua configuração.

Pré-requisitos

• Um servidor Linux (Ubuntu 22.04/24.04, Debian, RHEL ou Docker).
• Um domínio com registros DNS A apontando para o IP público do seu servidor.
• Portas 80 e 443 abertas no firewall — o Caddy precisa de ambas para o desafio ACME HTTP-01.
• Serviços backend rodando em portas localhost (Node.js, Python, PHP, etc.).

---

Arquitetura do Caddy

O Caddy é um binário estático único escrito em Go sem dependências de tempo de execução.

HTTPS automático via ACME. Quando você configura um domínio, o Caddy:

1. Detecta que o domínio precisa de um certificado.
2. Executa um desafio ACME HTTP-01 ou TLS-ALPN-01.
3. Armazena o certificado em ~/.local/share/caddy/ (ou /var/lib/caddy/ para instalações do sistema).
4. Agenda a renovação 30 dias antes do vencimento — automaticamente.
5. Inclui respostas OCSP nos handshakes TLS para verificações de revogação mais rápidas.

API de administração. O Caddy expõe uma API REST em localhost:2019 para mudanças de configuração ao vivo — sem necessidade de reinicialização.

---

Instalação

apt (Ubuntu/Debian — recomendado)

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

Docker

docker run -d \
  --name caddy \
  -p 80:80 -p 443:443 -p 443:443/udp \
  -v $PWD/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  caddy:latest

xcaddy — Compilações Personalizadas com Plugins

xcaddy build \
  --with github.com/caddy-dns/cloudflare \
  --with github.com/mholt/caddy-ratelimit

---

Sintaxe do Caddyfile

Blocos de site:

example.com {
    reverse_proxy localhost:3000
}

Opções globais:

{
    email admin@example.com
}

Snippets reutilizáveis:

(headers_comuns) {
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        -Server
    }
}

example.com {
    import headers_comuns
    reverse_proxy localhost:3000
}

---

Configuração do Proxy Reverso

Proxy Reverso Básico

example.com {
    reverse_proxy localhost:3000
}

O Caddy gerencia automaticamente o redirecionamento HTTP→HTTPS, emissão do certificado, renovação e grampeamento OCSP.

Balanceamento de Carga

example.com {
    reverse_proxy app1:3000 app2:3000 app3:3000 {
        lb_policy round_robin
    }
}

Política	Descrição
round_robin	Distribui requisições uniformemente entre backends
least_conn	Direciona ao backend com menos conexões ativas
ip_hash	Hash do IP do cliente para sessões fixas
cookie	Usa um cookie para persistência de sessão
uri_hash	Hash da URI da requisição

Verificações de Saúde Ativas e Passivas

example.com {
    reverse_proxy app1:3000 app2:3000 {
        lb_policy least_conn
        health_uri /health
        health_interval 10s
        health_timeout 5s
        fail_duration 30s
        max_fails 3
    }
}

Manipulação de Cabeçalhos

example.com {
    reverse_proxy localhost:3000 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_down -Server
        header_down -X-Powered-By
    }
}

---

HTTPS Automático em Profundidade

Como o Caddy Obtém Certificados

1. Chega uma requisição para example.com.
2. O Caddy verifica seu armazenamento de certificados — nenhum encontrado.
3. O Caddy executa um desafio ACME HTTP-01.
4. O servidor ACME (Let’s Encrypt) verifica o token.
5. O Caddy recebe o certificado assinado e o armazena.
6. HTTP redireciona automaticamente para HTTPS.
7. O Caddy renova o certificado 30 dias antes do vencimento.

TLS Sob Demanda

Para plataformas SaaS onde usuários adicionam domínios personalizados:

{
    on_demand_tls {
        ask http://localhost:8080/verificar-dominio
        interval 2m
        burst 5
    }
}

CA Interna para Desenvolvimento Local

localhost {
    tls internal
    reverse_proxy localhost:3000
}

Execute caddy trust para instalar a CA local do Caddy no armazenamento de confiança do sistema.

---

Padrões Comuns do Caddyfile

SPA com Roteamento do Lado do Cliente

app.example.com {
    root * /var/www/app
    try_files {path} /index.html
    file_server
}

PHP com PHP-FPM

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

---

Caddy vs Nginx vs Traefik vs HAProxy

Recurso	Caddy	Nginx	Traefik	HAProxy
HTTPS automático	Integrado, padrão	Manual (certbot)	Integrado	Manual
Sintaxe de configuração	Caddyfile simples	nginx.conf complexo	YAML/TOML	Complexo
Recarga em tempo real	Sim (API + sinal)	Sim (sinal)	Sim	Sim
Balanceamento de carga	8 políticas	Round-robin, IP hash	Múltiplos	Extenso
API de administração	REST JSON	Não	REST JSON	Socket
HTTP/3 (QUIC)	Sim	Sim (v1.25+)	Sim	Não
Melhor para	HTTPS automático, simplicidade	Arquivos estáticos de alto desempenho	Docker/K8s	Balanceamento TCP

---

Caddyfile de Produção: Hospedagem Multi-Site

{
    email ops@example.com
    admin localhost:2019
}

(headers_seguranca) {
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options SAMEORIGIN
        Referrer-Policy strict-origin-when-cross-origin
        -Server
    }
}

app.example.com {
    import headers_seguranca
    encode gzip zstd

    reverse_proxy app1:3000 app2:3000 {
        lb_policy least_conn
        health_uri /health
        health_interval 15s
        fail_duration 30s
    }
}

api.example.com {
    import headers_seguranca
    reverse_proxy localhost:8080 {
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

www.example.com {
    import headers_seguranca
    encode gzip zstd
    root * /var/www/marketing
    try_files {path} /index.html
    file_server
}

---

Armadilhas e Casos Especiais

• A porta 80 deve estar acessível. O Caddy usa o desafio ACME HTTP-01. Se a porta 80 estiver bloqueada, use o desafio DNS-01 com um plugin DNS via xcaddy.
• Limites de taxa no Let’s Encrypt. Máximo 50 certificados por domínio por semana. Use a CA de staging durante os testes.
• header_up Host pode quebrar alguns backends. Teste primeiro sem esta diretiva.
• A API de administração é somente localhost por padrão. Nunca exponha a porta 2019 publicamente.
• Recarga vs reinicialização. Use sempre systemctl reload caddy em produção.

Resumo

• HTTPS automático — O Caddy obtém e renova certificados do Let’s Encrypt/ZeroSSL sem configuração.
• Sintaxe simples — Cinco linhas no Caddyfile substituem centenas de linhas de configuração do Nginx.
• 8 políticas de balanceamento de carga — incluindo sessões fixas via cookie e IP hash.
• Verificações de saúde ativas e passivas — remove e re-adiciona backends com falha automaticamente.
• TLS sob demanda — emite certificados dinamicamente para domínios de usuários.
• API REST de administração — mudanças de configuração ao vivo em localhost:2019 sem reinicializações.

Artigos Relacionados

• Configuração de Proxy Reverso Nginx
• SSL Wildcard com Let’s Encrypt e Certbot
• Redes Docker Compose
• Configuração do Balanceador de Carga HAProxy