自動 HTTPS

Caddy 是第一個也是唯一一個預設自動使用 HTTPS 的網頁伺服器。

自動 HTTPS 為您的所有網站佈建 TLS 憑證並保持續期。它還會為您將 HTTP 重定向到 HTTPS！Caddy 使用安全且現代的預設值 —— 無需停機、額外配置或單獨的工具。

這是一個 28 秒的影片，展示了它的運作方式

選單

• 概述
• 啟用
• 效果
• 主機名稱要求
• 本地 HTTPS
• 測試
• ACME 挑戰
• 隨需 TLS
• 錯誤
• 儲存
• 萬用字元憑證

概述

預設情況下，Caddy 通過 HTTPS 提供所有網站。

• Caddy 使用自動本地信任的自簽憑證，通過 HTTPS 提供 IP 位址和本地/內部主機名稱（如果允許）。
  • 範例：localhost、127.0.0.1
• Caddy 使用來自公共 ACME CA（例如 Let's Encrypt 或 ZeroSSL ）的憑證，通過 HTTPS 提供公共 DNS 名稱。
  • 範例：example.com、sub.example.com、*.example.com

Caddy 保持所有託管憑證續期，並自動將 HTTP（預設埠 80）重定向到 HTTPS（預設埠 443）。

對於本地 HTTPS

• Caddy 可能會提示您輸入密碼，以將其唯一的根憑證安裝到您的信任儲存區中。這每個根憑證只發生一次；您可以隨時移除它。
• 任何未信任 Caddy 根 CA 憑證而訪問該網站的客戶端都將顯示安全錯誤。

對於公共網域名稱

• 如果您的網域的 A/AAAA 記錄指向您的伺服器，
• 埠 80 和 443 在外部是開啟的，
• Caddy 可以綁定到這些埠（或這些埠被轉發到 Caddy），
• 您的 資料目錄 是可寫入且持久的，
• 並且您的網域名稱出現在配置中的相關位置，

那麼網站將自動通過 HTTPS 提供服務。您不必再做任何事情。它就是這樣運作的！

由於 HTTPS 使用共享的公共基礎設施，因此作為伺服器管理員，您應該了解此頁面上的其餘資訊，以便您可以避免不必要的問題，在發生問題時進行故障排除，並正確配置進階部署。

啟用

當 Caddy 知道它正在服務的網域名稱（即主機名稱）或 IP 位址時，它會隱式啟用自動 HTTPS。根據您運行或配置 Caddy 的方式，有多種方法可以告訴 Caddy 您的網域/IP

• Caddyfile 中的網站位址
• 主機匹配器，位於 JSON 路由中的頂層
• 命令列標誌，例如 --domain 或 --from
• 自動化憑證載入器

以下任何一項都會阻止自動 HTTPS 被啟用，無論是全部還是部分

• 通過 JSON 或通過 Caddyfile 明確禁用它
• 在配置中未提供任何主機名稱或 IP 位址
• 僅監聽 HTTP 埠
• 在 Caddyfile 中，以 http:// 為 網站位址添加前綴
• 手動載入憑證（除非設定了 ignore_loaded_certificates）

特殊情況

• 以 .ts.net 結尾的網域將不由 Caddy 管理。相反，Caddy 將自動嘗試在握手時從本地運行的 Tailscale 實例獲取這些憑證。這需要 在您的 Tailscale 帳戶中啟用 HTTPS ，並且 Caddy 進程必須以 root 身份運行，或者您必須配置 tailscaled 以授予您的 Caddy 用戶獲取憑證的權限。

效果

當自動 HTTPS 啟用時，會發生以下情況

• 為 所有符合條件的網域名稱獲取和續期憑證
• HTTP 重定向到 HTTPS（這使用 HTTP 埠 80）

自動 HTTPS 永遠不會覆蓋顯式配置，它只會增強它。

如果您已經有一個 伺服器 監聽 HTTP 埠，則 HTTP->HTTPS 重定向路由將在您的路由之後插入，並帶有主機匹配器，但在用戶定義的 catch-all 路由之前。

如果需要，您可以自訂或禁用自動 HTTPS；例如，您可以跳過某些網域名稱或禁用重定向（對於 Caddyfile，請使用全域選項執行此操作）。

主機名稱要求

如果滿足以下條件，則所有主機名稱（網域名稱）都有資格獲得完全託管的憑證

