Caddy Özel Alan Adı Proxy'si
Özel kilise alan adları (mychurch.org → kilisenin B1 web sitesi), Caddy çalıştıran tek bir Windows EC2 makinesine gelir. Bu makine TLS sertifikalarını yönetir, her alan adını kendi {sub}.b1.church sitesine çözümler ve Host başlığını yeniden yazarak ters proxy yapar. Tüm yapılandırması iki dosyadan oluşur: statik bir Caddyfile ve Membership API'den yenilenen bir hosts.map. Bu yüzden yeniden başlatmalara çalışma zamanı durumu olmadan dayanır. Bu sayfa makinenin sıfırdan nasıl kurulduğunu, nasıl çalıştığını ve bunu yeniden kuracak herkesi ısıran, sahada test edilmiş tuzakları anlatır.
Bir isteğin B1App'e ulaştıktan sonra hangi kilise ve siteye nasıl çözüldüğü için bkz. Web Sitesi Yönlendirmesi ve Çoklu Site.
Bileşenler
| Parça | Açıklama |
|---|---|
| EC2 örneği | Windows Server; Elastic IP 3.23.251.61 (kiliselerin DNS kayıtlarında dünya genelinde kayıtlıdır; IP kalıcıdır, örnekler ise tek kullanımlıktır) |
C:\caddy\caddy.exe | Özel Caddy derlemesi, techknowlogick/certmagic-s3 depolama modülüyle. Standart Caddy sertifika deposunu okuyamaz |
C:\caddy\Caddyfile | Tüm proxy yapılandırması: isteğe bağlı TLS, ana bilgisayar→üst hedef map'i, www→apex yönlendirmeleri, :80→https |
C:\caddy\hosts.map | Yönlendirilebilir her alan adı için bir {domain} {sub}.b1.church satırı; Caddyfile'daki map bloğuna içe aktarılır |
sync-hostmap.ps1 + CaddyHostmapSync görevi | Zamanlanmış görev (5 dakikada bir ve açılışta, SYSTEM olarak) hosts.map dosyasını API'den yeniler; yalnızca değişiklik olduğunda Caddy'yi zarifçe yeniden yükler |
Windows hizmeti caddy (WinSW sarmalayıcısı) | caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile çalıştırır; hata durumunda otomatik yeniden başlatır. Caddy SCM farkındalığına sahip olmadığı için sarmalayıcı gereklidir |
S3 kovası churchapps-caddy-certs | Ortak sertifika deposu (region us-east-2, önek certs); sertifikalar makine yeniden kurulsa bile korunur |
IAM rolü CaddyRole | Örneğe S3 erişimi verir; Caddy AWS varsayılan kimlik bilgisi zincirini kullanır (yapılandırmada anahtar yoktur) |
Makinenin bağlı olduğu iki API uç noktası
İkisi de Membership API üzerindedir. authorize anonimdir. hostmap ise Api PR #67'den (2026-08-16) beri x-internal-key: <INTERNAL_API_KEY> başlığını gerektirir. sync-hostmap.ps1 bu anahtarı C:\caddy\internal-key.txt dosyasından okur:
| Uç nokta | Görevi |
|---|---|
GET /membership/domains/authorize?domain={host} | Caddy'nin isteğe bağlı TLS ask kapısı. Ana bilgisayar (www. ana bilgisayarı için üst alan adı) domains tablosunda bir satırsa 200 {"authorized":true}, aksi halde 404 döner. Bu, kötüye kullanıma karşı bir denetimdir: Caddy, bu uç noktanın reddettiği bir ana bilgisayar için sertifika vermez |
GET /membership/domains/hostmap | x-internal-key (veya sunucu yöneticisi JWT'si) gerektirir. text/plain biçiminde, sıralı ve tekilleştirilmiş {domain} {sub}.b1.church satırları döner. Site farkındalığı vardır: ikincil bir siteye atanmış alan adı, o sitenin alt alan adına yönlenir. map'in kaynağıdır |
İstek akışı
- Tarayıcı
mychurch.orgadresini3.23.251.61'e çözümler (apexAkaydı veyaCNAME proxy.b1.church). - Caddy TLS'yi sonlandırır. Sertifika S3'te varsa sunulur. SNI bilinmiyorsa
authorizesorulur; 200 dönerse Let's Encrypt üzerinden isteğe bağlı olarak verilir; 404 dönerse el sıkışma reddedilir. Sertifika yoktur, yanıt yoktur. Bilinmeyen bir ana bilgisayar HTTP hatası değil, TLS reddi alır. map, ana bilgisayarı{sub}.b1.church'e çözer.www.{apex}302 ile apex'e yönlendirilir. Yetkili ama henüz eşlenmemiş bir ana bilgisayar (≤5 dakikalık senkronizasyon penceresi içindeki yeni bir alan adı) temiz bir 404 alır.reverse_proxy,{sub}.b1.church:443'e SNI ve yeniden yazılmış Host ile bağlanır. Böylece Vercel'in kenar sunucusu B1App sitesini sunar. Caddy ayrıca ziyaretçinin özgün alan adınıX-Church-Hostolarak gönderir, çünkü VercelX-Forwarded-Hostbaşlığını yeniden yazılmış Host ile üzerine yazar. B1App ara katmanı bu başlığı yalnızca/domains/public/lookup/{host}isteği, alan adını istek ana bilgisayarıyla aynı{sub}'a eşlediğinde kabul eder. Kabul edilirse kanonikLinkbaşlığı,robots.txtvesitemap.xmliçinx-public-hostolarak sunulur. İstemcinin gönderdiğix-public-hosther zaman silinir. Schema.orgChurchJsonLdhâlâb1.churchURL'sini kullanır; bu yerde başlıkları okumak sayfaları dinamik hale getirirdi.-
- port ACME HTTP-01 doğrulamalarını geçirir ve diğer her şeyi https'e 308 ile yönlendirir.
Yeni alan adlarının yayılımı: B1Admin'de kaydedilen bir alan adı yaklaşık 5 dakika içinde yönlendirilebilir hale gelir (senkronizasyon görevi). Sertifikası ise ilk HTTPS isteğinde basılır.
Makineyi sıfırdan kurmak
Bu, sahada test edilmiş prosedürün özetidir. Adım adım kopyala-yapıştır komutlarının tamamı bu depoda değil, operasyon çalışma alanındadır. Önce ön koşullar gelir. Onlar olmadan kurulum çalışmaz:
- IAM:
CaddyRolerolünü (sertifika kovasına S3 erişimi) örneğe ekleyin. Makineden IMDSv2 ile doğrulayın. Düz bir IMDS GET isteğinin 401 dönmesi yalnızca IMDSv2'nin zorunlu olduğu anlamına gelir; "rol yok" anlamına gelmez. - API sağlığı: Başka bir şeyden önce
authorizesahte bir alan adı için 404 dönmeli,hostmapise (x-internal-keybaşlığıyla) 200 dönmelidir.
Ardından:
- İkili dosya: Caddy'nin derleme servisinden özel bir derleme indirin:
https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3(yazı sırasında v2.11.4, yaklaşık 57 MB; standart derleme yaklaşık 45 MB). Modül seçimi önemlidir.techknowlogick/certmagic-s3, mevcut sertifika düzenine uyanbucket/region/prefixanahtarlarını kullanır.ss098çatalı isehost/endpointkullanır ve mevcut sertifikaları bulamaz. - Dosyalar:
Caddyfile,sync-hostmap.ps1veinternal-key.txt(üretimINTERNAL_API_KEY, tek satır) dosyalarınıC:\caddy\içine koyun. Haritayı bir kezsync-hostmap.ps1 -NoReloadile doldurun. - İlk başlatmadan önceki kapılar:
caddy list-moduless3 depolama modülünü göstermelidir.caddy adaptdepolama bloğunda"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"üretmelidir.caddy validategeçmelidir. - Hizmet: WinSW ile kurun (hizmet kimliği
caddy, hata durumunda otomatik yeniden başlatma, döner günlükler). LocalSystem olarak çalışır ve rol kimlik bilgileri için IMDS'ye erişir. - Senkronizasyon görevi:
CaddyHostmapSyncgörevini kaydedin (SYSTEM, her 5 dakikada bir ve başlangıçta, 4 dakikalık yürütme sınırı). - Geçiş öncesi doğrulama: Alan adlarını
curl --resolveile127.0.0.1'e zorlayın. EIP taşınana kadar makinede gerçek trafik yoktur. Mevcut bir alan adı, taşınmış geçerli sertifikasıyla sunulmalıdır.www.302 dönmelidir. Bilinmeyen bir ana bilgisayar TLS ile reddedilmelidir.Restart-Service caddykomutundan sonra makine elle yeniden ısıtma yapılmadan sunmaya dönmelidir. Bu yeniden başlatma testi, statik tasarımın tüm amacıdır. - Canlıya geçiş: Elastic IP
3.23.251.61'i yeni örneğe yeniden bağlayın. Kiliselerin DNS kayıtları hiç değişmez.
Sahada test edilmiş tuzaklar (zor yoldan öğrenildi, geri dönmeyin)
| Tuzak | Belirti | Çözüm |
|---|---|---|
reverse_proxy transport'unda tls_server_name {vars.upstream} | Proxy'lenen her alan adı 502 verir. Map yer tutucuları TLS bağlantısı kurulurken boş çözülür ("either ServerName or InsecureSkipVerify must be specified") | Transport'a özgü yer tutucuyu kullanın: tls_server_name {http.reverse_proxy.upstream.host} |
hosts.map içinde yinelenen anahtarlar veya çöp satırlar | Caddy'nin map işleyicisi, yinelenen bir giriş anahtarında sert hata verir. Tek bir bozuk satır tüm yapılandırmayı çökertebilir | Senkronizasyon betiği boşlukları normalleştirir, hatalı satırları atar (yalnızca satırların %20'den fazlası bozuksa tamamını reddeder), ilk gelen kazanır şeklinde tekilleştirir ve BOM'suz UTF-8 yazar (BOM ilk harita anahtarını bozar). API de kaynakta boş veya boşluk içeren alan adı satırlarını filtreler |
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue) | Görev kaydı sessizce başarısız olur (aralık dışı XML, sonlandırılmayan hata) | Tekrarı, süresi olmadan ve Interval = "PT5M" ile bir MSFT_TaskRepetitionPattern CIM örneği olarak oluşturun. 4 dakikalık bir ExecutionTimeLimit ekleyin. İlk SYSTEM çalıştırması, soğuk bir TLS/CRL aramasında takılabilir |
Yönetici API'si yalnızca localhost:2019'a bağlanır. Eski çalışma zamanı modu, Membership API'nin yönlendirme yapılandırmalarını itebilmesi için bunu uzaktan açıyordu. Statik tasarım uzaktan itme gerektirmez ve daha küçük yüzey bilinçli bir tercihtir. Senkronizasyon betiğinin yerel olarak çalıştırdığı caddy reload, yönetici API'sinin tek tüketicisidir.
API'deki CaddyHelper (ve /membership/domains/caddy + /caddy/init uç noktaları), eski çalışma zamanı yapılandırmalı moda dönüş yolu olarak hâlâ mevcuttur. Statik makine birkaç hafta kararlı çalıştıktan sonra silinmesi planlanmıştır. O zamandan sonra authorize ve hostmap tek entegrasyon noktaları olacaktır.
İşletim
- Günlükler:
C:\caddy\içindeki WinSW döner günlükleri (hizmetin stdout ve stderr çıktısı; ters proxy hatalarıcaddy-service.err.logdosyasına düşer). Senkronizasyon geçmişiC:\caddy\sync-hostmap.logiçindedir. - Harita yenilemeyi zorlamak:
Start-ScheduledTask -TaskName CaddyHostmapSync. - Yapılandırma değişikliği:
C:\caddy\Caddyfiledosyasını düzenleyin, ardındancaddy validatevecaddy reloadçalıştırın (veyaRestart-Service caddykullanın; yeniden başlatmalar tasarım gereği güvenlidir). - Toplu alan adı silme işlemi, senkronizasyon betiğinin küçülme korumasını tasarım gereği tetikler. Kasıtlı büyük bir küçülmeyi kabul ettirmek için eski
hosts.mapdosyasını kenara taşıyın ve görevi yeniden çalıştırın. - Kiliseler için DNS talimatları sonsuza dek değişmez: apex
A 3.23.251.61veyaCNAME proxy.b1.church.
İlgili Sayfalar
- Web Sitesi Yönlendirmesi ve Çoklu Site: proxy'lenen bir isteğin B1App'te bir kilise ve siteye nasıl çözüldüğü
- API Dağıtımı:
authorizevehostmapuç noktalarını sunan Membership API'nin dağıtımı