Руководство по обновлению

Caddy 2 — это совершенно новая кодовая база, написанная с нуля, чтобы улучшить Caddy 1. Caddy 2 не совместим со старой версией Caddy 1. Но не беспокойтесь, для большинства базовых настроек изменения незначительные. Это руководство поможет вам перейти как можно легче.

Это руководство не будет углубляться в новые возможности — которые, кстати, очень крутые, вы должны изучить их — цель здесь — быстро запустить Caddy 2.

• Биты высокого порядка
• Шаги
• HTTPS и порты
• Командная строка
• Caddyfile
  • Основные изменения
  • basicauth
  • browse
  • errors
  • ext
  • fastcgi
  • gzip
  • header
  • log
  • proxy
  • redir
  • rewrite
  • root
  • status
  • templates
  • tls
• Файлы службы
• Плагины
• Получение помощи

Биты высокого порядка

• "Caddy 2" по-прежнему называется caddy. Мы можем использовать "Caddy 2", чтобы прояснить, какую версию использовать, чтобы сделать переход менее запутанным.
• Большинству пользователей просто нужно заменить свой caddy бинарник и обновлённый Caddyfile конфиг (после проверки работоспособности).
• Лучше всего начать работу с Caddy 2 без предположений, полученных от Caddy 1.
• Возможно, вы не сможете идеально воспроизвести свою узкоспециализированную конфигурацию v1 в v2. Обычно на это есть веская причина.
• Командная строка больше не используется для конфигурации сервера.
• Переменные среды больше не нужны для конфигурации.
• Основной способ настройки Caddy 2 — через его API, но также можно использовать caddy команду.
• Вы должны знать, что родной язык конфигурации Caddy 2 — JSON, а Caddyfile — всего лишь другой адаптер конфигурации, который преобразует его в JSON для вас. В крайне специфических/сложных случаях может потребоваться использовать JSON, так как не каждая возможная конфигурация может быть выражена в Caddyfile.
• Caddyfile в основном такой же, но и намного более мощный; директивы изменены.

Шаги

1. Ознакомьтесь с Caddy 2, выполнив наш учебник Начало работы.
2. Выполните шаг 1, если ещё не сделали. Серьёзно — мы не можем подчеркнуть, насколько важно хотя бы знать, как использовать Caddy 2. (Это интереснее!)
3. Воспользуйтесь приведенным ниже руководством, чтобы переключиться на ваши caddy команду(и).
4. Воспользуйтесь приведенным ниже руководством, чтобы переключиться на ваш Caddyfile.
5. Протестируйте новую конфигурацию локально или в среде разработки.
6. Тестирование, тестирование, ещё раз тестирование
7. Разверните и наслаждайтесь!

HTTPS и порты

По умолчанию порт Caddy больше не :2015. По умолчанию порт Caddy 2 — :443, или, если имя хоста/IP неизвестно, порт :80. Вы всегда можете настроить порты в своей конфигурации.

