全球選項

Caddyfile 提供一種方法，讓您可以指定套用在全域的選項。有些選項會作為預設值；有些會自訂 HTTP 伺服器，而不只套用在特定網站上；而另一些則會自訂 Caddyfile 轉接器 的行為。

Caddyfile 的最上方可以是全域選項區塊。這是沒有金鑰的區塊

{
	...
}

最多只能有一個，而且必須是 Caddyfile 的第一個區塊。

可能的選項如下 (按一下每個選項可跳到其文件)

{
	# General Options
	debug
	http_port    <port>
	https_port   <port>
	default_bind <hosts...>
	order <dir1> first|last|[before|after <dir2>]
	storage <module_name> {
		<options...>
	}
	storage_clean_interval <duration>
	admin   off|<addr> {
		origins <origins...>
		enforce_origin
	}
	persist_config off
	log [name] {
		output  <writer_module> ...
		format  <encoder_module> ...
		level   <level>
		include <namespaces...>
		exclude <namespaces...>
	}
	grace_period   <duration>
	shutdown_delay <duration>

	# TLS Options
	auto_https off|disable_redirects|ignore_loaded_certs|disable_certs
	email <yours>
	default_sni <name>
	fallback_sni <name>
	local_certs
	skip_install_trust
	acme_ca <directory_url>
	acme_ca_root <pem_file>
	acme_eab {
		key_id <key_id>
		mac_key <mac_key>
	}
	acme_dns <provider> ...
	on_demand_tls {
		ask      <endpoint>
		interval <duration>
		burst    <n>
	}
	key_type ed25519|p256|p384|rsa2048|rsa4096
	cert_issuer <name> ...
	renew_interval <duration>
	ocsp_interval  <duration>
	ocsp_stapling off
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}

	# Server Options
	servers [<listener_address>] {
		name <name>
		listener_wrappers {
			<listener_wrappers...>
		}
		timeouts {
			read_body   <duration>
			read_header <duration>
			write       <duration>
			idle        <duration>
		}
		trusted_proxies <module> ...
		client_ip_headers <headers...>
		metrics
		max_header_size <size>
		enable_full_duplex
		log_credentials
		protocols [h1|h2|h2c|h3]
		strict_sni_host [on|insecure_off]
	}

	# PKI Options
	pki {
		ca [<id>] {
			name                  <name>
			root_cn               <name>
			intermediate_cn       <name>
			intermediate_lifetime <duration>
			root {
				format <format>
				cert   <path>
				key    <path>
			}
			intermediate {
				format <format>
				cert   <path>
				key    <path>
			}
		}
	}

	# Event options
	events {
		on <event> <handler...>
	}
}

一般選項

debug

啟用除錯模式，這會將 預設記錄器 的記錄層級設為 DEBUG。這會顯示更多詳細資料，在進行疑難排解時很有用 (而且在生產環境中非常冗長)。我們要求您在 社群論壇 尋求協助之前先啟用此功能。例如，如果您在 Caddyfile 的最上方沒有其他全域選項，則

{
	debug
}

http_port

伺服器用於 HTTP 的埠號。

僅供內部使用；不會變更客戶端的 HTTP 埠。這通常用於在您的內部網路中，您需要將 80 埠轉發到另一個埠（例如 8080），然後 Caddy 才能接收，以進行路由。

預設值：80

https_port

伺服器用於 HTTPS 的埠。

僅供內部使用；不會變更客戶端的 HTTPS 埠。這通常用於在您的內部網路中，您需要將 443 埠轉發到另一個埠（例如 8443），然後 Caddy 才能接收，以進行路由。

預設值：443

default_bind

如果網站中未用 bind 指令，則用於所有網站的預設繫結位址。預設值：空白，會繫結到所有介面。

{
	default_bind 10.0.0.1
}

order

將順序指定給 HTTP 處理器指令。由於 HTTP 處理器會以順序鏈執行，因此必須以正確的順序執行處理器。標準指令有 預先定義的順序，但如果使用第三方 HTTP 處理器模組，您需要使用此選項或將指令放在 route 區塊 中，明確定義順序。順序可以絕對描述（first 或 last），或相對於另一個指令（before 或 after）。

