升級指南

Caddy 2 是全新的程式碼庫，從頭開始撰寫，以改善 Caddy 1。Caddy 2 與 Caddy 1 不相容。但不用擔心，對大多數基本設定來說，差異不大。本指南將協助您盡可能輕鬆地轉換。

本指南不會深入探討新功能——這些功能真的很酷，順帶一提，您應該了解它們——這裡的目標只是讓您快速在 Caddy 2 上執行和運行。

高階位元
步驟
HTTPS 和埠
命令列
Caddyfile
- 主要變更
- basicauth
- browse
- errors
- ext
- fastcgi
- gzip
- header
- log
- proxy
- redir
- rewrite
- root
- status
- templates
- tls
服務檔案
外掛程式
取得協助

高階位元

「Caddy 2」仍然只稱為 caddy。我們可能會使用「Caddy 2」來釐清版本，讓轉換過程不那麼令人困惑。
大多數使用者只需要更換其 caddy 二進位檔和其更新的 Caddyfile 設定檔（在測試其運作後）。
最好不要帶著從 Caddy 1 繼承的假設進入 Caddy 2。
您可能無法在 v2 中完美複製您的 v1 利基設定檔。通常，有充分的理由說明這一點。
命令列不再用於伺服器設定檔。
環境變數不再需要用於設定檔。
提供 Caddy 2 組態的主要方式是透過其 API，但 caddy 命令也可用於此目的。
您應該知道 Caddy 2 的原生組態語言是 JSON，而 Caddyfile 只是另一個組態轉接器，它會將組態轉換為 JSON。極為客製化/進階的使用案例可能需要 JSON，因為並非所有可能的組態都能透過 Caddyfile 表示。
Caddyfile 大致相同，但功能也更強大；指令已變更。

步驟

透過執行我們的入門教學，熟悉 Caddy 2。
如果您尚未執行，請執行步驟 1。說真的，我們無法強調至少了解如何使用 Caddy 2 有多麼重要。（它更有趣！）
使用以下指南轉換您的 caddy 命令。
使用以下指南轉換您的 Caddyfile。
在本地或暫存區測試您的新組態。
測試、測試、再測試
部署並盡情享受！

HTTPS 和埠

Caddy 的預設埠不再是 :2015。Caddy 2 的預設埠是 :443，或如果沒有已知的網域名稱/IP，則為埠 :80。您隨時可以在組態中自訂埠。

如果已知網域名稱或 IP，Caddy 2 的預設協定永遠是 HTTPS。這與 Caddy 1 不同，在 Caddy 1 中，預設只有看起來公開的網域使用 HTTPS。現在，每個網站都使用 HTTPS（除非您透過明確指定埠 :80 或 http:// 來停用它）。

IP 位址和 localhost 網域會從受本地信任的嵌入式 CA 取得憑證。所有其他網域將使用 ZeroSSL 或 Let's Encrypt。（這一切都可設定。）

憑證和 ACME 資源的儲存結構已變更。Caddy 2 可能會為您的網站取得新的憑證；但如果您有許多憑證，如果它沒有為您執行這項工作，您可以手動將它們移轉。請參閱問題 #2955 和 #3124 以取得詳細資訊。

命令列

caddy 命令現在是 caddy run。

所有命令列旗標都不同。移除它們；所有伺服器組態現在都存在於實際的組態文件中（通常是 Caddyfile 或 JSON）。您可能會在 JSON 結構或 Caddyfile 全域選項中找到您需要的内容，以取代 v1 中的大部分命令列旗標。

像 caddy -conf ../Caddyfile 的指令會變成 caddy run --config ../Caddyfile。

和之前一樣，如果你的 Caddyfile 在目前的資料夾中，Caddy 會自動尋找並使用它；這種情況下你不需要使用 --config 旗標。

訊號大多數都相同，除了 USR1 和 USR2 不再支援。改用 caddy reload 指令或 API 來載入新的設定。

在沒有任何設定的情況下執行 caddy 會執行一個簡單的檔案伺服器。在 Caddy 2 中等效的指令是 caddy file-server。

環境變數不再相關，除了 HOME（以及你設定的任何 XDG_* 變數）。CADDYPATH 已被作業系統慣例取代。

Caddyfile

v2 Caddyfile 與你已經熟悉的版本非常相似。你最需要做的事情是變更你的指令。

