ドキュメント
a プロジェクト

アップグレードガイド

Caddy 2は、Caddy 1を改善するためにゼロから書き直された、まったく新しいコードベースです。Caddy 2はCaddy 1と後方互換性がありません。しかし心配しないでください。ほとんどの基本的な設定では、それほど違いはありません。このガイドは、できるだけ簡単に移行するのに役立ちます。

このガイドでは、新しい機能（ちなみに非常にクールです。 学習するべきです）については詳しく説明しません。ここでは、Caddy 2を迅速に起動して実行することを目的としています。

重要なポイント

  • 「Caddy 2」は、依然としてcaddyと呼ばれています。移行を分かりやすくするために、「Caddy 2」を使用してバージョンを明確にする場合があります。
  • ほとんどのユーザーは、caddyバイナリと更新されたCaddyfile設定（動作することをテストした後）を置き換えるだけで済みます。
  • Caddy 1からの前提を一切持たずにCaddy 2に移行するのが最善策かもしれません。
  • v1の設定をv2で完全に複製できない場合があります。通常、それには正当な理由があります。
  • コマンドラインは、サーバー設定に使用されなくなりました。
  • 環境変数は、設定に必要なくなりました。
  • Caddy 2に設定を提供する主な方法はAPIですが、caddyコマンドも使用できます。
  • Caddy 2のネイティブな設定言語はJSONであり、CaddyfileはユーザーのためにJSONに変換する別の設定アダプターであることを知っておく必要があります。非常にカスタム/高度なユースケースでは、すべての可能な設定をCaddyfileで表現できるわけではないため、JSONが必要になる場合があります。
  • 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のデフォルトプロトコルは、ホスト名またはIPアドレスが既知の場合は常にHTTPSです。これは、Caddy 1ではパブリックに見えるドメインのみがデフォルトでHTTPSを使用していたこととは異なります。今では、（ポート:80またはhttp://を明示的に指定して無効にしない限り）すべてのサイトでHTTPSが使用されます。

IPアドレスとlocalhostドメインには、ローカルで信頼できる組み込みCAから証明書が発行されます。その他のすべてのドメインでは、ZeroSSLまたはLet's Encryptが使用されます。（これはすべて設定可能です。）

証明書とACMEリソースのストレージ構造が変更されました。Caddy 2はおそらくサイトの新しい証明書を取得しますが、多数の証明書がある場合は、Caddy 2が自動的に取得しない場合は手動で移行できます。詳細については、issue #2955と#3124を参照してください。

コマンドライン

caddyコマンドは、caddy runになりました。

すべてのコマンドラインフラグが異なります。削除してください。すべてのサーバー設定は、実際の構成ドキュメント（通常はCaddyfileまたはJSON）内に存在するようになりました。v1のコマンドラインフラグのほとんどを置き換えるには、JSON構造またはCaddyfileグローバルオプションに必要なものが見つかるでしょう。

caddy -conf ../Caddyfileのようなコマンドは、caddy run --config ../Caddyfileになります。

以前と同様に、Caddyfileが現在のフォルダにある場合、Caddyは自動的にそれを見つけて使用します。その場合は、--configフラグを使用する必要はありません。

シグナルはほとんど同じですが、USR1とUSR2はサポートされなくなりました。新しい設定を読み込むには、caddy reloadコマンドまたはAPIを使用してください。

設定なしでcaddyを実行すると、以前は単純なファイルサーバーが実行されていました。Caddy 2での同等のものはcaddy file-serverです。

環境変数は、HOME（およびオプションで設定したXDG_*変数）を除いて、関連なくなりました。CADDYPATHはOSの規約に置き換えられました。

Caddyfile

v2 Caddyfileは、既に慣れているものと非常によく似ています。主な作業は、ディレクティブを変更することです。

⚠️ 新しいディレクティブをよく読んでください！ 設定が高度な場合は特に、考慮すべき多くのニュアンスがあります。これらのヒントにより、ほとんどの切り替えは非常に迅速に行えますが、アップグレードの影響を理解するために、各ディレクティブのドキュメント全体を読んでください。そしてもちろん、本番環境に配置する前に、常に設定を徹底的にテストしてください。

