文件
由 贊助的專案

tls

設定站點的 TLS。

Caddy 的預設 TLS 設定是安全的。只有在您有充分的理由並了解其含義時才更改這些設定。 此指令最常見的用途是指定 ACME 帳戶電子郵件地址、更改 ACME CA 端點，或提供您自己的憑證。

相容性注意事項：由於 TLS 作為安全協定的敏感性，可能會在新次要版本或修補程式版本中對 TLS 預設值進行刻意調整。舊的或損壞的 TLS 版本、密碼、功能等可能會隨時移除。如果您的部署對變更極為敏感，您應該明確指定那些必須保持不變的值，並對升級保持警惕。在幾乎所有情況下，我們都建議使用預設設定。

語法

tls [internal|<email>] | [<cert_file> <key_file>] {
	protocols <min> [<max>]
	ciphers   <cipher_suites...>
	curves    <groups...>
	alpn      <values...>
	load      <paths...>
	ca        <ca_dir_url>
	ca_root   <pem_file>
	key_type  ed25519|p256|p384|rsa2048|rsa4096
	dns       <provider_name> [<params...>]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	eab       <key_id> <mac_key>
	on_demand
	reuse_private_keys
	client_auth {
		mode                   [request|require|verify_if_given|require_and_verify]
		trust_pool             <module>
		verifier 			   <module>
	}
	issuer          <issuer_name>  [<params...>]
	get_certificate <manager_name> [<params...>]
	insecure_secrets_log <log_file>
}

  • internal 表示使用 Caddy 的內部、本地信任的 CA 為此站點產生憑證。若要進一步設定 internal 簽發者，請使用 issuer 子指令。

  • <email> 是用於管理站點憑證的 ACME 帳戶的電子郵件地址。 您可能更喜歡使用 email 全域選項，以便一次為所有站點設定此選項。

  • <cert_file> 和 <key_file> 是憑證和私鑰 PEM 檔案的路徑。僅指定其中一個是無效的。

  • protocols 指定最小和最大協定版本。除非您知道自己在做什麼，否則請勿更改這些設定。 設定此項很少是必要的，因為 Caddy 將始終使用現代預設值。

    預設最小值：tls1.2，預設最大值：tls1.3

  • ciphers 指定密碼套件名稱的列表，依偏好順序降序排列。除非您知道自己在做什麼，否則請勿更改這些設定。請注意，密碼套件對於 TLS 1.3 是不可自訂的；並非所有 TLS 1.2 密碼都預設啟用。支援的名稱如下（依 Go stdlib 的偏好順序）：

    • TLS_AES_128_GCM_SHA256
    • TLS_CHACHA20_POLY1305_SHA256
    • TLS_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

  • curves 指定要支援的 EC 群組列表。建議不要更改預設值。支援的值為：

    • x25519mlkem768 (PQC)
    • x25519
    • secp256r1
    • secp384r1
    • secp521r1

  • alpn 是要在 TLS 握手 ALPN 擴展 中宣告的值的列表。

  • load 指定要從中載入憑證+金鑰捆綁 PEM 檔案的資料夾列表。

  • ca 更改 ACME CA 端點。這最常用於設定 Let's Encrypt 的暫存環境端點 進行測試，或設定內部 ACME 伺服器。（若要為整個 Caddyfile 更改此值，請改用 acme_ca 全域選項。）

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

  • key_type 是產生 CSR 時要使用的金鑰類型。 僅在您有特定需求時才設定此項。

  • dns 使用指定的提供者外掛程式啟用 DNS 挑戰，該外掛程式必須從 caddy-dns 儲存庫之一插入。每個提供者外掛程式在其名稱後可能有自己的語法；請參閱其文件以了解詳細資訊。維護對每個 DNS 提供者的支援是社群的共同努力。 了解如何在我們的 Wiki 上為您的提供者啟用 DNS 挑戰。

  • propagation_timeout 是一個 持續時間值，用於設定在使用 DNS 挑戰時等待 DNS TXT 記錄出現的最長時間。 設定為 -1 以停用傳播檢查。預設為 2 分鐘。

  • propagation_delay 是一個 持續時間值，用於設定在使用 DNS 挑戰時，在開始 DNS TXT 記錄傳播檢查之前要等待多長時間。預設值 0（不等待）。

  • dns_ttl 是一個 持續時間值，用於設定用於 DNS 挑戰的 TXT 記錄的 TTL。很少需要。

  • dns_challenge_override_domain 覆寫用於 DNS 挑戰的網域。這是為了將挑戰委派給不同的網域。

    如果您的主要網域的 DNS 提供者沒有可用的 DNS 外掛程式 ，您可能想要使用此選項。您可以改為使用子網域 _acme-challenge 為您的主要網域新增 CNAME 記錄，指向您確實有外掛程式的次要網域。此選項不需要外掛程式的特殊支援。

    當 ACME 簽發者嘗試解決您的主要網域的 DNS 挑戰時，他們將跟隨 CNAME 到您的次要網域以尋找 TXT 記錄。

    注意： 在此處使用來自 CNAME 記錄的完整標準名稱作為值 - _acme-challenge 子網域將不會自動前置。

  • resolvers 自訂執行 DNS 挑戰時使用的 DNS 解析器；這些解析器優先於系統解析器或任何預設解析器。如果在此處設定，解析器將傳播到所有已設定的憑證簽發者。

    這通常是 IP 位址的列表。例如，使用 Google Public DNS 

    resolvers 8.8.8.8 8.8.4.4

  • eab 使用您的 CA 提供的金鑰 ID 和 MAC 金鑰，為此站點設定 ACME 外部帳戶繫結 (EAB)。

  • on_demand 為站點區塊位址中給定的主機名稱啟用 隨需應變 TLS。 安全警告： 除非您還設定了 on_demand_tls 全域選項 以減輕濫用，否則在生產環境中執行此操作是不安全的。

  • reuse_private_keys 啟用在續訂憑證時重複使用私鑰。預設情況下，為每個新憑證建立一個新金鑰，以減輕金鑰釘扎並縮小金鑰洩露的範圍。金鑰釘扎違反了行業最佳實務。除非您有使用它的特定原因，否則不建議使用此選項；此選項可能會在未來版本中移除。

  • client_auth 啟用和設定 TLS 用戶端驗證：

    • mode 是驗證用戶端的模式。允許的值為：

      模式 描述
      request 要求用戶端提供憑證，但即使沒有憑證也允許；不驗證它
      require 要求用戶端提供憑證，但不驗證它
      verify_if_given 要求用戶端提供憑證；即使沒有憑證也允許，但如果有憑證則驗證它
      require_and_verify 要求用戶端提供已驗證的有效憑證

      預設值：如果提供 trust_pool 模組，則為 require_and_verify；否則為 require。

    • trust_pool 設定憑證授權單位 (CA) 的來源，這些憑證授權單位提供用於驗證用戶端憑證的憑證。

      用於提供信任憑證池的憑證授權單位，以及區段中的設定，取決於設定的信任池模組來源。Caddy 中提供的標準模組 列於下方。完整模組列表，包括第三方模組，列於 trust_pool JSON 文件中。

      可以使用多個 trusted_* 指令來指定多個 CA 或葉憑證。未列為葉憑證之一或未由任何指定的 CA 簽署的用戶端憑證將根據 mode 拒絕。

    • verifier 啟用自訂用戶端憑證驗證器模組的使用。這些模組可以執行自訂用戶端驗證檢查，例如確保憑證未撤銷。

  • issuer 設定自訂憑證簽發者，或取得憑證的來源。

    使用的簽發者以及此區段中接下來的選項取決於可用的 簽發者模組。 一些其他子指令（例如 ca 和 dns）實際上是設定 acme 簽發者的快捷方式（此子指令稍後新增），因此指定此指令和其他一些指令是令人困惑的，因此被禁止。

    可以多次指定此子指令以設定多個冗餘簽發者；如果一個簽發者未能簽發憑證，則將嘗試下一個簽發者。

  • get_certificate 啟用在握手時從 管理員模組 取得憑證。

  • insecure_secrets_log 啟用將 TLS 密鑰記錄到檔案。這也稱為 SSLKEYLOGFILE。使用 NSS 金鑰記錄格式，然後可以由 Wireshark 或其他工具解析。⚠️ 安全警告： 這是不安全的，因為它允許其他程式或工具解密 TLS 連線，因此完全損害了安全性。但是，此功能對於偵錯和疑難排解可能很有用。

