Caddyfile 教程

本教程将向你讲解 HTTP Caddyfile 的基础知识，以便你能够快速轻松地生成美观实用的站点配置。

目标

🔲 第一个站点
🔲 静态文件服务器
🔲 模板
🔲 压缩
🔲 多个站点
🔲 匹配器
🔲 环境变量
🔲 注释

先决条件

基本的终端/命令行技能
基本的文本编辑器技能
PATH 中的 caddy

创建一个名为 Caddyfile（无扩展名）的新文本文件。

你应该键入的第一件事是站点的地址

localhost

然后按 Enter 键并键入你希望它执行的操作。对于本教程，请将你的 Caddyfile 设为如下所示

localhost

respond "Hello, world!"

保存它并运行 Caddy（由于这是一个培训教程，我们将使用 --watch 标志，以便对 Caddyfile 所做的更改自动应用）

caddy run --watch

首次，系统会要求你输入密码。这是为了让 Caddy 能够通过 HTTPS 为你的网站提供服务。

在浏览器中打开 localhost，查看你的网络服务器运行，并完成 HTTPS！

这并不特别令人兴奋，因此，让我们将我们的静态响应更改为启用了目录列表的文件服务器

localhost

file_server browse

保存你的 Caddyfile，然后刷新浏览器选项卡。你应该会看到一个文件列表，或者如果当前目录中有一个索引文件，则会看到一个 HTML 页面。

添加功能

让我们对我们的文件服务器做一些有趣的事情：提供一个模板页面。创建一个新文件，并将此内容粘贴到其中

<!DOCTYPE html>
<html>
	<head>
		<title>Caddy tutorial</title>
	</head>
	<body>
		Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}
	</body>
</html>

将其另存为当前目录中的 caddy.html，并在浏览器中加载它：https://127.0.0.1/caddy.html

输出为

Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}

等一下。我们应该看到今天的日期。为什么不起作用？这是因为服务器尚未配置为评估模板！很容易修复，只需向 Caddyfile 添加一行，使其看起来像这样

localhost

templates
file_server browse

保存它，然后重新加载浏览器选项卡。你应该会看到

Page loaded at: Sat Apr 27 17:14:45 UTC 2024

使用 Caddy 的模板模块，你可以对静态文件执行许多有用的操作，例如包括其他 HTML 文件、进行子请求、设置响应头、处理数据结构等等！

使用快速且现代的压缩算法来压缩响应是一种很好的做法。让我们使用 encode 指令启用 Gzip 和 Zstandard 支持

localhost

encode zstd gzip
templates
file_server browse

这是启动一个半高级、可用于生产的网站的基本过程！

当你准备启用自动 HTTPS 时，只需用你的域名替换网站的地址（在本教程中为 localhost）。有关更多信息，请参阅我们的 HTTPS 快速入门指南。

多个网站

使用我们当前的 Caddyfile，我们只能有一个网站定义！只有第一行可以是网站的地址，然后文件的所有其他内容都必须是该网站的指令。

但是，很容易做到我们可以添加更多网站！

到目前为止，我们的 Caddyfile

localhost

encode zstd gzip
templates
file_server browse

等效于这个

localhost {
	encode zstd gzip
	templates
	file_server browse
}

除了第二个允许我们添加更多网站。

通过在花括号 { } 中包装我们的站点块，我们能够在同一个 Caddyfile 中定义多个不同的站点。

例如

:8080 {
	respond "I am 8080"
}

:8081 {
	respond "I am 8081"
}

在花括号中包装站点块时，只有地址出现花括号外，只有指令出现花括号内。

对于共享相同配置的多个站点，你可以添加更多地址，例如

:8080, :8081 {
	...
}

只要每个地址都是唯一的，你就可以定义任意多个不同的站点。

匹配器

我们可能只想对某些请求应用一些指令。例如，假设我们想要同时拥有一个文件服务器和一个反向代理，但我们显然不能在每个请求上都同时执行这两个操作！文件服务器将写入一个静态文件，或者反向代理将请求代理到后端。

此配置不会按我们想要的方式工作

localhost

file_server
reverse_proxy 127.0.0.1:9005

实际上，我们可能只想对 API 请求（即基本路径为 /api/ 的请求）使用反向代理。通过添加匹配器令牌，可以轻松实现此目的

localhost

file_server
reverse_proxy /api/* 127.0.0.1:9005

现在，反向代理将优先处理所有以 /api/ 开头的请求。

我们刚刚添加的 /api/* 令牌称为匹配器令牌。你可以看出它是一个匹配器令牌，因为它以正斜杠 / 开头，并且它出现在指令的正后方（但你始终可以在指令文档中查看它以确保）。

匹配器非常强大。你可以命名匹配器并使用它们，例如 @name 来匹配不仅仅是请求路径！在继续之前，请花点时间了解有关匹配器的更多信息！

环境变量

Caddyfile 适配器允许在解析 Caddyfile 之前替换环境变量。

首先，设置一个环境变量（在运行 Caddy 的同一 shell 中）

export SITE_ADDRESS=localhost:9055

然后，你可以在 Caddyfile 中像这样使用它

{$SITE_ADDRESS}

file_server

在解析 Caddyfile 之前，它将展开为

localhost:9055

file_server

你可以在 Caddyfile 中的任何位置使用环境变量，用于任意数量的令牌。

注释

你会发现最有帮助的最后一件事是：如果你想在 Caddyfile 中备注或记下任何内容，可以使用从 # 开始的注释

# this starts a comment