入门

欢迎使用 Caddy！本教程将探讨使用 Caddy 的基础知识，帮助您从高层次了解它。

目标

• 🔲 运行守护进程
• 🔲 尝试 API
• 🔲 为 Caddy 提供配置
• 🔲 测试配置
• 🔲 创建 Caddyfile
• 🔲 使用配置适配器
• 🔲 从初始配置开始
• 🔲 比较 JSON 和 Caddyfile
• 🔲 比较 API 和配置文件
• 🔲 在后台运行
• 🔲 零停机配置重新加载

先决条件

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

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

让我们从运行它开始

caddy

糟糕；没有子命令，caddy 命令只会显示帮助文本。如果您忘记了该怎么做，可以随时使用它。

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

caddy run

这会永远阻塞，但它在做什么？目前...什么也没做。默认情况下，Caddy 的配置（“config”）是空白的。我们可以使用另一个终端中的 管理 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 与 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 将回滚到上次有效的配置。