例如，若要使用 replace-response 外掛程式，您需要確定其指令在 encode 之後排序，以便它可以在回應編碼之前執行替換（因為回應會沿著處理器鏈向上傳遞，而不是向下傳遞）

{
	order replace after encode
}

storage

設定 Caddy 的儲存機制。預設值為 file_system。還有許多其他可用的 儲存模組 以外掛程式的形式提供。

例如，若要變更檔案系統的儲存位置

{
	storage file_system /path/to/custom/location
}

通常需要自訂儲存模組，當在 Caddy 的多個執行個體之間同步 Caddy 的儲存時，以確保它們都使用相同的憑證和金鑰。請參閱 自動 HTTPS 關於儲存的區段，以取得更多詳細資訊。

storage_clean_interval

掃描儲存單元以尋找舊或過期的資產並將其移除的頻率。這些掃描會對儲存模組執行大量讀取（和列示作業），因此請為大型部署選擇較長的間隔。接受 持續時間值。

儲存會在程序首次啟動時一律清除。然後，如果前一次清除在小於此間隔一半的時間內完成，則會在此持續時間後啟動新的清除（否則將略過下一次啟動）。

預設：24h

{
	storage_clean_interval 7d
}

admin

自訂 管理 API 端點。接受佔位符。採用 網路位址。

預設：localhost:2019，除非設定了 CADDY_ADMIN 環境變數。

如果設定為 off，則會停用管理端點。停用時，將無法變更設定，除非停止並啟動伺服器，因為 caddy reload 指令 使用管理 API 將新設定推送到正在執行的伺服器。

請記得將 --address CLI 標記與相容的 指令 搭配使用，以指定目前的管理端點，如果正在執行的伺服器的位址已從預設值變更。

也支援這些子選項

• origins 設定允許連線到端點的來源清單。

  會智慧地選擇預設值

  • 如果監聽位址是迴圈 (例如 localhost 或迴圈 IP，或 Unix socket)，則允許的來源為 localhost、::1 和 127.0.0.1，與監聽位址連接埠合併（因此 localhost:2019 是有效的來源）。
  • 如果監聽位址不是迴圈，則允許的來源與監聽位址相同。

  如果監聽位址主機不是萬用介面（萬用介面包括：空字串、0.0.0.0 或 [::]），則會執行 Host 標頭強制執行。實際上，這表示預設情況下，Host 標頭會經過驗證，以確保在 origins 中，因為介面是 localhost。但對於像 :2020 這樣的位址（具有萬用介面），則不會執行 Host 標頭驗證。

• enforce_origin 啟用強制執行 Origin 要求標頭。

  當監聽地址是萬用字元介面時，這最為有用（因為 Host 未驗證），且管理員 API 公開於公共網際網路。它啟用 CORS 預先驗證檢查，並確保 Origin 標頭已針對 origins 清單驗證。只有當你在開發機器上執行 Caddy，且需要從網路瀏覽器存取管理員 API 時，才使用這項功能。

例如，要在所有介面上公開管理員 API 於不同埠口上 — ⚠️ 此埠口不應公開，否則任何人都可以控制你的伺服器；如果你需要公開，請考慮啟用來源強制執行

{
	admin :2020
}

關閉管理員 API — ⚠️ 這使得無法重新載入設定檔，除非停止並啟動伺服器

{
	admin off
}

使用 Unix socket 作為管理員 API，允許透過檔案權限存取控制

{
	admin unix//run/caddy-admin.sock
}

僅允許具有相符 Origin 標頭的請求

{
	admin :2019 {
		origins localhost
		enforce_origin
	}
}

persist_config

控制是否應將目前的 JSON 設定檔保留到 設定檔目錄，以避免遺失透過管理員 API 執行的設定檔變更。目前，僅支援 off 選項。預設情況下，會保留設定檔。

{
	persist_config off
}

log

設定命名記錄器。

可以傳遞名稱來指出要自訂行為的特定記錄器。如果未指定名稱，則會修改 default 記錄器的行為。你可以進一步了解 default 記錄器，以及 Caddy 中記錄運作方式 的說明。

可以透過多次使用 log 設定具有不同名稱的多個記錄器。

這與 log 指令 不同，後者僅設定 HTTP 請求記錄（也稱為存取記錄）。log 全域選項與指令共用其設定結構（include 和 exclude 除外），且可以在指令的頁面中找到完整的說明文件。

