Перейти к основному содержимому

Прокси Caddy для пользовательских доменов

Пользовательские домены церквей (mychurch.org → веб-сайт церкви в B1) завершаются на одной коробке Windows EC2, на которой работает Caddy. Коробка отвечает за TLS-сертификаты, определяет, какому сайту {sub}.b1.church соответствует каждый домен, и проксирует запросы с переписанным заголовком Host. Вся её конфигурация состоит из двух файлов — статического Caddyfile и hosts.map, который обновляется из Membership API, — поэтому она переживает перезапуски без какого-либо состояния во время выполнения. На этой странице описано, как коробка собирается с нуля, как она работает и какие проверенные на практике подводные камни ждут того, кто будет её пересобирать.

Как запрос определяет церковь и сайт, попав в B1App, см. в Маршрутизация сайтов и несколько сайтов.

Компоненты​

ЭлементЧто это
Экземпляр EC2Windows 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

Поток запроса​

  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, поэтому 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.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)
Предупреждение

Admin API привязан только к localhost:2019. Устаревший режим времени выполнения открывал его удалённо, чтобы Membership API мог отправлять конфигурации маршрутов; статическая схема не требует удалённых отправок, а меньшая поверхность атаки — намеренное решение. caddy reload (запускаемый локально скриптом синхронизации) — единственный потребитель admin API.

Устаревший push во время выполнения

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.

Связанные страницы​