自動 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 的憑證透過 HTTPS 提供公用 DNS 名稱服務，例如 Let's Encrypt 或 ZeroSSL 。
  • 範例：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 知道您的網域/IP，具體取決於您如何執行或設定 Caddy

• 在 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 重新導向路由會在你的路由之後插入，但會在使用者定義的萬用路由之前。

你可以 自訂或停用自動 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 Local Authority」（除非您設定了不同的名稱）。如果您願意，可以隨時將它解除安裝（caddy untrust 指令可以輕鬆做到這一點）。

請注意，自動將憑證安裝到本機信任儲存體只是為了方便，而且無法保證會成功，特別是在使用容器或以非特權系統服務執行 Caddy 的情況下。最終，如果您依賴內部 PKI，系統管理員有責任確保 Caddy 的根 CA 已正確新增到必要的信任儲存體（這不屬於 Web 伺服器的範疇）。

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 查詢，然後使用包含特殊 ServerName 和 ALPN 值的 TLS 交握，透過埠 443 要求暫時加密資源。如果 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 在下列情況下很有用

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

當隨選 TLS 已啟用時，你不必在設定中指定網域名稱，即可取得它們的憑證。相反地，當收到 Caddy 尚未取得憑證的伺服器名稱 (SNI) 的 TLS 交握時，交握會暫停，而 Caddy 會取得憑證以用於完成交握。延遲通常只有幾秒鐘，而且只有那個最初的交握會很慢。所有後續的交握都很快速，因為憑證會被快取並重複使用，而且更新會在背景中進行。後續的交握可能會觸發憑證的維護以保持其更新，但如果憑證尚未過期，此維護會在背景中進行。

使用隨選 TLS

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

如果使用 JSON 設定，則在 TLS 自動化政策 中啟用隨選 TLS；如果使用 Caddyfile，則在 具有 tls 指令的網站區塊中啟用。

為防止濫用此功能，你必須設定限制。這是在 JSON 設定的 automation 物件 中，或 Caddyfile 的 on_demand_tls 全域選項 中進行。限制是「全域性的」，且無法針對每個網站或每個網域設定。主要的限制是「詢問」端點，Caddy 會將 HTTP 要求傳送至該端點，詢問它是否有權限取得並管理交握中網域的憑證。這表示你需要一些內部後端，例如，它可以查詢資料庫的帳戶表格，並查看客戶是否已使用該網域名稱註冊。

請注意您的 CA 能有多快地核發憑證。如果需要超過幾秒鐘，這將對使用者體驗造成負面影響（僅限第一個客戶端）。

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

請參閱我們的 wiki 文章以取得有關有效使用隨選 TLS 的更多資訊。

錯誤

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

預設情況下，憑證管理會在背景中執行。這表示它不會阻擋啟動或讓您的網站變慢。但是，這也表示伺服器將在所有憑證都可用之前執行。在背景中執行讓 Caddy 能夠在很長一段時間內以指數退避重試。

如果取得或更新憑證時發生錯誤，將會發生以下情況

1. Caddy 會在短暫暫停後重試一次，以防萬一只是偶然事件
2. Caddy 會暫停一下，然後切換到下一個已啟用的挑戰類型
3. 在嘗試所有已啟用的挑戰類型後，它會嘗試下一個設定的發行者
   • Let's Encrypt
   • ZeroSSL
4. 在嘗試所有發行者後，它會以指數退避
   • 嘗試之間最多間隔 1 天
   • 最長 30 天

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

ACME 挑戰至少需要幾秒鐘，而內部速率限制有助於減輕意外濫用。Caddy 使用內部速率限制，除了您或 CA 設定的內容外，讓您可以將一個包含一百萬個網域名稱的拼盤交給 Caddy，它將逐漸（但儘可能快）取得所有網域名稱的憑證。Caddy 的內部速率限制目前是每 10 秒對每個 ACME 帳戶 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 挑戰才能取得萬用字元憑證。