信任池提供者

這些是可以於 trust_pool 子指令中使用的標準信任池提供者

inline

inline 模組直接以 base64 DER 編碼格式解析 Caddyfile 中列出的信任根憑證。trust_der 指令可以重複多次。

trust_pool inline {
	trust_der      <base64_der>
}
  • trust_der 是用於驗證用戶端憑證的 base64 DER 編碼的 CA 憑證。

file

file 模組從磁碟上的 PEM 檔案讀取信任根憑證。pem_file 指令可以在同一行接受多個檔案路徑，並且可以重複多次。

... file [<pem_file>...] {
	pem_file <pem_file>...
}
  • pem_file 是 PEM CA 憑證檔案的路徑，用於驗證用戶端憑證。

pki_root

pki_root 模組從 PKI 應用程式 中定義的憑證授權單位取得根和信任憑證。authority 指令可以同時接受多個授權單位，並且可以重複多次。

... pki_root [<ca_name>...] {
	authority <ca_name>...
}
  • authority 是在 PKI 應用程式中設定的憑證授權單位的名稱。

pki_intermediate

pki_intermediate 模組從 PKI 應用程式 中定義的憑證授權單位取得中繼和信任憑證。authority 指令可以同時接受多個授權單位，並且可以重複多次。

... pki_intermediate [<ca_name>...] {
	authority <ca_name>...
}
  • authority 是在 PKI 應用程式中設定的憑證授權單位的名稱。

