入门

欢迎来到Caddy! 本教程将探讨使用Caddy的基础知识，并帮助你在高层次上熟悉它。

目标:

• 🔲 运行守护程序
• 🔲 试试API
• 🔲 给Caddy一个配置
• 🔲 测试配置
• 🔲 制作一个Caddy文件
• 🔲 使用配置适配器
• 🔲 从一个初始配置开始
• 🔲 比较JSON和Caddyfile
• 🔲 比较API和配置文件
• 🔲 在后台运行
• 🔲 零停机时间的配置重新加载

前提:

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

如果你从软件包管理器安装了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 \
	-X POST \
	-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，为我们适配后立即运行。

现在，在当前文件夹中有一个Caddy文件，让我们再次进行caddy运行:

caddy run

或者，如果您的 Caddyfile 在其他地方:

caddy run --config /path/to/Caddyfile

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

您现在可以尝试再次加载您的网站，您会看到它正在运行！

如您所见，您可以通过多种方式使用初始配置启动 Caddy:

• 当前目录下一个名为 Caddyfile 的文件
• --config 标志（可选择使用 --adapter 标志）
• --resume 标志（如果之前加载了配置）

JSON 与 Caddyfile

现在您知道 Caddyfile 刚刚为您转换为 JSON。

Caddyfile似乎比JSON更容易，但你应该总是使用它吗？每种方法都有优点和缺点。答案取决于你的要求和使用情况。

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

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

API 与配置文件

您还需要决定您的工作流程是基于 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 会回滚到上一个工作配置。