• output 設定記錄的寫入位置。

  請參閱 log 指令 以取得完整的說明文件。

• format 說明如何編碼或格式化記錄。

  請參閱 log 指令 以取得完整的說明文件。

• level 是要記錄的最低條目層級。

  預設值：INFO。

  可能的值：DEBUG、INFO、WARN、ERROR，以及極少見的 PANIC、FATAL。

• include 指定要包含在此記錄器中的記錄名稱。

  預設情況下，此清單為空（即包含所有記錄）。

  例如，若要僅包含管理員 API 發出的記錄，你會包含 admin.api。

• exclude 指定要從此記錄器中排除的記錄名稱。

  預設情況下，此清單為空（即不排除任何記錄）。

  例如，若要僅排除 HTTP 存取記錄，您會排除 http.log.access。

include 和 exclude 接受的記錄器名稱取決於所使用的模組，最簡單的發現方法是從先前的記錄中找出。

以下是將所有 http 存取記錄和管理記錄以 json 格式記錄至 stdout 的範例

{
	log default {
		output stdout
		format json
		include http.log.access admin.api
	}
}

grace_period

定義關閉 HTTP 伺服器（即在設定變更期間或 Caddy 停止時）的寬限期。

在寬限期內，不會接受新連線，閒置連線會關閉，且會不耐煩地等待主動連線完成其要求。如果客戶端未在寬限期內完成其要求，伺服器將強制終止以允許重新載入完成並釋放資源。接受 持續時間值。

預設情況下，寬限期為無限，這表示連線永遠不會強制關閉。

{
	grace_period 10s
}

shutdown_delay

定義 寬限期之前 的 持續時間，在此期間，即將停止的伺服器會繼續正常運作，但 {http.shutting_down} 佔位符會評估為 true，且 {http.time_until_shutdown} 會提供寬限期開始前的時間。

如果任何伺服器在設定變更期間關閉，這將導致延遲，並有效地將變更排程至稍後時間。這對於向此伺服器的健康檢查器宣告其即將毀滅很有用，並給予負載平衡器時間將其移出輪替；例如

{
	shutdown_delay 30s
}

example.com {
	handle /health-check {
		@goingDown vars {http.shutting_down} true
		respond @goingDown "Bye-bye in {http.time_until_shutdown}" 503
		respond 200
	}
	handle {
		respond "Hello, world!"
	}
}

TLS 選項

auto_https

設定 自動 HTTPS，這項功能讓 Caddy 能為您的網站自動化憑證管理和 HTTP 轉 HTTPS 重新導向。

有幾種模式可供選擇

• off：停用憑證自動化和 HTTP 轉 HTTPS 重新導向。

• disable_redirects：僅停用 HTTP 轉 HTTPS 重新導向。

• disable_certs：僅停用憑證自動化。

• ignore_loaded_certs：即使對於出現在手動載入憑證上的名稱，也要自動化憑證。如果您使用包含名稱（或萬用字元）的 tls 指令 指定憑證，但您希望自動管理這些名稱（或萬用字元），則這項功能會很有用。

{
	auto_https disable_redirects
}

email

您的電子郵件地址。主要用於在您的 CA 中建立 ACME 帳戶，並且在您的憑證出現問題時強烈建議使用。

{
	email admin@example.com
}

default_sni

當客戶端在其 ClientHello 中不使用 SNI 時，設定預設 TLS ServerName。

{
	default_sni example.com
}

fallback_sni

⚠️ 實驗性質

如果已設定，如果原始 ServerName 與快取中的任何憑證不符，則備援將成為 ClientHello 中的 TLS ServerName。

這項功能的使用非常小眾；通常如果客戶端是 CDN 並傳遞下游交握的 ServerName，但可以接受具有來源主機名的憑證，則您會將其設定為您的來源主機名。請注意，Caddy 必須管理此名稱的憑證。

{
	fallback_sni example.com
}

local_certs

導致所有憑證預設由內部發行，而不是透過（公開）ACME CA（例如 Let's Encrypt）發行。這在開發環境中作為快速切換很有用。

{
	local_certs
}

skip_install_trust

略過將當地 CA 的根安裝到系統信任儲存區以及 Java 和 Mozilla Firefox 信任儲存區的嘗試。

