Прокси Caddy для пользовательских доменов
Пользовательские домены церквей (mychurch.org → веб-сайт церкви в B1) завершаются на одной коробке Windows EC2, на которой работает Caddy. Коробка отвечает за TLS-сертификаты, определяет, какому сайту {sub}.b1.church соответствует каждый домен, и проксирует запросы с переписанным заголовком Host. Вся её конфигурация состоит из двух файлов — статического Caddyfile и hosts.map, который обновляется из Membership API, — поэтому она переживает перезапуски без какого-либо состояния во время выполнения. На этой странице описано, как коробка собирается с нуля, как она работает и какие проверенные на практике подводные камни ждут того, кто будет её пересобирать.
Как запрос определяет церковь и сайт, попав в B1App, см. в Маршрутизация сайтов и несколько сайтов.
Компоненты
| Элемент | Что это |
|---|---|
| Экземпляр EC2 | Windows Server; Elastic IP 3.23.251.61 (прописан в DNS церквей по всему миру — IP постоянный, экземпляры одноразовые) |
C:\caddy\caddy.exe | Собственная сборка Caddy с модулем хранилища techknowlogick/certmagic-s3 — стандартный Caddy не умеет читать хранилище сертификатов |
C:\caddy\Caddyfile | Вся конфигурация прокси: on-demand TLS, map от host к апстриму, перенаправления 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> с PR Api #67 (2026-08-16) — sync-hostmap.ps1 читает его из C:\caddy\internal-key.txt:
| Эндпоинт | Роль |
|---|---|
GET /membership/domains/authorize?domain={host} | Шлюз on-demand TLS ask для 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, поэтому edge Vercel отдаёт сайт B1App. Caddy также передаёт исходный домен посетителя какX-Church-Host(Vercel перезаписываетX-Forwarded-Hostпереписанным Host). Middleware 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) |
Admin API привязан только к localhost:2019. Устаревший режим времени выполнения открывал его удалённо, чтобы Membership API мог отправлять конфигурации маршрутов; статическая схема не требует удалённых отправок, а меньшая поверхность атаки — намеренное решение. caddy reload (запускаемый локально скриптом синхронизации) — единственный потребитель admin API.
CaddyHelper в API (и эндпоинты /membership/domains/caddy + /caddy/init) по-прежнему существуют как путь отката к старому режиму с конфигурацией во время выполнения. Их запланировано удалить, когда статическая коробка проработает стабильно пару недель — после этого единственными точками интеграции останутся authorize и hostmap.
Эксплуатация
- Журналы: ротируемые журналы WinSW в
C:\caddy\(stdout/err службы — ошибки 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