入门

欢迎来到 Caddy！本教程将探索使用 Caddy 的基础知识，并帮助您从高层次熟悉它。

目标

• 🔲 运行守护进程
• 🔲 尝试 API
• 🔲 给 Caddy 一个配置
• 🔲 测试配置
• 🔲 创建 Caddyfile
• 🔲 使用配置适配器
• 🔲 从初始配置开始
• 🔲 比较 JSON 和 Caddyfile
• 🔲 比较 API 和配置文件
• 🔲 在后台运行
• 🔲 零宕机时间配置重载

先决条件

• 基本终端/命令行技能
• 基本文本编辑器技能
• PATH 中包含 caddy 和 curl

如果您从包管理器安装了 Caddy，Caddy 可能已经在作为服务运行。如果是这样，请在进行本教程之前停止该服务。

让我们从运行它开始

caddy

糟糕；不带子命令，caddy 命令仅显示帮助文本。您可以在任何时候使用它来忘记要做什么。

要将 Caddy 作为守护进程启动，请使用 run 子命令

caddy run

这会永远阻塞，但它在做什么？目前... 什么也没做。默认情况下，Caddy 的配置（“config”）是空白的。我们可以使用另一个终端中的 admin API 来验证这一点

curl localhost:2019/config/

我们可以通过给 Caddy 一个配置来使其有用。这可以通过多种方式完成，但我们将从在下一节中使用 curl 向 /load 端点发出 POST 请求开始。

您的第一个配置

为了准备我们的请求，我们需要创建一个配置。在其核心，Caddy 的配置只是一个 JSON 文档。

将其保存到 JSON 文件（例如 caddy.json）

{
	"apps": {
		"http": {
			"servers": {
				"example": {
					"listen": [":2015"],
					"routes": [
						{
							"handle": [{
								"handler": "static_response",
								"body": "Hello, world!"
							}]
						}
					]
				}
			}
		}
	}
}

然后上传它

curl localhost:2019/load \
	-H "Content-Type: application/json" \
	-d @caddy.json

我们可以使用另一个 GET 请求来验证 Caddy 是否应用了我们的新配置

curl localhost:2019/config/

通过在浏览器中访问 localhost:2015 或使用 curl 来测试它是否工作

curl localhost:2015
Hello, world!

如果您看到Hello, world!，那么恭喜您——它正在工作！始终确保您的配置按预期工作是一个好主意，尤其是在部署到生产环境之前。

您的第一个 Caddyfile

仅仅为了 Hello World 就有点太麻烦了。

配置 Caddy 的另一种方法是使用 Caddyfile。我们在上面用 JSON 编写的相同配置可以简单地表示为

:2015

respond "Hello, world!"

将其保存到当前目录中名为 Caddyfile（无扩展名）的文件中。

如果 Caddy 已经在运行，请停止它 (Ctrl+C)，然后运行

caddy adapt

或者，如果您将 Caddyfile 存储在其他位置或将其命名为 Caddyfile 以外的名称

caddy adapt --config /path/to/Caddyfile

您将看到 JSON 输出！这里发生了什么？

我们刚刚使用了一个 配置适配器 将我们的 Caddyfile 转换为 Caddy 的原生 JSON 结构。

虽然我们可以获取该输出并发出另一个 API 请求，但我们可以跳过所有这些步骤，因为 caddy 命令可以为我们做到这一点。如果当前目录中有一个名为 Caddyfile 的文件，并且没有指定其他配置，Caddy 将加载 Caddyfile，为我们适配它，并立即运行它。

现在当前文件夹中有一个 Caddyfile，让我们再次执行 caddy run

caddy run

或者如果您的 Caddyfile 在其他位置

caddy run --config /path/to/Caddyfile

（如果它被称为其他不以 “Caddyfile” 开头的名称，您将需要指定 --adapter caddyfile。）

您现在可以再次尝试加载您的站点，您将看到它正在工作！

如您所见，有几种方法可以使用初始配置启动 Caddy

• 当前目录中名为 Caddyfile 的文件
• --config 标志（可选地带有 --adapter 标志）
• --resume 标志（如果之前加载过配置）

JSON vs. Caddyfile

现在您知道 Caddyfile 只是为您转换为 JSON。

Caddyfile 似乎比 JSON 更容易，但您应该始终使用它吗？每种方法都有优点和缺点。答案取决于您的需求和用例。

您需要决定哪种最适合您的用例。

重要的是要注意，JSON 和 Caddyfile（以及任何其他受支持的配置适配器）都可以与 Caddy 的 API 一起使用。但是，如果您使用 JSON，您将获得 Caddy 功能和 API 功能的全部范围。如果使用配置适配器，使用 API 加载或更改配置的唯一方法是 /load 端点。

API vs. 配置文件

您还需要决定您的工作流程是基于 API 还是基于 CLI。（您可以在同一服务器上同时使用 API 和配置文件，但我们不建议这样做：最好有一个单一的事实来源。）

API 或配置文件工作流程的选择与配置适配器的使用无关：您可以使用 JSON，但将其存储在文件中并使用命令行界面；相反，您也可以将 Caddyfile 与 API 一起使用。

但大多数人将使用 JSON+API 或 Caddyfile+CLI 组合。

如您所见，Caddy 非常适合各种用例和部署！

启动、停止、运行

由于 Caddy 是一个服务器，它会无限期地运行。这意味着在您执行 caddy run 后，您的终端不会解除阻塞，直到进程终止（通常使用 Ctrl+C）。

虽然 caddy run 是最常见的并且通常被推荐（尤其是在制作系统服务时！），但您可以选择使用 caddy start 来启动 Caddy 并使其在后台运行

caddy start

这将使您可以再次使用您的终端，这在某些交互式无头环境中很方便。

然后您将不得不自己停止该进程，因为 Ctrl+C 不会为您停止它

caddy stop

或使用 API 的 /stop 端点。

重新加载配置

您的服务器可以执行零宕机时间配置重新加载/更改。

所有加载或更改配置的 API 端点 都是优雅的，零宕机时间。

但是，当使用命令行时，可能会很想使用 Ctrl+C 停止您的服务器，然后再重新启动它以获取新配置。不要这样做：停止和启动服务器与配置更改无关，并且会导致宕机。

相反，使用 caddy reload 命令进行优雅的配置更改

caddy reload

这实际上只是在底层使用了 API。它将加载，并在必要时将您的配置文件适配为 JSON，然后优雅地替换活动配置而不会造成宕机。

如果加载新配置时出现任何错误，Caddy 将回滚到上次正常工作的配置。