{
	skip_install_trust
}

acme_ca

指定 ACME CA 目錄的 URL。強烈建議將其設定為 Let's Encrypt 的分段端點 以進行測試或開發。預設：ZeroSSL 和 Let's Encrypt 的生產端點。

請注意，全球設定的 ACME CA 可能不適用於所有網站；請參閱主機名稱需求以使用預設 ACME 發行者。

{
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

acme_ca_root

如果不在系統信任儲存區中，指定包含 ACME CA 端點受信任根憑證的 PEM 檔案。

{
	acme_ca_root /path/to/ca/root.pem
}

acme_eab

指定要對所有 ACME 交易使用的外部帳戶繫結。

例如，使用模擬 ZeroSSL 憑證

{
	acme_eab {
		key_id GD-VvWydSVFuss_GhBwYQQ
		mac_key MjXU3MH-Z0WQ7piMAnVsCpD1shgMiWx6ggPWiTmydgUaj7dWWWfQfA
	}
}

acme_dns

設定要對所有 ACME 交易使用的ACME DNS 挑戰提供者。

需要使用 DNS 提供者外掛程式自訂建置 Caddy。

提供者名稱後面的代幣會設定提供者，就像在 tls 指令的 acme 簽發者 中指定的一樣。

{
	acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

on_demand_tls

設定 隨選 TLS，在啟用的時候，但不會啟用它（若要啟用，請使用 tls 指令的 on_demand 子指令）。在生產環境中使用時需要，以防止濫用。

• ask 會讓 Caddy 對指定的 URL 發出 HTTP 要求，詢問是否允許對網域核發憑證。

  要求的查詢字串為 ?domain=，其中包含網域名稱的值。

  如果端點傳回 2xx 狀態碼，Caddy 將被授權取得該名稱的憑證。任何其他狀態碼將導致取消核發憑證，並讓 TLS 交握出錯。

• interval 和 burst 允許在 <duration> 間隔內執行 <n> 憑證操作。

{
	on_demand_tls {
		ask https://127.0.0.1:9123/ask
	}
}

https:// {
	tls {
		on_demand
	}
}

key_type

指定要為 TLS 憑證產生的金鑰類型；只有在您有特定需求要自訂時才變更這個設定。

可能的值為：ed25519、p256、p384、rsa2048、rsa4096。

{
	key_type ed25519
}

cert_issuer

定義 TLS 憑證的簽發者（或來源）。

這允許在全球設定簽發者，而不是像使用 tls 指令的 issuer 子指令 那樣在每個網站設定。

如果您想要設定多個簽發者來嘗試，可以重複使用。它們將按照定義的順序嘗試。

{
	cert_issuer acme {
		...
	}
	cert_issuer zerossl {
		...
	}
}

renew_interval

掃描所有載入的受管理憑證的到期時間，並在過期時觸發更新的頻率。

預設值：10m

{
	renew_interval 30m
}

ocsp_interval

檢查 OCSP 釘選 是否需要更新的頻率。

預設值：1h

{
	ocsp_interval 2h
}

ocsp_stapling

可以設定為 off 以停用 OCSP 釘選。在回應者因為防火牆而無法存取的環境中很有用。

{
	ocsp_stapling off
}

preferred_chains

如果您的 CA 提供多個憑證鏈，您可以使用此選項指定 Caddy 應優先選擇的鏈。設定下列選項之一

• smallest 會告訴 Caddy 優先選擇位元組數最少的鏈。

• root_common_name 是包含一個或多個常用名稱的清單；Caddy 會選擇第一個根與至少一個指定的常用名稱相符的鏈。

• any_common_name 是包含一個或多個常用名稱的清單；Caddy 會選擇第一個簽發者與至少一個指定的常用名稱相符的鏈。

請注意，將 preferred_chains 指定為全域選項將影響所有簽發者，除非有任何 覆寫簽發者層級設定。

{
	preferred_chains smallest
}

{
	preferred_chains {
		root_common_name "ISRG Root X2"
	}
}

伺服器選項

使用可能橫跨多個網站的設定自訂 HTTP 伺服器，因此無法在網站區塊中正確設定。這些選項會影響 HTTP 層底下的監聽器/socket 或其他設施。

可以指定多次，並使用不同的 listener_address 值為每個伺服器設定不同的選項。例如，servers :443 將只套用到繫結至監聽器地址 :443 的伺服器。略過監聽器地址將會將選項套用到任何剩餘的伺服器。

例如，要為埠 :80 和 :443 上的伺服器設定不同的選項，您需要指定兩個 servers 區塊

{
	servers :443 {
		listener_wrappers {
			http_redirect
			tls
		}
	}

	servers :80 {
		protocols h1 h2c
	}
}

使用 servers 時，它只會套用到實際出現在 Caddyfile 中的伺服器（即由網站區塊產生）。請記住，自動 HTTPS 會建立一個監聽埠 80（或 http_port 選項）的伺服器，用於提供 HTTP->HTTPS 重新導向並解決 ACME HTTP 挑戰；這會在執行階段發生，即在 Caddyfile 適配器套用 servers 之後。換句話說，這表示 servers 不會套用到 :80，除非您明確宣告一個網站區塊，例如 http:// 或 :80。

name

指定給此伺服器的自訂名稱。通常有助於在記錄和指標中透過其名稱識別伺服器。如果未設定，Caddy 會使用 srvX 模式動態定義它，其中 X 從 0 開始，並根據設定中的伺服器數量遞增。

請記住，只有設定中網站區塊產生的伺服器才會套用設定。自動 HTTPS 會在執行階段建立一個 :80 伺服器（或 http_port），因此如果您要重新命名它，您至少需要一個空的 http:// 網站區塊。

例如

{
	servers :443 {
		name https
	}
	
	servers :80 {
		name http
	}
}

example.com {
}

http:// {
}