storage

storage 模組從 Caddy 儲存 中提取信任憑證根。authority 指令可以同時接受多個授權單位，並且可以重複多次。

... storage [<storage_keys>...] {
	storage <storage_module>
	keys    <storage_keys>...
}

  • storage 是一個可選的儲存模組以供使用。如果未指定，將使用預設儲存模組。如果指定，則只能指定一次。

  • keys 是儲存憑證 PEM 檔案的儲存金鑰列表。該指令在同一行接受多個值，並且可以指定多次。

http

http 模組從 HTTP 端點取得信任憑證。endpoints 指令可以同時接受多個端點，並且可以重複多次。

... http [<endpoints...>] {
	endpoints   <endpoints...>
	tls         <tls_config>
}

  • endpoints 是從中取得憑證的 HTTP 端點列表。該指令在同一行接受多個值，並且可以指定多次。

  • tls 是連接到 HTTP 端點時使用的可選 TLS 設定。區段解析在 以下章節 中定義。

TLS
... {
	ca                    <ca_module>
	insecure_skip_verify
	handshake_timeout     <duration>
	server_name           <name>
	renegotiation         <never|once|freely>
}

  • ca 是一個可選指令，用於定義信任池的提供者。設定遵循 trust_pool 的相同行為。如果指定，則只能指定一次。

  • insecure_skip_verify 關閉 TLS 握手驗證，使連線不安全且容易受到中間人攻擊。請勿在生產環境中使用。 驗證是針對系統信任的憑證授權單位或由 ca 指令確定的憑證授權單位完成的。

  • handshake_timeout 是等待 TLS 握手完成的最長 持續時間。預設值：無逾時。

  • server_name 設定在驗證 TLS 握手中收到的憑證時使用的伺服器名稱。預設情況下，這將使用上游位址的主機部分。

  • renegotiation 設定 TLS 重新協商級別。TLS 重新協商是在第一次握手後執行後續握手的行為。級別可以是以下之一：

    • never（預設值）停用重新協商。
    • once 允許遠端伺服器每個連線請求重新協商一次。
    • freely 允許遠端伺服器重複請求重新協商。

簽發者

這些簽發者隨 tls 指令標準配備

acme

使用 ACME 協定取得憑證。請注意，acme 是預設簽發者（使用 Let's Encrypt），因此通常不需要明確設定它。

