【Caddy2】最新Caddy2配置文件解析

原創聲明

作者：Billyme (詩)

博客園：https://www.cnblogs.com/billyme/

CSDN ：https://blog.csdn.net/horizon08

Gitee：https://billyme.gitee.io/blog/

本文為 Billyme 原創作品，僅發表於以上平台，不允許轉載

Caddy 介紹

Caddy官網：CaddyServer

THE ULTIMATE SERVER
Caddy 2 is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go

Caddy2的升級指南

升級指南🔗

Caddy 2 是一個全新的代碼庫，從頭開始編寫，以改進 Caddy 1。Caddy 2 不向后兼容 Caddy 1。但不用擔心，對於大多數基本設置，並沒有太大的不同。本指南將幫助您盡可能輕松地過渡。

本指南不會深入研究可用的新功能——它們真的很酷，順便說一下，你應該學習它們——這里的目標是讓你快速啟動並運行 Caddy 2。

菜單🔗

• 高位
• 腳步
• HTTPS 和端口
• 命令行
• 球童檔案
  • 主要變化
  • 基本認證
  • 瀏覽
  • 錯誤
  • 分機
  • 快速cgi
  • 壓縮包
  • 標題
  • 日志
  • 代理
  • 重新目錄
  • 改寫
  • 根
  • 狀態
  • 模板
  • 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 基本相同，但功能更強大；指令已更改。

腳步🔗

1. 通過我們的入門教程熟悉 Caddy 2 。
2. 如果您還沒有，請執行第 1 步。說真的——我們不能強調至少知道如何使用 Caddy 2 的重要性。（它更有趣！）
3. 使用以下指南轉換您的caddy命令。
4. 使用以下指南轉換您的 Caddyfile。
5. 在本地或暫存中測試您的新配置。
6. 測試，測試，再測試
7. 部署並玩得開心！

HTTPS 和端口🔗

Caddy 的默認端口不再是:2015. Caddy 2 的默認端口是:443，或者，如果不知道主機名/IP，則為 port :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.1 中的大多數命令行標志。

像這樣的命令caddy -conf ../Caddyfile會變成caddy run --config ../Caddyfile.

和以前一樣，如果您的 Caddyfile 在當前文件夾中，Caddy 會自動找到並使用它；在這種情況下，您不需要使用該--config標志。

信號基本相同，只是不再支持 USR1 和 USR2。請改用caddy reload命令或API來加載新配置。

在沒有任何配置的情況下運行caddy用於運行簡單的文件服務器。Caddy 2 中的等價物是caddy file-server.

環境變量不再相關，除了HOME（並且，可選地，XDG_*您設置的任何變量）。CADDYPATH被操作系統約定所取代。