• 非空
• 僅由字母數字、連字符、點和萬用字元 (*) 組成
• 不以點開頭或結尾 (RFC 1034)

此外，如果滿足以下條件，主機名稱有資格獲得公開信任的憑證

• 不是 localhost（包括 .localhost、.local 和 .home.arpa TLD）
• 不是 IP 位址
• 只有一個萬用字元 * 作為最左邊的標籤

本地 HTTPS

Caddy 為所有指定主機（網域、IP 或主機名稱）的網站自動使用 HTTPS，包括內部和本地主機。某些主機要么不是公共的（例如 127.0.0.1、localhost），要么通常不符合公開信任憑證的資格（例如 IP 位址 —— 您可以從某些 CA 獲得它們的憑證）。除非禁用，否則這些仍然通過 HTTPS 提供服務。

為了通過 HTTPS 提供非公共網站，Caddy 生成自己的憑證授權單位 (CA) 並使用它來簽署憑證。信任鏈由根憑證和中繼憑證組成。葉憑證由中繼憑證簽署。它們儲存在 Caddy 的資料目錄中的 pki/authorities/local。

Caddy 的本地 CA 由 Smallstep 程式庫 提供支援。

本地 HTTPS 不使用 ACME，也不執行任何 DNS 驗證。它僅在本地電腦上運作，並且僅在安裝了 CA 根憑證的地方受到信任。

CA 根憑證

根憑證的私鑰是使用密碼學安全的偽隨機源唯一生成的，並以有限的權限持久儲存到儲存裝置中。它僅在執行簽署任務時載入到記憶體中，之後離開作用域以進行垃圾回收。

雖然 Caddy 可以配置為直接使用根憑證進行簽署（以支援不合規的客戶端），但預設情況下禁用了此功能，並且根密鑰僅用於簽署中繼憑證。

首次使用根密鑰時，Caddy 將嘗試將其安裝到系統的本地信任儲存區中。如果它沒有這樣做的權限，它將提示輸入密碼。如果不希望這樣做，可以在配置中禁用此行為。如果由於以非特權用戶身份運行而失敗，您可以運行 caddy trust 以特權用戶身份重試安裝。

安裝 Caddy 的根 CA 後，您將在本地信任儲存區中看到它為「Caddy 本地授權單位」（除非您配置了不同的名稱）。如果您願意，您可以隨時卸載它（caddy untrust 命令使這變得容易）。

請注意，自動將憑證安裝到本地信任儲存區僅是為了方便起見，並不能保證有效，尤其是在使用容器或 Caddy 以非特權系統服務運行的情況下。最終，如果您依賴內部 PKI，則系統管理員有責任確保 Caddy 的根 CA 已正確添加到必要的信任儲存區（這超出了網頁伺服器的範圍）。

CA 中繼憑證

還將生成中繼憑證和密鑰，它們將用於簽署葉（個別網站）憑證。

與根憑證不同，中繼憑證的生命週期短得多，並會在需要時自動續期。

測試

為了測試或實驗您的 Caddy 配置，請確保您將 ACME 端點更改為暫存或開發 URL，否則您很可能會遇到速率限制，這可能會阻止您訪問 HTTPS 長達一周，具體取決於您遇到的速率限制。

Caddy 的預設 CA 之一是 Let's Encrypt ，它有一個暫存端點 ，它不受相同的 速率限制 約束

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

ACME 挑戰

獲取公開信任的 TLS 憑證需要來自公開信任的第三方授權單位的驗證。如今，此驗證過程已通過 ACME 協議 自動化，並且可以通過以下三種方式之一（「挑戰類型」）執行，如下所述。

預設情況下啟用前兩種挑戰類型。如果啟用了多個挑戰，Caddy 會隨機選擇一個，以避免意外依賴特定的挑戰。隨著時間的推移，它會了解哪種挑戰類型最成功，並將開始優先選擇它，但在必要時會退回到其他可用的挑戰類型。

HTTP 挑戰

HTTP 挑戰對候選主機名稱的 A/AAAA 記錄執行權威 DNS 查找，然後使用 HTTP 通過埠 80 請求臨時加密資源。如果 CA 看到預期的資源，則會頒發憑證。

此挑戰要求埠 80 可從外部訪問。如果 Caddy 無法監聽埠 80，則來自埠 80 的數據包必須轉發到 Caddy 的 HTTP 埠。