... acme [<directory_url>] {
	dir      <directory_url>
	test_dir <test_directory_url>
	email    <email>
	timeout  <duration>
	disable_http_challenge
	disable_tlsalpn_challenge
	alt_http_port    <port>
	alt_tlsalpn_port <port>
	eab <key_id> <mac_key>
	trusted_roots <pem_files...>
	dns [<provider_name> [<options>]]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}
}

  • dir 是 ACME CA 目錄的 URL。

    預設值：https://acme-v02.api.letsencrypt.org/directory

  • test_dir 是一個可選的備用目錄，用於在重試挑戰時使用；如果所有挑戰都失敗，則在重試期間將使用此端點；如果您希望 CA 具有暫存端點，並且想要避免對其生產端點進行速率限制，這會很有用。

    預設值：https://acme-staging-v02.api.letsencrypt.org/directory

  • email 是 ACME 帳戶聯絡電子郵件地址。

  • timeout 是一個 持續時間值，用於設定等待 ACME 操作逾時的時間。

  • disable_http_challenge 將停用 HTTP 挑戰。

  • disable_tlsalpn_challenge 將停用 TLS-ALPN 挑戰。

  • alt_http_port 是用於服務 HTTP 挑戰的替代埠；它必須在埠 80 上發生，因此您必須將封包轉發到此替代埠。

  • alt_tlsalpn_port 是用於服務 TLS-ALPN 挑戰的替代埠；它必須在埠 443 上發生，因此您必須將封包轉發到此替代埠。

  • eab 指定外部帳戶繫結，某些 ACME CA 可能需要此繫結。

  • trusted_roots 是在連線到 ACME CA 伺服器時要信任的一個或多個根憑證（作為 PEM 檔案名稱）。

  • dns 設定 DNS 挑戰。必須在此處設定提供者，除非 dns 全域選項 指定了全域適用的 DNS 提供者模組。

  • propagation_timeout 是一個 持續時間值，用於設定在使用 DNS 挑戰時等待 DNS TXT 記錄出現的最長時間。 設定為 -1 以停用傳播檢查。預設為 2 分鐘。

  • propagation_delay 是一個 持續時間值，用於設定在使用 DNS 挑戰時，在開始 DNS TXT 記錄傳播檢查之前要等待多長時間。預設值 0（不等待）。

  • dns_ttl 是一個 持續時間值，用於設定用於 DNS 挑戰的 TXT 記錄的 TTL。很少需要。

  • dns_challenge_override_domain 覆寫用於 DNS 挑戰的網域。這是為了將挑戰委派給不同的網域。

    如果您的主要網域的 DNS 提供者沒有可用的 DNS 外掛程式 ，您可能想要使用此選項。您可以改為使用子網域 _acme-challenge 為您的主要網域新增 CNAME 記錄，指向您確實有外掛程式的次要網域。此選項不需要外掛程式的特殊支援。

    當 ACME 簽發者嘗試解決您的主要網域的 DNS 挑戰時，他們將跟隨 CNAME 到您的次要網域以尋找 TXT 記錄。

    注意： 在此處使用來自 CNAME 記錄的完整標準名稱作為值 - _acme-challenge 子網域將不會自動前置。

  • resolvers 自訂執行 DNS 挑戰時使用的 DNS 解析器；這些解析器優先於系統解析器或任何預設解析器。如果在此處設定，解析器將傳播到所有已設定的憑證簽發者。

    這通常是 IP 位址的列表。例如，使用 Google Public DNS 

    resolvers 8.8.8.8 8.8.4.4

  • preferred_chains 指定 Caddy 應偏好的憑證鏈；如果您的 CA 提供多個鏈，這會很有用。使用以下選項之一：

    • smallest 將告訴 Caddy 偏好位元組數最少的鏈。

    • root_common_name 是一個或多個通用名稱的列表；Caddy 將選擇第一個具有與至少一個指定的通用名稱匹配的根的鏈。

    • any_common_name 是一個或多個通用名稱的列表；Caddy 將選擇第一個具有與至少一個指定的通用名稱匹配的簽發者的鏈。

zerossl

使用 ZeroSSL 的專有憑證簽發 API 取得憑證。需要 API 金鑰，並且可能還需要付款，具體取決於您的方案。請注意，此問題與 ZeroSSL 的 ACME 端點 不同。若要使用 ZeroSSL 的 ACME 端點，請使用上述設定為 ZeroSSL 的 ACME 目錄端點的 acme 簽發者。

... zerossl <api_key> {
	validity_days <days>
	alt_http_port <port>
	dns <provider_name> ...
	propagation_delay <duration>
	propagation_timeout <duration>
	resolvers <list...>
	dns_ttl <duration>
}
  • validity_days 定義憑證的生命週期。僅接受某些值；請參閱 ZeroSSL 的文件 以了解詳細資訊。
  • alt_http_port 是用於完成 ZeroSSL 的 HTTP 驗證的埠，如果不是埠 80。
  • dns 啟用 CNAME 驗證方法，使用指定的 DNS 提供者和給定的設定進行自動記錄配置。必須從 caddy-dns 儲存庫安裝 DNS 提供者外掛程式。每個提供者外掛程式在其名稱後可能有自己的語法；請參閱其文件以了解詳細資訊。維護對每個 DNS 提供者的支援是社群的共同努力。
  • propagation_delay 是在檢查 CNAME 記錄傳播之前要等待多長時間。
  • propagation_timeout 是在放棄之前等待 CNAME 記錄傳播多長時間。
  • resolvers 定義在檢查 CNAME 記錄傳播時要使用的自訂 DNS 解析器。
  • dns_ttl 設定作為驗證過程一部分建立的 CNAME 記錄的 TTL。