主な変更点

  • 静的ファイルを提供している場合は、Caddy 2ではデフォルトでこれが想定されないため、file_serverディレクティブを追加する必要があります。Caddy 2は、セキュリティ上の理由から、デフォルトではMIMEをスニッフィングしません。Content-Typeがない場合は、headerディレクティブを使用してヘッダーを自分で設定する必要がある場合があります。

  • v1では、リクエストパスでのみディレクティブをフィルタリング（または「マッチング」）できました。v2では、リクエストマッチングははるかに強力です。HTTPハンドラーチェーンにミドルウェアを追加する、または何らかの方法でHTTPリクエスト/レスポンスを操作するv2ディレクティブはすべて、この新しいマッチング機能を利用します。v2リクエストマッチャーの詳細を読む。v2 Caddyfileを理解するには、それらについて知っておく必要があります。

  • 多くのプレースホルダーは同じですが、多くは変更されており、多くの新しいプレースホルダーが追加されています。これにはCaddyfileの省略形も含まれます。

  • Caddy 2のログはすべて構造化されており、デフォルトの形式はJSONです。すべてのログレベルは、同じログに送信して処理できます（必要に応じてカスタマイズできます）。

  • Caddy 1ではパス接頭辞でリクエストを一致させた場所では、Caddy 2ではパスの一致はデフォルトで正確になります。/foo/のような接頭辞に一致させたい場合は、Caddy 2では/foo/*を使用する必要があります。

ここで、最も一般的なv1ディレクティブの一部をリストし、v2 Caddyfileで使用するように変換する方法について説明します。

⚠️ このページにv1ディレクティブがないからといって、v2でそれができないわけではありません！一部のv1ディレクティブは不要です。うまく変換できません。または、v2では他の方法で実行されます。高度なカスタマイズを行う場合は、JSONに切り替えて必要なものを取得する必要がある場合があります。ドキュメントを参照して必要なものを見つけてください！

basicauth

HTTP Basic認証は、引き続きbasicauthディレクティブを使用して設定されます。ただし、Caddy 2の設定ではプレーンテキストのパスワードは受け入れられません。caddy hash-passwordが役立ちます。

  • v1
basicauth /secret/ Bob hiccup
  • v2
basicauth /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

v1のfastcgiディレクティブは、ディスク上のファイルの試行、リクエストの書き換え、リダイレクトなど、多くの処理を行っていました。v2のphp_fastcgiディレクティブもこれらを自動的に行いますが、要件が異なる場合は変更できる拡張形式をドキュメントで説明しています。

php_fastcgiディレクティブはデフォルトでPHPを想定するため、v2ではphpプリセットは必要ありません。php_fastcgi 127.0.0.1:9000 phpのような行は、リバースプロキシがphpという名前の2番目のバックエンドがあると誤解し、接続エラーにつながります。

サブディレクティブはv2で異なります。PHPではおそらく何も必要ありません。

gzip

単一のディレクティブencodeは、複数の圧縮形式を含むすべてのレスポンスエンコーディングに使用されるようになりました。

  • v1
gzip
  • v2
encode gzip

豆知識：Caddy 2はzstdもサポートしています（ただし、ブラウザはまだサポートしていません）。

ほとんど変更されていませんが、v2では部分文字列の置換ができるようになったため、はるかに強力になっています。

  • v1
header / Strict-Transport-Security max-age=31536000;
  • v2
header Strict-Transport-Security max-age=31536000;

log

アクセスログを有効にします。logディレクティブはv2でも使用できますが、すべてのログはデフォルトでJSONとしてエンコードされた構造化されたログになります。

アクセスログを有効にする推奨方法は、次のとおりです。

log

これにより、構造化されたログがstderrに出力されます。（ファイルまたはネットワークソケットにも出力できます。logディレクティブのドキュメントを参照してください。）

デフォルトでは、ログは構造化されたJSON形式になります。レガシーの理由でCommon Log Format（CLF）でログが必要な場合は、transform-encoderプラグインを使用できます。

proxy

v2の同等物はreverse_proxyです。

注目すべきサブディレクティブの変更点としては、header_upstreamとheader_downstreamがそれぞれheader_upとheader_downになり、ロードバランシング関連のサブディレクティブにはlb_が接頭辞として付けられています。

もう1つの重要な違いは、v2プロキシがデフォルトで全ての受信ヘッダーをそのまま渡すこと（Hostヘッダーを含む）と、X-Forwarded-Forヘッダーを設定することです。言い換えれば、v1の「透過」モードはv2では基本的にデフォルトとなっています（ただし、X-Real-IPなどの他のヘッダーが必要な場合は、自分で設定する必要があります）。header_upサブディレクティブを使用して、Hostヘッダーを上書き/カスタマイズすることもできます。

v2ではWebsocketプロキシが「そのまま動作」します。v1のようにWebsocketを「有効化」する必要はありません。

改良されたマッチャーサポートのおかげで、v2ではrewriteハックが不要になったため、withoutサブディレクティブは削除されました。

  • v1
proxy / localhost:9005
  • v2
reverse_proxy localhost:9005

redir

変更なし。ただし、オプションのステータスコード引数に関するいくつかの詳細を除きます。ほとんどの設定では、変更を加える必要はありません。

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

rewrite

リクエストの書き換え（「内部リダイレクト」）のセマンティクスがわずかに変更されました。単純なパスプレフィックス以外のものに対してリクエストをマッチングする方法として、v1でいわゆる「rewriteハック」を使用していた場合、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の通常のマッチャートークンをどのように使用しているかに注目してください。このディレクティブではもはや特別なケースではありません。

まず、すべてのrewriteハックを削除し、代わりに名前付きマッチャーに変換します。各v1のrewriteを評価して、v2で本当に必要かどうかを確認します。ヒント：パスプレフィックスを追加するためにrewriteを使用し、その同じプレフィックスを削除するためにwithoutを使用してproxyを使用するv1のカディファイルは、rewriteハックであり、削除できます。

高度なルーティングロジックをより詳細に制御するために、新しいrouteおよびhandleディレクティブが役立つ場合があります。

root

変更なし。ただし、ルートパスが/で始まる場合は、パスマッチャーと区別するために*マッチャートークンを追加する必要があります。

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

v2ではマッチャーを受け入れるため、リクエストに応じてサイトルートを変更することもできます。

静的ファイルを提供する場合は、file_serverディレクティブを追加してください。Caddy 2ではデフォルトでは有効になっていないのに対し、v1では常に有効でした。

status

v2の同等のものはrespondであり、レスポンスボディを書き込むこともできます。

  • v1
status 404 /secrets/
  • v2
respond /secrets/* 404

templates

templatesディレクティブの全体的な構文は変更されていませんが、実際のテンプレートアクション/関数は異なり、大幅に改善されています。たとえば、テンプレートはファイルのインクルード、マークダウンのレンダリング、内部サブリクエストの実行、フロントマターの解析などができます！

新しい関数についてはドキュメントを参照してください。

  • v1: templates
  • v2: templates

tls

tlsディレクティブの基本は変更されていません。たとえば、独自の証明書とキーを指定します。

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

しかし、Caddyの自動HTTPSロジックは変更されているため、注意してください！

暗号スイート名も変更されています。

Caddy 2での一般的な構成は、localhostまたはIPアドレスではない開発ホスト名に対してローカルで信頼できる証明書を提供するために、tls internalを使用することです。

ほとんどのサイトでは、このディレクティブはまったく必要ありません。

サービスファイル

Caddyの展開には、公式のsystemdサービスファイルのいずれかを使用することをお勧めします。

カスタムサービスファイルが必要な場合は、当社のサービスファイルをベースにしてください。それらは正当な理由で注意深く調整されています！必要に応じてカスタマイズしてください。

プラグイン

v1用に記述されたプラグインは、v2と自動的に互換性があるわけではありません。多くのv1プラグインはv2では必要ありません。一方、v2はv1よりもはるかに拡張性があり柔軟性があります！

Caddy 2のプラグインを作成する場合は、Caddyモジュールの書き方を学習してください。

プラグインを使用してCaddy 2をビルドする

Caddy 2は、インタラクティブなダウンロードページでプラグイン付きでダウンロードできます。あるいは、Caddyを自分でビルドし、含めるプラグインを選択することもできます。xcaddyは、Caddyのmain.goファイルの手順を自動化します。

ヘルプの入手

Caddyの動作に苦労している場合は、まず当社のWebサイトでドキュメントを確認してください。新しいことを試してみて、何が起こっているのかを理解する時間を取りましょう。v2はv1とは多くの点で大きく異なります（しかし、非常に馴染み深いものでもあります）！

それでも支援が必要な場合は、コミュニティに参加してください！他人を助けることが自分自身を助ける最良の方法である場合もあります。