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ça | O que é |
|---|---|
| Instância EC2 | Windows 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.exe | Build 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\Caddyfile | Toda a configuração do proxy: TLS sob demanda, map de host→upstream, redirecionamentos www→apex, :80→https |
C:\caddy\hosts.map | Uma linha {domínio} {sub}.b1.church por domínio roteável, importada no bloco map do Caddyfile |
sync-hostmap.ps1 + tarefa CaddyHostmapSync | Tarefa 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-certs | Armazenamento compartilhado de certificados (region us-east-2, prefixo certs) — os certificados sobrevivem à reconstrução das instâncias |
Papel IAM CaddyRole | Concede à 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:
| Endpoint | Papel |
|---|---|
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/hostmap | Exige 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
- O navegador resolve
minhaigreja.org→3.23.251.61(registroAno apex, ouCNAME proxy.b1.church). - 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). - O
mapresolve 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. - O
reverse_proxyconecta em{sub}.b1.church:443com 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 comoX-Church-Host(a Vercel sobrescreve oX-Forwarded-Hostcom 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 comox-public-hostpara o cabeçalhoLinkcanônico, orobots.txte ositemap.xml; umx-public-hostenviado pelo cliente é sempre removido. OChurchJsonLddo schema.org ainda usa a URLb1.church(ler cabeçalhos ali tornaria as páginas dinâmicas). - 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:
- 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". - Saúde da API:
authorizeprecisa retornar 404 para um domínio falso ehostmap(com o cabeçalhox-internal-key) precisa retornar 200 antes de qualquer outra coisa.
Depois:
- 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-s3usa as chavesbucket/region/prefix, que correspondem ao layout existente de certificados; o forkss098usahost/endpointe não encontrará os certificados existentes. - Arquivos:
Caddyfile+sync-hostmap.ps1+internal-key.txt(oINTERNAL_API_KEYde produção, uma linha) emC:\caddy\; semeie o mapa uma vez comsync-hostmap.ps1 -NoReload. - Verificações antes do primeiro start:
caddy list-modulesprecisa mostrar o módulo de armazenamento s3;caddy adaptprecisa emitir"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"no bloco de armazenamento;caddy validateprecisa passar. - 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. - Tarefa de sincronização: registre
CaddyHostmapSync(SYSTEM, a cada 5 min + na inicialização, limite de execução de 4 minutos). - Verifique antes da troca forçando a resolução dos domínios para
127.0.0.1comcurl --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; eRestart-Service caddyprecisa voltar servindo sem nenhuma reconfiguração manual — esse teste de reinício é todo o propósito do desenho estático. - 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)
| Armadilha | Sintoma | Correção |
|---|---|---|
tls_server_name {vars.upstream} no transporte do reverse_proxy | Todo 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.map | O handler map do Caddy falha de forma definitiva com uma chave de entrada duplicada — uma linha ruim pode derrubar a configuração inteira | O 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) |
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.
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 emcaddy-service.err.log); histórico de sincronização emC:\caddy\sync-hostmap.log. - Forçar atualização do mapa:
Start-ScheduledTask -TaskName CaddyHostmapSync. - Mudança de configuração: edite
C:\caddy\Caddyfile, depoiscaddy validate+caddy reload(ouRestart-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.mapantigo 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.61ouCNAME proxy.b1.church.
Páginas relacionadas
- Roteamento de sites e multi-site — como a requisição proxiada se resolve para uma igreja/site no B1App
- Implantação da API — implantando a API de Membership que serve
authorize/hostmap