file_server

Статический файловый сервер, поддерживающий реальные и виртуальные файловые системы. Он формирует пути к файлам, добавляя путь URI запроса к корневому пути сайта корневому пути сайта.

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

Чаще всего, директива file_server используется совместно с директивой root для установки корневого каталога файлов для всего сайта. Эта директива также имеет поддирективу root (см. ниже) для установки корня только для этого обработчика (не рекомендуется). Обратите внимание, что корневой каталог сайта не гарантирует изоляции: файловый сервер предотвращает обход каталогов из компонентов пути, но символические ссылки внутри корневого каталога всё ещё могут позволять доступ за пределами корневого каталога.

При возникновении ошибок (например, файл не найден 404, нет доступа к файлу 403), будут вызваны маршруты обработки ошибок. Используйте директиву handle_errors для определения маршрутов обработки ошибок и отображения пользовательских страниц ошибок.

При использовании browse, вывод по умолчанию производится с помощью HTML-шаблона. Клиенты могут запросить список каталога в формате JSON или в виде обычного текста, соответственно используя заголовки Accept: application/json или Accept: text/plain. Вывод в формате JSON может быть полезен для скриптов, а вывод в формате обычного текста может быть полезен для использования в терминалах.

Синтаксис

file_server [<matcher>] [browse] {
	fs            <backend...>
	root          <path>
	hide          <files...>
	index         <filenames...>
	browse        [<template_file>] {
		reveal_symlinks
	}
	precompressed [<formats...>]
	status        <status>
	disable_canonical_uris
	pass_thru
	sort          <sort_field> [<direction>]
}

• fs указывает альтернативную (возможно, виртуальную) файловую систему для использования. Любой модуль Caddy в пространстве имён caddy.fs может быть использован здесь. Любой путь корня/префикс всё ещё будет применяться к модулям альтернативной файловой системы. По умолчанию используется локальный диск.

  xcaddy v0.4.0 вводит флаг --embed для встраивания дерева файловой системы в пользовательский сборку Caddy и регистрирует модуль fs с именем embedded, который позволяет распространять ваш статический сайт как исполняемый файл Caddy.

• root устанавливает путь к корневому каталогу сайта. Он похож на директиву root, за исключением того, что он применяется только к данному экземпляру файлового сервера и переопределяет любой другой корневой каталог сайта, который мог быть определён. По умолчанию: {http.vars.root} или текущая рабочая директория. Примечание: Эта поддиректива изменяет только корень для этого обработчика. Для того, чтобы другие директивы (например, try_files или templates) знали тот же корневой каталог сайта, используйте директиву root вместо этого.

• hide — список файлов или папок для скрытия; если запрошен, файловый сервер будет имитировать их отсутствие. Принимает плейсхолдеры и шаблоны glob. Обратите внимание, что это *пути файловой системы*, а НЕ пути запроса. Другими словами, относительные пути используют текущую рабочую директорию в качестве базы, а НЕ корневой каталог сайта; и все пути преобразуются в абсолютный вид перед сравнением (если это возможно). Указание имени файла или шаблона без разделителя пути будет скрывать все файлы с соответствующим именем независимо от его расположения; в противном случае будет попытка сопоставления по префиксу пути, а затем по шаблону glob. Поскольку это конфигурация Caddyfile, активные конфигурационные файлы будут добавлены по умолчанию.

• index — список имён файлов для поиска файлов-индексов. По умолчанию: index.html index.txt

• browse включает вывод списков файлов для запросов к каталогам, у которых нет файла индекса.

  • <template_file> — необязательный пользовательский шаблонный файл для использования в списках каталогов. По умолчанию используется шаблон, который можно извлечь с помощью команды caddy file-server export-template, которая выведет шаблон по умолчанию в стандартный вывод. Встроенный шаблон также можно найти здесь в исходном коде. Шаблоны просмотра могут использовать действия из модуля стандартных шаблонов также.

  • reveal_symlinks включает отображение целевых файлов символических ссылок в списках каталогов. По умолчанию цели символических ссылок скрыты, и показан только сам файл ссылки.

  • sort изменяет сортировку по умолчанию для списков каталогов. Первый параметр — поле/столбец для сортировки: name, namedirfirst, size или time. Второй аргумент — необязательное направление: asc или desc. Например, sort name desc отсортирует по имени в порядке убывания.

• precompressed — список форматов кодирования для поиска предварительно сжатых файлов-дополнительных файлов. Аргументы представляют собой упорядоченный список форматов кодирования для поиска предварительно сжатых файлов-дополнительных файлов. Поддерживаемые форматы: gzip (.gz), zstd (.zst) и br (.br). Если форматы не указаны, они устанавливаются по умолчанию как br zstd gzip (в этом порядке).

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

• status — необязательный код состояния для переопределения, который будет использоваться при записи ответа. Особенно полезно при ответе на запрос с пользовательской страницей ошибки. Может быть кодом состояния из 3 цифр, например: 404. Поддерживаются плейсхолдеры. По умолчанию записываемый код состояния будет обычно 200 или 206 для частичного содержимого.

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

• pass_thru включает режим pass-thru, который переходит к следующему обработчику HTTP в маршруте, если запрашиваемый файл не найден, вместо вызова ошибки 404 (вызывая маршруты handle_errors). На практике это полезно только внутри блока route с другими директивами обработчика, следующими за file_server, так как эта директива фактически установлена последней.

Примеры

Статический файловый сервер из текущей директории:

file_server

С включённым отображением списка файлов:

file_server browse

Отображение только статических файлов в папке /static:

file_server /static/*

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

example.com {
	root * /srv
	file_server
}

Скрыть все папки .git и их содержимое:

file_server {
	hide .git
}

Если клиент поддерживает (заголовок Accept-Encoding), проверяет существование предварительно сжатых файлов вместе с запрошенным файлом. Таким образом, если запрашивается /path/to/file, он проверяет наличие /path/to/file.br, /path/to/file.zst и /path/to/file.gz в этом порядке и выводит первый доступный файл с соответствующим заголовком Content-Encoding:

file_server {
	precompressed
}