球童檔案🔗

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/，則需要/foo/*在 Caddy 2 中匹配。

我們將在這里列出一些最常見的 v1 指令，並描述如何轉換它們以在 v2 Caddyfile 中使用。

⚠️僅僅因為此頁面缺少 v1 指令並不意味着 v2 不能做到！一些 v1 指令不需要，翻譯不好，或者在 v2 中以其他方式實現。對於一些高級定制，您可能需要下拉到 JSON 以獲得您想要的。瀏覽我們的文檔以找到您需要的內容！

基本認證🔗

HTTP 基本身份驗證仍使用該basicauth指令進行配置。但是，Caddy 2 配置不接受明文密碼。您必須對它們進行哈希處理，這caddy hash-password可以提供幫助。

• v1：

basicauth /secret/ Bob hiccup

• v2：

basicauth /secret/* {
	Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}

瀏覽🔗

現在通過file_server指令啟用文件瀏覽。

• v1：

browse /subfolder/

• v2：

file_server /subfolder/* browse

錯誤🔗

自定義錯誤頁面可以使用handle_errors.

• v1: :

errors {
	404 404.html
	500 500.html
}

• v2: :

handle_errors {
	rewrite * /{http.error.status_code}.html
	file_server
}

分機🔗

隱含的文件擴展名可以用try_files.

• v1： ext .html
• v2： try_files {path}.html {path}

快速cgi🔗

假設您正在使用 PHP，則 v2 等效項是php_fastcgi.

• v1：

fastcgi / localhost:9005 php

• v2：

php_fastcgi localhost:9005

請注意，fastcgiv1 中的指令在后台做了很多工作，包括嘗試磁盤上的文件、重寫請求，甚至重定向。v2php_fastcgi指令也為您做這些事情，但文檔提供了擴展形式，如果您的要求不同，您可以對其進行修改。

phpv2中不需要預設，因為該php_fastcgi指令默認采用 PHP。諸如此類的行php_fastcgi 127.0.0.1:9000 php會導致反向代理認為有第二個后端稱為php，從而導致連接錯誤。

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

壓縮包🔗

現在，一個指令encode用於所有響應編碼，包括多種壓縮格式。

• v1：

gzip

• v2：

encode gzip

有趣的事實：Caddy 2 也支持zstd（但還沒有瀏覽器支持）。

標題🔗

大部分沒有改變，但現在更強大，因為它可以在 v2 中進行子字符串替換。

• v1：

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

• v2：

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

日志🔗

啟用訪問記錄；該log指令仍然可以在 v2 中使用，但默認情況下，所有日志都是結構化的，編碼為 JSON。

啟用訪問日志的推薦方法很簡單：

log

它將結構化日志發送到標准錯誤。（您也可以發送到文件或網絡套接字；請參閱log指令文檔。）

默認情況下，日志將采用結構化JSON 格式。如果由於遺留原因您仍然需要通用日志格式 (CLF) 的日志，您可以使用該transform-encoder插件。

代理🔗

v2 等效項是reverse_proxy.

顯着的子指令變化分別為header_upstream和；和負載平衡相關的子指令以 . 為前綴。header_downstream``header_up``header_down``lb_

另一個顯着的區別是 v2 代理默認通過所有傳入的標頭（包括Host標頭）並設置X-Forwarded-For標頭。換句話說，v1 的“透明”模式基本上是 v2 中的默認模式（但如果您需要 X-Real-IP 等其他標頭，則必須自己設置）。您仍然可以Host使用header_up子指令覆蓋/自定義標頭。

Websocket 代理在 v2 中“正常工作”；無需像 v1 那樣“啟用”websocket。

由於改進的匹配器支持，v2 中不再需要重寫黑客，因此without子指令已被刪除。

• v1：

proxy / localhost:9005

• v2：

reverse_proxy localhost:9005

重新目錄🔗

不變，除了一些關於可選狀態碼參數的細節。大多數配置不需要進行任何更改。

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

改寫🔗

請求重寫（“內部重定向”）的語義略有改變。如果您在 v1 中使用所謂的“rewrite hack”作為匹配請求而不是簡單路徑前綴的方式，那么在 v2 中這是完全沒有必要的。

新指令非常簡單但非常強大，因為它的rewrite大部分復雜性都由v2 中的匹配器處理：

• v1：

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

• v2：

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

請注意我們如何簡單地使用 Caddy 2 的常用匹配器令牌；它不再是該指令的特例。

首先刪除所有重寫黑客；將它們變成命名匹配器。評估每個 v1rewrite以查看 v2 中是否真的需要它。提示：rewrite用於添加路徑前綴然后刪除相同前綴proxy的v1 Caddyfilewithout是一種重寫技巧，可以被消除。

您可能會發現新的route和handle指令對於更好地控制高級路由邏輯很有用。

根🔗

未更改，但如果您的根路徑以 開頭/，則需要添加*匹配器標記以將其與路徑匹配器區分開來。

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

因為它接受 v2 中的匹配器，這意味着您還可以根據請求更改站點根目錄。

如果提供靜態文件，請記住添加file_server指令，因為默認情況下 Caddy 2 不假設這一點，而在 v1 中始終啟用它。

狀態🔗

v2 等效的是respond，它也可以寫一個響應體。

• v1：

status 404 /secrets/

• v2：

respond /secrets/* 404

模板🔗

指令的整體語法templates沒有改變，但實際的模板動作/功能是不同的並且有很大的改進。例如，模板能夠包含文件、渲染 markdown、制作內部子請求、解析前端內容等等！

有關新功能的詳細信息，請參閱文檔。

• 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 兼容。v2 甚至不需要許多 v1 插件。另一方面，v2 比 v1 更容易擴展和靈活！

如果您想為 Caddy 2 編寫插件，請學習如何編寫 Caddy 模塊。

使用插件構建 Caddy 2🔗

Caddy 2 可以在交互式下載頁面通過插件下載。或者，您可以使用自己構建 Caddyxcaddy並選擇要包含的插件。xcaddy自動執行 Caddy 的main.go文件中的指令。

獲得幫助🔗

如果您難以讓 Caddy 正常工作，請先瀏覽我們的網站以獲取文檔。花時間嘗試新事物並了解正在發生的事情 - v2 在很多方面與 v1 非常不同（但也非常熟悉）！

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

最佳實踐

1. 部署靜態網頁

http://yousite.com {
	encode gzip # gzip壓縮
	root * /var/web/wwwroot # web根目錄
	file_server browse  # 啟動靜態資源
}

​ 注意，如果配置根目錄下有index.html文件，則會自動部署為靜態網頁，如果沒有則為由Caddy提供的文件共享的瀏覽網頁如下。

2. 部署File_server

yousite.com {
   	root * /var/share #根目錄
   	file_server browse #啟動web文件服務
}

3. 反向代理

 yousite.com {
      	reverse_proxy localhost:8082 #反向代理
 }
     

4. 部署

  caddy adapt  ## 加載配置文件
  
  caddy fmt	 ## 格式化配置
  
  caddy start  ## 啟動服務

注意，如果為重新部署，請將最后一句start換為 caddy reload

參考資源

1. Caddyserver Document