Общие шаблоны Caddyfile

Эта страница демонстрирует несколько полных и минимальных конфигураций Caddyfile для распространённых случаев использования. Они могут служить полезной отправной точкой для ваших собственных документов Caddyfile.

Это не готовые решения; вам нужно будет настроить своё доменное имя, порты/сокеты, пути к каталогам и т. д. Они предназначены для иллюстрации некоторых из наиболее распространённых шаблонов конфигурации.

• Статический веб-сервер
• Обратный прокси
• PHP
• Перенаправление поддомена www.
• Косые черты в конце пути
• Сертификаты с подстановочным знаком
• Одностраничные приложения (SPA)
• Caddy, проксирующий к другому Caddy

Статический веб-сервер

example.com {
	root * /var/www
	file_server
}

Как обычно, первая строка — это адрес сайта. Директива root указывает путь к корню сайта (* означает соответствие всем запросам, чтобы избежать путаницы с матчером путей) — измените путь к вашему сайту, если он не находится в текущем рабочем каталоге. Наконец, мы активируем статический веб-сервер статический веб-сервер.

Обратный прокси

Проксирование всех запросов:

example.com {
	reverse_proxy localhost:5000
}

Проксирование только запросов с путём, начинающимся с /api/, и предоставление статических файлов для всех остальных запросов:

example.com {
	root * /var/www
	reverse_proxy /api/* localhost:5000
	file_server
}

Это использует матчер запросов для соответствия только запросам, начинающимся с /api/, и их проксированию на бэкенд. Все остальные запросы будут обрабатываться из корневого каталога сайта с помощью root и статического веб-сервера. Это также зависит от того, что reverse_proxy расположено выше в порядке директивы по сравнению с file_server.

Здесь есть много других reverse_proxy примеров.

PHP

PHP-FPM

При работе службы PHP FastCGI что-то подобное работает для большинства современных приложений PHP:

example.com {
	root * /srv/public
	encode
	php_fastcgi localhost:9000
	file_server
}

Настройте корень сайта соответственно; этот пример предполагает, что веб-корень вашего приложения PHP находится внутри каталога public — запросы к файлам, которые существуют на диске, будут обрабатываться с помощью file_server, а всё остальное будет перенаправлено на index.php для обработки приложением PHP.

Иногда вы можете использовать сокет Unix для подключения к PHP-FPM:

php_fastcgi unix//run/php/php8.2-fpm.sock

Директива php_fastcgi фактически является просто сокращением для нескольких элементов конфигурации.

FrankenPHP

В качестве альтернативы вы можете использовать FrankenPHP, который представляет собой дистрибутив Caddy, который вызывает PHP напрямую с использованием CGO (Go до связей C). Это может быть вплоть до 4 раз быстрее, чем с PHP-FPM, и даже лучше, если вы можете использовать режим worker.

{
    frankenphp
    order php_server before file_server
}
example.com {
	root * /srv/public
    encode zstd br gzip
    php_server
}

Перенаправление поддомена www.

Чтобы добавить поддомен www. с HTTP-перенаправлением:

example.com {
	redir https://www.{host}{uri}
}
www.example.com {
}

Чтобы удалить его:

www.example.com {
	redir https://example.com{uri}
}
example.com {
}

Чтобы удалить его для нескольких доменов одновременно; это использует {labels.*}-заменители, которые являются частями имени хоста, 0-индексированные справа (например, 0=com, 1=example-one, 2=www):

www.example-one.com, www.example-two.com {
	redir https://{labels.1}.{labels.0}{uri}
}
example-one.com, example-two.com {
}

Косые черты в конце пути

Обычно вам не придётся настраивать это самостоятельно; директива file_server автоматически добавляет или удаляет косые черты в конце пути из запросов с помощью HTTP-перенаправлений, в зависимости от того, является ли запрашиваемый ресурс каталогом или файлом соответственно.

Однако, если вам нужно, вы всё ещё можете принудительно использовать косые черты в своей конфигурации. Существует два способа сделать это: внутренне или внешне.

Внутреннее принуждение

Это использует директиву rewrite. Caddy перепишет URI внутри, чтобы добавить или удалить косую черту в конце:

example.com {
	rewrite /add     /add/
	rewrite /remove/ /remove
}

Используя перепись, запросы с косой чертой в конце и без неё будут одинаковыми.

Внешнее принуждение

Это использует директиву redir. Caddy попросит браузер изменить URI, чтобы добавить или удалить косую черту в конце:

example.com {
	redir /add     /add/
	redir /remove/ /remove
}

Используя перенаправление, клиент должен повторно выпустить запрос, принуждая к единственному допустимому URI для ресурса.

Сертификаты с подстановочным знаком

Если вам нужно обслуживать несколько поддоменов с одним и тем же сертификатом с подстановочным знаком, лучший способ сделать это — с Caddyfile, подобным этому, используя директиву handle и host matchers:

*.example.com {
	tls {
		dns <provider_name> [<params...>]
	}
	@foo host foo.example.com
	handle @foo {
		respond "Foo!"
	}
	@bar host bar.example.com
	handle @bar {
		respond "Bar!"
	}	# Fallback for otherwise unhandled domains
	handle {
		abort
	}
}

Вы должны включить вызов DNS для автоматического управления Caddy сертификатами с подстановочным знаком.

Одностраничные приложения (SPA)

Когда веб-страница выполняет свою собственную маршрутизацию, серверы могут получать множество запросов на страницы, которые не существуют на стороне сервера, но которые могут быть отображены на стороне клиента, если вместо этого будет обслуживаться единственный файл индекса. Веб-приложения, спроектированные таким образом, известны как SPA или одностраничные приложения.

Основная идея заключается в том, чтобы сервер «попробовал найти файлы», чтобы увидеть, существует ли запрашиваемый файл на стороне сервера, и если нет, перейти к файлу индекса, где клиент выполняет маршрутизацию (обычно с помощью JavaScript на стороне клиента).

Типичная конфигурация SPA обычно выглядит примерно так:

example.com {
	root * /srv
	encode
	try_files {path} /index.html
	file_server
}

Если ваше SPA связано с API или другими конечными точками, работающими только на стороне сервера, вы захотите использовать блоки handle, чтобы обрабатывать их исключительно:

example.com {
	encode
	handle /api/* {
		reverse_proxy backend:8000
	}
	handle {
		root * /srv
		try_files {path} /index.html
		file_server
	}
}

Если ваш index.html содержит ссылки на ваши ресурсы JS/CSS с хешированными именами файлов, вы можете рассмотреть добавление заголовка Cache-Control, чтобы указать клиентам, что не нужно кешировать его (чтобы, если ресурсы изменятся, браузеры загружали новые). Поскольку переписывание try_files используется для обслуживания ваших index.html из любого пути, который не соответствует другому файлу на диске, вы можете обернуть try_files в route, чтобы обработчик header работал после переписывания (обычно он работал бы до этого из-за порядка директивы):

route {
	try_files {path} /index.html
	header /index.html Cache-Control "public, max-age=0, must-revalidate"
}

Caddy, проксирующий к другому Caddy

Если у вас есть один экземпляр Caddy, доступный публично (назовём его «фронт»), и другой экземпляр Caddy в вашей частной сети (назовём его «бэк») обслуживающий ваше приложение, вы можете использовать директиву reverse_proxy для передачи запросов.

Фронтовый экземпляр:

foo.example.com, bar.example.com {
	reverse_proxy 10.0.0.1:80
}

Задний экземпляр:

{
	servers {
		trusted_proxies static private_ranges
	}
}
http://foo.example.com {
	reverse_proxy foo-app:8080
}
http://bar.example.com {
	reverse_proxy bar-app:9000
}

• В этом примере обслуживаются два разных домена, проксируясь к одному и тому же экземпляру Caddy (бэк), на порту 80. Ваш задний экземпляр обслуживает два домена по-разному, поэтому он настроен с двумя отдельными блоками сайта.

• На бэке http:// используется для приёма HTTP на порту 80. Фронтовый экземпляр завершает TLS, и трафик между фронтом и бэком находится в частной сети, поэтому нет необходимости повторно шифровать его.

• Вы можете использовать другой порт, например 8080, на заднем экземпляре, если вам нужно; просто добавьте :8080 к каждому адресу сайта в конфигурации бэка или задайте глобальный параметр http_port на значение 8080.

• На бэке глобальный параметр trusted_proxies используется для того, чтобы сказать Caddy доверять фронтовому экземпляру как прокси. Это гарантирует, что реальный IP-адрес клиента сохраняется.

• Далее, вы могли бы иметь более одного бэк-экземпляра, между которыми вы балансируете нагрузку. Вы могли бы настроить mTLS (взаимный TLS), используя acme_server на фронтовом экземпляре, таким образом, что он действует как CA для заднего экземпляра (полезно, если трафик между фронтом и бэком пересекает недоверенные сети).