listener_wrappers

允許設定 listener wrappers，它可以修改 socket listener 的行為。它們會按照給定的順序套用。

有一個特殊的 no-op tls listener wrapper 提供為標準模組，用來標記 TLS 應該在 listener wrappers 鏈中處理的位置。它只應該在另一個 listener wrapper 必須置於 TLS 握手之前時使用。這不會啟用伺服器的 TLS；例如，如果這用於你的 :80 HTTP 伺服器，它仍會作為 no-op。

包含的 http_redirect listener wrapper 可以查看即將到來的要求的前幾個位元組，以確定它是否可能是 HTTP（而不是 TLS），並在同一個埠上觸發 HTTP 到 HTTPS 的重新導向，但使用 https:// 這個 scheme。這在非標準埠（除了 443）上提供 HTTPS 時最有用，因為瀏覽器會嘗試 HTTP，除非指定 scheme。不要在 HTTP 伺服器上使用這個。它必須置於 tls listener wrapper 之前。例如

{
	servers {
		listener_wrappers {
			http_redirect
			tls
		}
	}
}

也包含 proxy_protocol listener wrapper（在 v2.7.0 之前，它只能透過外掛程式取得），它啟用 PROXY protocol 分析（由 HAProxy 推廣）。這必須在 tls listener wrapper 之前使用，因為它會在連線開始時分析純文字資料

{
	servers {
		listener_wrappers {
			proxy_protocol {
				timeout 2s
				allow 192.168.86.1/24 192.168.86.1/24
			}
			tls
		}
	}
}

timeouts

• read_body 是 duration value，它設定允許從客戶端上傳中讀取的時間長度。將這個設定為短的非零值可以減輕 slowloris 攻擊，但也可能影響合法地慢的客戶端。預設為沒有逾時。

• read_header 是 duration value，它設定允許從客戶端要求標頭中讀取的時間長度。預設為沒有逾時。

• write 是 duration value，它設定允許寫入客戶端的時間長度。請注意，在提供大型檔案時將這個設定為小值可能會對合法地慢的客戶端產生負面影響。預設為沒有逾時。

• idle 是 duration value，它設定在啟用 keep-alives 時等待下一個要求的最長時間。預設為 5 分鐘，以幫助避免資源耗盡。

{
	servers {
		timeouts {
			read_body   10s
			read_header 5s
			write       30s
			idle        10m
		}
	}
}

trusted_proxies

允許設定代理伺服器的 IP 範圍 (CIDR)，請求應從該範圍信任。預設情況下，不信任任何代理伺服器。