此挑戰預設為啟用，不需要顯式配置。

TLS-ALPN 挑戰

TLS-ALPN 挑戰對候選主機名稱的 A/AAAA 記錄執行權威 DNS 查找，然後使用 TLS 握手通過埠 443 請求臨時加密資源，其中包含特殊的 ServerName 和 ALPN 值。如果 CA 看到預期的資源，則會頒發憑證。

此挑戰要求埠 443 可從外部訪問。如果 Caddy 無法監聽埠 443，則來自埠 443 的數據包必須轉發到 Caddy 的 HTTPS 埠。

此挑戰預設為啟用，不需要顯式配置。

DNS 挑戰

DNS 挑戰對候選主機名稱的 TXT 記錄執行權威 DNS 查找，並查找具有特定值的特殊 TXT 記錄。如果 CA 看到預期的值，則會頒發憑證。

此挑戰不需要任何開啟的埠，並且請求憑證的伺服器不需要可從外部訪問。但是，DNS 挑戰需要配置。Caddy 需要知道訪問您的網域 DNS 提供商的憑證，以便它可以設定（和清除）特殊的 TXT 記錄。如果啟用了 DNS 挑戰，則預設情況下會禁用其他挑戰。

由於 ACME CA 在查找 TXT 記錄以進行挑戰驗證時遵循 DNS 標準，因此您可以使用 CNAME 記錄將挑戰的響應委派給其他 DNS 區域。這可以用於將 _acme-challenge 子網域委派給另一個區域。如果您的 DNS 提供商不提供 API，或者 Caddy 的 DNS 插件之一不支持它，這尤其有用。

DNS 提供商支援是一項社群工作。在我們的 wiki 中了解如何為您的提供商啟用 DNS 挑戰。

隨需 TLS

Caddy 開創了一項我們稱之為隨需 TLS 的新技術，它在第一次需要它的 TLS 握手期間動態獲取新憑證，而不是在配置載入時。至關重要的是，這不需要在您的配置中提前硬編碼網域名稱。

許多企業依靠此獨特功能來擴展其 TLS 部署，從而降低成本，並在服務數萬個網站時避免操作上的麻煩。

如果符合以下條件，隨需 TLS 非常有用

• 當您啟動或重新載入伺服器時，您不知道所有網域名稱，
• 網域名稱可能無法立即正確配置（DNS 記錄尚未設定），
• 您無法控制網域名稱（例如，它們是客戶網域）。

當啟用隨需 TLS 時，您無需在配置中指定網域名稱即可獲取它們的憑證。相反，當收到針對 Caddy 尚未擁有憑證的伺服器名稱 (SNI) 的 TLS 握手時，握手將被暫停，同時 Caddy 獲取憑證以用於完成握手。延遲通常只有幾秒鐘，只有初始握手很慢。所有未來的握手都很快，因為憑證被緩存和重用，並且續期在後台發生。未來的握手可能會觸發憑證的維護以保持續期，但如果憑證尚未過期，則此維護在後台發生。

使用隨需 TLS

隨需 TLS 必須同時啟用和限制，以防止濫用。

如果使用 JSON 配置，則在 TLS 自動化策略中啟用隨需 TLS；如果使用 Caddyfile，則在 帶有 tls 指令的站點塊中啟用。

為了防止濫用此功能，您必須配置限制。這在 JSON 配置的 automation 物件或 Caddyfile 的 on_demand_tls 全域選項中完成。限制是「全域的」，不能按站點或按網域配置。主要限制是一個「詢問」端點，Caddy 將向其發送 HTTP 請求，以詢問它是否有權獲取和管理握手中網域的憑證。這意味著您需要一些內部後端，例如，它可以查詢您資料庫的帳戶表，並查看客戶是否已使用該網域名稱註冊。

請注意您的 CA 發放憑證的速度。如果需要幾秒鐘以上，這將對用戶體驗產生負面影響（僅適用於第一個客戶端）。

由於其延遲性質以及防止濫用所需的額外配置，我們建議僅在您的實際用例如上所述時才啟用隨需 TLS。

有關有效使用隨需 TLS 的更多資訊，請參閱我們的 wiki 文章。

錯誤

如果憑證管理發生錯誤，Caddy 會盡力繼續運行。

