Перейти до основного вмісту

Проксі Caddy для власних доменів

Власні домени церков (mychurch.org → сайт церкви в B1) обслуговуються єдиним сервером Windows EC2, на якому працює Caddy. Сервер володіє сертифікатами TLS, зіставляє кожен домен з його сайтом {sub}.b1.church і виконує зворотне проксіювання з переписаним заголовком Host. Уся його конфігурація складається з двох файлів: статичного Caddyfile і hosts.map, який оновлюється з Membership API. Тому він переживає перезапуски без жодного стану під час роботи. Ця сторінка описує, як сервер будується з нуля, як він працює і які перевірені на практиці пастки чекають на того, хто відбудовуватиме його заново.

Про те, як запит визначає церкву чи сайт після того, як потрапляє до B1App, див. Маршрутизація сайтів і багатосайтовість.

Компоненти​

КомпонентОпис
EC2 instanceWindows 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

Потік запиту​

  1. Браузер визначає mychurch.org → 3.23.251.61 (запис A для апекса або CNAME proxy.b1.church).
  2. Caddy завершує TLS. Якщо сертифікат є в S3 — обслуговує його; для невідомого SNI запитується authorize; 200 → видача за запитом через Let's Encrypt; 404 → рукостискання відхиляється (без сертифіката та без відповіді — невідомий хост отримує відмову TLS, а не помилку HTTP).
  3. map визначає Host як {sub}.b1.church; www.{apex} отримує 302 на апекс; хост, який авторизований, але не має відображення (новий домен у межах ≤5-хвилинного вікна синхронізації), отримує чисту 404.
  4. 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.org ChurchJsonLd і далі використовує URL b1.church (читання заголовків там зробило б сторінки динамічними).
  5. Порт 80 пропускає виклики ACME HTTP-01 і перенаправляє з кодом 308 усе інше на https.

Поширення нового домену: домен, збережений у B1Admin, стає доступним для маршрутизації протягом ~5 хвилин (завдання синхронізації); його сертифікат випускається під час першого HTTPS-запиту.

Побудова сервера з нуля​

Стисло з перевіреної на практиці процедури (покрокова інструкція з готовими командами міститься в робочому просторі операцій, а не в цьому репозиторії). Спочатку передумови — без них збірка не працюватиме:

  1. IAM: прикріпіть CaddyRole (доступ до S3 для бакета сертифікатів) до інстансу. Перевірте через IMDSv2 з самого сервера — зауважте, що просте GET до IMDS із відповіддю 401 означає лише те, що IMDSv2 увімкнено примусово, а не «немає ролі».
  2. Стан API: authorize має повертати 404 для неіснуючого домену, а hostmap (із заголовком x-internal-key) — 200, перш ніж робити будь-що інше.

Далі:

  1. Бінарний файл: завантажте власну збірку з сервісу збірки 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 і не знайде наявні сертифікати.
  2. Файли: Caddyfile + sync-hostmap.ps1 + internal-key.txt (продуктивний INTERNAL_API_KEY, один рядок) до C:\caddy\; один раз заповніть мапу командою sync-hostmap.ps1 -NoReload.
  3. Перевірки перед першим запуском: caddy list-modules має показувати модуль сховища s3; caddy adapt має видавати "module":"s3","bucket":"churchapps-caddy-certs","region":"us-east-2","prefix":"certs" у блоці сховища; caddy validate має пройти успішно.
  4. Служба: встановіть через WinSW (ідентифікатор служби caddy, автоматичний перезапуск у разі збою, журнали з ротацією). Працює від імені LocalSystem, який має доступ до IMDS для облікових даних ролі.
  5. Завдання синхронізації: зареєструйте CaddyHostmapSync (SYSTEM, кожні 5 хвилин і під час запуску, ліміт виконання 4 хвилини).
  6. Перевірка до перемикання: примусово зіставте домени з 127.0.0.1 за допомогою curl --resolve (на сервері немає реального трафіку, доки EIP не переміщено). Наявний домен має обслуговуватися з чинним перенесеним сертифікатом; www. має повертати 302; невідомий хост має отримувати відмову TLS; а Restart-Service caddy має повернути сервер у робочий стан без жодного ручного повторного заповнення. Саме цей тест перезапуску і є головною метою статичної архітектури.
  7. Перемикання в робочий режим: перепризначте 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.

Застарілий push під час виконання

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.

Пов'язані сторінки​