入門

歡迎使用 Caddy！本教學將探討使用 Caddy 的基礎知識，並幫助您在高階層面上熟悉它。

目標

• 🔲 執行守護程式
• 🔲 嘗試 API
• 🔲 給 Caddy 一個設定
• 🔲 測試設定
• 🔲 建立 Caddyfile
• 🔲 使用設定轉接器
• 🔲 從初始設定開始
• 🔲 比較 JSON 和 Caddyfile
• 🔲 比較 API 和設定檔
• 🔲 在背景中執行
• 🔲 零停機時間設定重新載入

先備條件

• 基本的終端機 / 命令列技能
• 基本的文字編輯器技能
• 您的 PATH 中有caddy 和 curl

如果您從套件管理員安裝 Caddy，Caddy 可能已經作為服務執行。如果是這樣，請在執行本教學之前停止服務。

讓我們從執行它開始

caddy

糟糕；沒有子命令，caddy 命令只會顯示說明文字。當您忘記要執行什麼時，您可以隨時使用它。

若要將 Caddy 作為守護程式啟動，請使用 run 子命令

caddy run

這會永遠封鎖，但它在做什麼？目前... 什麼也沒做。預設情況下，Caddy 的組態（「config」）是空白的。我們可以使用另一個終端的 管理 API 來驗證這一點

curl localhost:2019/config/

我們可以透過提供組態來讓 Caddy 變得有用。這可以用很多方式來完成，但我們將從在下一個區段中使用 curl 對 /load 端點發出 POST 請求開始。

你的第一個組態

為了準備我們的請求，我們需要建立一個組態。Caddy 的組態核心只是一個 JSON 文件。

將其儲存到 JSON 檔案（例如 caddy.json）

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

然後上傳

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

我們可以使用另一個 GET 請求來驗證 Caddy 是否套用我們的新組態

curl localhost:2019/config/

透過在瀏覽器中前往 localhost:2015 或使用 curl 來測試它是否運作

curl localhost:2015
Hello, world!

如果你看到 Hello, world!，那麼恭喜你——它運作了！在部署到生產環境之前，確保你的組態按照你的預期運作永遠是個好主意。

你的第一個 Caddyfile

這有點費工，只為了 Hello World。

另一種組態 Caddy 的方式是使用 Caddyfile。我們在上面用 JSON 編寫的相同組態可以簡單地表示為

:2015

respond "Hello, world!"

將其儲存到當前目錄中名為 Caddyfile（沒有副檔名）的檔案中。

如果 Caddy 已經在執行中，請停止它（Ctrl+C），然後執行

caddy adapt

或者如果你將 Caddyfile 儲存在其他地方或將其命名為 Caddyfile 以外的名稱

caddy adapt --config /path/to/Caddyfile

你會看到 JSON 輸出！這裡發生了什麼事？

我們剛剛使用 組態轉接器 將我們的 Caddyfile 轉換為 Caddy 的原生 JSON 結構。

雖然我們可以取得該輸出並發出另一個 API 請求，但我們可以跳過所有這些步驟，因為 caddy 指令可以為我們執行此操作。如果當前目錄中有一個名為 Caddyfile 的檔案，並且沒有指定其他組態，Caddy 將載入 Caddyfile，為我們轉接它，並立即執行它。

現在當前資料夾中有一個 Caddyfile，讓我們再次執行 caddy run

caddy run

或者，如果您的 Caddyfile 在其他地方

caddy run --config /path/to/Caddyfile

(如果它被稱為其他不以「Caddyfile」開頭的名稱，您將需要指定 --adapter caddyfile.)

您現在可以嘗試再次載入您的網站，您將看到它正在運作！

正如您所見，有幾種方法可以使用初始設定啟動 Caddy

• 當前目錄中名為 Caddyfile 的檔案
• --config 旗標（選擇性地搭配 --adapter 旗標）
• --resume 旗標（如果先前已載入設定）

JSON 與 Caddyfile

現在您知道 Caddyfile 只是為您轉換成 JSON。

Caddyfile 看起來比 JSON 容易，但您是否應該始終使用它？每種方法都有優缺點。答案取決於您的需求和使用案例。

您需要決定哪個最適合您的使用案例。

重要的是要注意，JSON 和 Caddyfile（以及 任何其他受支援的設定介面卡）都可以與 Caddy 的 API 一起使用。但是，如果您使用 JSON，您將獲得 Caddy 的完整功能和 API 功能。如果使用設定介面卡，使用 API 載入或變更設定的唯一方法是 /load 端點。

API 與設定檔案

您還需要決定您的工作流程是基於 API 還是基於 CLI。（您可以在同一伺服器上同時使用 API 和設定檔案，但我們不建議這樣做：最好有一個真實來源。）

API 或設定檔工作流程的選擇與設定檔轉接器的使用無關：你可以使用 JSON，但將其儲存在檔案中並使用命令列介面；反之，你也可以將 Caddyfile 與 API 搭配使用。

但大多數人會使用 JSON+API 或 Caddyfile+CLI 組合。

正如你所見，Caddy 非常適合各種使用案例和部署！

啟動、停止、執行

由於 Caddy 是伺服器，因此會無限期執行。這表示在你執行 caddy run 之後，除非終止程序（通常使用 Ctrl+C），否則終端機不會解除封鎖。

儘管 caddy run 最為常見且通常建議使用（尤其是在建立系統服務時！），你也可以使用 caddy start 來啟動 Caddy 並讓它在背景中執行

caddy start

這將讓你能夠再次使用終端機，這在某些互動式無頭環境中很方便。

之後你必須自行停止程序，因為 Ctrl+C 無法為你停止它

caddy stop

或者使用 API 的 /stop 端點。

重新載入設定檔

你的伺服器可以執行零停機時間設定檔重新載入/變更。

所有載入或變更設定檔的 API 端點 都會以零停機時間優雅地執行。

然而，在使用命令列時，你可能會想使用 Ctrl+C 停止伺服器，然後重新啟動它以載入新的設定檔。請不要這樣做：停止和啟動伺服器與設定檔變更無關，而且會導致停機時間。

相反地，請使用 caddy reload 指令進行優雅的設定檔變更

caddy reload

這實際上只是在幕後使用 API。它會載入你的設定檔，並在必要時將其轉換為 JSON，然後在不中斷服務的情況下優雅地取代目前的設定檔。

如果載入新的設定檔時有任何錯誤，Caddy 會回滾到最後一個正常運作的設定檔。