Проксі Caddy для власних доменів
Власні домени церков (mychurch.org → сайт церкви в B1) обслуговуються єдиним сервером Windows EC2, на якому працює Caddy. Сервер володіє сертифікатами TLS, зіставляє кожен домен з його сайтом {sub}.b1.church і виконує зворотне проксіювання з переписаним заголовком Host. Уся його конфігурація складається з двох файлів: статичного Caddyfile і hosts.map, який оновлюється з Membership API. Тому він переживає перезапуски без жодного стану під час роботи. Ця сторінка описує, як сервер будується з нуля, як він працює і які перевірені на практиці пастки чекають на того, хто відбудовуватиме його заново.
Про те, як запит визначає церкву чи сайт після того, як потрапляє до B1App, див. Маршрутизація сайтів і багатосайтовість.
Компоненти
| Компонент | Опис |
|---|---|
| EC2 instance | Windows Server; Elastic IP 3.23.251.61 (вказаний у DNS церков по всьому світу — IP постійний, а інстанси одноразові) |
C:\caddy\caddy.exe | Власна збірка Caddy з модулем сховища techknowlogick/certmagic-s3 — стандартний Caddy не може читати сховище сертифікатів |
C:\caddy\Caddyfile | Уся конфігурація проксі: TLS за запитом, map від хоста до upstream, переспрямування з www на апекс, :80 → https |
C:\caddy\hosts.map | Один рядок {domain} {sub}.b1.church для кожного домену, що може маршрутизуватися; імпортується до блоку map у Caddyfile |
sync-hostmap.ps1 + завдання CaddyHostmapSync | Заплановане завдання (кожні 5 хвилин і під час завантаження, від імені SYSTEM) оновлює hosts.map з API і коректно перезавантажує Caddy лише у разі змін |
Служба Windows caddy (обгортка WinSW) | Запускає caddy.exe run --config C:\caddy\Caddyfile --adapter caddyfile; автоматичний перезапуск у разі збою. Caddy не підтримує SCM, тому потрібна обгортка |
S3-бакет churchapps-caddy-certs | Спільне сховище сертифікатів (region us-east-2, префікс certs) — сертифікати переживають перебудову інстансів |
IAM-роль CaddyRole | Надає інстансу доступ до S3; Caddy використовує стандартний ланцюжок облікових даних AWS (ключі в конфігурації відсутні) |
Два кінцевих точки API, від яких залежить сервер
Обидві знаходяться в Membership API. authorize доступна анонімно; hostmap вимагає заголовок x-internal-key: <INTERNAL_API_KEY> починаючи з Api PR #67 (2026-08-16) — sync-hostmap.ps1 читає його з C:\caddy\internal-key.txt:
| Кінцева точка | Призначення |
|---|---|
GET /membership/domains/authorize?domain={host} | Шлюз ask для TLS за запитом у Caddy: 200 {"authorized":true}, якщо хост (або, для хоста з www., його апекс) є рядком у domains; інакше 404. Це засіб контролю зловживань — Caddy не видаватиме сертифікат для хоста, який ця кінцева точка відхиляє |
GET /membership/domains/hostmap | Вимагає x-internal-key (або JWT адміністратора сервера). text/plain, відсортовані та без дублікатів рядки {domain} {sub}.b1.church (з урахуванням сайтів: домен, призначений другорядному сайту, вказує на піддомен цього сайту). Джерело для map |
Потік запиту
- Браузер визначає
mychurch.org→3.23.251.61(записAдля апекса абоCNAME proxy.b1.church). - Caddy завершує TLS. Якщо сертифікат є в S3 — обслуговує його; для невідомого SNI запитується
authorize; 200 → видача за запитом через Let's Encrypt; 404 → рукостискання відхиляється (без сертифіката та без відповіді — невідомий хост отримує відмову TLS, а не помилку HTTP). mapвизначає Host як{sub}.b1.church;www.{apex}отримує 302 на апекс; хост, який авторизований, але не має відображення (новий домен у межах ≤5-хвилинного вікна синхронізації), отримує чисту 404.reverse_proxyпідключається до{sub}.b1.church:443з SNI і Host, переписаними на upstream, тож edge Vercel обслуговує сайт B1App. Caddy також передає початковий домен відвідувача якX-Church-Host(Vercel перезаписуєX-Forwarded-Hostпереписаним Host). Проміжне програмне забезпечення B1App приймає його лише тоді, коли/domains/public/lookup/{host}зіставляє його з тим самим{sub}, що й хост запиту, а потім передає його якx-public-hostдля канонічного заголовкаLink,robots.txtіsitemap.xml; надісланий клієнтомx-public-hostзавжди видаляється. Schema.orgChurchJsonLdі далі використовує URLb1.church(читання заголовків там зробило б сторінки динамічними).- Порт 80 пропускає виклики ACME HTTP-01 і перенаправляє з кодом 308 усе інше на https.
Поширення нового домену: домен, збережений у B1Admin, стає доступним для маршрутизації протягом ~5 хвилин (завдання синхронізації); його сертифікат випускається під час першого HTTPS-запиту.
Побудова сервера з нуля
Стисло з перевіреної на практиці процедури (покрокова інструкція з готовими командами міститься в робочому просторі операцій, а не в цьому репозиторії). Спочатку передумови — без них збірка не працюватиме:
- IAM: прикріпіть
CaddyRole(доступ до S3 для бакета сертифікатів) до інстансу. Перевірте через IMDSv2 з самого сервера — зауважте, що просте GET до IMDS із відповіддю 401 означає лише те, що IMDSv2 увімкнено примусово, а не «немає ролі». - Стан API:
authorizeмає повертати 404 для неіснуючого домену, аhostmap(із заголовкомx-internal-key) — 200, перш ніж робити будь-що інше.
Далі:
- Бінарний файл: завантажте власну збірку з сервісу збірки Caddy —
https://caddyserver.com/api/download?os=windows&arch=amd64&p=github.com/techknowlogick/certmagic-s3(~57 МБ проти ~45 МБ стандартної; v2.11.4 на момент написання). Вибір модуля важливий:techknowlogick/certmagic-s3використовує ключіbucket/region/prefix, що відповідають наявному розміщенню сертифікатів; форкss098використовуєhost/endpointі не знайде наявні сертифікати. - Файли:
Caddyfile+sync-hostmap.ps1+internal-key.txt(продуктивнийINTERNAL_API_KEY, один рядок) доC:\caddy\; один раз заповніть мапу командоюsync-hostmap.ps1 -NoReload. - Перевірки перед першим запуском:
caddy list-modulesмає показувати модуль сховища s3;caddy adaptмає видавати"module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs"у блоці сховища;caddy validateмає пройти успішно. - Служба: встановіть через WinSW (ідентифікатор служби
caddy, автоматичний перезапуск у разі збою, журнали з ротацією). Працює від імені LocalSystem, який має доступ до IMDS для облікових даних ролі. - Завдання синхронізації: зареєструйте
CaddyHostmapSync(SYSTEM, кожні 5 хвилин і під час запуску, ліміт виконання 4 хвилини). - Перевірка до перемикання: примусово зіставте домени з
127.0.0.1за допомогоюcurl --resolve(на сервері немає реального трафіку, доки EIP не переміщено). Наявний домен має обслуговуватися з чинним перенесеним сертифікатом;www.має повертати 302; невідомий хост має отримувати відмову TLS; аRestart-Service caddyмає повернути сервер у робочий стан без жодного ручного повторного заповнення. Саме цей тест перезапуску і є головною метою статичної архітектури. - Перемикання в робочий режим: перепризначте Elastic IP
3.23.251.61новому інстансу. DNS церков ніколи не змінюється.
Перевірені на практиці підводні камені (здобуті важкою ціною — не допускайте регресу)
| Підводний камінь | Симптом | Виправлення |
|---|---|---|
tls_server_name {vars.upstream} у транспорті reverse_proxy | Кожен проксійований домен повертає 502: плейсхолдери map розв'язуються порожніми на момент TLS-підключення («either ServerName or InsecureSkipVerify must be specified») | Використовуйте плейсхолдер, вбудований у транспорт: tls_server_name {http.reverse_proxy.upstream.host} |
Дубльовані ключі або сміттєві рядки в hosts.map | Обробник map у Caddy з помилкою завершується при дубльованому вхідному ключі — один поганий рядок може зупинити всю конфігурацію | Скрипт синхронізації нормалізує пробіли, відкидає некоректні рядки (відхиляє все повністю лише якщо >20% є поганими), видаляє дублікати з збереженням першого входження і записує UTF-8 без BOM (BOM пошкоджує перший ключ мапи). API також відфільтровує рядки доменів, що порожні або містять пробіли, ще на джерелі |
Register-ScheduledTask -RepetitionDuration ([TimeSpan]::MaxValue) | Реєстрація завдання мовчки не вдається (XML поза допустимим діапазоном, нефатальна помилка) | Побудуйте повторення як екземпляр CIM MSFT_TaskRepetitionPattern з Interval = "PT5M" і без тривалості; додайте ExecutionTimeLimit 4 хвилини (перший запуск від SYSTEM може зависнути на холодному пошуку TLS/CRL) |
Адміністративний API прив'язаний лише до localhost:2019. Застарілий режим виконання відкривав його віддалено, щоб Membership API міг надсилати конфігурації маршрутів; статичній архітектурі віддалені надсилання не потрібні, а менша поверхня атаки є свідомим рішенням. caddy reload (який локально запускає скрипт синхронізації) — єдиний споживач адміністративного API.
CaddyHelper в API (а також кінцеві точки /membership/domains/caddy і /caddy/init) і досі існують як шлях відкату до старого режиму з конфігурацією під час виконання. Їх заплановано видалити після того, як статичний сервер пропрацює стабільно кілька тижнів — після цього єдиними точками інтеграції залишаться authorize і hostmap.
Експлуатація
- Журнали: журнали з ротацією WinSW у
C:\caddy\(stdout/stderr служби — помилки reverse-proxy потрапляють доcaddy-service.err.log); історія синхронізації — уC:\caddy\sync-hostmap.log. - Примусове оновлення мапи:
Start-ScheduledTask -TaskName CaddyHostmapSync. - Зміна конфігурації: відредагуйте
C:\caddy\Caddyfile, а потім виконайтеcaddy validate+caddy reload(абоRestart-Service caddy— перезапуски безпечні за задумом). - Масове видалення доменів спрацьовує за задумом на захисті від зменшення в скрипті синхронізації; щоб прийняти навмисне велике скорочення, перемістіть старий
hosts.mapубік і перезапустіть завдання. - Інструкції щодо DNS для церков не змінюються назавжди: апекс
A 3.23.251.61абоCNAME proxy.b1.church.
Пов'язані сторінки
- Маршрутизація сайтів і багатосайтовість — як проксійований запит визначає церкву/сайт у B1App
- Розгортання API — розгортання Membership API, який обслуговує
authorize/hostmap