Pular para o conteúdo principal

Proxy de domínio personalizado com Caddy

Domínios personalizados de igrejas (minhaigreja.org → o site B1 da igreja) terminam em uma única máquina EC2 Windows rodando o Caddy. A máquina é dona dos certificados TLS, resolve cada domínio para o seu site {sub}.b1.church e faz proxy reverso com um cabeçalho Host reescrito. Toda a sua configuração são dois arquivos — um Caddyfile estático e um hosts.map atualizado a partir da API de Membership — então ela sobrevive a reinicializações sem nenhum estado em tempo de execução. Esta página cobre como a máquina é montada do zero, como ela opera e as armadilhas testadas em campo que vão pegar quem for reconstruí-la.

Para saber como uma requisição se resolve para uma igreja/site depois que chega ao B1App, veja Roteamento de sites e multi-site.

Componentes​

PeçaO que é
Instância EC2Windows Server; Elastic IP 3.23.251.61 (incorporado ao DNS das igrejas no mundo todo — o IP é permanente, as instâncias são descartáveis)
C:\caddy\caddy.exeBuild personalizado do Caddy com o módulo de armazenamento techknowlogick/certmagic-s3 — o Caddy padrão não consegue ler o armazenamento de certificados
C:\caddy\CaddyfileToda a configuração do proxy: TLS sob demanda, map de host→upstream, redirecionamentos www→apex, :80→https
C:\caddy\hosts.mapUma linha {domínio} {sub}.b1.church por domínio roteável, importada no bloco map do Caddyfile
sync-hostmap.ps1 + tarefa CaddyHostmapSyncTarefa agendada (a cada 5 min + na inicialização, como SYSTEM) que atualiza o hosts.map a partir da API e recarrega o Caddy de forma graciosa somente quando há mudança
Serviço Windows caddy (wrapper WinSW)Roda caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile; reinicia automaticamente em caso de falha. O Caddy não é compatível com o SCM, então um wrapper é obrigatório
Bucket S3 churchapps-caddy-certsArmazenamento compartilhado de certificados (region us-east-2, prefixo certs) — os certificados sobrevivem à reconstrução das instâncias
Papel IAM CaddyRoleConcede à instância acesso ao S3; o Caddy usa a cadeia padrão de credenciais da AWS (nenhuma chave na configuração)

Os dois endpoints da API dos quais a máquina depende​

Ambos na API de Membership. authorize é anônimo; hostmap exige o cabeçalho x-internal-key: <INTERNAL_API_KEY> desde o PR #67 da Api (16/08/2026) — o sync-hostmap.ps1 o lê de C:\caddy\internal-key.txt:

EndpointPapel
GET /membership/domains/authorize?domain={host}O gate ask de TLS sob demanda do Caddy: 200 {"authorized":true} quando o host (ou, para um host www., o seu apex) é uma linha em domains; 404 caso contrário. É o controle contra abuso — o Caddy não emite certificado para um host que este endpoint rejeita
GET /membership/domains/hostmapExige x-internal-key (ou um JWT de administrador do servidor). text/plain, linhas {domínio} {sub}.b1.church ordenadas e sem duplicatas (sensível ao site: um domínio atribuído a um site secundário aponta para o subdomínio daquele site). Fonte do map

Fluxo da requisição​

  1. O navegador resolve minhaigreja.org → 3.23.251.61 (registro A no apex, ou CNAME proxy.b1.church).
  2. O Caddy encerra o TLS. Certificado disponível no S3 → serve; SNI desconhecido → pergunta ao authorize; 200 → emite sob demanda pelo Let's Encrypt; 404 → o handshake é recusado (sem certificado, sem resposta — um host desconhecido recebe recusa de TLS, e não um erro HTTP).
  3. O map resolve o Host para {sub}.b1.church; www.{apex} recebe um 302 para o apex; um host autorizado mas ainda não mapeado (um domínio recém-criado dentro da janela de sincronização de até 5 minutos) recebe um 404 limpo.
  4. O reverse_proxy conecta em {sub}.b1.church:443 com SNI e Host reescritos para o upstream, de modo que a borda da Vercel serve o site do B1App. O Caddy também envia o domínio original do visitante como X-Church-Host (a Vercel sobrescreve o X-Forwarded-Host com o Host reescrito). O middleware do B1App aceita esse cabeçalho somente quando /domains/public/lookup/{host} o mapeia para o mesmo {sub} do host da requisição, e então o expõe como x-public-host para o cabeçalho Link canônico, o robots.txt e o sitemap.xml; um x-public-host enviado pelo cliente é sempre removido. O ChurchJsonLd do schema.org ainda usa a URL b1.church (ler cabeçalhos ali tornaria as páginas dinâmicas).
  5. A porta 80 atende os desafios ACME HTTP-01 e redireciona com 308 todo o resto para https.

Propagação de novo domínio: um domínio salvo no B1Admin se torna roteável em até ~5 minutos (a tarefa de sincronização); seu certificado é emitido no primeiro acesso HTTPS.

Montando a máquina do zero​