啟用此功能會導致信任的請求從 HTTP 標頭中解析出真實的用戶端 IP（預設為 X-Forwarded-For；請參閱 client_ip_headers 以設定其他標頭）。如果受信任，用戶端 IP 會新增到 存取記錄 中，可用作 {client_ip} 佔位符，並允許使用 client_ip 比對器。如果請求不是來自受信任的代理伺服器，則用戶端 IP 會設定為直接傳入連線的遠端 IP 位址。

某些比對器或處理常式可能會使用請求的信任狀態來做決定。例如，如果受信任，reverse_proxy 處理常式會代理並擴充敏感的 X-Forwarded-* 請求標頭。

目前，只有 static IP 來源模組 包含在 Caddy 的標準發行版中，但這可以用外掛程式 擴充 以維護動態 IP 範圍清單。

static

採用靜態（不變）IP 範圍（CIDR）清單來信任。

作為捷徑，private_ranges 可用於比對所有私有 IPv4 和 IPv6 範圍。這與指定所有這些範圍相同：192.168.0.0/16 172.16.0.0/12 10.0.0.0/8 127.0.0.1/8 fd00::/8 ::1。

語法如下

trusted_proxies static [private_ranges] <ranges...>

以下是一個完整範例，信任一個範例 IPv4 範圍和一個 IPv6 範圍

{
	servers {
		trusted_proxies static 12.34.56.0/24 1200:ab00::/32
	}
}

client_ip_headers

與 trusted_proxies 配對，允許設定用於確定用戶端 IP 位址的標頭。預設情況下，只考慮 X-Forwarded-For。可以指定多個標頭欄位，在這種情況下，會使用第一個非空標頭值。

{
	servers {
		trusted_proxies static private_ranges
		client_ip_headers X-Forwarded-For X-Real-IP
	}
}

metrics

啟用 Prometheus 指標收集；在擷取指標之前需要啟用。請注意，指標會降低非常忙碌伺服器的效能。（我們的社群正在努力改善這一點。請參與！）

{
	servers {
		metrics
	}
}

max_header_size

從用戶端的 HTTP 請求標頭中解析的最大大小。如果超過限制，伺服器將回應 HTTP 狀態 431 請求標頭欄位太大。它接受 go-humanize 支援的所有格式。預設情況下，限制為 1MB。

{
	servers {
		max_header_size 5MB
	}
}

enable_full_duplex

啟用 HTTP/1 要求的全雙工通訊。僅在 Caddy 使用 Go 1.21 或更新版本建置時有效。

對於 HTTP/1 要求，Go HTTP 伺服器在開始寫入回應之前，預設會使用要求主體的任何未讀取部分，這會阻止處理常式同時從要求中讀取並寫入回應。啟用此選項會停用此行為，並允許處理常式在同時寫入回應時繼續從要求中讀取。

對於 HTTP/2+ 要求，Go HTTP 伺服器總是允許同時讀取和回應，因此此選項無效。

請使用 HTTP 客戶端徹底測試，因為某些較舊的客戶端可能不支援全雙工 HTTP/1，這可能會導致它們陷入僵局。請參閱 golang/go#57786 以取得更多資訊。

⚠️ 這是實驗性功能。可能會變更或移除。

{
	servers {
		enable_full_duplex
	}
}

log_credentials

從 Caddy v2.5 開始，預設情況下，具有潛在敏感資訊的標頭（Cookie、Set-Cookie、Authorization 和 Proxy-Authorization）會在存取日誌中以空值記錄（請參閱 log 指令）。

如果您希望不刪除這些標頭，可以啟用 log_credentials 選項。

{
	servers {
		log_credentials
	}
}

protocols

要支援的 HTTP 協定的空白分隔清單。

預設值：h1 h2 h3

可接受的值為

• h1 代表 HTTP/1.1
• h2 代表 HTTP/2
• h2c 代表明文傳輸的 HTTP/2
• h3 代表 HTTP/3

目前，啟用 HTTP/2（包括 H2C）必然意味著啟用 HTTP/1.1，因為 Go 標準函式庫不允許我們在使用其 HTTP 伺服器時停用 HTTP/1.1。但是，HTTP/1.1 或 HTTP/3 可以獨立啟用。