⚠️ 務必閱讀新的指令！特別是如果你的設定比較進階，有很多細微差別需要考慮。這些提示可以讓你快速地完成大部分的切換，但請為每個指令閱讀完整的說明文件，以便你了解升級的影響。當然，在將設定檔投入生產環境之前，務必徹底測試你的設定檔。

主要變更

如果你要提供靜態檔案，你需要新增一個 file_server 指令，因為 Caddy 2 預設不會執行此動作。出於安全考量，Caddy 2 也不會預設嗅探 MIME 類型；如果缺少 Content-Type，你可能需要使用 header 指令自行設定標頭。
在 v1 中，你只能根據請求路徑篩選（或「比對」）指令。在 v2 中，請求比對的功能強大許多。任何新增中間軟體到 HTTP 處理器鏈或以任何方式處理 HTTP 請求/回應的 v2 指令都會利用這個新的比對功能。進一步了解 v2 請求比對器。你需要了解這些比對器才能理解 v2 Caddyfile。
雖然許多佔位符都相同，但許多已經改變，現在有許多新的佔位符，包括 Caddyfile 的簡寫。
Caddy 2 的記錄檔皆為結構化，預設格式為 JSON。所有記錄等級都可直接傳送到同一個記錄檔進行處理（但您可依需要自訂）。
在 Caddy 1 中，您可以透過路徑前綴比對要求，而 Caddy 2 中的路徑比對預設為完全比對。如果您要比對前綴，例如 /foo/，您需要在 Caddy 2 中使用 /foo/*。

我們會在此列出一些最常見的 v1 指令，並說明如何轉換為 v2 Caddyfile 中使用。

⚠️ 即使此頁面中沒有 v1 指令，並不表示 v2 無法執行！有些 v1 指令並非必要，無法順利轉換，或在 v2 中以其他方式實現。對於部分進階自訂，您可能需要使用 JSON 才能取得您要的結果。探索我們的文件，找出您需要的內容！

basicauth

HTTP 基本驗證仍使用 basicauth 指令進行設定。不過，Caddy 2 設定不接受純文字密碼。您必須將其雜湊，而 caddy hash-password 可以協助您執行此動作。

basicauth /secret/ Bob hiccup

basicauth /secret/* {
	Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}

browse

檔案瀏覽現已透過 file_server 指令啟用。

browse /subfolder/

file_server /subfolder/* browse

errors

自訂錯誤頁面可透過 handle_errors 完成。

errors {
	404 404.html
	500 500.html
}

handle_errors {
	rewrite * /{err.status_code}.html
	file_server
}

ext

隱含檔案副檔名可透過 try_files 完成。

v1: ext .html
v2: try_files {path}.html {path}

fastcgi

假設您提供 PHP 服務，v2 等效指令為 php_fastcgi。

fastcgi / localhost:9005 php

php_fastcgi localhost:9005

請注意，v1 中的 fastcgi 指令在幕後執行許多工作，包括嘗試磁碟上的檔案、重寫要求，甚至重新導向。v2 php_fastcgi 指令也會為您執行這些工作，但文件會提供其擴充形式，如果您有不同的需求，您可以修改此形式。

v2 中不需要 php 預設值，因為 php_fastcgi 指令預設假設為 PHP。例如 php_fastcgi 127.0.0.1:9000 php 會導致反向代理認為有一個名為 php 的第二個後端，進而導致連線錯誤。

v2 中的子指令不同，您可能不需要任何 PHP 子指令。

gzip

現在單一指令 encode 用於所有回應編碼，包含多種壓縮格式。

gzip

encode gzip

有趣的事實：Caddy 2 也支援 zstd（但目前沒有瀏覽器支援）。

幾乎沒有改變，但現在強大許多，因為它可以在 v2 中進行子字串替換。

header / Strict-Transport-Security max-age=31536000;

header Strict-Transport-Security max-age=31536000;

log

啟用存取記錄；log 指令仍可在 v2 中使用，但所有記錄都是結構化的，預設編碼為 JSON。

啟用存取記錄的建議方式很簡單

log

它會將結構化記錄發射到 stderr。（你也可以發射到檔案或網路插槽；請參閱 log 指令文件。）

預設情況下，記錄將採用結構化 JSON 格式。如果你出於舊有原因仍需要常見記錄格式 (CLF) 的記錄，可以使用 transform-encoder 外掛程式。

proxy

v2 等效指令是 reverse_proxy。

值得注意的子指令變更包括 header_upstream 和 header_downstream 已分別變更為 header_up 和 header_down；與負載平衡相關的子指令則加上 lb_ 前綴。

另一個顯著差異是 v2 代理預設傳遞所有輸入標頭（包含 Host 標頭），並設定 X-Forwarded-For 標頭。換句話說，v1 的「透明」模式基本上是 v2 的預設值（但如果你需要其他標頭，例如 X-Real-IP，則必須自行設定）。你仍可以使用 header_up 子指令覆寫/自訂 Host 標頭。

WebSocket 代理在 v2 中「正常運作」；不需要像 v1 一樣「啟用」WebSocket。

without 子指令已移除，因為由於改進的比對器支援，在 v2 中不再需要重寫技巧。

proxy / localhost:9005

reverse_proxy localhost:9005

redir

未變更，除了關於選用狀態碼引數的一些詳細資訊。大多數設定不需要進行任何變更。

v1： redir https://example.com{uri}
v2： redir https://example.com{uri}

rewrite

請求改寫（「內部重新導向」）的語意已略有變更。如果您在 v1 中使用所謂的「改寫技巧」來比對非單純路徑前綴的其他請求，那麼在 v2 中完全不需要這樣做。

新的 rewrite 指令非常簡單，但功能強大，因為它的複雜性大部分都由 v2 中的比對器處理

rewrite {
	if {>User-Agent} has mobile
	to /mobile{uri}
}

@mobile {
	header User-Agent *mobile*
}
rewrite @mobile /mobile{uri}

請注意我們如何簡單地使用 Caddy 2 常見的比對器代碼；它不再是此指令的特殊情況。

首先移除所有改寫技巧；改為將它們轉換成命名比對器。評估每個 v1 rewrite，以查看它是否真的需要在 v2 中使用。提示：使用 rewrite 新增路徑前綴，然後使用 without proxy 移除相同前綴的 v1 Caddyfile 是改寫技巧，可以消除。

您可能會發現新的 route 和 handle 指令對於更精確地控制進階路由邏輯很有用。

root

不變，但如果您的根路徑以 / 開頭，您需要新增 * 比對器代碼，以將它與路徑比對器區分開來。

v1： root /var/www
v2： root * /var/www

由於它接受 v2 中的比對器，這表示您也可以根據請求變更網站根目錄。

請記得，如果您要提供靜態檔案，請新增 file_server 指令，因為 Caddy 2 預設不會假設這一點，而 v1 中始終已啟用它。

status

v2 等效指令為 respond，它也可以寫入回應主體。

status 404 /secrets/

respond /secrets/* 404

templates

templates 指令的整體語法不變，但實際的範本動作/函式不同，而且改進許多。例如，範本能夠包含檔案、呈現標記、進行內部子請求、剖析前端事項等！

參閱文件，以取得有關新函式的詳細資料。

v1： templates
v2： templates

tls

tls 指令的基本原理不變，例如指定您自己的憑證和金鑰

v1： tls cert.pem key.pem
v2： tls cert.pem key.pem

但 Caddy 的自動 HTTPS 邏輯已變更，請注意這一點！

加密組名稱也已變更。

Caddy 2 中常見的組態是使用 tls internal，讓它提供一個本機信任的憑證給一個開發主機名稱，該主機名稱不是 localhost 或 IP 位址。

大多數網站根本不需要這個指令。

服務檔案

我們建議使用我們的其中一個官方 systemd 服務檔案來部署 Caddy。

如果你需要一個自訂的服務檔案，請以我們的為基礎。它們經過仔細調整，有其充分的理由！如有需要，務必自訂你的檔案。

外掛程式

為 v1 編寫的外掛程式不會自動與 v2 相容。許多 v1 外掛程式在 v2 中甚至不需要。另一方面，v2 比 v1 更容易擴充且更靈活！

如果你想為 Caddy 2 編寫外掛程式，瞭解如何編寫 Caddy 模組。

使用外掛程式建置 Caddy 2

可以在互動式下載頁面下載帶有外掛程式的 Caddy 2。或者，你可以使用 xcaddy 自行建置 Caddy，並選擇要包含哪些外掛程式。xcaddy 會自動執行 Caddy main.go 檔案中的指令。

取得協助

如果你在讓 Caddy 運作時遇到困難，請先瀏覽我們的網站以取得文件。花點時間嘗試新事物並了解發生了什麼事 - v2 在許多方面與 v1 非常不同（但也很熟悉）！

如果你仍然需要協助，請加入我們的社群！你可能會發現幫助他人也是幫助自己的最佳方式。