Resumido a partir do procedimento testado em campo (o passo a passo completo com comandos para copiar e colar fica no workspace de operações, e não neste repositório). Pré-requisitos primeiro — sem eles a montagem não funciona:

  1. IAM: anexe o CaddyRole (acesso ao S3 do bucket de certificados) à instância. Verifique pelo IMDSv2 a partir da máquina — observe que um GET simples ao IMDS que retorna 401 significa apenas que o IMDSv2 é obrigatório, e não que "não há papel".
  2. Saúde da API: authorize precisa retornar 404 para um domínio falso e hostmap (com o cabeçalho x-internal-key) precisa retornar 200 antes de qualquer outra coisa.

Depois:

  1. Binário: baixe um build personalizado do serviço de builds do Caddy — https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3 (~57 MB contra ~45 MB do padrão; v2.11.4 na data desta redação). A escolha do módulo importa: techknowlogick/certmagic-s3 usa as chaves bucket/region/prefix, que correspondem ao layout existente de certificados; o fork ss098 usa host/endpoint e não encontrará os certificados existentes.
  2. Arquivos: Caddyfile + sync-hostmap.ps1 + internal-key.txt (o INTERNAL_API_KEY de produção, uma linha) em C:\caddy\; semeie o mapa uma vez com sync-hostmap.ps1 -NoReload.
  3. Verificações antes do primeiro start: caddy list-modules precisa mostrar o módulo de armazenamento s3; caddy adapt precisa emitir "module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs" no bloco de armazenamento; caddy validate precisa passar.
  4. Serviço: instale pelo WinSW (id do serviço caddy, reinício automático em falha, logs rotativos). Roda como LocalSystem, que alcança o IMDS para as credenciais do papel.
  5. Tarefa de sincronização: registre CaddyHostmapSync (SYSTEM, a cada 5 min + na inicialização, limite de execução de 4 minutos).
  6. Verifique antes da troca forçando a resolução dos domínios para 127.0.0.1 com curl --resolve (a máquina não tem tráfego real até o EIP ser movido): um domínio existente precisa servir com um certificado válido reaproveitado; www. precisa retornar 302; um host desconhecido precisa ser recusado no TLS; e Restart-Service caddy precisa voltar servindo sem nenhuma reconfiguração manual — esse teste de reinício é todo o propósito do desenho estático.
  7. Entrada em produção: reassocie o Elastic IP 3.23.251.61 à nova instância. O DNS das igrejas nunca muda.

Armadilhas testadas em campo (aprendidas da forma difícil — não regredir)​

ArmadilhaSintomaCorreção
tls_server_name {vars.upstream} no transporte do reverse_proxyTodo domínio com proxy retorna 502: os placeholders do map resolvem vazios no momento do dial TLS ("either ServerName or InsecureSkipVerify must be specified")Use o placeholder nativo do transporte: tls_server_name {http.reverse_proxy.upstream.host}
Chaves duplicadas ou linhas lixo em hosts.mapO handler map do Caddy falha de forma definitiva com uma chave de entrada duplicada — uma linha ruim pode derrubar a configuração inteiraO script de sincronização normaliza os espaços, descarta linhas malformadas (rejeitando tudo somente se mais de 20% forem ruins), remove duplicatas (vence a primeira) e grava UTF-8 sem BOM (um BOM corrompe a primeira chave do map). A API também filtra linhas de domínio vazias ou com espaços na origem
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue)O registro da tarefa falha silenciosamente (XML fora do intervalo, erro não terminal)Monte a repetição como uma instância CIM de MSFT_TaskRepetitionPattern com Interval = "PT5M" e sem duração; adicione um ExecutionTimeLimit de 4 minutos (a primeira execução como SYSTEM pode travar em uma consulta de TLS/CRL a frio)
Aviso

A API administrativa escuta somente em localhost:2019. O modo legado em tempo de execução a expunha remotamente para que a API de Membership enviasse configurações de rotas; o desenho estático não precisa de envios remotos, e a superfície menor é deliberada. caddy reload (executado localmente pelo script de sincronização) é o único consumidor da API administrativa.

Envio legado em tempo de execução

O CaddyHelper da API (e os endpoints /membership/domains/caddy + /caddy/init) ainda existem como caminho de rollback para o modo antigo configurado em tempo de execução. Eles estão agendados para exclusão quando a máquina estática estiver estável por algumas semanas — depois disso, authorize + hostmap são os únicos pontos de integração.

Operação​

  • Logs: logs rotativos do WinSW em C:\caddy\ (stdout/err do serviço — erros de reverse proxy caem em caddy-service.err.log); histórico de sincronização em C:\caddy\sync-hostmap.log.
  • Forçar atualização do mapa: Start-ScheduledTask -TaskName CaddyHostmapSync.
  • Mudança de configuração: edite C:\caddy\Caddyfile, depois caddy validate + caddy reload (ou Restart-Service caddy — reinícios são seguros por desenho).
  • Exclusão em massa de domínios aciona a guarda de redução do script de sincronização por desenho; mova o hosts.map antigo para outro lugar e execute a tarefa novamente para aceitar uma redução grande e intencional.
  • Instruções de DNS para as igrejas não mudam nunca: apex A 3.23.251.61 ou CNAME proxy.b1.church.

Páginas relacionadas​