常見 Caddyfile 範例

此頁示範幾個完整且最小的 Caddyfile 設定，適用於常見的使用案例。這些範例可以作為您自己的 Caddyfile 文件的起點。

這些範例並非適用於所有情況；您必須自訂您的網域名稱、埠/socket、目錄路徑等。這些範例旨在說明一些最常見的設定範例。

• 靜態檔案伺服器
• 反向代理
• PHP
• 重新導向 www. 次網域
• 尾隨斜線
• 萬用字元憑證
• 單頁式應用程式 (SPA)
• Caddy 代理到另一個 Caddy

靜態檔案伺服器

example.com {
	root * /var/www
	file_server
}

與往常一樣，第一行是網站地址。 root 指令 指定網站根目錄的路徑（* 表示比對所有要求，以區別於 路徑比對器）—如果路徑不是目前的作業目錄，請變更為您的網站路徑。最後，我們啟用 靜態檔案伺服器。

反向代理

代理所有要求

example.com {
	reverse_proxy localhost:5000
}

僅代理路徑以 /api/ 開頭的要求，並為其他所有內容提供靜態檔案

example.com {
	root * /var/www
	reverse_proxy /api/* localhost:5000
	file_server
}

這使用 請求比對器 來比對僅從 /api/ 開頭的請求，並將其代理到後端。所有其他請求將從網站 root 使用 靜態檔案伺服器 來提供服務。這也取決於 reverse_proxy 在 指令順序 中高於 file_server 的事實。

這裡有更多 reverse_proxy 範例。

PHP

PHP-FPM

在 PHP FastCGI 服務執行時，類似這樣的內容適用於大多數現代 PHP 應用程式

example.com {
	root * /srv/public
	encode gzip
	php_fastcgi localhost:9000
	file_server
}

相應地自訂網站根目錄；此範例假設您的 PHP 應用程式的網頁根目錄位於 public 目錄中—對磁碟上存在的檔案的請求將使用 file_server 來提供服務，而其他任何內容將會路由到 index.php 以供 PHP 應用程式處理。

您有時可以使用 Unix socket 連線到 PHP-FPM

php_fastcgi unix//run/php/php8.2-fpm.sock

php_fastcgi 指令實際上只是 多個組態片段 的捷徑。

FrankenPHP

或者，您可以使用 FrankenPHP，它是 Caddy 的一個發行版，使用 CGO（轉換為 C 的 Go 繫結）直接呼叫 PHP。這可能比使用 PHP-FPM 快上 4 倍，如果您能使用工作者模式，則會更好。

{
    frankenphp
    order php_server before file_server
}

example.com {
	root * /srv/public
    encode zstd br gzip
    php_server
}

重新導向 www. 次網域

要使用 HTTP 重新導向來新增www.次網域

example.com {
	redir https://www.{host}{uri}
}

www.example.com {
}

要移除它

www.example.com {
	redir https://example.com{uri}
}

example.com {
}

要同時為多個網域移除它；這使用 {labels.*} 佔位符，它們是主機名的部分，從右邊開始編號為 0（例如 0=com、1=example-one、2=www）

www.example-one.com, www.example-two.com {
	redir https://{labels.1}.{labels.0}{uri}
}

example-one.com, example-two.com {
}

尾隨斜線

您通常不需要自己組態這個；file_server 指令會透過 HTTP 重新導向自動從請求中新增或移除尾斜線，具體取決於所請求的資源分別是目錄還是檔案。

但是，如果您需要，您仍然可以使用組態來強制使用尾斜線。有兩種方法可以做到：內部或外部。

內部強制

這使用 rewrite 指令。Caddy 會在內部重新寫入 URI 以新增或移除尾斜線

example.com {
	rewrite /add     /add/
	rewrite /remove/ /remove
}

使用重寫後，帶有或不帶尾斜線的請求將會相同。

外部強制

這使用 redir 指令。Caddy 會要求瀏覽器變更 URI 以新增或移除尾斜線

example.com {
	redir /add     /add/
	redir /remove/ /remove
}

使用重新導向後，客戶端必須重新發出請求，強制使用資源的單一可接受 URI。

萬用字元憑證

如果您需要使用相同的萬用字元憑證提供多個子網域，最好的處理方式是使用類似這樣的 Caddyfile，利用 handle 指令 和 host 比對器

*.example.com {
	tls {
		dns <provider_name> [<params...>]
	}

	@foo host foo.example.com
	handle @foo {
		respond "Foo!"
	}

	@bar host bar.example.com
	handle @bar {
		respond "Bar!"
	}

	# Fallback for otherwise unhandled domains
	handle {
		abort
	}
}

您必須啟用 ACME DNS 挑戰 才能讓 Caddy 自動管理萬用字元憑證。

單頁式應用程式 (SPA)

當網頁執行自己的路由時，伺服器可能會收到許多不存在於伺服器端的頁面請求，但只要提供單一的索引檔案，這些頁面就可以在客戶端端進行呈現。採用這種架構的網路應用程式稱為 SPA，或單頁式應用程式。

主要概念是讓伺服器「嘗試檔案」以查看請求的檔案是否存在於伺服器端，如果不存在，則退回至索引檔案，讓客戶端進行路由（通常使用客戶端端的 JavaScript）。

典型的 SPA 設定通常看起來像這樣

example.com {
	root * /srv
	encode gzip
	try_files {path} /index.html
	file_server
}

如果您的 SPA 與 API 或其他僅限伺服器端的端點結合，您會希望使用 handle 區塊來專門處理這些端點

example.com {
	encode gzip

	handle /api/* {
		reverse_proxy backend:8000
	}

	handle {
		root * /srv
		try_files {path} /index.html
		file_server
	}
}

Caddy 代理到另一個 Caddy

如果您有一個 Caddy 執行個體公開存取（我們稱之為「前端」），另一個 Caddy 執行個體在您的私人網路中（我們稱之為「後端」）提供您的實際應用程式，您可以使用 reverse_proxy 指令 傳遞請求。

前端執行個體

foo.example.com, bar.example.com {
	reverse_proxy 10.0.0.1:80
}

後端執行個體

{
	servers {
		trusted_proxies static private_ranges
	}
}

http://foo.example.com {
	reverse_proxy foo-app:8080
}

http://bar.example.com {
	reverse_proxy bar-app:9000
}

• 此範例提供兩個不同的網域，將兩個網域都代理至相同的後端 Caddy 執行個體，使用埠 80。您的後端執行個體以不同的方式提供兩個網域，因此使用兩個獨立的網站區塊進行設定。

• 在後端，http:// 用於接受埠 80 上的 HTTP。前端執行個體終止 TLS，且前端與後端之間的流量位於私人網路中，因此不需要重新加密。

• 如果您需要，可以在後端執行個體上使用不同的埠，例如 8080；只要在後端設定中的每個網站地址後面加上 :8080，或將 http_port 全域選項 設定為 8080 即可。

• 在後端，trusted_proxies 全域選項 用於告知 Caddy 將前端執行個體視為代理伺服器。這可確保保留實際客戶端 IP。

• 更進一步，你可以擁有多個後端實例，它們之間可以進行負載平衡。你可以在前端實例上使用acme_server設定 mTLS（相互 TLS），這樣它就可以充當後端實例的 CA（如果前端和後端之間的流量通過不可信網路，這會很有用）。