По умолчанию протокол Caddy 2 — всегда HTTPS, если известен имя хоста или IP. Это отличается от Caddy 1, где только публико-похожие домены использовали HTTPS по умолчанию. Теперь каждый сайт использует HTTPS (если вы не отключите его, явно указав порт :80 или http://).

Для IP-адресов и локальных доменов будут выдаваться сертификаты от доверенной локальной встроенной CA. Все остальные домены будут использовать ZeroSSL или Let's Encrypt. (Это всё настраивается).

Структура хранения сертификатов и ресурсов ACME изменилась. Caddy 2, вероятно, получит новые сертификаты для ваших сайтов; но если у вас много сертификатов, вы можете перенести их вручную, если он этого не сделает за вас. Подробности см. в вопросах #2955 и #3124.

Командная строка

Команда caddy теперь caddy run.

Все флаги командной строки отличаются. Удалите их; вся конфигурация сервера теперь находится в самом документе конфигурации (обычно Caddyfile или JSON). Вероятно, вы найдёте то, что вам нужно, в структуре JSON или в глобальных параметрах Caddyfile, чтобы заменить большинство флагов командной строки из v1.

Команда, подобная caddy -conf ../Caddyfile, станет caddy run --config ../Caddyfile.

Как и прежде, если ваш Caddyfile находится в текущем каталоге, Caddy автоматически найдёт и использует его; вам не нужно использовать флаг --config в этом случае.

Сигналы в основном те же, за исключением USR1 и USR2, которые больше не поддерживаются. Используйте команду caddy reload или API вместо этого, чтобы загрузить новую конфигурацию.

Запуск caddy без какой-либо конфигурации раньше запускал простой файловый сервер. Эквивалент в Caddy 2 — caddy file-server.

Переменные среды больше не актуальны, за исключением HOME (и, необязательно, любых XDG_* переменных, которые вы установили). CADDYPATH заменяется на конвенции ОС .

Caddyfile

Caddyfile v2 очень похож на тот, с которым вы уже знакомы. Основное, что вам нужно сделать, — это изменить свои директивы.

⚠️ Обязательно ознакомьтесь с новыми директивами! Особенно если ваша конфигурация более сложная, есть много нюансов, которые необходимо учитывать. Эти советы помогут вам быстро перейти, но, пожалуйста, прочитайте полную документацию по каждой директиве, чтобы понять последствия обновления. И, конечно же, всегда тщательно тестируйте свои конфигурации перед их использованием в рабочей среде.

Основные изменения

• Если вы передаёте статические файлы, вам нужно добавить file_server директиву, поскольку Caddy 2 не предполагает этого по умолчанию. Caddy 2 также не распознаёт MIME по умолчанию по соображениям безопасности; если Content-Type отсутствует, вам может потребоваться установить заголовок самостоятельно с помощью директивы header.

• В v1 вы могли фильтровать (или «сопоставлять») директивы только по пути запроса. В v2 сопоставление запросов намного мощнее. Любые директивы v2, которые добавляют middleware в цепочку обработчиков HTTP или каким-либо образом изменяют HTTP-запрос/ответ, используют эту новую функциональность сопоставления. Узнайте больше о сопоставителях запросов v2. Вам нужно будет о них знать, чтобы понять Caddyfile v2.

• Хотя многие заменители остаются прежними, многие из них изменились, и теперь доступно множество новых, включая сокращения для Caddyfile.

• Логи Caddy 2 структурированы, и по умолчанию используется формат JSON. Все уровни логов могут быть просто направлены в один лог для обработки (но вы можете настроить это при необходимости).

• Где в Caddy 1 вы сопоставляли запросы по префиксу пути, по умолчанию в Caddy 2 сопоставление пути является точным. Если вам нужно сопоставить префикс, например, /foo/, вам потребуется /foo/* в Caddy 2.

Мы перечислим здесь некоторые из наиболее распространённых директив v1 и опишем, как их преобразовать для использования в Caddyfile v2.

⚠️ Просто потому, что директива v1 отсутствует на этой странице, не означает, что v2 её не поддерживает! Некоторые директивы v1 не нужны, плохо переводятся или реализуются другими способами в v2. Для некоторых расширенных настроек вам может потребоваться перейти к JSON, чтобы получить желаемый результат. Изучите нашу документацию, чтобы найти то, что вам нужно!

basicauth

Базовая аутентификация HTTP по-прежнему настраивается с помощью basic_auth директивы. Однако конфигурация Caddy 2 не принимает пароли в открытом тексте. Вам необходимо их хешировать, в чём может помочь caddy hash-password.

• v1:

basicauth /secret/ Bob hiccup

• v2:

basic_auth /secret/* {
	Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}

browse

Просмотр файлов теперь включен с помощью file_server директивы.

• v1:

browse /subfolder/

• v2:

file_server /subfolder/* browse

errors

Пользовательские страницы ошибок могут быть реализованы с помощью handle_errors.

• v1:

errors {
	404 404.html
	500 500.html
}

• v2:

handle_errors {
	rewrite * /{err.status_code}.html
	file_server
}

ext

Подразумеваемые расширения файлов можно реализовать с помощью try_files.

• v1: ext .html
• v2: try_files {path}.html {path}

fastcgi

Предполагая, что вы используете PHP, эквивалент v2 — php_fastcgi.

• v1:

fastcgi / localhost:9005 php

• v2:

php_fastcgi localhost:9005

Обратите внимание, что директива fastcgi из v1 выполняла много действий под капотом, включая поиск файлов на диске, переписывание запросов и даже перенаправление. Директива v2 php_fastcgi также выполняет эти действия, но документация даёт её расширенную форму, которую можно изменить, если ваши требования отличаются.

В v2 не нужен предварительно установленный php, поскольку директива php_fastcgi по умолчанию предполагает PHP. Строка типа php_fastcgi 127.0.0.1:9000 php заставит обратный прокси-сервер полагать, что существует второй бэкенд под названием php, что приведёт к ошибкам подключения.

Поддирективы отличаются в v2 — для PHP вам, вероятно, не понадобятся никакие из них.

gzip

Теперь для всех кодировок ответов, включая несколько форматов сжатия, используется одна директива encode.

• v1:

gzip

• v2:

encode gzip

Интересный факт: Caddy 2 также поддерживает zstd (но пока браузеры её не поддерживают).

header

В основном без изменений, но теперь намного мощнее, поскольку в v2 может выполнять подстрочные замены.

• v1:

header / Strict-Transport-Security max-age=31536000;

• v2:

header Strict-Transport-Security max-age=31536000;

Журналирование

Включает ведение журнала доступа; директива log по-прежнему может использоваться в версии v2, но все журналы по умолчанию структурированы и закодированы в формате JSON.

Рекомендуемый способ включения ведения журнала доступа:

log

который отправляет структурированные журналы в stderr. (Вы также можете отправлять их в файл или сетевой сокет; см. log документы по директиве.)

По умолчанию журналы будут в структурированном формате JSON. Если по соображениям совместимости вам всё ещё нужны журналы в формате Common Log Format (CLF), вы можете использовать плагин transform-encoder.

Прокси

Эквивалент v2 — reverse_proxy.

Заметные изменения в поддирективах: header_upstream и header_downstream стали, соответственно, header_up и header_down; а поддирективы, связанные с балансировкой нагрузки, имеют префикс lb_.

Ещё одно важное отличие заключается в том, что прокси v2 по умолчанию пропускает все входящие заголовки (включая заголовок Host) и устанавливает заголовок X-Forwarded-For. Другими словами, режим «прозрачный» v1 по умолчанию в v2 (но если вам нужны другие заголовки, такие как X-Real-IP, вы должны установить их самостоятельно). Вы по-прежнему можете переопределить/настроить заголовок Host, используя поддирективу header_up.

Проксирование WebSocket «работает» в v2; нет необходимости «включать» WebSocket, как в v1.

Поддиректива without была удалена, так как в v2 улучшенные средства соответствия сделали ненужными «хитрости» с перенаправлением.

• v1:

proxy / localhost:9005

• v2:

reverse_proxy localhost:9005

Перенаправление

Без изменений, за исключением нескольких деталей о необязательном аргументе кода состояния. Большинству конфигураций не придётся вносить какие-либо изменения.

• v1: redir https://example.com{uri}
• v2: redir https://example.com{uri}

Перезапись

Семантика перезаписи запросов («внутреннее перенаправление») незначительно изменилась. Если вы использовали так называемую «хитрость с перезаписью» в v1, чтобы сопоставлять запросы с чем-то, кроме простого префикса пути, это совершенно не нужно в v2.

Новая директива rewrite очень проста, но очень мощна, поскольку большая часть её сложности обрабатывается средствами сопоставления в v2:

• v1:

rewrite {
	if {>User-Agent} has mobile
	to /mobile{uri}
}

• v2:

@mobile {
	header User-Agent *mobile*
}
rewrite @mobile /mobile{uri}

Обратите внимание, как мы просто используем обычные маркеры сопоставления Caddy 2; эта директива больше не является специальным случаем.

Начните с удаления всех «хитростей» перезаписи; преобразуйте их в имена сопоставлений вместо этого. Оцените каждую v1 rewrite, чтобы понять, действительно ли она нужна в v2. Подсказка: файл Caddyfile v1, использующий rewrite для добавления префикса пути, а затем proxy с without для удаления этого же префикса, является «хитростью» перезаписи и может быть убрана.

Вам могут оказаться полезны новые директивы route и handle для лучшего контроля над расширенной логикой маршрутизации.

Корень

Без изменений, но если путь вашего корня начинается с /, вам потребуется добавить маркер сопоставления *, чтобы отличить его от сопоставления по пути.

• v1: root /var/www
• v2: root * /var/www

Поскольку в v2 он принимает сопоставление, это означает, что вы также можете изменять корень сайта в зависимости от запроса.

Не забудьте добавить file_server директиву, если вы обслуживаете статические файлы, так как Caddy 2 по умолчанию этого не предполагает, в то время как в v1 это всегда было включено.

Статус

Эквивалент v2 — respond, которая также может записывать тело ответа.

• v1:

status 404 /secrets/

• v2:

respond /secrets/* 404

Шаблоны

Общий синтаксис директивы templates не изменился, но сами действия/функции шаблонов отличаются и значительно улучшены. Например, шаблоны могут включать файлы, рендерить Markdown, выполнять внутренние подзапросы, парсить заголовок front matter и многое другое!

См. документацию для подробностей о новых функциях.

• v1: templates
• v2: templates

TLS

Основы директивы tls не изменились, например, указание собственного сертификата и ключа:

• v1: tls cert.pem key.pem
• v2: tls cert.pem key.pem

Но логика автоматического HTTPS в Caddy изменилась, так что будьте внимательны!

Также изменились имена наборов шифрования.

Типичная конфигурация в Caddy 2 — использовать tls internal, чтобы он обслуживал локально-доверенный сертификат для домена разработчика, который не является localhost или IP-адресом.

Большинству сайтов эта директива не нужна.

Файлы службы

Мы рекомендуем использовать один из наших официальных файлов службы systemd для развертывания Caddy.

Если вам нужен собственный файл службы, возьмите за основу наш. Они тщательно подобраны по соображениям удобства! Не забудьте скорректировать его при необходимости.

Плагины

Плагины, написанные для v1, не совместимы с v2 автоматически. Многие плагины v1 в v2 даже не нужны. С другой стороны, v2 намного легче расширять и настраивать, чем v1!

Если вы хотите написать плагин для Caddy 2, узнайте, как написать модуль Caddy.

Сборка Caddy 2 с плагинами

Caddy 2 можно скачать с плагинами на странице интерактивного скачивания. Или вы можете скомпилировать Caddy самостоятельно, используя xcaddy и выбрать, какие плагины включить. xcaddy автоматизирует инструкции в файле main.go Caddy.

Получение помощи

Если у вас проблемы с работой Caddy, сначала ознакомьтесь с документацией на нашем сайте. Потратьте время на эксперименты и понимание того, что происходит — v2 сильно отличается от v1 во многих отношениях (но и очень похож)!

Если вам всё ещё нужна помощь, присоединяйтесь к нашему сообществу! Возможно, помощь другим — лучший способ помочь себе.