文件
一個 項目

tls

為網站設定 TLS。

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

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

語法

tls [internal|<email>] | [<cert_file> <key_file>] {
	protocols <min> [<max>]
	ciphers   <cipher_suites...>
	curves    <curves...>
	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
	client_auth {
		mode                   [request|require|verify_if_given|require_and_verify]
		trusted_ca_cert        <base64_der>
		trusted_ca_cert_file   <filename>
		trusted_leaf_cert      <base64_der>
		trusted_leaf_cert_file <filename>
	}
	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 標準函式庫的偏好順序）：

    • 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 曲線清單。建議不要變更這些設定。支援的值為：

    • 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 公共 DNS 

    resolvers 8.8.8.8 8.8.4.4

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

  • on_demand 為網站區塊的位址中指定的網域名稱啟用 依需求 TLS。安全性警告：在實際環境中執行此操作並不安全，除非你還設定 on_demand_tls 全域選項 以減輕濫用。

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

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

      模式 說明
      請求 要求客戶端提供憑證，但即使沒有憑證也允許；不驗證
      需要 要求客戶端提供憑證，但不驗證
      verify_if_given 要求客戶端提供憑證；即使沒有憑證也允許，但如果有則驗證
      require_and_verify 要求客戶端提供經過驗證的有效憑證

      預設值：如果提供任何 trusted_ca_cert 或 trusted_leaf_cert，則為 require_and_verify；否則為 require。

    • trusted_ca_cert 是對應於用來驗證客戶端憑證的 CA 憑證的 base64 DER 編碼。

    • trusted_ca_cert_file 是對應於用來驗證客戶端憑證的 PEM CA 憑證檔案的路徑。

    • trusted_leaf_cert 是可接受的 base64 DER 編碼客戶端葉憑證。

    • trusted_leaf_cert_file 是對應於用來驗證客戶端憑證的 PEM CA 憑證檔案的路徑。

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

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

    使用的發行者和此區段中後面的選項取決於可用的 發行者模組。其他一些子指令，例如 ca 和 dns，實際上是設定 acme 發行者的捷徑（而且此子指令是稍後才加入的），因此指定此指令和其中一些其他指令會造成混淆，因此禁止這樣做。

    此子指令可以指定多次以設定多個備援發行者；如果一個發行者無法核發憑證，將會嘗試下一個發行者。

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

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

發行者

這些發行者是 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 挑戰。

  • 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 公共 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

使用 ACME 協定取得憑證，特別是 ZeroSSL。請注意，zerossl 是預設的發行者，因此通常不需明確設定。

... zerossl [<api_key>] {
	...
}

zerossl 的語法與 acme 完全相同，但名稱為 zerossl，且可以選擇性地輸入您的 ZeroSSL API 金鑰。

其功能也相同，但預設會使用 ZeroSSL 的目錄，且可以自動協商 EAB 憑證（而使用 acme 發行者時，您必須手動提供 EAB 憑證並設定目錄端點）。

在明確設定 zerossl 時，需要設定 email，以便您的憑證可以顯示在您的 ZeroSSL 儀表板中。

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 使用者 取得憑證的權限。

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

get_certificate tailscale  # often unnecessary!

http

透過發出 HTTP(S) 要求來取得憑證。回應必須具有 200 狀態碼，而且主體必須包含一個 PEM 鏈，其中包括完整的憑證（含中間憑證）以及私密金鑰。

get_certificate http <url>

  • url 是要發出要求的完整網址。強烈建議出於效能考量，這應為一個本機端點。網址會加上下列查詢字串參數：

    • server_name：SNI 值
    • signature_schemes：簽章演算法的十六進位 ID 清單，以逗號分隔
    • cipher_suites：加密組的十六進位 ID 清單，以逗號分隔

範例

使用自訂憑證和金鑰。憑證應具有與網站地址相符的 SAN

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

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

example.com {
	tls internal
}

使用本地受信任憑證，但以 隨選 方式管理，而不是在背景中管理。這讓您可以將任何網域指向您的 Caddy 執行個體，並讓它自動為您提供憑證。如果您的 Caddy 執行個體是公開可存取的，則不應使用此功能，因為攻擊者可能會使用它來耗盡您的伺服器資源

https:// {
	tls internal {
		on_demand
	}
}

為內部 CA 使用自訂選項（無法使用 tls internal 捷徑）

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

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

example.com {
	tls your@email.com
}

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

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

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

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

啟用 TLS 用戶端驗證，並要求用戶端提出有效的憑證，透過 trusted_ca_cert_file 針對所有提供的 CA 進行驗證

example.com {
	tls {
		client_auth {
			mode                 require_and_verify
			trusted_ca_cert_file ../caddy.ca.cer
			trusted_ca_cert_file ../root.ca.cer
		}
	}
}