Caddy proxy za domene cerkva
Domene cerkva po meri (mychurch.org → spletno mesto cerkve B1) se končajo na enem samem Windows EC2 strežniku, na katerem teče Caddy. Ta strežnik hrani TLS certifikate, vsako domeno preslika na njeno spletno mesto {sub}.b1.church in zahteve posreduje naprej s prepisano glavo Host. Njegova celotna konfiguracija je sestavljena iz dveh datotek, statične Caddyfile in datoteke hosts.map, ki se osvežuje iz Membership API-ja. Zato po ponovnem zagonu deluje brez stanja med izvajanjem. Ta stran opisuje, kako je strežnik zgrajen od začetka, kako deluje in katere preizkušene pasti lahko prizadenejo vsakogar, ki ga ponovno gradi.
Za to, kako zahteva po prihodu v B1App pride do cerkve ali spletnega mesta, glejte Usmerjanje spletnih mest in več spletnih mest.
Sestavni deli
| Del | Kaj je |
|---|---|
| EC2 instanca | Windows Server; elastični IP 3.23.251.61 (vgrajen v DNS cerkva po svetu — IP je trajen, instance pa so zamenljive) |
C:\caddy\caddy.exe | Prilagojena različica Caddy z modulom za shranjevanje techknowlogick/certmagic-s3 — standardni Caddy ne more brati shrambe certifikatov |
C:\caddy\Caddyfile | Celotna konfiguracija proxyja: TLS na zahtevo, preslikava map gostitelj→vir, preusmeritve www→apex, :80→https |
C:\caddy\hosts.map | Ena vrstica {domain} {sub}.b1.church za vsako domeno, ki jo je mogoče usmerjati; uvožena v blok map v Caddyfile |
sync-hostmap.ps1 + naloga CaddyHostmapSync | Načrtovana naloga (vsakih 5 minut in ob zagonu, kot SYSTEM) osveži hosts.map iz API-ja in Caddy elegantno ponovno naloži samo ob spremembi |
Storitev Windows caddy (ovoj WinSW) | Izvaja caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile; samodejni ponovni zagon ob napaki. Caddy ni SCM-aware, zato je ovoj obvezen |
S3 bucket churchapps-caddy-certs | Skupna shramba certifikatov (region us-east-2, predpona certs) — certifikati preživijo ponovne gradnje instanc |
IAM vloga CaddyRole | Instanci omogoča dostop do S3; Caddy uporablja privzeto verigo poverilnic AWS (v konfiguraciji ni ključev) |
Dva API-ja, od katerih je strežnik odvisen
Oba sta na Membership API-ju. authorize je anonimen, hostmap pa od Api PR #67 (2026-08-16) zahteva glavo x-internal-key: <INTERNAL_API_KEY>. Skripta sync-hostmap.ps1 jo prebere iz C:\caddy\internal-key.txt:
| Endpoint | Vloga |
|---|---|
GET /membership/domains/authorize?domain={host} | Vrata ask za TLS na zahtevo pri Caddy: 200 {"authorized":true}, če je gostitelj (ali pri gostitelju www. njegov apex) vrstica v domains; sicer 404. To je nadzor zlorab — Caddy ne bo izdal certifikata za gostitelja, ki ga ta endpoint zavrne |
GET /membership/domains/hostmap | Zahteva x-internal-key (ali JWT skrbniškega strežnika). Vrne text/plain, urejene in deduplicirane vrstice {domain} {sub}.b1.church (upoštevajo spletna mesta: domena, dodeljena sekundarnemu spletnemu mestu, kliče poddomeno tega spletnega mesta). Vir za map |
Potek zahteve
- Brskalnik razreši
mychurch.org→3.23.251.61(zapis apexAaliCNAME proxy.b1.church). - Caddy zaključi TLS. Če je certifikat v S3, ga postreže; za neznani SNI se vpraša
authorize; odgovor 200 → izda certifikat na zahtevo prek Let's Encrypt; odgovor 404 → rokovanje je zavrnjeno (brez certifikata, brez odgovora — neznan gostitelj dobi zavrnitev TLS, ne napake HTTP). maprazreši gostitelja v{sub}.b1.church;www.{apex}dobi preusmeritev 302 na apex; gostitelj, ki je odobren, a še ni preslikan (nova domena znotraj okna sinhronizacije ≤5 minut), dobi čist odgovor 404.reverse_proxyse poveže na{sub}.b1.church:443s SNI, glava Host pa je prepisana na vir, tako da Vercelov rob postreže spletno mesto B1App. Caddy obiskovalčevo prvotno domeno pošlje tudi kotX-Church-Host(Vercel prepišeX-Forwarded-Hosts prepisanim Host). Vmesna programska oprema B1App jo sprejme samo, če/domains/public/lookup/{host}to domeno preslika na isti{sub}kot gostitelj zahteve. Nato jo izpostavi kotx-public-hostza kanonično glavoLink,robots.txtinsitemap.xml; s strani odjemalca poslanix-public-hostje vedno odstranjen. Schema.orgChurchJsonLdše vedno uporablja URLb1.church(branje glav tam bi naredilo strani dinamične).- Vrata 80 posredujejo izzive ACME HTTP-01 in vse ostalo preusmerijo s 308 na https.
Širjenje nove domene: domena, shranjena v B1Admin, postane usmerljiva v približno 5 minutah (naloga sinhronizacije); njen certifikat se izda ob prvem zahtevku HTTPS.
Gradnja strežnika od začetka
Strnjeno po preizkušenem postopku (celoten postopek po korakih s kopirnimi ukazi je v delovnem prostoru za operacije, ne v tem repozitoriju). Najprej predpogoji — brez njih gradnja ne deluje:
- IAM: pripnite
CaddyRole(dostop do S3 za shrambo certifikatov) na instanco. Preverite prek IMDSv2 z javnega strežnika — opomba: sam GET na IMDS, ki vrne 401, pomeni le, da je IMDSv2 vsiljen, ne pa »brez vloge«. - Zdravje API-ja:
authorizemora za neobstoječo domeno vrniti 404,hostmap(z glavox-internal-key) pa 200, preden karkoli drugega.
Nato:
- Binarna datoteka: prenesite prilagojeno gradnjo iz storitve gradnje Caddy:
https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3(~57 MB v primerjavi z ~45 MB standardne različice; v2.11.4 ob pisanju). Izbira modula je pomembna:techknowlogick/certmagic-s3uporablja ključebucket/region/prefix, ki ustrezajo obstoječi postavitvi certifikatov; vejicass098uporabljahost/endpointin ne bo našla obstoječih certifikatov. - Datoteke:
Caddyfile+sync-hostmap.ps1+internal-key.txt(produkcijskiINTERNAL_API_KEY, ena vrstica) vC:\caddy\; enkrat napolnite preslikavo zsync-hostmap.ps1 -NoReload. - Vrata pred prvim zagonom:
caddy list-modulesmora prikazati modul za shranjevanje s3;caddy adaptmora v bloku shranjevanja izpisati"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs";caddy validatemora uspeti. - Storitev: namestite prek WinSW (ID storitve
caddy, samodejni ponovni zagon ob napaki, sprotni dnevniki). Teče kot LocalSystem, ki doseže IMDS za poverilnice vloge. - Naloga sinhronizacije: registrirajte
CaddyHostmapSync(SYSTEM, vsakih 5 minut in ob zagonu, omejitev izvajanja 4 minute). - Preverjanje pred preklopom: domene prisilno razrešite na
127.0.0.1zcurl --resolve(strežnik nima pravega prometa, dokler se EIP ne premakne): obstoječa domena mora strežati z veljavnim, prenesenim certifikatom;www.mora dati 302; neznan gostitelj mora dobiti zavrnitev TLS;Restart-Service caddymora ponovno zagnati strežbo brez ročnega ponovnega polnjenja — prav ta test ponovnega zagona je bistvo statične zasnove. - Prehod v produkcijo: ponovno povežite elastični IP
3.23.251.61z novo instanco. DNS cerkva se nikoli ne spremeni.
Preizkušene pasti (spoznane na težek način — ne vračajte se k njim)
| Past | Simptom | Popravek |
|---|---|---|
tls_server_name {vars.upstream} v transportu reverse_proxy | Vsaka posredovana domena vrne 502: nadomestni znaki v preslikavi se ob vzpostavitvi TLS izpraznijo ("either ServerName or InsecureSkipVerify must be specified") | Uporabite nadomestni znak, ki je del transporta: tls_server_name {http.reverse_proxy.upstream.host} |
Podvojeni ključi ali nesmiselne vrstice v hosts.map | Obdelovalnik map pri Caddy ob podvojenem vhodnem ključu ustavi nalaganje z napako — ena slaba vrstica lahko podre celotno konfiguracijo | Skripta za sinhronizacijo normalizira presledke, izpusti napačno oblikovane vrstice (zavrne v celoti le, če je >20 % slabih), odstrani podvojene vnose tako, da obdrži prvega, in zapiše UTF-8 brez BOM (BOM pokvari prvi ključ preslikave). API tudi filtrira prazne vrstice domen oziroma tiste, ki vsebujejo presledek, že pri viru |
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue) | Registracija naloge tiho odpove (XML z vrednostjo izven območja, nepreklicna napaka) | Ponovitev zgradite kot primerek CIM MSFT_TaskRepetitionPattern z Interval = "PT5M" in brez trajanja; dodajte ExecutionTimeLimit 4 minute (prvi zagon kot SYSTEM se lahko zatakne ob hladnem iskanju TLS/CRL) |
Administrativni API se veže samo na localhost:2019. Zastareli način izvajanja je to izpostavil na daljavo, da je Membership API lahko potiskal konfiguracije poti; statična zasnova ne potrebuje potiskov na daljavo, manjša površina pa je namerna. caddy reload (ki ga lokalno zažene skripta za sinhronizacijo) je edini porabnik administrativnega API-ja.
CaddyHelper v API-ju (ter endpointa /membership/domains/caddy in /caddy/init) še vedno obstaja kot pot za vrnitev na stari način, konfiguriran med izvajanjem. Načrtovano je, da bodo izbrisani, ko bo statični strežnik nekaj tednov stabilen — potem sta authorize in hostmap edini točki vključitve.
Delovanje
- Dnevniki: sprotni dnevniki WinSW v
C:\caddy\(standardni izhod/napake storitve — napake reverse-proxyja končajo vcaddy-service.err.log); zgodovina sinhronizacije vC:\caddy\sync-hostmap.log. - Prisilno osveži preslikavo:
Start-ScheduledTask -TaskName CaddyHostmapSync. - Sprememba konfiguracije: uredite
C:\caddy\Caddyfile, natocaddy validate+caddy reload(aliRestart-Service caddy— ponovni zagoni so po zasnovi varni). - Množično brisanje domen sproži zaščito pred krčenjem skripte za sinhronizacijo, kar je namerno; stari
hosts.mappremaknite na stran in ponovno zaženite nalogo, da sprejmete namerno veliko krčenje. - Navodila DNS za cerkve se ne spremenijo nikoli: apex
A 3.23.251.61aliCNAME proxy.b1.church.
Sorodne strani
- Usmerjanje spletnih mest in več spletnih mest — kako se posredovana zahteva razreši v cerkev/spletno mesto v B1App
- Namestitev API-ja — namestitev Membership API-ja, ki strežbo
authorize/hostmap