【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。

菜单🔗

高位🔗

  • “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：
1
basicauth /secret/ Bob hiccup
  • v2：
1
2
3
basicauth /secret/* {
	Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX
}

浏览🔗

现在通过file_server指令启用文件浏览。

  • v1：
1
browse /subfolder/
  • v2：
1
file_server /subfolder/* browse

错误🔗

自定义错误页面可以使用handle_errors.

  • v1: :
1
2
3
4
errors {
	404 404.html
	500 500.html
}
  • v2: :
1
2
3
4
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：
1
fastcgi / localhost:9005 php
  • v2：
1
php_fastcgi localhost:9005

请注意，fastcgiv1 中的指令在后台做了很多工作，包括尝试磁盘上的文件、重写请求，甚至重定向。v2php_fastcgi指令也为您做这些事情，但文档提供了扩展形式，如果您的要求不同，您可以对其进行修改。

phpv2中不需要预设，因为该php_fastcgi指令默认采用 PHP。诸如此类的行php_fastcgi 127.0.0.1:9000 php会导致反向代理认为有第二个后端称为php，从而导致连接错误。

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

压缩包🔗

现在，一个指令encode用于所有响应编码，包括多种压缩格式。

  • v1：
1
gzip
  • v2：
1
encode gzip

有趣的事实：Caddy 2 也支持zstd（但还没有浏览器支持）。

标题🔗

大部分没有改变，但现在更强大，因为它可以在 v2 中进行子字符串替换。

  • v1：
1
header / Strict-Transport-Security max-age=31536000;
  • v2：
1
header Strict-Transport-Security max-age=31536000;

日志🔗

启用访问记录；该log指令仍然可以在 v2 中使用，但默认情况下，所有日志都是结构化的，编码为 JSON。

启用访问日志的推荐方法很简单：

1
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：
1
proxy / localhost:9005
  • v2：
1
reverse_proxy localhost:9005

重新目录🔗

不变，除了一些关于可选状态码参数的细节。大多数配置不需要进行任何更改。

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

改写🔗

请求重写（“内部重定向”）的语义略有改变。如果您在 v1 中使用所谓的“rewrite hack”作为匹配请求而不是简单路径前缀的方式，那么在 v2 中这是完全没有必要的。

新指令非常简单但非常强大，因为它的rewrite大部分复杂性都由v2 中的匹配器处理：

  • v1：
1
2
3
4
rewrite {
	if {>User-Agent} has mobile
	to /mobile{uri}
}
  • v2：
1
2
3
4
@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：
1
status 404 /secrets/
  • v2：
1
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. 部署静态网页
1
2
3
4
5
http://yousite.com {
	encode gzip # gzip压缩
	root * /var/web/wwwroot # web根目录
	file_server browse  # 启动静态资源
}

​ 注意，如果配置根目录下有index.html文件，则会自动部署为静态网页，如果没有则为由Caddy提供的文件共享的浏览网页如下。

  1. 部署File_server
1
2
3
4
yousite.com {
   	root * /var/share #根目录
   	file_server browse #启动web文件服务
}
  1. 反向代理
1
2
3
4
yousite.com {
     	reverse_proxy localhost:8082 #反向代理
}

  1. 部署

    1
    2
    3
    4
    5
    caddy adapt  ## 加载配置文件

    caddy fmt	 ## 格式化配置

    caddy start  ## 启动服务

    注意，如果为重新部署，请将最后一句start换为 caddy reload

参考资源

  1. Caddyserver Document