請注意，H2C（「明文 HTTP/2」或「TCP 上的 H2」）和 HTTP/3 沒有由 Go 標準函式庫實作，因此某些功能或特點可能會受到限制。我們建議不要啟用 H2C，除非您的應用程式絕對需要。

{
	servers :80 {
		protocols h1 h2c
	}
}

strict_sni_host

啟用此功能需要要求的 Host 標頭與客戶端 TLS ClientHello 傳送的 ServerName 值相符，這是使用 TLS 客戶端驗證時必要的防護措施。如果發生不符，HTTP 狀態 421 Misdirected Request 回應會寫入客戶端。

如果已設定 客戶端驗證，此選項將自動開啟。這禁止 TLS 客戶端驗證繞過（網域前端），否則可以在 TLS 握手期間傳送未受保護的 SNI 值，然後在建立連線後將受保護的網域放入 Host 標頭中。此行為是安全的預設值，但您可以使用 insecure_off 明確關閉它；例如，在執行網域前端所需的代理伺服器的情況下，且存取不受主機名稱限制。

{
	servers {
		strict_sni_host on
	}
}

PKI 選項

PKI（公開金鑰基礎建設）應用程式是 Caddy 的 Local HTTPS 和 ACME 伺服器 功能的基礎。此應用程式定義了能夠簽署憑證的憑證授權機構 (CA)。

預設 CA ID 為 local。如果在設定 ca 時省略 ID，則假設為 local。

name

憑證核發機構面向使用者的名稱。

預設：Caddy Local Authority

{
	pki {
		ca local {
			name "My Local CA"
		}
	}
}

root_cn

要放入根憑證 CommonName 欄位的名稱。

預設：{pki.ca.name} - {time.now.year} ECC Root

{
	pki {
		ca local {
			root_cn "My Local CA - 2024 ECC Root"
		}
	}
}

intermediate_cn

要放入中間憑證 CommonName 欄位的名稱。

預設：{pki.ca.name} - ECC Intermediate

{
	pki {
		ca local {
			intermediate_cn "My Local CA - ECC Intermediate"
		}
	}
}

intermediate_lifetime

中間憑證有效的持續時間。這個值必須小於根憑證的存續期（3600d 或 10 年）。

預設：7d。不建議變更這個值，除非絕對必要。

{
	pki {
		ca local {
			intermediate_lifetime 30d
		}
	}
}

root

一組金鑰對（憑證和私鑰），用於作為 CA 的根。如果未指定，系統會自動產生並管理一組。

• format 是提供憑證和私鑰的格式。目前僅支援 pem_file，這是預設值，因此這個欄位是選填的。
• cert 是憑證。使用 pem_file 格式時，這應該是 PEM 檔案的路徑。
• key 是私鑰。使用 pem_file 格式時，這應該是 PEM 檔案的路徑。

intermediate

一組金鑰對（憑證和私鑰），用於作為 CA 的中間。如果未指定，系統會自動產生並管理一組。

• format 是提供憑證和私鑰的格式。目前僅支援 pem_file，這是預設值，因此這個欄位是選填的。
• cert 是憑證。使用 pem_file 格式時，這應該是 PEM 檔案的路徑。
• key 是私鑰。使用 pem_file 格式時，這應該是 PEM 檔案的路徑。

{
	pki {
		ca local {
			root {
				format pem_file
				cert /path/to/root.pem
				key /path/to/root.key
			}
			intermediate {
				format pem_file
				cert /path/to/intermediate.pem
				key /path/to/intermediate.key
			}
		}
	}
}

事件選項

當發生（或即將發生）有趣的事情時，Caddy 模組會發出事件。

事件通常包含一個元資料有效負載。了解事件及其有效負載的最佳方法是查看每個模組的文件，但你也可以透過啟用debug 全域選項並閱讀記錄檔，來查看事件及其資料有效負載。

on

將事件處理常式繫結到指定的事件。指定事件處理常式模組的名稱，後接其組態。

例如，在取得憑證後執行一個指令（需要第三方外掛程式 ），並使用佔位符將事件有效負載的一部分傳遞給指令碼

{
	events {
		on cert_obtained exec ./my-script.sh {event.data.certificate_path}
	}
}

事件

這些標準事件由 Caddy 發出

• tls 事件
• reverse_proxy 事件

外掛程式也可能發出事件，因此請查看其文件以取得詳細資訊。