php_fastcgi

Настроенный директива, которая проксирует запросы к серверу PHP FastCGI, такому как php-fpm.

• Синтаксис
• Расширенная форма
  • Описание
• Примеры

Caddy's reverse_proxy способен обслуживать любые приложения FastCGI, но эта директива настраивается специально для приложений PHP. Эта директива является удобным сокращением, заменяющим более длинную конфигурацию.

Ожидается, что любой index.php в корне сайта будет действовать как маршрутизатор. Если это нежелательно, переконфигурируйте поддирективу try_files для изменения поведения перенаправления по умолчанию или используйте расширенную форму в качестве основы и настройте её по своим потребностям.

В дополнение к перечисленным ниже поддирективам, эта директива также поддерживает все поддирективы reverse_proxy. Например, можно включить балансировку нагрузки и проверки работоспособности.

Большинство современных приложений PHP работают без дополнительных поддиректив или настройки. Поддирективы обычно используются только в определенных особых случаях или с устаревшими приложениями PHP.

Синтаксис

php_fastcgi [<matcher>] <php-fpm_gateways...> {
	root <path>
	split <substrings...>
	index <filename>|off
	try_files <files...>
	env [<key> <value>]
	resolve_root_symlink
	capture_stderr
	dial_timeout  <duration>
	read_timeout  <duration>
	write_timeout <duration>
	<any other reverse_proxy subdirectives...>
}

• <php-fpm_gateways...> — это адреса серверов FastCGI. Обычно это TCP-сокет или файл сокета Unix.

• root устанавливает корневую папку сайта. Рекомендуется всегда использовать директиву root в сочетании с php_fastcgi, но настройка этого значения может быть полезной, когда ваш PHP-FPM upstream использует другой корень, отличный от Caddy (см. пример). По умолчанию используется значение директивы root, если она используется, в противном случае используется текущий рабочий каталог Caddy.

• split устанавливает подстроки для разделения URI на две части. Первая совпадающая подстрока будет использована для разделения «информации о пути» от пути. Первая часть дополняется совпадающей подстрокой и будет рассматриваться как фактическое имя ресурса (скрипта CGI). Вторая часть будет установлена в PATH_INFO для использования скриптом CGI. По умолчанию: .php

• index указывает имя файла, который будет обрабатываться как файл индекса каталога. Это влияет на файловый матчер в расширенной форме. По умолчанию: index.php. Может быть установлено в off для отключения перенаправления по умолчанию на index.php при отсутствии соответствующего файла.

• try_files указывает замену по умолчанию для перенаправления try-files. Подробности см. в try_files директиве. По умолчанию: {path} {path}/index.php index.php.

• env устанавливает дополнительную переменную среды заданному значению. Может быть указано несколько раз для нескольких переменных среды. По умолчанию все соответствующие переменные среды FastCGI уже установлены (включая HTTP-заголовки), но вы можете добавлять или переопределять переменные по мере необходимости.

• resolve_root_symlink когда папка root является символической ссылкой (symlink), это позволяет разрешить её до фактического значения. Это иногда используется как стратегия развертывания, просто переключая сиmlink, чтобы он указывал на новую версию в другой папке. Отключено по умолчанию для избежания повторных вызовов системы.

• capture_stderr включает захват и логирование любых сообщений, отправленных сервером fastcgi upstream на stderr. Ведение журнала выполняется на уровне WARN по умолчанию. Если ответ имеет 4xx или 5xx статус, то используется уровень ERROR. По умолчанию, stderr игнорируется.

• dial_timeout — это значение длительности, которое устанавливает время ожидания при подключении к сокету upstream. По умолчанию: 3s.

• read_timeout — это значение длительности, которое устанавливает время ожидания при чтении из upstream FastCGI. По умолчанию: без таймаута.

• write_timeout — это значение длительности, которое устанавливает время ожидания при отправке данных в FastCGI upstream. По умолчанию: без таймаута.

Поскольку эта директива является настраиваемым обёрткой над обратным проксированием, вы можете использовать любые поддирективы reverse_proxy для его настройки.

Расширенная форма

Директива php_fastcgi (без поддиректив) эквивалентна следующей конфигурации. Большинство современных приложений PHP работают хорошо с этой предопределенной настройкой. Если ваше приложение не работает, вы можете использовать эту основу и настроить её по мере необходимости вместо использования сокращенного php_fastcgi.

route {	# Add trailing slash for directory requests
	# This redirection is automatically disabled if "{http.request.uri.path}/index.php"
	# doesn't appear in the try_files list
	@canonicalPath {
		file {path}/index.php
		not path */
	}
	redir @canonicalPath {http.request.orig_uri.path}/ 308	# If the requested file does not exist, try index files and assume index.php always exists
	@indexFiles file {
		try_files {path} {path}/index.php index.php
		try_policy first_exist_fallback
		split_path .php
	}
	rewrite @indexFiles {file_match.relative}	# Proxy PHP files to the FastCGI responder
	@phpFiles path *.php
	reverse_proxy @phpFiles <php-fpm_gateway> {
		transport fastcgi {
			split .php
		}
	}
}