預設情況下，憑證管理在後台執行。這意味著它不會阻止啟動或減慢您的網站速度。但是，這也意味著即使在所有憑證都可用之前，伺服器也會運行。在後台運行允許 Caddy 在很長一段時間內使用指數退避重試。

如果獲取或續期憑證時發生錯誤，會發生以下情況

1. Caddy 在短暫暫停後重試一次，以防萬一只是僥倖
2. Caddy 短暫暫停，然後切換到下一個啟用的挑戰類型
3. 在嘗試了所有啟用的挑戰類型後，它會嘗試下一個配置的簽發者
   • Let's Encrypt
   • ZeroSSL
4. 在嘗試了所有簽發者後，它會指數退避
   • 嘗試之間最多 1 天
   • 最多 30 天

在使用 Let's Encrypt 進行重試期間，Caddy 會切換到他們的 暫存環境 ，以避免速率限制問題。這不是一個完美的策略，但總體來說它很有幫助。

ACME 挑戰至少需要幾秒鐘，內部速率限制有助於減輕意外濫用。Caddy 除了您或 CA 配置的速率限制之外，還使用內部速率限制，以便您可以向 Caddy 提供包含一百萬個網域名稱的盤子，它將逐步但盡可能快地獲取所有網域名稱的憑證。Caddy 的內部速率限制目前為每個 ACME 帳戶每 10 秒 10 次嘗試。

為了避免洩漏資源，當配置更改時，Caddy 會中止正在進行的任務（包括 ACME 交易）。雖然 Caddy 能夠處理頻繁的配置重新載入，但請注意操作方面的考慮因素，例如這一點，並考慮批處理配置更改以減少重新載入，並使 Caddy 有機會實際完成在後台獲取憑證。

簽發者回退

Caddy 是第一個（也是迄今為止唯一一個）伺服器，在無法成功獲取憑證的情況下，支援完全冗餘的自動故障轉移到其他 CA。

預設情況下，Caddy 啟用兩個與 ACME 兼容的 CA：Let's Encrypt 和 ZeroSSL 。如果 Caddy 無法從 Let's Encrypt 獲取憑證，它將嘗試使用 ZeroSSL；如果兩者都失敗，它將退避並稍後再次重試。在您的配置中，您可以自訂 Caddy 用於獲取憑證的簽發者，無論是通用簽發者還是特定名稱的簽發者。

儲存

Caddy 將把公共憑證、私鑰和其他資產儲存在其配置的儲存設施中（或預設設施，如果未配置 —— 有關詳細資訊，請參閱連結）。

使用預設配置時，您需要了解的主要事項是 $HOME 資料夾必須是可寫入且持久的。 為了幫助您進行故障排除，如果指定了 --environ 標誌，Caddy 會在啟動時列印其環境變數。

配置為使用相同儲存裝置的任何 Caddy 實例都將自動共享這些資源並協調憑證管理作為叢集。

在嘗試任何 ACME 交易之前，Caddy 將測試配置的儲存裝置，以確保它是可寫入的並且具有足夠的容量。這有助於減少不必要的鎖定爭用。

萬用字元憑證

當 Caddy 配置為服務具有符合條件的萬用字元名稱的站點時，它可以獲取和管理萬用字元憑證。如果站點名稱僅其最左邊的網域標籤是萬用字元，則該站點名稱符合萬用字元的條件。例如，*.example.com 符合條件，但以下不符合條件：sub.*.example.com、foo*.example.com、*bar.example.com 和 *.*.example.com。

如果使用 Caddyfile，Caddy 會按字面意義對待站點名稱，並考慮憑證主體名稱。換句話說，定義為 sub.example.com 的站點將導致 Caddy 管理 sub.example.com 的憑證，而定義為 *.example.com 的站點將導致 Caddy 管理 *.example.com 的萬用字元憑證。您可以在我們的常用 Caddyfile 模式頁面上看到此示範。如果您需要不同的行為，則 JSON 配置使您可以更精確地控制憑證主體和站點名稱（「主機匹配器」）。

萬用字元憑證代表廣泛的授權程度，僅當您有太多子網域以至於為它們管理單獨的憑證會給 PKI 帶來壓力或導致您達到 CA 強制的速率限制時才應使用。

注意： Let's Encrypt 要求 DNS 挑戰才能獲取萬用字元憑證。