全域選項

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>
	metrics {
		per_host
	}

	# 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> ...
	dns <provider> ...
	ech <public_names...> {
		dns <provider> ...
	}
	on_demand_tls {
		ask        <endpoint>
		permission <module>
	}
	key_type ed25519|p256|p384|rsa2048|rsa4096
	cert_issuer <name> ...
	renew_interval <duration>
	cert_lifetime  <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>
		}
		keepalive_interval <duration>
		trusted_proxies <module> ...
		client_ip_headers <headers...>
		trace
		max_header_size <size>
		enable_full_duplex
		log_credentials
		protocols [h1|h2|h2c|h3]
		strict_sni_host [on|insecure_off]
	}

	# File Systems
	filesystem <name> <module> {
		<options...>
	}

	# 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

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

{
	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 DNS 挑戰提供者以用於所有 ACME 交易。

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

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

{
	acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

dns

配置預設 DNS 提供者，以便在相關內容中未在本機指定其他提供者時使用。例如，如果啟用了 ACME DNS 挑戰，但未配置 DNS 提供者，則將使用此全域預設值。它也適用於發布加密的 ClientHello (ECH) 配置。

您的 Caddy 二進位檔必須使用指定的 DNS 提供者模組編譯才能運作。

範例，使用來自環境變數的憑證

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

（需要 Caddy 2.10 beta 1 或更新版本。）

ech

透過在 TLS 握手中使用指定的公用網域名稱作為純文字伺服器名稱 (SNI) 來啟用加密的 ClientHello (ECH)。在正確的條件下，ECH 可以幫助保護連線期間線路上的站點網域名稱。Caddy 將為每個指定的公用名稱產生並發布一個 ECH 配置。發布是相容的用戶端（例如正確配置的現代瀏覽器）如何知道使用 ECH 來存取您的站點。

為了正常運作，ECH 配置必須以用戶端期望的方式發布。大多數瀏覽器（啟用 DNS over HTTPS 或 DNS over TLS）都期望 ECH 配置發布到 HTTPS 類型 DNS 記錄。Caddy 會自動執行這種發布，但您必須使用 dns 子選項或全域使用 dns 全域選項指定 DNS 提供者，並且您的 Caddy 二進位檔必須使用指定的 DNS 提供者模組建置。（自訂建置可在我們的 下載頁面上取得。）

隱私權聲明

• 一般而言，建議最大化您的 匿名集 的大小。因此，我們通常建議大多數用戶配置僅一個公用網域名稱來保護您的所有站點。
• 您的伺服器應該是您指定的公用網域名稱的權威伺服器（即它們應該指向您的伺服器），因為 Caddy 將為它們取得憑證。這些憑證對於幫助符合規範的用戶端在某些情況下可靠且安全地使用 ECH 連線至關重要。它們僅用於促進正確的 ECH 握手，而不用於應用程式資料（您的站點 — 除非您定義的站點與您的公用網域名稱相同）。
• 每種情況可能都不同。如果風險很高，我們建議諮詢專家檢閱您的威脅模型，因為 ECH 不是一體適用的解決方案。

範例，使用來自環境變數的憑證，以發布到停放在 Cloudflare 的名稱伺服器

{
	dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	ech ech.example.net
}

這應該會導致相容的用戶端使用 ech.example.net 載入您的所有站點，而不是以純文字公開的個別站點名稱。

成功發布需要您的站點網域停放在配置的 DNS 提供者處，並且可以使用給定的憑證/提供者配置修改記錄。

（需要 Caddy 2.10 beta 1 或更新版本。）

on_demand_tls

配置 隨需 TLS 在啟用它的地方，但不啟用它（若要啟用它，請使用 tls 指令的 on_demand 子指令）。生產環境中必須使用，以防止濫用。

• ask 將導致 Caddy 向給定的 URL 發出 HTTP 請求，詢問是否允許網域簽發憑證。

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

  如果端點傳回 2xx 狀態碼，Caddy 將被授權為該名稱取得憑證。任何其他狀態碼都會導致取消憑證簽發並使 TLS 握手錯誤。

• permission 允許使用自訂模組來判斷是否應為特定名稱簽發憑證。模組必須實作 caddytls.OnDemandPermission 介面。包含一個 http 權限模組，ask 選項使用它，並且仍然作為向後相容性的快捷方式。

• ⚠️ interval 和 burst 速率限制選項曾經可用，但不建議使用。如果您仍然擁有它們，請從您的配置中移除它們。

{
	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
}

cert_lifetime

要求 CA 簽發憑證的有效期限。

此值用於計算 ACME 訂單的 notAfter 欄位；因此系統必須具有合理同步的時鐘。注意：並非所有 CA 都支援此功能。請查看您的 CA 的 ACME 文件，以了解是否允許此功能以及可以使用哪些值。

預設值：0（CA 選擇有效期限，通常為 90 天）

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

{
	cert_lifetime 30d
}

ocsp_interval

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

預設值：1h

{
	ocsp_interval 2h
}

ocsp_stapling

可以設定為 off 以停用 OCSP stapling。在由於防火牆而無法連線到回應器的環境中很有用。

{
	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

允許配置 監聽器包裝器，它可以修改 socket 監聽器的行為。它們依給定的順序套用。

tls

tls 監聽器包裝器是一個無操作監聽器包裝器，用於標記 TLS 監聽器在監聽器包裝器鏈中的位置。只有當另一個監聽器包裝器必須放置在 TLS 握手之前時才應使用它。

http_redirect

http_redirect 為 TLS 連接埠上作為 HTTP 請求傳入的連線提供 HTTP -> HTTPS 重新導向，方法是透過偵測前幾個位元組，判斷它不是 TLS 握手，而是 HTTP 請求。當在非標準連接埠（443 以外的連接埠）上提供 HTTPS 時，這最有用，因為瀏覽器會嘗試 HTTP，除非指定了協定。它必須放置在 tls 監聽器包裝器之前。以下範例

{
	servers {
		listener_wrappers {
			http_redirect
			tls
		}
	}
}

proxy_protocol

proxy_protocol 監聽器包裝器（在 v2.7.0 之前，它僅透過外掛程式可用）啟用 PROXY 協定剖析（由 HAProxy 推廣）。這必須在 tls 監聽器包裝器之前使用，因為它會剖析連線開始時的純文字資料

proxy_protocol {
	timeout <duration>
	allow <cidrs...>
	deny <cidrs...>
	fallback_policy <policy>
}

• timeout 指定等待 PROXY 標頭的最長持續時間。預設值為 5s。

• allow 是受信任來源的 CIDR 範圍清單，用於接收 PROXY 標頭。Unix socket 依預設是受信任的，並且不屬於此選項。

• deny 是受信任來源的 CIDR 範圍清單，用於拒絕來自這些來源的 PROXY 標頭。

• fallback_policy 是當 PROXY 標頭來自允許/拒絕清單中都不存在的位址時要採取的動作。預設的回退策略是 ignore。fallback_policy 的接受值為

  • ignore：來自 PROXY 標頭的位址，但接受連線
  • use：來自 PROXY 標頭的位址
  • reject：當發送 PROXY 標頭時拒絕連線
  • require：連線以發送 PROXY 標頭，如果不存在則拒絕
  • skip：接受連線，無需 PROXY 標頭。

例如，對於 HTTPS 伺服器（需要 tls 監聽器包裝器）接受來自特定 IP 位址範圍的 PROXY 標頭，並拒絕來自不同範圍的 PROXY 標頭，逾時時間為 2 秒

{
	servers {
		listener_wrappers {
			proxy_protocol {
				timeout 2s
				allow 192.168.86.1/24 192.168.86.1/24
				deny 10.0.0.0/8
				fallback_policy reject
			}
			tls
		}
	}
}

timeouts

• read_body 是一個 持續時間值，用於設定允許從用戶端上傳讀取的最長時間。將其設定為較短的非零值可以減輕 slowloris 攻擊，但也可能影響合法緩慢的用戶端。預設值為無逾時。

• read_header 是一個 持續時間值，用於設定允許從用戶端請求標頭讀取的最長時間。預設值為無逾時。

• write 是一個 持續時間值，用於設定允許寫入用戶端的最長時間。請注意，在提供大型檔案時將其設定為較小的值可能會對合法緩慢的用戶端產生負面影響。預設值為無逾時。

• idle 是一個 持續時間值，用於設定在啟用 keep-alive 時等待下一個請求的最長時間。預設值為 5 分鐘，以幫助避免資源耗盡。

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

keepalive_interval

TCP keepalive 封包的傳送間隔，以便在沒有其他資料傳輸時在 TCP 層保持連線存活。預設值為 15s。

{
	servers {
		keepalive_interval 30s
	}
}

trusted_proxies

允許配置應該信任請求的 Proxy 伺服器的 IP 範圍 (CIDR)。依預設，不信任任何 Proxy。

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

某些比對器或處理常式可能會使用請求的信任狀態來做出決策。例如，如果受信任，reverse_proxy 處理常式將 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
	}
}

trusted_proxies_strict

當啟用 trusted_proxies 時，標頭（由 client_ip_headers 配置）中的 IP 依預設從左到右剖析。找到的第一個不受信任的 IP 位址會變成真實的用戶端位址。自 v2.8 起，您可以使用 trusted_proxies_strict 選擇從右到左剖析這些標頭。依預設，為了向後相容性，此選項已停用。

上游 Proxy（例如 HAProxy、CloudFlare、AWS ALB、CloudFront 等）會將每個新的連線遠端位址附加到 X-Forwarded-For 的右側。建議在使用這些 Proxy 時啟用 trusted_proxies_strict，因為最左邊的 IP 位址可能會被用戶端詐騙。

{
	servers {
		trusted_proxies static private_ranges
		trusted_proxies_strict
	}
}

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 指標收集；在抓取指標之前是必要的。請注意，指標會降低非常繁忙伺服器上的效能。（我們的社群正在努力改善這一點。請參與！）

{
	metrics
}

您可以新增 per_host 選項，以使用指標的主機名稱來標記指標。

{
	metrics {
		per_host
	}
}

追蹤 (trace)

記錄每個被調用的個別處理常式。需要日誌以 DEBUG 級別發出 (您可以使用 debug 全域選項 來做到這一點)。

注意：這可能會記錄您的 HTTP 處理常式模組的組態；當組態中有敏感資料時，請勿在不安全的環境中啟用此功能。

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

{
	servers {
		trace
	}
}

max_header_size

從用戶端的 HTTP 請求標頭中剖析的最大大小。如果超出限制，伺服器將以 HTTP 狀態 431 Request Header Fields Too Large 回應。它接受 go-humanize 支援的所有格式。預設情況下，限制為 1MB。

{
	servers {
		max_header_size 5MB
	}
}

enable_full_duplex

為 HTTP/1 請求啟用全雙工通訊。只有在 Caddy 使用 Go 1.21 或更高版本建置時才有效。

對於 HTTP/1 請求，預設情況下，Go HTTP 伺服器會在開始寫入回應之前，消耗請求 body 中任何未讀取的部分，從而阻止處理常式同時從請求中讀取和寫入回應。啟用此選項會停用此行為，並允許處理常式在同時寫入回應時繼續從請求中讀取。

對於 HTTP/2+ 請求，Go HTTP 伺服器始終允許並行讀取和回應，因此此選項無效。

請使用您的 HTTP 用戶端徹底測試，因為某些較舊的用戶端可能不支援全雙工 HTTP/1，這可能會導致它們死鎖。有關更多資訊，請參閱 golang/go#57786。

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

{
	servers {
		enable_full_duplex
	}
}

log_credentials

預設情況下，具有包含潛在敏感資訊（Cookie、Set-Cookie、Authorization 和 Proxy-Authorization）的標頭的存取日誌（使用 log 指令 啟用）將記錄為 REDACTED。

如果您希望不要編輯這些標頭，您可以啟用 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 明確關閉它；例如，在執行網域前置是期望的且存取不受主機名稱限制的 Proxy 的情況下。

{
	servers {
		strict_sni_host on
	}
}

檔案系統 (File Systems)

filesystem 全域選項允許宣告一個或多個可用於檔案 I/O 的檔案系統。

這可以讓您連線到雲端中運行的遠端檔案系統，或具有類似檔案介面的資料庫，甚至從 Caddy 二進位檔案中嵌入的檔案讀取。

檔案系統以名稱宣告以識別它們。這表示如果您需要，您可以連線到多個相同類型的檔案系統。

預設情況下，Caddy 沒有任何檔案系統模組，因此您需要使用您要使用的檔案系統的外掛程式來建置 Caddy。

範例 (Example)

使用虛構的 custom 檔案系統模組，您可以宣告兩個檔案系統

{
	filesystem foo custom {
		...
	}

	filesystem bar custom {
		...
	}
}

foo.example.com {
	fs foo
	file_server
}

foo.example.com {
	fs bar
	file_server
}

PKI 選項 (PKI Options)

PKI（公開金鑰基礎設施）應用程式是 Caddy 的 本地 HTTPS 和 ACME 伺服器 功能的基礎。該應用程式定義了能夠簽署憑證的憑證授權單位 (CA)。

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

name

憑證授權單位的面向使用者名稱。

預設值：Caddy 本地授權單位 (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
			}
		}
	}
}

事件選項 (Event Options)

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

事件通常包含元資料酬載。了解事件及其酬載的最佳方法是從每個模組的文件中學習，但您也可以透過啟用 debug 全域選項 並閱讀日誌來查看事件及其資料酬載。

on

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

例如，在取得憑證後執行命令（需要 第三方外掛程式 ），並使用佔位符將事件酬載的一部分傳遞到腳本

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

事件 (Events)

Caddy 發出以下標準事件

• tls 事件
• reverse_proxy 事件

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