internal

從內部憑證授權單位取得憑證。

... internal {
	ca       <name>
	lifetime <duration>
	sign_with_root
}

  • ca 是要使用的內部 CA 的名稱。預設值：local。請參閱 PKI 應用程式全域選項 以設定 local CA，或建立替代 CA。

    預設情況下，根 CA 憑證的生命週期為 3600d（10 年），中繼憑證的生命週期為 7d（7 天）。

    Caddy 將嘗試將根 CA 憑證安裝到系統信任儲存區，但當 Caddy 以非特權使用者身分執行，或在 Docker 容器中執行時，這可能會失敗。在這種情況下，需要手動安裝根 CA 憑證，可以使用 caddy trust 命令，或透過 從容器中複製出來。

  • lifetime 是一個 持續時間值，用於設定內部簽發的葉憑證的有效期。預設值：12h。除非絕對必要，否則不建議更改此值。它必須短於中繼憑證的生命週期。

  • sign_with_root 強制根憑證成為簽發者，而不是中繼憑證。不建議這樣做，僅應在裝置/用戶端未正確驗證憑證鏈時使用（非常罕見）。

憑證管理器

憑證管理器模組與簽發者模組不同，因為使用管理器模組意味著外部工具或服務正在保持憑證續訂，而簽發者模組意味著 Caddy 本身正在管理憑證。（簽發者模組將憑證簽署請求 (CSR) 作為輸入，但憑證管理器模組將 TLS ClientHello 作為輸入。）

這些管理器模組隨 tls 指令標準配備

tailscale

從本地運行的 Tailscale 實例取得憑證。 必須在您的 Tailscale 帳戶中啟用 HTTPS（或您的開源 Headscale 伺服器 ）；並且 Caddy 程式必須以 root 身分運行，或者您必須設定 tailscaled 以授予您的 Caddy 使用者 提取憑證的權限。

注意：這通常是不必要的！ Caddy 會自動為所有 *.ts.net 網域使用 Tailscale，而無需任何額外設定。

get_certificate tailscale  # often unnecessary!

http

get_certificate (http)

get_certificate http <url>

  • 透過發出 HTTP(S) 請求取得憑證。回應必須具有 200 狀態碼，並且主體必須包含 PEM 鏈，包括完整憑證（帶有中繼憑證）以及私鑰。

    • url 是要發出請求的完整 URL。強烈建議這是一個本地端點，以提高效能。URL 將使用以下查詢字串參數進行擴充：
    • server_name：SNI 值
    • signature_schemes：以逗號分隔的簽章演算法十六進位 ID 列表

cipher_suites：以逗號分隔的密碼套件十六進位 ID 列表

範例

example.com {
	tls cert.pem key.pem
}

使用自訂憑證和金鑰。憑證應具有與站點位址匹配的 SAN

example.com {
	tls internal
}

對於當前站點區塊上的所有主機，使用 本地信任的 憑證，而不是透過 ACME / Let's Encrypt 的公用憑證（在開發環境中很有用）

https:// {
	tls internal {
		on_demand
	}
}

使用本地信任的憑證，但以 隨需應變 方式管理，而不是在背景中管理。這允許您將任何網域指向您的 Caddy 實例，並讓它自動為您佈建憑證。如果您的 Caddy 實例是公開可存取的，則不應使用此方法，因為攻擊者可能會使用它來耗盡伺服器的資源

example.com {
	tls {
		issuer internal {
			ca foo
		}
	}
}

使用內部 CA 的自訂選項（不能使用 tls internal 快捷方式）

example.com {
	tls your@email.com
}

為您的 ACME 帳戶指定電子郵件地址（但如果所有站點僅使用一個電子郵件，我們建議改用 email 全域選項）

*.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
}

為在環境變數中使用帳戶憑證的 Cloudflare 管理的網域啟用 DNS 挑戰。這解鎖了需要 DNS 驗證的萬用字元憑證支援

https:// {
	tls {
		get_certificate http https://127.0.0.1:9007/certs
	}
}

透過 HTTP 取得憑證鏈，而不是讓 Caddy 管理它。請注意，get_certificate 意味著已啟用 on_demand，使用模組提取憑證而不是觸發 ACME 簽發

example.com {
	tls {
		client_auth {
			trust_pool file ../caddy.ca.cer ../root.ca.cer
		}
	}
}