Описание

• Первая секция обрабатывает канонизацию пути запроса. Цель — убедиться, что запросы, направленные на папку на диске, фактически имеют конечный слэш /, добавленный к пути запроса, чтобы только один URL был валиден для запросов в эту папку.

  Эта канонизация выполняется только если поддиректива try_files содержит {path}/index.php (по умолчанию).

  Это выполняется с помощью матчера запросов, который соответствует только запросам, не заканчивающимся на слэше, и которые соответствуют папке на диске, содержащей файл index.php, и если совпадение найдено, выполняет HTTP 308 перенаправление с добавленным конечным слэшем. Например, это перенаправит запрос с путем /foo на /foo/ (добавляя /, чтобы канонизировать путь к папке), если файл /foo/index.php существует на диске.

• Следующая секция обрабатывает перенаправление путей на основе наличия соответствующего файла на диске. Это также имеет побочный эффект — запоминание части пути после .php (если в пути запроса был .php). Это важно для Caddy, чтобы правильно установить переменные среды FastCGI.

  • Сначала проверяется, является ли {path} существующим файлом на диске. Если это так, то перенаправляется на этот путь. Это по существу обрывает дальнейшие действия и гарантирует, что запросы к файлам, которые существуют на диске, не будут перенаправлены другими способами (см. следующие шаги ниже). Например, если на диске есть файл /js/app.js, запрос к этому пути будет сохранён.

  • Во-вторых, проверяется, является ли {path}/index.php существующим файлом на диске. Если это так, то перенаправляется на этот путь. Для запросов к папке, например, /foo/, будет искаться /foo//index.php (что нормализуется до /foo/index.php), и запрос будет перенаправлен на этот путь, если он существует. Это поведение иногда полезно, если вы запускаете другое приложение PHP в подпапке вашего корня сайта.

  • Наконец, всегда перенаправляется на index.php (он почти всегда существует для современных приложений PHP). Это позволяет вашему PHP-приложению обрабатывать любые запросы к путям, не соответствующим файлам на диске, используя скрипт index.php в качестве точки входа.

• И, наконец, последняя секция фактически проксирует запрос к вашему серверу PHP FastCGI (или PHP-FPM) для фактического выполнения вашего кода PHP. Матчер запросов будет соответствовать только запросам, заканчивающимся на .php, поэтому любые файлы, которые не являются скриптами PHP и существуют на диске, не будут обрабатываться этой директивой и будут переданы дальше.

Директива php_fastcgi обычно недостаточно. Её почти всегда следует использовать в паре с root директивой для установки расположения ваших файлов на диске (для современных приложений PHP это может быть /var/www/html/public, где папка public содержит ваши index.php) и file_server директивой для обслуживания ваших статических файлов (JS, CSS, изображения и т.д.), которые не обрабатываются этой директивой и передаются дальше.

Примеры

Проксируйте все запросы PHP к FastCGI-ответчику, слушающему на 127.0.0.1:9000:

php_fastcgi 127.0.0.1:9000

То же самое, но только для запросов под /blog/:

php_fastcgi /blog/* localhost:9000

При использовании PHP-FPM, слушающего через сокет Unix:

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

Директива root почти всегда используется для указания папки, содержащей скрипты PHP, а file_server — для обслуживания статических файлов:

example.com {
	root * /var/www/html/public
	php_fastcgi 127.0.0.1:9000
	file_server
}

При обслуживании нескольких приложений PHP с Caddy, ваш корень сайта для каждого приложения должен быть разным, чтобы Caddy мог читать и обслуживать ваши статические файлы отдельно и определять, существуют ли файлы PHP.

Если вы используете Docker, часто ваши контейнеры PHP-FPM будут иметь файлы, смонтированные в одном корне. В этом случае решение состоит в том, чтобы смонтировать файлы в ваш контейнер Caddy в разные папки, а затем использовать поддирективу root для установки корня для каждого контейнера:

app1.example.com {
	root * /srv/app1/public
	php_fastcgi app1:9000 {
		root /var/www/html/public
	}
	file_server
}
app2.example.com {
	root * /srv/app2/public
	php_fastcgi app2:9000 {
		root /var/www/html/public
	}
	file_server
}

Для сайта PHP, который не использует index.php в качестве точки входа, вы можете перейти к выводу ошибки 404 вместо этого. Ошибку можно перехватить и обработать с помощью handle_errors директивы:

example.com {
	php_fastcgi localhost:9000 {
		try_files {path} {path}/index.php =404
	}
	handle_errors {
		respond "{err.status_code}{err.status_text}"
	}
}