開始使用

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

目標

• 🔲 執行常駐程式
• 🔲 嘗試 API
• 🔲 給 Caddy 一個配置
• 🔲 測試配置
• 🔲 製作 Caddyfile
• 🔲 使用配置轉接器
• 🔲 從初始配置開始
• 🔲 比較 JSON 和 Caddyfile
• 🔲 比較 API 和配置文件
• 🔲 在背景執行
• 🔲 零停機時間配置重新載入

先決條件

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

如果您從套件管理器安裝了 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 vs. Caddyfile

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

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

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

重要的是要注意，JSON 和 Caddyfile（以及任何其他支援的配置轉接器）都可以與 Caddy 的 API 一起使用。但是，如果您使用 JSON，您將獲得 Caddy 功能和 API 功能的完整範圍。如果使用配置轉接器，透過 API 載入或變更配置的唯一方法是 /load 端點。

API vs. 配置文件

您還需要決定您的工作流程是基於 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 會回滾到最後一個正常運作的配置。